package gudusoft.gsqlparser.lineage.v2.identity;

import gudusoft.gsqlparser.lineage.v2.Finding;
import gudusoft.gsqlparser.lineage.v2.SqllrException;
import gudusoft.gsqlparser.lineage.v2.SqllrResources;
import gudusoft.gsqlparser.lineage.v2.json.CanonicalJson;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.HashSet;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.TreeSet;

/**
 * Recomputes every id of a lineage document from the identity inputs it carries ({@code identity-v1.md},
 * Section 6), as the reference's {@code check-ids} and {@code fill-ids} do ({@code sqllr_ids.py},
 * {@code DocumentIds} and {@code check_document}).
 *
 * <p>Canonical segment keys are read from the document ({@code canonicalKey}); checking them against the
 * identifier-rule data is the IDENTITY stage's job. An endpoint declared {@code LOCAL} whose class is portable
 * is accepted and listed as unchecked, because the qualification policy needs the profile data.</p>
 *
 * <p>A finding is reported where the reference reports it; every input the class cannot check is listed as a
 * note. Owner chains and derived-unit chains are walked with explicit lists, so their length is not limited by
 * the thread stack; a chain that returns to itself is a note (owners) or {@code REF_OWNER_CYCLE} (units).</p>
 *
 * @since 4.2.17
 */
public final class DocumentIds {

    /** Findings and notes of one run. */
    public static final class Report {
        private final List<Finding> findings;
        private final List<String> notes;
        private final Object document;

        Report(List<Finding> findings, List<String> notes, Object document) {
            this.findings = Collections.unmodifiableList(findings);
            this.notes = Collections.unmodifiableList(notes);
            this.document = document;
        }

        /** Mismatches ({@code ID_MISMATCH}, {@code ID_MISSING}, ...) and rejected inputs. */
        public List<Finding> getFindings() {
            return findings;
        }

        /** The inputs that could not be checked. */
        public List<String> getNotes() {
            return notes;
        }

        /** For {@link #fill(Object)}: the document with every computable id filled in; null otherwise. */
        public Object getDocument() {
            return document;
        }
    }

    /**
     * {@code check-ids}: recomputes every id of a document, and the id of the dependency snapshot each analysis
     * context names (looked up among the snapshots this library ships).
     */
    public static Report check(Object document) {
        return check(document, null);
    }

    /** As {@link #check(Object)}, with the given dependency snapshot (a parsed snapshot file) for every context. */
    public static Report check(Object document, Object snapshot) {
        DocumentIds ids = new DocumentIds(document, false);
        Set<Object> seen = new HashSet<Object>();
        for (Object item : list(map(document).get("analysisContexts"))) {
            Object snapshotId = item instanceof Map<?, ?> ? ((Map<?, ?>) item).get("dependencySnapshotId") : null;
            if (!seen.add(snapshotId == null ? NULL_KEY : snapshotId)) {
                continue;
            }
            String where = "analysisContexts ref " + map(item).get("ref") + ": dependencySnapshotId";
            String path = "snapshot";
            Map<?, ?> found = null;
            if (snapshot != null) {
                found = map(snapshot);
            } else {
                for (String candidate : shippedSnapshots()) {
                    Map<?, ?> parsed = map(SqllrResources.json(candidate));
                    if (snapshotId != null && snapshotId.equals(parsed.get("snapshotId"))) {
                        found = parsed;
                        path = candidate;
                        break;
                    }
                }
            }
            if (found == null) {
                ids.notes.add("dependency snapshot " + snapshotId + " not found among the shipped snapshots; its id is used"
                        + " as declared");
                continue;
            }
            String recomputed = snapshotIdOf(found);
            if (!recomputed.equals(found.get("snapshotId"))) {
                ids.findings.add(new Finding("ID_MISMATCH", path, "snapshotId " + found.get("snapshotId") + ", computed "
                        + recomputed));
            }
            if (!recomputed.equals(snapshotId)) {
                ids.findings.add(new Finding("ID_MISMATCH", where, "declared " + snapshotId + ", snapshot " + path
                        + " computes " + recomputed));
            }
        }
        ids.run();
        return new Report(ids.findings, ids.notes, null);
    }

    /**
     * {@code fill-ids}: a copy of the document with every computable id, numeric key, key and record id set,
     * and every id that is not computed removed.
     */
    public static Report fill(Object document) {
        Object copy = mutableCopy(document);
        DocumentIds ids = new DocumentIds(copy, true);
        ids.run();
        return new Report(ids.findings, ids.notes, copy);
    }

    /** The id of a dependency snapshot: {@code DependencySnapshotIdV1} of the file without {@code snapshotId}. */
    public static String snapshotIdOf(Object snapshot) {
        Map<String, Object> manifest = new LinkedHashMap<String, Object>();
        for (Map.Entry<?, ?> entry : map(snapshot).entrySet()) {
            if (!"snapshotId".equals(entry.getKey())) {
                manifest.put((String) entry.getKey(), entry.getValue());
            }
        }
        Map<String, Object> inputs = new LinkedHashMap<String, Object>();
        inputs.put("manifest", manifest);
        return IdentityV1.compute(IdentityV1.DEPENDENCY_SNAPSHOT, inputs).getId();
    }

    /** The shipped snapshot files, sorted by path. */
    public static List<String> shippedSnapshots() {
        List<String> out = new ArrayList<String>();
        for (String path : new TreeSet<String>(SqllrResources.index().keySet())) {
            if (path.startsWith("snapshots/") && path.endsWith(".json")) {
                out.add(path);
            }
        }
        return out;
    }

    // ---------------------------------------------------------------------------------------------

    private static final Object NULL_KEY = new Object();
    private static final List<String> DIGEST_PRECEDENCE = IdentityV1.DIGEST_DOMAINS;

    private final Map<?, ?> doc;
    private final boolean fill;
    private final List<Finding> findings = new ArrayList<Finding>();
    private final List<String> notes = new ArrayList<String>();
    private final Map<Object, Object[]> byRef = new HashMap<Object, Object[]>();
    private final Map<?, ?> header;
    private final Map<Object, String> units = new HashMap<Object, String>();
    private final Map<Object, String> contexts = new HashMap<Object, String>();
    private final Map<Object, String[]> endpoints = new HashMap<Object, String[]>();
    private final Map<Object, String[]> facts = new HashMap<Object, String[]>();

    private DocumentIds(Object document, boolean fill) {
        this.doc = map(document);
        this.fill = fill;
        this.header = map(doc.get("header"));
        Map<?, ?> explain = map(doc.get("explainGraph"));
        Object[][] collections = {
                {"analysisContexts", doc.get("analysisContexts")}, {"sourceUnits", doc.get("sourceUnits")},
                {"statements", doc.get("statements")}, {"scopes", doc.get("scopes")}, {"endpoints", doc.get("endpoints")},
                {"facts", doc.get("facts")}, {"factCandidates", doc.get("factCandidates")},
                {"candidateSets", doc.get("candidateSets")},
                {"occurrences", doc.get("occurrences")}, {"targetFieldOccurrences", doc.get("targetFieldOccurrences")},
                {"diagnostics", doc.get("diagnostics")}, {"explainGraph.nodes", explain.get("nodes")},
                {"explainGraph.microEdges", explain.get("microEdges")},
                {"explainGraph.candidateSets", explain.get("candidateSets")},
                {"explainGraph.supportPaths", explain.get("supportPaths")}};
        for (Object[] collection : collections) {
            for (Object item : list(collection[1])) {
                index((String) collection[0], item);
            }
            if ("factCandidates".equals(collection[0])) {
                for (Object item : list(collection[1])) {
                    for (String side : new String[] {"source", "target"}) {
                        Object end = map(item).get(side);
                        if (end instanceof Map<?, ?> && ((Map<?, ?>) end).containsKey("candidateSet")) {
                            index("candidateSets", ((Map<?, ?>) end).get("candidateSet"));
                        }
                    }
                }
            }
        }
    }

    private static Map<?, ?> map(Object value) {
        return value instanceof Map<?, ?> ? (Map<?, ?>) value : Collections.emptyMap();
    }

    private static List<?> list(Object value) {
        return value instanceof List<?> ? (List<?>) value : Collections.emptyList();
    }

    /**
     * The map key of a reference value: integers by numeric value whatever their Java type (a producer may
     * build maps with Integer or BigInteger), booleans and everything else as they are.
     */
    private static Object refKey(Object value) {
        if (value == null) {
            return NULL_KEY;
        }
        if (value instanceof Integer || value instanceof Short || value instanceof Byte) {
            return Long.valueOf(((Number) value).longValue());
        }
        if (value instanceof java.math.BigInteger && ((java.math.BigInteger) value).bitLength() < 64) {
            return Long.valueOf(((java.math.BigInteger) value).longValue());
        }
        return value;
    }

    private void index(String collection, Object item) {
        Object ref = item instanceof Map<?, ?> ? ((Map<?, ?>) item).get("ref") : null;
        if (byRef.containsKey(refKey(ref))) {
            findings.add(new Finding("REF_DUPLICATE", collection + " ref " + ref, "ref used twice"));
        }
        byRef.put(refKey(ref), new Object[] {collection, item});
    }

    private Map<?, ?> get(Object ref, String collection) {
        Object[] found = byRef.get(refKey(ref));
        if (found == null || !collection.equals(found[0])) {
            throw new SqllrException("REF_DANGLING", "ref " + ref + " is not a " + collection + " object");
        }
        return map(found[1]);
    }

    private void compare(String location, Object declared, String computed, String what) {
        if (computed == null && declared != null) {
            findings.add(new Finding("ID_UNEXPECTED", location, "declares " + what + " " + declared + ", but none is computed"));
        } else if (computed != null && declared == null) {
            findings.add(new Finding("ID_MISSING", location, what + " " + computed + " is computed but not declared"));
        } else if (computed != null && !computed.equals(declared)) {
            findings.add(new Finding("ID_MISMATCH", location, "declared " + declared + ", computed " + computed));
        }
    }

    private void compareNumeric(String location, Object declared, String id) {
        if (declared != null && (id == null || !declared.equals(IdentityV1.numericKey(id)))) {
            findings.add(new Finding("ID_NUMERIC_KEY_MISMATCH", location, "numericKey " + declared + " is not derived from "
                    + id));
        }
    }

    private static Map<String, Object> inputs(Object... pairs) {
        Map<String, Object> out = new LinkedHashMap<String, Object>();
        for (int i = 0; i < pairs.length; i += 2) {
            out.put((String) pairs[i], pairs[i + 1]);
        }
        return out;
    }

    private static Map<String, Object> status(String status) {
        return inputs("status", status);
    }

    // -- source units and analysis contexts

    private Map<?, ?> contextOf(Map<?, ?> unit) {
        return get(unit.get("analysisContextRef"), "analysisContexts");
    }

    private Map<String, Object> scopeOf(Map<?, ?> unit) {
        Map<?, ?> context = contextOf(unit);
        Object profile = context.get("pathProfile");
        Object producer = map(context.get("producer")).get("name");
        return inputs("profile", profile, "producer", IdentityV1.PATH_PROFILE_V1.equals(profile) ? null : producer);
    }

    /**
     * The {@code SourceUnitIdV1} of a unit. A {@code DERIVED} unit needs its parent's id first; the parent
     * chain is walked with an explicit list, and a chain that returns to a unit is {@code REF_OWNER_CYCLE}.
     */
    private String unitId(Map<?, ?> unit) {
        List<Map<?, ?>> chain = new ArrayList<Map<?, ?>>();
        Set<Map<?, ?>> onChain = Collections.newSetFromMap(new java.util.IdentityHashMap<Map<?, ?>, Boolean>());
        Map<?, ?> current = unit;
        while (!units.containsKey(refKey(current.get("ref")))) {
            if (!onChain.add(current)) {
                throw new SqllrException("REF_OWNER_CYCLE", "the parent chain of source unit " + unit.get("ref")
                        + " returns to unit " + current.get("ref"));
            }
            chain.add(current);
            if (!"DERIVED".equals(current.get("identityKind"))) {
                break;
            }
            current = get(current.get("parentUnitRef"), "sourceUnits");
        }
        for (int i = chain.size() - 1; i >= 0; i--) {
            Map<?, ?> item = chain.get(i);
            Object kind = item.get("identityKind");
            Map<String, Object> in;
            if ("NAMED".equals(kind)) {
                in = inputs("kind", "NAMED", "namespace", item.get("namespace"), "logicalName", item.get("logicalName"));
            } else if ("CONTENT_ADDRESSED".equals(kind)) {
                in = inputs("kind", "CONTENT_ADDRESSED", "contextDomain", item.get("contextDomain"), "contentDigest",
                        item.get("contentDigest"));
            } else if ("DERIVED".equals(kind)) {
                Map<?, ?> parentUnit = get(item.get("parentUnitRef"), "sourceUnits");
                String parent = units.get(refKey(parentUnit.get("ref")));
                Map<?, ?> site = get(item.get("siteStatementRef"), "statements");
                in = inputs("kind", "DERIVED", "parentUnit", parent != null ? parent : status(IdentityV1.LOCAL),
                        "statementOrdinal", site.get("ordinal"), "pathScope", scopeOf(parentUnit),
                        "sitePath", item.get("sitePath"), "siteOrdinal", item.get("siteOrdinal"),
                        "variantOrdinal", item.get("variantOrdinal"));
            } else {
                in = inputs("kind", "LOCAL");
            }
            units.put(refKey(item.get("ref")), IdentityV1.compute(IdentityV1.SOURCE_UNIT, in).getId());
        }
        return units.get(refKey(unit.get("ref")));
    }

    private String contextId(Map<?, ?> unit) {
        Object key = refKey(unit.get("ref"));
        if (!contexts.containsKey(key)) {
            Map<Object, Object> digests = new HashMap<Object, Object>();
            for (Object digest : list(unit.get("digests"))) {
                digests.put(map(digest).get("domain"), digest);
            }
            Object chosen = null;
            for (String domain : DIGEST_PRECEDENCE) {
                if (digests.containsKey(domain)) {
                    chosen = digests.get(domain);
                    break;
                }
            }
            Map<?, ?> context = contextOf(unit);
            if (unitId(unit) == null || chosen == null) {
                contexts.put(key, null);
            } else {
                Map<?, ?> metadata = map(context.get("metadata"));
                Map<?, ?> dialect = map(context.get("dialect"));
                Map<?, ?> redaction = map(context.get("redaction"));
                Map<?, ?> producer = map(context.get("producer"));
                Object resolution = unit.containsKey("resolutionInputDigests") ? unit.get("resolutionInputDigests")
                        : new ArrayList<Object>();
                contexts.put(key, IdentityV1.compute(IdentityV1.ANALYSIS_CONTEXT, inputs(
                        "producerName", producer.get("name"), "producerVersion", producer.get("version"),
                        "dependencySnapshot", context.get("dependencySnapshotId"),
                        "dialectId", dialect.get("id"), "dialectVersion", dialect.get("version"),
                        "identifierPolicyId", map(context.get("identifierPolicy")).get("policyId"),
                        "pathProfile", context.get("pathProfile"),
                        "effectiveOptionsDigest", context.get("effectiveOptionsDigest"),
                        "metadataStatus", metadata.get("status"), "metadataDigest", metadata.get("digest"),
                        "redactionPolicyId", redaction.get("policyId"),
                        "redactionPolicyVersion", redaction.get("policyVersion"),
                        "capabilities", context.get("capabilities"), "decoding", unit.get("decoding"),
                        "sourceContentDigest", chosen, "resolutionInputDigests", resolution)).getId());
            }
        }
        return contexts.get(key);
    }

    private void checkContext(Map<?, ?> context, String where) {
        Map<?, ?> metadata = map(context.get("metadata"));
        if ("NONE".equals(metadata.get("status")) || !metadata.containsKey("digest")) {
            return;
        }
        if (!metadata.containsKey("artifacts")) {
            notes.add(where + ": metadata artifacts not listed; the metadata digest is not checked");
            return;
        }
        String computed = IdentityV1.compute(IdentityV1.METADATA_DIGEST, inputs("artifacts", metadata.get("artifacts"))).getId();
        if (!computed.equals(metadata.get("digest"))) {
            findings.add(new Finding("ID_MISMATCH", where, "metadata digest " + metadata.get("digest") + ", artifacts compute "
                    + computed));
        }
    }

    // -- endpoints

    private List<Object> segmentInputs(Map<?, ?> endpoint) {
        List<Object> out = new ArrayList<Object>();
        for (Object item : list(map(endpoint.get("name")).get("segments"))) {
            Map<?, ?> seg = map(item);
            Object role = seg.get("role");
            if ("PRODUCER_DEFAULT".equals(seg.get("kind"))) {
                out.add(inputs("role", role, "kind", "PRODUCER_DEFAULT"));
            } else if ("AUTHORITY".equals(role) || "LOCATION".equals(role)) {
                out.add(inputs("role", role, "kind", "NAMED", "canonicalKey", seg.get("text")));
            } else if (seg.containsKey("keyUnavailable")) {
                out.add(inputs("role", role, "kind", "NAMED", "keyUnavailable", seg.get("keyUnavailable")));
            } else if (seg.containsKey("canonicalKey")) {
                out.add(inputs("role", role, "kind", "NAMED", "canonicalKey", seg.get("canonicalKey")));
            } else {
                return null;
            }
        }
        return out;
    }

    /** (top-level owner, full field path) of a FIELD endpoint; the path is null when a key is missing. */
    private Object[] fieldPath(Map<?, ?> endpoint) {
        List<Map<?, ?>> chain = new ArrayList<Map<?, ?>>();
        Set<Map<?, ?>> visited = Collections.newSetFromMap(new java.util.IdentityHashMap<Map<?, ?>, Boolean>());
        Map<?, ?> current = endpoint;
        Map<?, ?> owner = get(current.get("ownerRef"), "endpoints");
        while ("FIELD".equals(owner.get("kind"))) {
            chain.add(current);
            if (!visited.add(current)) {
                return new Object[] {owner, null};
            }
            current = owner;
            owner = get(current.get("ownerRef"), "endpoints");
        }
        // current is the top-level field; owner its relation (or ROW_SET, ...).
        List<?> segments = list(map(current.get("name")).get("segments"));
        if (segments.size() != 1) {
            return new Object[] {owner, null};
        }
        Map<?, ?> seg = map(segments.get(0));
        List<Object> path = new ArrayList<Object>();
        if (seg.containsKey("keyUnavailable")) {
            path.add(inputs("kind", "FIELD", "keyUnavailable", seg.get("keyUnavailable")));
        } else if (seg.containsKey("canonicalKey")) {
            path.add(inputs("kind", "FIELD", "canonicalKey", seg.get("canonicalKey")));
        } else {
            return new Object[] {owner, null};
        }
        for (int i = chain.size() - 1; i >= 0; i--) {
            for (Object item : list(chain.get(i).get("pathSegments"))) {
                Map<?, ?> segment = map(item);
                Map<String, Object> copy = new LinkedHashMap<String, Object>();
                for (String name : new String[] {"kind", "canonicalKey", "index", "keyUnavailable"}) {
                    if (segment.containsKey(name)) {
                        copy.put(name, segment.get(name));
                    }
                }
                path.add(copy);
            }
        }
        return new Object[] {owner, path};
    }

    /**
     * (status, id) recomputed for an endpoint; null when the document lacks an input. A FIELD or ROW_SET needs
     * its owner's result first: the owner chain is followed with an explicit list and computed from the far
     * end back, in the order the reference's recursion computes it.
     */
    private String[] endpointResult(Map<?, ?> endpoint) {
        List<Object[]> pending = new ArrayList<Object[]>(); // {endpoint, path} awaiting their owner's result
        Map<?, ?> current = endpoint;
        String[] result;
        while (true) {
            Object key = refKey(current.get("ref"));
            if (endpoints.containsKey(key)) {
                result = endpoints.get(key);
                break;
            }
            endpoints.put(key, null); // guards against owner cycles
            Object kind = current.get("kind");
            Object declared = map(current.get("identity")).get("status");
            String identityClass = kind instanceof String ? IdentityV1.IDENTITY_CLASS.get(kind) : null;
            if (IdentityV1.OPAQUE_PRODUCER_LOCAL.equals(declared)) {
                result = new String[] {IdentityV1.OPAQUE_PRODUCER_LOCAL, null};
            } else if (identityClass == null) {
                result = new String[] {IdentityV1.LOCAL, null};
            } else if (IdentityV1.LOCAL.equals(declared) && "ROUTINE".equals(identityClass)
                    && !current.containsKey("signature")) {
                // without a signature the overload is not proven: a routine is LOCAL whatever its qualification
                // (spec P1-3; EndpointIdV1 blocks it), so nothing is left unchecked
                result = new String[] {IdentityV1.LOCAL, null};
            } else if (IdentityV1.LOCAL.equals(declared)
                    && ("RELATION".equals(identityClass) || "ROUTINE".equals(identityClass))) {
                notes.add("endpoint ref " + current.get("ref") + ": declared LOCAL; the qualification policy is not checked");
                result = new String[] {IdentityV1.LOCAL, null};
            } else if ("RELATION".equals(identityClass) || "ROUTINE".equals(identityClass)) {
                result = null;
                List<Object> segments = segmentInputs(current);
                if (segments == null) {
                    notes.add("endpoint ref " + current.get("ref") + ": a NAMED segment has no canonicalKey; not recomputed");
                } else {
                    Map<String, Object> in = inputs("endpointKind", kind, "segments", segments);
                    if ("ROUTINE".equals(kind)) {
                        in.put("routineNamespace", current.get("routineNamespace"));
                        in.put("routineKind", current.get("routineKind"));
                        if (current.containsKey("signature")) {
                            in.put("signature", current.get("signature"));
                        }
                    }
                    IdentityV1.IdResult computed = IdentityV1.compute(IdentityV1.ENDPOINT, in);
                    result = new String[] {computed.getStatus(), computed.getId()};
                }
            } else {
                Map<?, ?> owner;
                Object path;
                if ("FIELD".equals(kind)) {
                    Object[] found = fieldPath(current);
                    owner = (Map<?, ?>) found[0];
                    path = found[1];
                } else {
                    owner = get(current.get("ownerRef"), "endpoints");
                    path = new ArrayList<Object>();
                }
                pending.add(new Object[] {current, path});
                current = owner;
                continue;
            }
            endpoints.put(key, result);
            break;
        }
        for (int i = pending.size() - 1; i >= 0; i--) {
            Map<?, ?> item = (Map<?, ?>) pending.get(i)[0];
            Object path = pending.get(i)[1];
            String[] ownerResult = result;
            if (ownerResult != null && path == null && ownerResult[1] == null
                    && (IdentityV1.LOCAL.equals(ownerResult[0])
                    || IdentityV1.OPAQUE_PRODUCER_LOCAL.equals(ownerResult[0]))) {
                // a FIELD of a LOCAL owner (a routine's unnamed return field) is LOCAL whatever its path: its status
                // is the worst of the owner's and the path's, and no path status ranks above LOCAL
                result = new String[] {ownerResult[0], null};
            } else if (ownerResult == null || path == null) {
                notes.add("endpoint ref " + item.get("ref") + ": owner or field key not available; not recomputed");
                result = null;
            } else {
                Object ownerInput = ownerResult[1] != null ? ownerResult[1] : status(ownerResult[0]);
                Map<String, Object> in = inputs("endpointKind", item.get("kind"), "owner", ownerInput);
                if ("FIELD".equals(item.get("kind"))) {
                    in.put("path", path);
                }
                IdentityV1.IdResult computed = IdentityV1.compute(IdentityV1.ENDPOINT, in);
                result = new String[] {computed.getStatus(), computed.getId()};
            }
            endpoints.put(refKey(item.get("ref")), result);
        }
        return result;
    }

    private Object endpointInput(Object ref) {
        String[] result = endpointResult(get(ref, "endpoints"));
        if (result == null) {
            return null;
        }
        return result[1] != null ? result[1] : status(result[0]);
    }

    /** ("OK", id or null) or ("UNCHECKED", null). */
    private String[] factId(Map<?, ?> fact) {
        Object key = refKey(fact.get("ref"));
        if (!facts.containsKey(key)) {
            Object source = endpointInput(fact.get("sourceRef"));
            Object target = endpointInput(fact.get("targetRef"));
            if (source == null || target == null) {
                facts.put(key, new String[] {"UNCHECKED", null});
            } else {
                Map<String, Object> in = inputs("kind", fact.get("kind"), "source", source, "target", target);
                if (fact.containsKey("role")) {
                    in.put("role", fact.get("role"));
                }
                facts.put(key, new String[] {"OK", IdentityV1.compute(IdentityV1.FACT, in).getId()});
            }
        }
        return facts.get(key);
    }

    private Map<String, Object> sideInput(Map<?, ?> end) {
        if (end.containsKey("endpointRef")) {
            Object value = endpointInput(end.get("endpointRef"));
            return value == null ? null : inputs("endpoint", value);
        }
        Map<?, ?> set = map(end.get("candidateSet"));
        List<Object> members = new ArrayList<Object>();
        for (Object member : list(set.get("candidateRefs"))) {
            members.add(endpointInput(member));
        }
        if (members.contains(null)) {
            return null;
        }
        return inputs("candidates", members, "membership", set.get("membership"));
    }

    private Map<String, Object> subjectInput(Map<?, ?> occurrence) {
        if (occurrence.containsKey("factRef")) {
            String[] fact = factId(get(occurrence.get("factRef"), "facts"));
            if ("UNCHECKED".equals(fact[0])) {
                return null;
            }
            return inputs("kind", "FACT", "fact", fact[1] != null ? fact[1] : status(IdentityV1.LOCAL));
        }
        Map<?, ?> candidate = get(occurrence.get("factCandidateRef"), "factCandidates");
        Map<String, Object> source = sideInput(map(candidate.get("source")));
        Map<String, Object> target = sideInput(map(candidate.get("target")));
        if (source == null || target == null) {
            return null;
        }
        Map<String, Object> subject = inputs("kind", "CANDIDATE", "factKind", candidate.get("kind"), "source", source,
                "target", target);
        if (candidate.containsKey("role")) {
            subject.put("role", candidate.get("role"));
        }
        return subject;
    }

    // -- the whole document

    private interface Check {
        void run();
    }

    private void guard(String where, Check check) {
        try {
            check.run();
        } catch (SqllrException e) {
            findings.add(new Finding(e.getCode(), where, e.getDetail()));
        }
    }

    private void run() {
        for (Object item : list(doc.get("analysisContexts"))) {
            final Map<?, ?> context = map(item);
            final String where = "analysisContexts ref " + context.get("ref");
            guard(where, new Check() {
                @Override
                public void run() {
                    checkContext(context, where);
                }
            });
        }
        for (Object item : list(doc.get("sourceUnits"))) {
            final Map<?, ?> unit = map(item);
            final String where = "sourceUnits ref " + unit.get("ref");
            guard(where, new Check() {
                @Override
                public void run() {
                    checkUnit(unit, where);
                }
            });
        }
        for (Object item : list(doc.get("endpoints"))) {
            final Map<?, ?> endpoint = map(item);
            final String where = "endpoints ref " + endpoint.get("ref");
            guard(where, new Check() {
                @Override
                public void run() {
                    checkEndpoint(endpoint, where);
                }
            });
        }
        for (Object item : list(doc.get("facts"))) {
            final Map<?, ?> fact = map(item);
            final String where = "facts ref " + fact.get("ref");
            guard(where, new Check() {
                @Override
                public void run() {
                    checkFact(fact, where);
                }
            });
        }
        for (Object item : list(doc.get("occurrences"))) {
            final Map<?, ?> occurrence = map(item);
            final String where = "occurrences ref " + occurrence.get("ref");
            guard(where, new Check() {
                @Override
                public void run() {
                    checkOccurrence(occurrence, where);
                }
            });
        }
        for (Object item : list(map(doc.get("explainGraph")).get("nodes"))) {
            final Map<?, ?> node = map(item);
            final String where = "explainGraph.nodes ref " + node.get("ref");
            guard(where, new Check() {
                @Override
                public void run() {
                    checkNode(node, where);
                }
            });
        }
    }

    @SuppressWarnings("unchecked")
    private void settle(Map<?, ?> obj, String member, String where, String computed, String what) {
        if (fill) {
            Map<String, Object> target = (Map<String, Object>) obj;
            if (computed == null) {
                target.remove(member);
            } else {
                target.put(member, computed);
            }
        } else {
            compare(where, obj.get(member), computed, what);
        }
    }

    private void checkUnit(Map<?, ?> unit, String where) {
        settle(unit, "unitId", where, unitId(unit), "unitId");
        settle(unit, "analysisContextId", where, contextId(unit), "analysisContextId");
        Object mode = header.get("sourceEmbedding");
        if (unit.containsKey("text") && ("FULL".equals(mode) || "REDACTED".equals(mode))) {
            String domain = "FULL".equals(mode) ? "DECODED_TEXT_SHA256" : "REDACTED_TEXT_SHA256";
            List<Object> declared = new ArrayList<Object>();
            for (Object digest : list(unit.get("digests"))) {
                if (domain.equals(map(digest).get("domain"))) {
                    declared.add(map(digest).get("value"));
                }
            }
            Object text = unit.get("text");
            String actual = text instanceof String ? Framing.hex(IdentityV1.sha256(Framing.utf8((String) text))) : null;
            if (actual == null || !declared.equals(Arrays.<Object>asList(actual))) {
                findings.add(new Finding("ID_SOURCE_DIGEST_MISMATCH", where, "embedded text does not match " + domain));
            }
        }
    }

    @SuppressWarnings("unchecked")
    private void checkEndpoint(Map<?, ?> endpoint, String where) {
        String[] result = endpointResult(endpoint);
        if (result == null) {
            return;
        }
        String status = result[0];
        String id = result[1];
        Map<?, ?> identity;
        if (fill) {
            Map<String, Object> target = (Map<String, Object>) endpoint;
            if (!(target.get("identity") instanceof Map<?, ?>)) {
                target.put("identity", new LinkedHashMap<String, Object>());
            }
            identity = (Map<?, ?>) target.get("identity");
            ((Map<String, Object>) identity).put("status", status);
        } else {
            identity = map(endpoint.get("identity"));
            if (!status.equals(identity.get("status"))) {
                findings.add(new Finding("ID_MISMATCH", where, "declared status " + identity.get("status") + ", computed "
                        + status));
            }
        }
        settle(identity, "id", where, id, "id");
        if (fill) {
            settle(identity, "numericKey", where, id == null ? null : IdentityV1.numericKey(id), "numericKey");
        } else {
            compareNumeric(where, identity.get("numericKey"), id);
        }
    }

    private void checkFact(Map<?, ?> fact, String where) {
        String[] result = factId(fact);
        if ("UNCHECKED".equals(result[0])) {
            notes.add(where + ": an endpoint was not recomputed; the Fact id is not checked");
            return;
        }
        settle(fact, "id", where, result[1], "id");
        if (fill) {
            settle(fact, "numericKey", where, result[1] == null ? null : IdentityV1.numericKey(result[1]), "numericKey");
        } else {
            compareNumeric(where, fact.get("numericKey"), result[1]);
        }
    }

    private void checkOccurrence(Map<?, ?> occurrence, String where) {
        Map<?, ?> statement = get(occurrence.get("statementRef"), "statements");
        Map<?, ?> unit = get(statement.get("sourceUnitRef"), "sourceUnits");
        Map<String, Object> subject = subjectInput(occurrence);
        if (subject == null) {
            notes.add(where + ": an endpoint was not recomputed; the key is not checked");
            return;
        }
        String unitId = unitId(unit);
        String key = IdentityV1.compute(IdentityV1.OCCURRENCE_KEY, inputs(
                "sourceUnit", unitId != null ? unitId : status(IdentityV1.LOCAL),
                "statementOrdinal", statement.get("ordinal"), "subject", subject, "pathScope", scopeOf(unit),
                "path", occurrence.get("path"), "ordinal", occurrence.get("ordinal"))).getId();
        String context = contextId(unit);
        String record = key != null && context != null
                ? IdentityV1.compute(IdentityV1.OCCURRENCE_RECORD, inputs("occurrenceKey", key, "analysisContext", context))
                .getId() : null;
        settle(occurrence, "key", where, key, "key");
        settle(occurrence, "recordId", where, record, "recordId");
    }

    private void checkNode(Map<?, ?> node, String where) {
        Map<?, ?> statement = get(node.get("statementRef"), "statements");
        Map<?, ?> unit = get(statement.get("sourceUnitRef"), "sourceUnits");
        String unitId = unitId(unit);
        String key = IdentityV1.compute(IdentityV1.EXPLAIN_NODE_KEY, inputs(
                "sourceUnit", unitId != null ? unitId : status(IdentityV1.LOCAL),
                "statementOrdinal", statement.get("ordinal"), "pathScope", scopeOf(unit), "path", node.get("path"),
                "nodeKind", node.get("kind"), "ordinal", node.get("ordinal"))).getId();
        String context = contextId(unit);
        String record = key != null && context != null
                ? IdentityV1.compute(IdentityV1.EXPLAIN_NODE_RECORD, inputs("nodeKey", key, "analysisContext", context))
                .getId() : null;
        settle(node, "key", where, key, "key");
        settle(node, "recordId", where, record, "recordId");
    }

    /** A deep copy with mutable objects and arrays, for {@link #fill(Object)}. */
    private static Object mutableCopy(Object value) {
        return CanonicalJson.parse(CanonicalJson.jcsBytes(value));
    }
}