package gudusoft.gsqlparser.slpc.adapter;

import gudusoft.gsqlparser.dlineage.dataflow.model.ResultSetType;
import gudusoft.gsqlparser.dlineage.dataflow.model.xml.column;
import gudusoft.gsqlparser.dlineage.dataflow.model.xml.dataflow;
import gudusoft.gsqlparser.dlineage.dataflow.model.xml.argument;
import gudusoft.gsqlparser.dlineage.dataflow.model.xml.oraclePackage;
import gudusoft.gsqlparser.dlineage.dataflow.model.xml.procedure;
import gudusoft.gsqlparser.dlineage.dataflow.model.xml.relationship;
import gudusoft.gsqlparser.dlineage.dataflow.model.xml.sourceColumn;
import gudusoft.gsqlparser.dlineage.dataflow.model.xml.table;
import gudusoft.gsqlparser.dlineage.dataflow.model.xml.targetColumn;
import gudusoft.gsqlparser.dlineage.dataflow.model.xml.transform;
import gudusoft.gsqlparser.slpc.identity.SlpcIdentity;
import gudusoft.gsqlparser.slpc.model.SlpcDocument;
import gudusoft.gsqlparser.slpc.model.SlpcObject;
import gudusoft.gsqlparser.slpc.validation.SlpcSemanticValidator;

import java.nio.charset.StandardCharsets;
import java.net.URI;
import java.net.URISyntaxException;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.ArrayDeque;
import java.util.ArrayList;
import java.util.Collections;
import java.util.Comparator;
import java.util.HashMap;
import java.util.HashSet;
import java.util.IdentityHashMap;
import java.util.LinkedHashMap;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.TreeMap;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

/**
 * Projects one already-completed legacy {@link dataflow} POJO to SLPC v0.2.
 * This class never receives or parses SQL and never interprets display text as
 * identity.  Semantics absent from the POJO are quarantined or diagnosed.
 */
public final class LegacyDlineageAdapter {

    public static final String ADAPTER_NAME = "LegacyDlineageAdapter";
    public static final String ADAPTER_VERSION = "0.2.0";
    private static final String URI_POLICY = "SLPC-URI-OPAQUE-LOCATOR-V1";
    private static final Pattern SECRET_LOCATOR = Pattern.compile(
            "(?i)(?:password|passwd|secret|token|access[_-]?key|credential)\\s*[:=]");
    private static final Pattern LEGACY_COORDINATE = Pattern.compile(
            "\\[\\s*(-?\\d+)\\s*,\\s*(-?\\d+)\\s*,\\s*(-?\\d+)\\s*\\]\\s*,\\s*"
                    + "\\[\\s*(-?\\d+)\\s*,\\s*(-?\\d+)\\s*,\\s*(-?\\d+)\\s*\\]");

    public LegacyAdaptation adapt(dataflow legacy, LegacyAdapterContext context) {
        if (legacy == null) throw new IllegalArgumentException("completed dlineage result must not be null");
        if (context == null) throw new IllegalArgumentException("adapter context must not be null");

        State state = new State(context);
        state.legacyInputCount = countLegacyRecords(legacy);
        state.artifact = artifact(context);
        state.statement = statement(state.artifact, context, legacy);
        state.statementId = state.statement.string("statementId");
        state.hasSourceLocation = state.statement.get("sourceLocation") != null;
        indexLegacySourceLocations(legacy, state);
        buildEndpoints(legacy, state);
        buildRoutineParameterFlows(state);
        buildObjectRelationships(legacy, state);
        buildStatementOperation(legacy, state);
        buildLineage(legacy, state);
        buildJoinSemantics(legacy, state);
        buildIntermediateGraph(legacy, state);
        materializeFactsAndOccurrences(state, state.factOccurrenceDrafts);
        materializeObjectRelationships(state);
        accountErrors(legacy, state);
        return state.finish();
    }

    private void buildEndpoints(dataflow legacy, State state) {
        List<EndpointDraft> drafts = new ArrayList<EndpointDraft>();
        List<SystemFieldDraft> systemFields = new ArrayList<SystemFieldDraft>();
        for (table relation : dataflow.getAllTables(legacy)) {
            EndpointDraft relationDraft = endpoint(relation, null, state, true, "OBJECT", relation.getId());
            drafts.add(relationDraft);
            state.tableDrafts.put(relation, relationDraft);
            for (column field : relation.getColumns()) {
                if (isRelationRows(field)) {
                    systemFields.add(new SystemFieldDraft(relation, field));
                    continue;
                }
                EndpointDraft fieldDraft = endpoint(relation, field, state, true, "FIELD", field.getId());
                drafts.add(fieldDraft);
                state.columnDrafts.put(field, fieldDraft);
            }
        }
        for (procedure routine : allProcedures(legacy)) {
            table synthetic = routineTable(routine);
            LegacyAdapterContext.RoutineBinding binding = state.context.routineBindingResolver().resolve(routine);
            if (binding != null && !validRoutineBinding(routine, binding, state)) binding = null;
            if (binding != null && hasReturnParameter(binding)) synthetic.setType("function");
            if (binding != null) state.routineBindings.put(routine, binding);
            EndpointDraft routineDraft = endpoint(synthetic, null, state, false, "PROCEDURE", routine.getId(),
                    binding == null ? null : binding.routineIdentity());
            drafts.add(routineDraft); state.routineDrafts.put(routine, routineDraft);
            if (binding != null) {
                Map<String, EndpointDraft> parameters = new LinkedHashMap<String, EndpointDraft>();
                for (LegacyAdapterContext.RoutineParameterBinding parameter : binding.parameters()) {
                    EndpointDraft parameterDraft = parameterEndpoint(routine, parameter, routineDraft, state);
                    drafts.add(parameterDraft); parameters.put(parameter.bindingKey(), parameterDraft);
                    state.parameterBindingByDraft.put(parameterDraft, parameter);
                }
                state.parameterDraftsByRoutine.put(routine, parameters);
            }
        }
        Collections.sort(drafts, new Comparator<EndpointDraft>() {
            @Override public int compare(EndpointDraft left, EndpointDraft right) {
                int rank = left.canonical == null ? 1 : 0;
                int otherRank = right.canonical == null ? 1 : 0;
                if (rank != otherRank) return rank - otherRank;
                int key = utf8Compare(left.sortKey, right.sortKey);
                if (key != 0) return key;
                return left.stableTieBreaker.compareTo(right.stableTieBreaker);
            }
        });
        List<EndpointDraft> uniqueDrafts = new ArrayList<EndpointDraft>();
        Map<String, EndpointDraft> representativeByKey = new LinkedHashMap<String, EndpointDraft>();
        for (EndpointDraft draft : drafts) {
            String key = (draft.canonical == null ? "1\u0000" : "0\u0000") + draft.sortKey;
            EndpointDraft representative = representativeByKey.get(key);
            if (representative == null) { representativeByKey.put(key, draft); uniqueDrafts.add(draft); }
            else if (!representative.sameSemanticIdentity(draft)) throw new IllegalStateException("SLPC endpoint identity collision: " + draft.sortKey);
            draft.representative = representative == null ? draft : representative;
        }
        for (int index = 0; index < uniqueDrafts.size(); index++) {
            EndpointDraft draft = uniqueDrafts.get(index); draft.endpointRef = local("ep-", index + 1);
            SlpcObject endpoint = draft.withRef();
            state.endpoints.add(endpoint);
            state.endpointByRef.put(draft.endpointRef, endpoint);
        }
        for (EndpointDraft draft : drafts) {
            draft.endpointRef = draft.representative.endpointRef;
            LegacyAdapterContext.RoutineParameterBinding parameter = state.parameterBindingByDraft.get(draft);
            if (parameter != null) {
                state.parameterRefByKey.put(parameterKey(draft.routine, parameter.bindingKey()), draft.endpointRef);
                if (parameter.legacyArgumentId() != null) {
                    state.mappedArgumentIds.add(parameter.legacyArgumentId());
                    state.coverage.add(new LegacyCoverageReport.Entry("ARGUMENT", parameter.legacyArgumentId(),
                            draft.canonical == null ? LegacyCoverageReport.Outcome.QUARANTINED
                                    : LegacyCoverageReport.Outcome.EXACT,
                            draft.endpointRef, draft.canonical == null ? "parameter identity unavailable"
                                    : "routine parameter endpoint"));
                }
            } else if (draft.field == null) {
                state.tableRefs.put(draft.relation, draft.endpointRef);
                putLegacyRef(state.endpointByLegacyId, draft.relation.getId(), draft.endpointRef);
                state.coverage.add(new LegacyCoverageReport.Entry(draft.legacyKind, safeId(draft.legacyId, draft.stableTieBreaker),
                        draft.canonical == null ? LegacyCoverageReport.Outcome.QUARANTINED : LegacyCoverageReport.Outcome.EXACT,
                        draft.endpointRef, draft.canonical == null ? "identity unavailable" : "canonical endpoint"));
            } else {
                state.columnRefs.put(draft.field, draft.endpointRef);
                putLegacyRef(state.endpointByLegacyId, draft.field.getId(), draft.endpointRef);
                state.coverage.add(new LegacyCoverageReport.Entry(draft.legacyKind, safeId(draft.legacyId, draft.stableTieBreaker),
                        draft.canonical == null ? LegacyCoverageReport.Outcome.QUARANTINED : LegacyCoverageReport.Outcome.EXACT,
                        draft.endpointRef, draft.canonical == null ? "identity unavailable" : "canonical endpoint"));
            }
        }
        for (Map.Entry<EndpointDraft, LegacyAdapterContext.RoutineParameterBinding> entry
                : state.parameterBindingByDraft.entrySet()) {
            EndpointDraft draft = entry.getKey();
            LegacyAdapterContext.RoutineParameterBinding parameter = entry.getValue();
            if (parameter.legacyArgumentId() != null) {
                state.endpointByLegacyId.put(parameter.legacyArgumentId(), draft.endpointRef);
            }
            if (parameter.boundLegacyEndpointId() != null) {
                String previous = state.endpointByLegacyId.get(parameter.boundLegacyEndpointId());
                if (previous == null) {
                    routineBindingLoss(state, parameter.bindingKey(),
                            "Bound legacy endpoint does not exist in the completed POJO: "
                                    + parameter.boundLegacyEndpointId());
                } else {
                    state.endpointByLegacyId.put(parameter.boundLegacyEndpointId(), draft.endpointRef);
                }
            }
        }
        for (SystemFieldDraft systemField : systemFields) {
            String holderRef = state.tableRefs.get(systemField.relation);
            putLegacyRef(state.endpointByLegacyId, systemField.field.getId(), holderRef);
            state.coverage.add(new LegacyCoverageReport.Entry("FIELD", safeId(systemField.field.getId(), "RelationRows"),
                    LegacyCoverageReport.Outcome.CONDITIONAL, holderRef,
                    "SLPC_PSEUDO_COLUMN_REJECTED: normalized to the holder relation"));
            state.differences.add(new IntentionalDiffLedger.Entry(
                    IntentionalDiffLedger.Category.EXPECTED_SEMANTIC_CORRECTION,
                    safeId(systemField.field.getId(), "RelationRows"), "SLPC_PSEUDO_COLUMN_REJECTED",
                    "Legacy RelationRows is normalized to its holder relation and is not published as a field endpoint."));
        }
        if (!systemFields.isEmpty()) {
            state.diagnostics.add(diagnostic("SLPC_PSEUDO_COLUMN_REJECTED", "INFO", "DOCUMENT", null,
                    "Legacy RelationRows system columns were normalized to holder relations instead of field endpoints."));
        }
        if (hasUnavailableIdentity(drafts)) {
            state.diagnostics.add(diagnostic("SLPC_IDENTITY_UNAVAILABLE", "INFO", "DOCUMENT", null,
                    "Legacy display names are not treated as persistent identity; unresolved endpoints remain candidates."));
        }
        if (state.hasLegacyEndpointAmbiguity) {
            state.diagnostics.add(diagnostic("SLPC_ENDPOINT_AMBIGUOUS", "WARN", "DOCUMENT", null,
                    "At least one unresolved legacy relation carries multiple candidate tables; no candidate name was promoted to identity."));
        }
        if (state.hasStorageIdentityUnavailable) {
            state.diagnostics.add(diagnostic("SLPC_STORAGE_IDENTITY_UNAVAILABLE", "WARN", "DOCUMENT", null,
                    "At least one storage locator was absent, malformed, credential-bearing, or contained query/fragment data; it was redacted and quarantined."));
        }
        accountNonEndpointObjects(legacy, state);
    }

    private EndpointDraft endpoint(table relation, column field, State state, boolean allowIdentity,
            String legacyKind, String legacyId) {
        return endpoint(relation, field, state, allowIdentity, legacyKind, legacyId, null);
    }

    private EndpointDraft endpoint(table relation, column field, State state, boolean allowIdentity,
            String legacyKind, String legacyId, LegacyAdapterContext.ResolvedIdentity resolvedOverride) {
        String objectKind = "PROCEDURE".equals(legacyKind) ? routineObjectKind(relation) : objectKind(relation, state);
        String level = field == null ? endpointLevel(relation, legacyKind) : "FIELD";
        String storageLocator = field == null && "FILE".equals(objectKind) ? normalizedStorageLocator(relation) : null;
        List<Object> display = storageLocator == null ? displaySegments(relation, field)
                : Collections.<Object>singletonList(display("OBJECT", storageLocator));
        if (field == null && "FILE".equals(objectKind) && storageLocator == null) {
            state.hasStorageIdentityUnavailable = true;
            display = Collections.<Object>singletonList(display("OBJECT", "<redacted-storage-locator>"));
        }
        boolean intermediate = !"PROCEDURE".equals(legacyKind) && isIntermediate(relation);
        LegacyAdapterContext.ResolvedIdentity resolved = resolvedOverride != null ? resolvedOverride
                : intermediate || !allowIdentity || storageLocator != null || isScopedObjectKind(objectKind) ? null
                : state.context.identityResolver().resolve(relation, field);
        SlpcObject identity;
        String resolution, publication, canonical = null;
        List<Object> extensions = Collections.emptyList();
        if (storageLocator != null) {
            String scheme = storageScheme(storageLocator);
            identity = SlpcObject.builder().put("kind", "URI_EXACT").put("strength", "EXACT")
                    .put("normalizationPolicyId", URI_POLICY).put("scheme", scheme)
                    .put("locatorDigest", uriLocatorDigest(URI_POLICY, scheme, storageLocator)).build();
            resolution = "RESOLVED"; publication = "ELIGIBLE";
            extensions = Collections.<Object>singletonList(SlpcObject.builder()
                    .put("extensionType", "gsp.storage-asset.v1").put("schemaVersion", "1.0.0")
                    .put("criticality", "OPTIONAL").put("payload", SlpcObject.builder()
                            .put("secretFreeNormalizedLocator", storageLocator).build()).build());
        } else if (resolved == null) {
            boolean ambiguous = hasCandidateTables(relation);
            if (ambiguous) state.hasLegacyEndpointAmbiguity = true;
            String reason = intermediate ? "UNBOUND_RESULT_SET" : ambiguous ? "AMBIGUOUS"
                    : isScopedObjectKind(objectKind) ? "SCOPE_UNAVAILABLE" : "OTHER";
            identity = SlpcObject.builder().put("kind", "UNAVAILABLE").put("strength", "UNAVAILABLE").put("reason", reason).build();
            resolution = ambiguous ? "AMBIGUOUS" : "UNRESOLVED"; publication = "INELIGIBLE";
        } else {
            identity = resolved.identity(); resolution = resolved.resolutionStatus(); publication = resolved.publicationState();
        }
        SlpcObject provisional = SlpcObject.builder().put("endpointRef", "ep-000001").putNull("canonicalEndpointId")
                .put("endpointLevel", level).put("objectKind", objectKind).put("displaySegments", display)
                .put("identity", identity).put("resolutionStatus", resolution).put("publicationState", publication)
                .putNull("scope").put("extensions", extensions).build();
        if ((resolved != null || storageLocator != null) && isCanonicalIdentity(identity)) {
            canonical = SlpcIdentity.endpointId(provisional);
            provisional = provisional.toBuilder().put("canonicalEndpointId", canonical).build();
        }
        String sortKey = canonical == null ? SlpcIdentity.candidateEndpointKey(provisional) : canonical;
        String tie = safe(relation.getId()) + "\u0000" + safe(field == null ? null : field.getId()) + "\u0000"
                + safe(relation.getName()) + "\u0000" + safe(field == null ? null : field.getName());
        return new EndpointDraft(relation, field, provisional, canonical, sortKey, tie, legacyKind, legacyId);
    }

    private String normalizedStorageLocator(table relation) {
        String raw = nonEmpty(relation.getUri());
        if (raw == null) raw = nonEmpty(relation.getLocation());
        if (raw == null) raw = nonEmpty(relation.getName());
        if (raw == null) return null;
        raw = raw.trim();
        if (raw.length() >= 2 && ((raw.charAt(0) == '\'' && raw.charAt(raw.length() - 1) == '\'')
                || (raw.charAt(0) == '"' && raw.charAt(raw.length() - 1) == '"'))) {
            raw = raw.substring(1, raw.length() - 1);
        }
        if (SECRET_LOCATOR.matcher(raw).find()) return null;
        try {
            URI uri = new URI(raw).normalize();
            if (uri.getScheme() == null || uri.getScheme().isEmpty() || uri.getUserInfo() != null
                    || uri.getQuery() != null || uri.getFragment() != null) return null;
            String scheme = uri.getScheme().toLowerCase(java.util.Locale.ROOT);
            String ascii = uri.toASCIIString();
            return scheme + ascii.substring(uri.getScheme().length());
        } catch (URISyntaxException invalid) {
            return null;
        }
    }

    private String storageScheme(String locator) {
        int separator = locator.indexOf(':');
        if (separator <= 0) throw new IllegalArgumentException("normalized storage locator has no scheme");
        return locator.substring(0, separator);
    }

    private String uriLocatorDigest(String policy, String scheme, String locator) {
        try {
            MessageDigest digest = MessageDigest.getInstance("SHA-256");
            digest.update("SLPC-URI-LOCATOR-DIGEST-V1".getBytes(StandardCharsets.US_ASCII));
            digest.update((byte) 0); digest.update(SlpcIdentity.string(policy));
            digest.update(SlpcIdentity.string(scheme)); digest.update(SlpcIdentity.string(locator));
            StringBuilder result = new StringBuilder();
            for (byte item : digest.digest()) result.append(String.format("%02x", item & 255));
            return result.toString();
        } catch (NoSuchAlgorithmException impossible) { throw new IllegalStateException(impossible); }
    }

    private List<procedure> allProcedures(dataflow legacy) {
        List<procedure> result = new ArrayList<procedure>(legacy.getProcedures());
        for (oraclePackage pkg : legacy.getPackages()) result.addAll(pkg.getProcedures());
        return result;
    }

    private table routineTable(procedure routine) {
        table result = new table(); result.setId(routine.getId()); result.setName(safe(routine.getName()));
        result.setServer(routine.getServer()); result.setDatabase(routine.getDatabase()); result.setSchema(routine.getSchema());
        result.setType("function".equalsIgnoreCase(routine.getType()) ? "function" : "procedure");
        return result;
    }

    private boolean validRoutineBinding(procedure routine, LegacyAdapterContext.RoutineBinding binding, State state) {
        Set<String> argumentIds = new HashSet<String>();
        for (argument item : routine.getArguments()) if (item.getId() != null) argumentIds.add(item.getId());
        Set<String> usedArguments = new HashSet<String>(), keys = new HashSet<String>();
        Set<Integer> ordinals = new HashSet<Integer>();
        boolean valid = true;
        for (LegacyAdapterContext.RoutineParameterBinding parameter : binding.parameters()) {
            if (!keys.add(parameter.bindingKey()) || !ordinals.add(parameter.ordinal())
                    || !equalsAny(parameter.role(), "IN", "OUT", "INOUT", "RETURN", "TABLE_RETURN_FIELD")) {
                valid = false; break;
            }
            if (parameter.legacyArgumentId() == null) {
                if (!equalsAny(parameter.role(), "RETURN", "TABLE_RETURN_FIELD")) { valid = false; break; }
            } else if (!argumentIds.contains(parameter.legacyArgumentId())
                    || !usedArguments.add(parameter.legacyArgumentId())) {
                valid = false; break;
            }
        }
        if (!valid) routineBindingLoss(state, safeId(routine.getId(), safe(routine.getName())),
                "Routine binding contains an unknown/duplicate argument, ordinal, binding key, or parameter role.");
        return valid;
    }

    private boolean hasReturnParameter(LegacyAdapterContext.RoutineBinding binding) {
        for (LegacyAdapterContext.RoutineParameterBinding parameter : binding.parameters()) {
            if (equalsAny(parameter.role(), "RETURN", "TABLE_RETURN_FIELD")) return true;
        }
        return false;
    }

    private EndpointDraft parameterEndpoint(procedure routine,
            LegacyAdapterContext.RoutineParameterBinding parameter, EndpointDraft routineDraft, State state) {
        table synthetic = routineTable(routine);
        column field = new column(); field.setId(parameter.legacyArgumentId() == null
                ? "return:" + parameter.bindingKey() : parameter.legacyArgumentId());
        field.setName(parameter.displayName());
        LegacyAdapterContext.ResolvedIdentity resolved = parameter.identity();
        SlpcObject identity = resolved.identity(); String canonical = null;
        String resolution = resolved.resolutionStatus(), publication = resolved.publicationState();
        SlpcObject scope = null;
        if (routineDraft.canonical != null) {
            scope = SlpcObject.builder().put("scopeKind", "PROCEDURE").put("scopeId", routineDraft.canonical)
                    .put("definedAtStatementId", state.statementId).build();
        } else {
            identity = SlpcObject.builder().put("kind", "UNAVAILABLE").put("strength", "UNAVAILABLE")
                    .put("reason", "SCOPE_UNAVAILABLE").build();
            resolution = "UNRESOLVED"; publication = "INELIGIBLE";
        }
        SlpcObject.Builder payload = SlpcObject.builder().put("parameterRole", parameter.role())
                .put("parameterOrdinal", parameter.ordinal()).put("routineBindingKey", parameter.bindingKey());
        if (parameter.declaredType() != null) payload.put("declaredType", parameter.declaredType());
        List<Object> extensions = Collections.<Object>singletonList(SlpcObject.builder()
                .put("extensionType", "gsp.routine-parameter.v1").put("schemaVersion", "1.0.0")
                .put("criticality", "OPTIONAL").put("payload", payload.build()).build());
        SlpcObject provisional = SlpcObject.builder().put("endpointRef", "ep-000001").putNull("canonicalEndpointId")
                .put("endpointLevel", "VARIABLE").put("objectKind", "PARAMETER")
                .put("displaySegments", displaySegments(synthetic, field)).put("identity", identity)
                .put("resolutionStatus", resolution).put("publicationState", publication)
                .put("scope", scope).put("extensions", extensions).build();
        if (routineDraft.canonical != null && isCanonicalIdentity(identity)) {
            canonical = SlpcIdentity.endpointId(provisional);
            provisional = provisional.toBuilder().put("canonicalEndpointId", canonical).build();
        }
        String sortKey = canonical == null ? SlpcIdentity.candidateEndpointKey(provisional) : canonical;
        String tie = safe(routine.getId()) + "\u0000parameter\u0000" + parameter.ordinal()
                + "\u0000" + parameter.bindingKey();
        EndpointDraft result = new EndpointDraft(synthetic, field, provisional, canonical, sortKey, tie,
                parameter.legacyArgumentId() == null ? "RETURN_PARAMETER" : "ARGUMENT",
                parameter.legacyArgumentId() == null ? parameter.bindingKey() : parameter.legacyArgumentId());
        result.routine = routine;
        return result;
    }

    private String parameterKey(procedure routine, String bindingKey) {
        return safeId(routine.getId(), safe(routine.getName())) + "\u0000" + bindingKey;
    }

    private void routineBindingLoss(State state, String owner, String message) {
        state.diagnostics.add(diagnostic("SLPC_ROUTINE_BINDING_UNPROVEN", "WARN", "DOCUMENT", null, message));
        state.differences.add(new IntentionalDiffLedger.Entry(IntentionalDiffLedger.Category.KNOWN_UNSUPPORTED_WITH_LOSS,
                owner, "GSP_LEGACY_ROUTINE_ARGUMENT_BINDING_UNAVAILABLE", message));
    }

    private void accountNonEndpointObjects(dataflow legacy, State state) {
        for (oraclePackage pkg : legacy.getPackages()) {
            String owner = safeId(pkg.getId(), safe(pkg.getName()));
            state.coverage.add(new LegacyCoverageReport.Entry("PACKAGE", owner,
                    LegacyCoverageReport.Outcome.UNSUPPORTED_WITH_LOSS, null, "GSP_LEGACY_PACKAGE_ENDPOINT_UNSUPPORTED"));
            state.differences.add(new IntentionalDiffLedger.Entry(IntentionalDiffLedger.Category.KNOWN_UNSUPPORTED_WITH_LOSS,
                    owner, "GSP_LEGACY_PACKAGE_ENDPOINT_UNSUPPORTED", "SLPC v0.2 has no package endpoint kind; contained routines remain visible."));
            for (argument item : pkg.getArguments()) accountArgument(item, state);
            for (procedure routine : pkg.getProcedures()) for (argument item : routine.getArguments()) accountArgument(item, state);
        }
        for (procedure routine : legacy.getProcedures()) for (argument item : routine.getArguments()) accountArgument(item, state);
        for (gudusoft.gsqlparser.dlineage.dataflow.model.xml.process process : legacy.getProcesses()) {
            String owner = safeId(process.getId(), "process");
            state.coverage.add(new LegacyCoverageReport.Entry("PROCESS", owner,
                    LegacyCoverageReport.Outcome.CONDITIONAL, state.statementId,
                    "Legacy process is represented by artifact/statement provenance, not a catalog endpoint."));
            state.differences.add(new IntentionalDiffLedger.Entry(IntentionalDiffLedger.Category.EXPECTED_PRESENTATION_DIFFERENCE,
                    owner, "GSP_LEGACY_PROCESS_AS_PROVENANCE", "Legacy process presentation maps to SLPC artifact/statement provenance."));
        }
    }

    private void accountArgument(argument item, State state) {
        if (item.getId() != null && state.mappedArgumentIds.contains(item.getId())) return;
        String owner = safeId(item.getId(), "argument");
        state.diagnostics.add(diagnostic("SLPC_ROUTINE_BINDING_UNPROVEN", "WARN", "DOCUMENT", null,
                "A routine argument was retained only in loss accounting because no authoritative overload/formal binding was supplied."));
        state.coverage.add(new LegacyCoverageReport.Entry("ARGUMENT", owner,
                LegacyCoverageReport.Outcome.UNSUPPORTED_WITH_LOSS, null, "GSP_LEGACY_ROUTINE_ARGUMENT_BINDING_UNAVAILABLE"));
        state.differences.add(new IntentionalDiffLedger.Entry(IntentionalDiffLedger.Category.KNOWN_UNSUPPORTED_WITH_LOSS,
                owner, "GSP_LEGACY_ROUTINE_ARGUMENT_BINDING_UNAVAILABLE", "An argument needs a proven routine/parameter binding before it can become an endpoint or fact."));
    }

    private void buildRoutineParameterFlows(State state) {
        for (Map.Entry<procedure, LegacyAdapterContext.RoutineBinding> entry : state.routineBindings.entrySet()) {
            procedure routine = entry.getKey(); LegacyAdapterContext.RoutineBinding binding = entry.getValue();
            String routineRef = endpointAtLevel(state.endpointByLegacyId.get(routine.getId()), "ROUTINE", state);
            if (routineRef == null || !canonicalEndpoint(routineRef, state)) {
                routineBindingLoss(state, safeId(routine.getId(), safe(routine.getName())),
                        "Routine parameters require a canonical overload-aware routine identity.");
                continue;
            }
            state.hasRoutineBinding = true;
            for (LegacyAdapterContext.RoutineValueFlow flow : binding.flows()) {
                if (!equalsAny(flow.role(), "DIRECT", "TRANSFORM", "CONDITION", "AGGREGATE", "DERIVED")
                        || !equalsAny(flow.operationKind(), "NONE", "GROUP_BY", "WINDOW", "SORT")
                        || !equalsAny(flow.operationInputKind(), "NONE", "GROUP_KEY", "PARTITION_KEY",
                                "ORDER_KEY", "FRAME_BOUND")) {
                    routineBindingLoss(state, safeId(routine.getId(), safe(routine.getName())),
                            "Routine flow returned an axis/role/operation code outside the SLPC v0.2 registry.");
                    continue;
                }
                String sourceRef = routineValueRef(routine, flow.source(), state);
                String targetRef = routineValueRef(routine, flow.target(), state);
                if (sourceRef == null || targetRef == null || sourceRef.equals(targetRef)) {
                    routineBindingLoss(state, safeId(routine.getId(), safe(routine.getName())),
                            "Routine flow did not bind two distinct completed-POJO/parameter endpoints.");
                    continue;
                }
                FactSemantics semantics = FactSemantics.publish("VALUE", flow.role(), flow.operationKind(),
                        flow.operationInputKind(), false);
                SlpcObject semantic = semanticRecord(sourceRef, targetRef, semantics, state);
                if (state.parameterRefByKey.containsValue(sourceRef)
                        || state.parameterRefByKey.containsValue(targetRef)) state.hasRoutineParameterFlow = true;
                boolean canonical = isCanonicalFact(semantic, state.endpointByRef);
                String key = canonical ? SlpcIdentity.factId(semantic, state.endpointByRef)
                        : SlpcIdentity.factCandidateFingerprint(semantic, state.endpointByRef);
                FactGroup group = state.factGroups.get(key);
                if (group == null) {
                    group = new FactGroup(semantic, canonical, key); state.factGroups.put(key, group);
                } else if (!group.sameSemantic(semantic)) {
                    throw new IllegalStateException("SLPC routine fact fingerprint collision: " + key);
                }
                FactOccurrenceDraft occurrence = new FactOccurrenceDraft(group, null, null,
                        canonical ? "RESOLVED" : "UNRESOLVED", Collections.<Object>emptyList(),
                        Collections.<Object>emptyList(), sourceLocations(routine.getCoordinate(), state), routineRef);
                group.occurrences.add(occurrence); state.factOccurrenceDrafts.add(occurrence);
                state.hasRoutineParameterFlow = true;
            }
        }
    }

    private String routineValueRef(procedure routine, LegacyAdapterContext.RoutineValueRef value, State state) {
        String ref = value.parameterBindingKey() == null
                ? state.endpointByLegacyId.get(value.legacyEndpointId())
                : state.parameterRefByKey.get(parameterKey(routine, value.parameterBindingKey()));
        SlpcObject endpoint = ref == null ? null : state.endpointByRef.get(ref);
        if (endpoint == null || !("FIELD".equals(endpoint.string("endpointLevel"))
                || "VARIABLE".equals(endpoint.string("endpointLevel")))) return null;
        return ref;
    }

    private void buildObjectRelationships(dataflow legacy, State state) {
        for (table relation : dataflow.getAllTables(legacy)) {
            String relationRef = state.tableRefs.get(relation);
            if (relationRef == null || isIntermediate(relation)) continue;
            List<String> primary = new ArrayList<String>();
            for (column field : relation.getColumns()) {
                String fieldRef = state.columnRefs.get(field);
                if (fieldRef == null) continue;
                if (Boolean.TRUE.equals(field.isPrimaryKey())) primary.add(fieldRef);
                if (Boolean.TRUE.equals(field.isUnqiueKey())) {
                    addKeyRelationship("UNIQUE_KEY", relationRef,
                            Collections.singletonList(fieldRef), "column:" + safeId(field.getId(), field.getName()), state);
                }
            }
            if (!primary.isEmpty()) addKeyRelationship("PRIMARY_KEY", relationRef, primary,
                    "table:" + safeId(relation.getId(), relation.getName()), state);
        }

        for (relationship relation : legacy.getRelationships()) {
            String type = safe(relation.getType());
            if ("call".equals(type)) {
                mapCallRelationship(relation, state);
            } else if ("fdd".equals(type)) {
                mapNonFactObjectRelationship(relation, state);
            }
        }
        mapForeignKeyRelationships(legacy, state);
    }

    private void addKeyRelationship(String kind, String relationRef, List<String> fields,
            String legacyEvidence, State state) {
        sortEndpointRefs(fields, state);
        List<Object> participants = Collections.<Object>singletonList(
                SlpcObject.builder().put("role", "KEY_RELATION").put("endpointRef", relationRef).build());
        List<Object> keyFields = new ArrayList<Object>();
        for (int index = 0; index < fields.size(); index++) {
            keyFields.add(SlpcObject.builder().put("ordinal", index + 1)
                    .put("fieldEndpointRef", fields.get(index)).build());
        }
        addObjectRelationship(kind, participants, keyFields, null, legacyEvidence, state);
    }

    private void mapForeignKeyRelationships(dataflow legacy, State state) {
        Map<String, relationship> byId = new HashMap<String, relationship>();
        List<relationship> foreignKeys = new ArrayList<relationship>();
        for (relationship relation : legacy.getRelationships()) {
            if (!("er".equals(relation.getType())
                    || "fdd".equals(relation.getType()) && "foreign_key".equals(relation.getEffectType()))) continue;
            foreignKeys.add(relation); byId.put(legacyId(relation), relation);
        }
        for (LegacyAdapterContext.ForeignKeyBinding binding
                : state.context.compositeForeignKeyResolver().resolve(legacy)) {
            if (!mapAuthoritativeForeignKey(binding, byId, state)) {
                for (String evidenceId : binding.evidenceRelationshipIds()) {
                    relationship relation = byId.get(evidenceId);
                    if (relation != null) accountDedicatedLoss(relation, state, "SLPC_COMPOSITE_FK_PAIRING_UNPROVEN",
                            "Caller-supplied composite FK pairing failed validation against the completed POJO.");
                }
            }
        }
        Map<String, List<relationship>> unresolvedFamilies = new LinkedHashMap<String, List<relationship>>();
        for (relationship relation : foreignKeys) {
            if (state.dedicatedRelationshipAccounting.contains(legacyId(relation))) continue;
            String family = foreignKeyFamily(relation, state);
            if (!unresolvedFamilies.containsKey(family)) unresolvedFamilies.put(family, new ArrayList<relationship>());
            unresolvedFamilies.get(family).add(relation);
        }
        for (List<relationship> family : unresolvedFamilies.values()) {
            Set<String> foreignFields = new HashSet<String>(), referencedFields = new HashSet<String>();
            for (relationship relation : family) {
                String target = relation.getTarget() == null ? null : resolveTargetField(relation.getTarget(), state);
                if (target != null) foreignFields.add(target);
                for (sourceColumn source : relation.getSources()) {
                    String ref = resolveSourceField(source, state); if (ref != null) referencedFields.add(ref);
                }
            }
            if (foreignFields.size() == 1 && referencedFields.size() == 1) {
                for (relationship relation : family) mapSingleColumnForeignKey(relation, state);
            } else {
                for (relationship relation : family) accountDedicatedLoss(relation, state,
                        "SLPC_COMPOSITE_FK_PAIRING_UNPROVEN",
                        "Legacy FK/ER output does not retain declaration-order composite key pairs; authoritative AST/catalog pairing is required.");
            }
        }
    }

    private String foreignKeyFamily(relationship relation, State state) {
        String foreign = relationEndpoint(relation.getTarget(), state), referenced = null;
        for (sourceColumn source : relation.getSources()) {
            String candidate = relationEndpoint(source, state);
            if (referenced == null) referenced = candidate;
            else if (!equalValues(referenced, candidate)) return "invalid:" + legacyId(relation);
        }
        return "fk:" + safe(foreign) + "\u0000" + safe(referenced);
    }

    private boolean mapAuthoritativeForeignKey(LegacyAdapterContext.ForeignKeyBinding binding,
            Map<String, relationship> byId, State state) {
        Set<String> evidenceIds = new LinkedHashSet<String>(binding.evidenceRelationshipIds());
        if (evidenceIds.size() != binding.evidenceRelationshipIds().size()) return false;
        List<relationship> evidence = new ArrayList<relationship>();
        for (String id : evidenceIds) {
            relationship relation = byId.get(id); if (relation == null) return false; evidence.add(relation);
        }
        String foreignRelation = null, referencedRelation = null;
        Set<String> foreignFields = new HashSet<String>(), referencedFields = new HashSet<String>();
        List<Object> pairs = new ArrayList<Object>();
        int ordinal = 1;
        for (LegacyAdapterContext.ForeignKeyPair pair : binding.keyPairs()) {
            String foreignField = endpointAtLevel(state.endpointByLegacyId.get(pair.foreignKeyFieldLegacyId()), "FIELD", state);
            String referencedField = endpointAtLevel(state.endpointByLegacyId.get(pair.referencedFieldLegacyId()), "FIELD", state);
            if (foreignField == null || referencedField == null
                    || !foreignFields.add(foreignField) || !referencedFields.add(referencedField)) return false;
            String pairForeignRelation = null, pairReferencedRelation = null;
            for (relationship relation : evidence) {
                if (matches(relation.getTarget(), pair.foreignKeyFieldLegacyId())) {
                    pairForeignRelation = relationEndpoint(relation.getTarget(), state);
                    for (sourceColumn source : relation.getSources()) {
                        if (matches(source, pair.referencedFieldLegacyId())) {
                            pairReferencedRelation = relationEndpoint(source, state); break;
                        }
                    }
                }
                if (pairForeignRelation != null && pairReferencedRelation != null) break;
            }
            if (pairForeignRelation == null || pairReferencedRelation == null) return false;
            if (foreignRelation == null) foreignRelation = pairForeignRelation;
            if (referencedRelation == null) referencedRelation = pairReferencedRelation;
            if (!foreignRelation.equals(pairForeignRelation) || !referencedRelation.equals(pairReferencedRelation)) return false;
            pairs.add(SlpcObject.builder().put("ordinal", ordinal++)
                    .put("foreignKeyFieldRef", foreignField).put("referencedFieldRef", referencedField).build());
        }
        if (foreignRelation == null || referencedRelation == null) return false;
        List<Object> participants = new ArrayList<Object>();
        participants.add(participant("FOREIGN_KEY_RELATION", foreignRelation));
        participants.add(participant("REFERENCED_RELATION", referencedRelation));
        for (relationship relation : evidence) {
            addObjectRelationship("FOREIGN_KEY_REFERENCE", participants, null, pairs, legacyId(relation), state);
            markForeignKeyMapped(relation, state);
        }
        state.diagnostics.add(diagnostic("SLPC_COMPOSITE_FK_PAIRING_PROVEN", "INFO", "DOCUMENT", null,
                "Composite foreign-key keyPairs preserve caller-authoritative declaration order."));
        return true;
    }

    private boolean matches(targetColumn value, String legacyFieldId) {
        return value != null && (legacyFieldId.equals(value.getId()) || legacyFieldId.equals(value.getTarget_id()));
    }

    private boolean matches(sourceColumn value, String legacyFieldId) {
        return value != null && (legacyFieldId.equals(value.getId()) || legacyFieldId.equals(value.getSource_id()));
    }

    private void mapSingleColumnForeignKey(relationship relation, State state) {
        targetColumn target = relation.getTarget();
        if (target == null || relation.getSources().isEmpty()) {
            accountDedicatedLoss(relation, state, "SLPC_OBJECT_RELATIONSHIP_UNPUBLISHABLE",
                    "Legacy FK/ER record has no target/source key pair.");
            return;
        }
        String foreignRelation = relationEndpoint(target, state);
        String foreignField = resolveTargetField(target, state);
        sourceColumn source = relation.getSources().get(0);
        String referencedRelation = relationEndpoint(source, state);
        String referencedField = resolveSourceField(source, state);
        boolean mapped = foreignRelation != null && foreignField != null
                && referencedRelation != null && referencedField != null;
        if (mapped) {
            List<Object> participants = new ArrayList<Object>();
            participants.add(participant("FOREIGN_KEY_RELATION", foreignRelation));
            participants.add(participant("REFERENCED_RELATION", referencedRelation));
            List<Object> pairs = Collections.<Object>singletonList(SlpcObject.builder().put("ordinal", 1)
                    .put("foreignKeyFieldRef", foreignField).put("referencedFieldRef", referencedField).build());
            addObjectRelationship("FOREIGN_KEY_REFERENCE", participants, null, pairs, legacyId(relation), state);
        }
        if (mapped) {
            markForeignKeyMapped(relation, state);
        } else {
            accountDedicatedLoss(relation, state, "SLPC_OBJECT_RELATIONSHIP_UNPUBLISHABLE",
                    "Legacy FK/ER participants could not be bound at relation and field levels.");
        }
    }

    private void markForeignKeyMapped(relationship relation, State state) {
        markDedicatedMapped(relation, state, "FOREIGN_KEY_REFERENCE");
        state.diagnostics.add(diagnostic("SLPC_LEGACY_FK_DATAFLOW_RECLASSIFIED", "INFO", "DOCUMENT", null,
                "Legacy FK/ER dataflow was reclassified as a structural FOREIGN_KEY_REFERENCE."));
        state.differences.add(new IntentionalDiffLedger.Entry(IntentionalDiffLedger.Category.EXPECTED_SEMANTIC_CORRECTION,
                legacyId(relation), "SLPC_LEGACY_FK_DATAFLOW_RECLASSIFIED",
                "A catalog foreign key is structural metadata and is not a runtime VALUE dependency."));
    }

    private void mapCallRelationship(relationship relation, State state) {
        String caller = routineEndpoint(relation.getCaller(), relation.getProcedureId(), state);
        boolean mapped = false;
        boolean hasCallee = false;
        for (sourceColumn calleeValue : relation.getCallees()) {
            String callee = routineEndpoint(calleeValue, state);
            if (callee != null) hasCallee = true;
            if (caller == null || callee == null) continue;
            List<Object> participants = new ArrayList<Object>();
            participants.add(SlpcObject.builder().put("role", "CALLER_ROUTINE").put("endpointRef", caller).build());
            participants.add(SlpcObject.builder().put("role", "CALLEE_ROUTINE").put("endpointRef", callee).build());
            addObjectRelationship("CALLS", participants, null, null, legacyId(relation), state);
            mapped = true;
        }
        if (mapped) markDedicatedMapped(relation, state, "CALLS");
        else if (caller == null && hasCallee) {
            // A top-level CALL has no caller routine by definition. It is
            // accounted by the CALL_ROUTINE statement operation builder.
        }
        else accountDedicatedLoss(relation, state, "SLPC_OBJECT_RELATIONSHIP_UNPUBLISHABLE",
                "A CALLS relationship requires both a proven caller routine and a cataloged callee routine; top-level calls remain statement operations.");
    }

    private void mapNonFactObjectRelationship(relationship relation, State state) {
        targetColumn target = relation.getTarget();
        if (target == null) return;
        String targetRelation = relationEndpoint(target, state);
        for (sourceColumn source : relation.getSources()) {
            String sourceRelation = relationEndpoint(source, state);
            if (targetRelation == null || sourceRelation == null) continue;
            String targetKind = endpointKind(targetRelation, state);
            String sourceKind = endpointKind(sourceRelation, state);
            List<Object> participants = new ArrayList<Object>();
            String relationshipKind = null;
            if ("STREAM".equals(targetKind) && !isStorageKind(sourceKind)) {
                relationshipKind = "STREAMS_FROM";
                participants.add(participant("STREAM", targetRelation));
                participants.add(participant("BASE_RELATION", sourceRelation));
            } else if (isStorageKind(sourceKind) && !isStorageKind(targetKind)) {
                relationshipKind = "READS_FROM";
                participants.add(participant("CONSUMER_RELATION", targetRelation));
                participants.add(participant("STORAGE_ASSET", sourceRelation));
            } else if (!isStorageKind(sourceKind) && isStorageKind(targetKind)) {
                relationshipKind = "WRITES_TO";
                participants.add(participant("PRODUCER_RELATION", sourceRelation));
                participants.add(participant("STORAGE_ASSET", targetRelation));
            } else if (equalsAny(relation.getEffectType(), "synonym", "create_synonym")) {
                relationshipKind = "SYNONYM_OF";
                participants.add(participant("SYNONYM", targetRelation));
                participants.add(participant("BASE_OBJECT", sourceRelation));
            }
            if (relationshipKind != null) addObjectRelationship(relationshipKind, participants, null, null,
                    legacyId(relation), state);
        }
    }

    private SlpcObject participant(String role, String endpointRef) {
        return SlpcObject.builder().put("role", role).put("endpointRef", endpointRef).build();
    }

    private boolean isStorageKind(String kind) { return "FILE".equals(kind) || "STAGE".equals(kind); }

    private boolean isScopedObjectKind(String kind) {
        return equalsAny(kind, "TEMP_TABLE", "GLOBAL_TEMP_TABLE", "TABLE_VARIABLE", "SCALAR_VARIABLE", "CURSOR", "PARAMETER");
    }

    private String endpointKind(String ref, State state) {
        SlpcObject endpoint = ref == null ? null : state.endpointByRef.get(ref);
        return endpoint == null ? null : endpoint.string("objectKind");
    }

    private String routineEndpoint(targetColumn value, String fallbackId, State state) {
        if (value == null) return endpointAtLevel(state.endpointByLegacyId.get(fallbackId), "ROUTINE", state);
        String result = endpointAtLevel(state.endpointByLegacyId.get(value.getId()), "ROUTINE", state);
        if (result == null) result = endpointAtLevel(state.endpointByLegacyId.get(value.getTarget_id()), "ROUTINE", state);
        if (result == null) result = endpointAtLevel(state.endpointByLegacyId.get(value.getParent_id()), "ROUTINE", state);
        if (result == null) result = endpointAtLevel(state.endpointByLegacyId.get(fallbackId), "ROUTINE", state);
        return result;
    }

    private String routineEndpoint(sourceColumn value, State state) {
        String result = endpointAtLevel(state.endpointByLegacyId.get(value.getId()), "ROUTINE", state);
        if (result == null) result = endpointAtLevel(state.endpointByLegacyId.get(value.getSource_id()), "ROUTINE", state);
        if (result == null) result = endpointAtLevel(state.endpointByLegacyId.get(value.getParent_id()), "ROUTINE", state);
        return result;
    }

    private String routineEndpoint(String legacyProcedureId, State state) {
        return endpointAtLevel(state.endpointByLegacyId.get(legacyProcedureId), "ROUTINE", state);
    }

    private void addObjectRelationship(String kind, List<Object> participants, List<Object> keyFields,
            List<Object> keyPairs, String legacyEvidence, State state) {
        SlpcObject.Builder semanticBuilder = SlpcObject.builder().put("relationshipKind", kind)
                .put("participants", participants);
        if (keyFields != null) semanticBuilder.put("keyFields", keyFields);
        if (keyPairs != null) semanticBuilder.put("keyPairs", keyPairs);
        SlpcObject semantic = semanticBuilder.build();
        boolean canonical = relationshipCanonical(semantic, state);
        String fingerprint = canonical ? SlpcIdentity.objectRelationshipId(semantic, state.endpointByRef)
                : SlpcIdentity.objectRelationshipCandidateFingerprint(semantic, state.endpointByRef);
        RelationshipGroup group = state.relationshipGroups.get(fingerprint);
        if (group == null) {
            group = new RelationshipGroup(semantic, canonical, fingerprint);
            state.relationshipGroups.put(fingerprint, group);
        } else if (!group.semantic.equals(semantic)) {
            throw new IllegalStateException("SLPC object relationship fingerprint collision: " + fingerprint);
        }
        group.legacyEvidence.add(legacyEvidence);
        List<Object> locations = state.sourceLocationsByLegacyEvidence.get(legacyEvidence);
        if (locations != null) for (Object value : locations) {
            SlpcObject location = (SlpcObject) value;
            group.sourceLocations.put(sourceLocationKey(location), location);
        }
    }

    private boolean relationshipCanonical(SlpcObject semantic, State state) {
        for (Object value : semantic.array("participants")) {
            if (!canonicalEndpoint(((SlpcObject) value).string("endpointRef"), state)) return false;
        }
        for (String details : new String[] {"keyFields", "keyPairs"}) {
            List<Object> values = semantic.array(details);
            if (values == null) continue;
            for (Object value : values) {
                SlpcObject item = (SlpcObject) value;
                for (String field : new String[] {"fieldEndpointRef", "foreignKeyFieldRef", "referencedFieldRef"}) {
                    if (item.string(field) != null && !canonicalEndpoint(item.string(field), state)) return false;
                }
            }
        }
        return true;
    }

    private boolean canonicalEndpoint(String ref, State state) {
        SlpcObject endpoint = ref == null ? null : state.endpointByRef.get(ref);
        return endpoint != null && endpoint.string("canonicalEndpointId") != null;
    }

    private void markDedicatedMapped(relationship relation, State state, String target) {
        if (!state.dedicatedRelationshipAccounting.add(legacyId(relation))) return;
        state.coverage.add(new LegacyCoverageReport.Entry("RELATIONSHIP", legacyId(relation),
                LegacyCoverageReport.Outcome.CONDITIONAL, target,
                "legacy record mapped to typed SLPC structural/operation semantics; identity controls publication"));
    }

    private void accountDedicatedLoss(relationship relation, State state, String code, String message) {
        if (!state.dedicatedRelationshipAccounting.add(legacyId(relation))) return;
        accountLoss(relation, state, code, message);
    }

    private void buildLineage(dataflow legacy, State state) {
        for (relationship relation : legacy.getRelationships()) {
            if (equalsAny(relation.getType(), "join", "call", "er", "crud", "fddi")) {
                // Consumed by their dedicated structural, operation, join, or
                // verified path-evidence mapping.
                continue;
            }
            if (!"fdd".equals(relation.getType()) && !"fdr".equals(relation.getType())
                    && !"frd".equals(relation.getType())) {
                accountUnsupportedRelationship(relation, state);
                continue;
            }
            if (state.dedicatedRelationshipAccounting.contains(legacyId(relation))) continue;
            if (unsupportedFactEffect(relation.getEffectType())) {
                accountLoss(relation, state, "SLPC_OPERATION_UNSUPPORTED",
                        "Legacy effectType '" + safe(relation.getEffectType())
                                + "' requires a typed operation/object relationship mapping and is not published as a VALUE/ROW fact in M1.");
                continue;
            }
            targetColumn target = relation.getTarget();
            if (target == null || relation.getSources().isEmpty()) {
                accountLoss(relation, state, "SLPC_ENDPOINT_UNRESOLVED",
                        "Dataflow relation has no target or source in the completed legacy POJO.");
                continue;
            }
            List<String> owners = new ArrayList<String>();
            boolean conditional = effectNeedsAdditionalMapping(relation.getEffectType());
            if (conditional) {
                accountSemanticGap(relation, "SLPC_OPERATION_UNSUPPORTED",
                        "Legacy effectType '" + safe(relation.getEffectType())
                                + "' retains its proven data dependency, but its additional statement/operation semantics are not mapped in M1.", state);
            }
            for (sourceColumn source : relation.getSources()) {
                if (hasCandidateParents(source)) {
                    conditional = true;
                    accountSemanticGap(relation, "SLPC_ENDPOINT_AMBIGUOUS",
                            "Legacy sourceColumn contains multiple candidate parents; the adapter will not select one as the lineage source.", state);
                    continue;
                }
                FactSemantics semantics = semantics(relation, source);
                if (semantics.diagnosticCode != null) {
                    conditional = true;
                    accountSemanticGap(relation, semantics.diagnosticCode, semantics.diagnosticMessage, state);
                }
                if (!semantics.publish) continue;
                String targetRef = resolveTarget(target, semantics, state);
                if (targetRef == null) {
                    accountSemanticGap(relation, "SLPC_ENDPOINT_UNRESOLVED",
                            "The legacy target cannot be bound at the endpoint level required by " + semantics.axis + ".", state);
                    continue;
                }
                String sourceRef = semantics.derived ? null : resolveSource(source, semantics, state);
                if (!semantics.derived && sourceRef == null) {
                    accountSemanticGap(relation, "SLPC_ENDPOINT_UNRESOLVED",
                            "A proven legacy relation source could not be bound without coarsening its endpoint level.", state);
                    continue;
                }
                SlpcObject semantic = semanticRecord(sourceRef, targetRef, semantics, state);
                boolean canonical = isCanonicalFact(semantic, state.endpointByRef);
                String semanticKey = canonical ? SlpcIdentity.factId(semantic, state.endpointByRef)
                        : SlpcIdentity.factCandidateFingerprint(semantic, state.endpointByRef);
                FactGroup group = state.factGroups.get(semanticKey);
                if (group == null) {
                    group = new FactGroup(semantic, canonical, semanticKey);
                    state.factGroups.put(semanticKey, group);
                } else if (!group.sameSemantic(semantic)) {
                    throw new IllegalStateException("SLPC fact fingerprint collision: " + semanticKey);
                }
                SlpcObject transformation = transformationEvidence(relation, source);
                SlpcObject predicate = evidence(predicateText(relation, semantics));
                List<Object> literalInputs = semantics.derived
                        ? Collections.<Object>singletonList(redactedLiteral(state, state.nextRedactionOrdinal++))
                        : Collections.<Object>emptyList();
                FactOccurrenceDraft occurrence = new FactOccurrenceDraft(group, transformation, predicate,
                        canonical ? "RESOLVED" : "UNRESOLVED", literalInputs, Collections.<Object>emptyList(),
                        sourceLocations(relation, state), routineEndpoint(relation.getProcedureId(), state));
                group.occurrences.add(occurrence); state.factOccurrenceDrafts.add(occurrence); owners.add(semanticKey);
            }
            if (owners.isEmpty()) {
                accountLoss(relation, state, "SLPC_ENDPOINT_NOT_PUBLISHABLE",
                        "No source could be represented without inventing an endpoint.");
            } else {
                state.coverage.add(new LegacyCoverageReport.Entry("RELATIONSHIP", legacyId(relation),
                        conditional ? LegacyCoverageReport.Outcome.CONDITIONAL
                                : allCanonical(owners, state) ? LegacyCoverageReport.Outcome.EXACT : LegacyCoverageReport.Outcome.QUARANTINED,
                        join(owners), "VALUE/ROW semantics preserved; identity controls publication"));
            }
        }
    }

    private void buildStatementOperation(dataflow legacy, State state) {
        String kind = operationKind(state.context.statementKind());
        List<Object> participants = new ArrayList<Object>();
        List<String> physicalSources = new ArrayList<String>(), targets = new ArrayList<String>(), outputs = new ArrayList<String>();
        for (table relation : dataflow.getAllTables(legacy)) {
            String ref = state.tableRefs.get(relation);
            if (ref == null) continue;
            if (isIntermediate(relation)) outputs.add(ref);
            else if (relation.isTarget() || createdInSql(relation)) targets.add(ref);
            else physicalSources.add(ref);
        }
        sortEndpointRefs(physicalSources, state); sortEndpointRefs(targets, state); sortEndpointRefs(outputs, state);
        physicalSources = distinct(physicalSources); targets = distinct(targets); outputs = distinct(outputs);
        if ("QUERY".equals(kind)) {
            addParticipants(participants, "READ_RELATION", physicalSources);
            if (!outputs.isEmpty()) {
                operationLoss(state, "SLPC_ADAPTER_CAPABILITY_GAP",
                        "Legacy result-set names and cleared isTarget flags do not prove which intermediate is the top-level QUERY output; OUTPUT_RELATION is omitted.");
            }
        } else if ("INSERT".equals(kind) || "UPDATE".equals(kind) || "DELETE".equals(kind)) {
            List<String> writeTargets = physicalRelationshipTargets(legacy, state);
            if (writeTargets.size() != 1) {
                operationLoss(state, "SLPC_ENDPOINT_UNRESOLVED",
                        "A " + kind + " operation requires exactly one proven legacy target; observed " + writeTargets.size() + ".");
                return;
            }
            addParticipants(participants, "WRITE_TARGET", writeTargets);
            physicalSources.removeAll(writeTargets);
            addParticipants(participants, "READ_SOURCE", physicalSources);
        } else if ("MERGE".equals(kind)) {
            List<String> mergeTargets = physicalRelationshipTargets(legacy, state);
            if (mergeTargets.size() != 1) {
                operationLoss(state, "SLPC_ENDPOINT_UNRESOLVED",
                        "A MERGE operation requires exactly one proven legacy target; observed " + mergeTargets.size() + ".");
                return;
            }
            addParticipants(participants, "MERGE_TARGET", mergeTargets);
            physicalSources.removeAll(mergeTargets);
            addParticipants(participants, "MERGE_SOURCE", physicalSources);
        } else if (equalsAny(kind, "CREATE_TABLE", "CREATE_TABLE_AS", "CREATE_VIEW", "CREATE_MATERIALIZED_VIEW")) {
            List<String> createdObjects = "CREATE_VIEW".equals(kind) ? refsByKind(legacy, state, "VIEW")
                    : "CREATE_MATERIALIZED_VIEW".equals(kind) ? refsByKind(legacy, state, "MATERIALIZED_VIEW")
                    : targets;
            String created = singleOrLoss(createdObjects, kind + " CREATED_OBJECT", state);
            if (created == null) return;
            addParticipants(participants, "CREATED_OBJECT", Collections.singletonList(created));
            if (!"CREATE_TABLE".equals(kind)) addParticipants(participants, "READ_SOURCE", physicalSources);
        } else if ("CREATE_EXTERNAL_TABLE".equals(kind)) {
            List<String> storage = refsByStorage(legacy, state, true), relations = refsByStorage(legacy, state, false);
            relations.retainAll(targets);
            String created = singleOrLoss(relations, "CREATE_EXTERNAL_TABLE CREATED_OBJECT", state);
            if (created == null) return;
            addParticipants(participants, "CREATED_OBJECT", Collections.singletonList(created));
            addParticipants(participants, "STORAGE_SOURCE", storage);
        } else if ("CREATE_STAGE".equals(kind)) {
            List<String> stages = refsByKind(legacy, state, "STAGE");
            String created = singleOrLoss(stages, "CREATE_STAGE CREATED_OBJECT", state);
            if (created == null) return;
            addParticipants(participants, "CREATED_OBJECT", Collections.singletonList(created));
            List<String> files = refsByKind(legacy, state, "FILE");
            addParticipants(participants, "STORAGE_SOURCE", files);
        } else if ("CREATE_STREAM".equals(kind)) {
            String[] pair = firstRelationshipPair(state.relationshipGroups, "STREAMS_FROM");
            if (pair == null || !canonicalEndpoint(pair[0], state) || !canonicalEndpoint(pair[1], state)) {
                operationLoss(state, "SLPC_ENDPOINT_UNRESOLVED",
                        "CREATE_STREAM requires one canonical STREAMS_FROM pair; candidate-only structure is retained without an invalid operation.");
                return;
            }
            addParticipants(participants, "CREATED_STREAM", Collections.singletonList(pair[0]));
            addParticipants(participants, "BASE_RELATION", Collections.singletonList(pair[1]));
        } else if ("CREATE_ROUTINE".equals(kind)) {
            String routine = singleOrLoss(refsAtLevel(state, "ROUTINE"), "CREATE_ROUTINE CREATED_ROUTINE", state);
            if (routine == null) return;
            addParticipants(participants, "CREATED_ROUTINE", Collections.singletonList(routine));
        } else if ("CALL_ROUTINE".equals(kind)) {
            List<String> callees = new ArrayList<String>();
            for (relationship relation : legacy.getRelationships()) if ("call".equals(relation.getType())) {
                for (sourceColumn callee : relation.getCallees()) {
                    String ref = routineEndpoint(callee, state); if (ref != null) callees.add(ref);
                }
            }
            sortEndpointRefs(callees, state); callees = distinct(callees);
            String callee = singleOrLoss(callees, "CALL_ROUTINE CALLEE_ROUTINE", state);
            if (callee == null) return;
            addParticipants(participants, "CALLEE_ROUTINE", Collections.singletonList(callee));
            for (relationship relation : legacy.getRelationships()) if ("call".equals(relation.getType())) {
                markDedicatedMapped(relation, state, "CALL_ROUTINE");
            }
        } else if ("RENAME".equals(kind) || "SWAP".equals(kind) || "CLONE".equals(kind)) {
            String effect = "RENAME".equals(kind) ? "rename_table" : "SWAP".equals(kind) ? "swap_table" : "clone_table";
            String[] pair = operationPair(legacy, effect, state);
            if (pair == null) { operationLoss(state, "SLPC_ENDPOINT_UNRESOLVED", kind + " requires one proven source/target object pair."); return; }
            if ("RENAME".equals(kind)) {
                addParticipants(participants, "BEFORE_OBJECT", Collections.singletonList(pair[0]));
                addParticipants(participants, "AFTER_OBJECT", Collections.singletonList(pair[1]));
            } else if ("SWAP".equals(kind)) {
                addParticipants(participants, "SWAP_LEFT_OBJECT", Collections.singletonList(pair[1]));
                addParticipants(participants, "SWAP_RIGHT_OBJECT", Collections.singletonList(pair[0]));
            } else {
                addParticipants(participants, "CLONE_SOURCE", Collections.singletonList(pair[0]));
                addParticipants(participants, "CLONE_TARGET", Collections.singletonList(pair[1]));
            }
        } else if ("LOAD".equals(kind)) {
            List<String> storage = refsByStorage(legacy, state, true);
            List<String> writes = nonStorageTargets(legacy, state);
            String target = singleOrLoss(writes, "LOAD WRITE_TARGET", state); if (target == null) return;
            addParticipants(participants, "STORAGE_SOURCE", storage);
            addParticipants(participants, "WRITE_TARGET", Collections.singletonList(target));
            markEffects(legacy, state, "LOAD", "copy", "load");
        } else if ("UNLOAD".equals(kind) || "INSERT_OVERWRITE_DIRECTORY".equals(kind)) {
            List<String> storage = refsByStorage(legacy, state, true);
            String target = singleOrLoss(storage, kind + " STORAGE_TARGET", state); if (target == null) return;
            addParticipants(participants, "READ_SOURCE", nonStorageSources(legacy, state));
            addParticipants(participants, "STORAGE_TARGET", Collections.singletonList(target));
            markEffects(legacy, state, kind, "unload", "copy");
        } else if (equalsAny(kind, "ALTER", "DROP", "TRUNCATE")) {
            List<String> affected = affectedObjects(legacy, state);
            String target = singleOrLoss(affected, kind + " AFFECTED_OBJECT", state); if (target == null) return;
            addParticipants(participants, "AFFECTED_OBJECT", Collections.singletonList(target));
            for (relationship relation : legacy.getRelationships()) if ("crud".equals(relation.getType())
                    || isOperationEffect(relation.getEffectType())) markDedicatedMapped(relation, state, kind);
        } else {
            List<String> affected = new ArrayList<String>(); affected.addAll(targets); affected.addAll(physicalSources);
            sortEndpointRefs(affected, state); addParticipants(participants, "AFFECTED_OBJECT", distinct(affected));
        }
        String content = contentSemantics(kind);
        String resolution = participantsCanonical(participants, state) ? "RESOLVED" : "UNRESOLVED";
        SlpcObject provisional = SlpcObject.builder().put("statementOperationId", "slso1-" + zeros(64))
                .put("statementId", state.statementId).put("operationOrdinal", 1).put("operationKind", kind)
                .put("participants", participants).put("contentSemantics", content).put("quality", occurrenceQuality(resolution))
                .put("sourceLocations", statementSourceLocations(state.statement))
                .put("extensions", Collections.emptyList()).build();
        state.statementOperations.add(provisional.toBuilder()
                .put("statementOperationId", SlpcIdentity.statementOperationId(provisional, state.endpointByRef)).build());
    }

    private void operationLoss(State state, String code, String message) {
        state.diagnostics.add(diagnostic(code, "WARN", "STATEMENT", state.statementId, message));
        state.differences.add(new IntentionalDiffLedger.Entry(IntentionalDiffLedger.Category.KNOWN_UNSUPPORTED_WITH_LOSS,
                state.statementId, code, message));
    }

    private String operationKind(String statementKind) {
        String normalized = safe(statementKind).trim().toUpperCase(java.util.Locale.ROOT)
                .replace('-', '_').replace(' ', '_');
        if ("SELECT".equals(normalized)) return "QUERY";
        if ("CREATE_PROCEDURE".equals(normalized) || "CREATE_FUNCTION".equals(normalized)) return "CREATE_ROUTINE";
        if ("CALL".equals(normalized) || "EXECUTE".equals(normalized) || "EXEC".equals(normalized)) return "CALL_ROUTINE";
        if ("ALTER_TABLE".equals(normalized)) return "ALTER";
        if ("DROP_TABLE".equals(normalized)) return "DROP";
        if ("TRUNCATE_TABLE".equals(normalized)) return "TRUNCATE";
        if (equalsAny(normalized, "QUERY", "INSERT", "UPDATE", "DELETE", "MERGE", "CREATE_TABLE",
                "CREATE_TABLE_AS", "CREATE_VIEW", "CREATE_MATERIALIZED_VIEW", "CREATE_EXTERNAL_TABLE",
                "CREATE_STAGE", "CREATE_STREAM", "CREATE_ROUTINE", "CREATE_SYNONYM", "CREATE_INDEX",
                "RENAME", "SWAP", "CLONE", "LOAD", "UNLOAD", "INSERT_OVERWRITE_DIRECTORY",
                "CALL_ROUTINE", "ALTER", "DROP", "TRUNCATE", "OTHER")) return normalized;
        return "OTHER";
    }

    private String contentSemantics(String operationKind) {
        if ("QUERY".equals(operationKind)) return "CONTENT_READ";
        if ("INSERT".equals(operationKind) || "LOAD".equals(operationKind)) return "CONTENT_WRITE";
        if (equalsAny(operationKind, "UPDATE", "DELETE", "MERGE", "ALTER")) return "MUTATION";
        if (equalsAny(operationKind, "CREATE_TABLE", "CREATE_VIEW", "CREATE_EXTERNAL_TABLE", "CREATE_STAGE",
                "CREATE_STREAM", "CREATE_ROUTINE", "CREATE_SYNONYM", "CREATE_INDEX")) return "DEFINITION_ONLY";
        if (equalsAny(operationKind, "CREATE_TABLE_AS", "CREATE_MATERIALIZED_VIEW", "CLONE", "UNLOAD",
                "INSERT_OVERWRITE_DIRECTORY")) return "CONTENT_COPY";
        if ("RENAME".equals(operationKind)) return "IDENTITY_CONTINUITY";
        if ("SWAP".equals(operationKind)) return "CONTENT_EXCHANGE";
        if ("CALL_ROUTINE".equals(operationKind)) return "NOT_APPLICABLE";
        if (equalsAny(operationKind, "DROP", "TRUNCATE")) return "DELETION";
        return "UNKNOWN";
    }

    private String singleOrLoss(List<String> values, String label, State state) {
        sortEndpointRefs(values, state); values = distinct(values);
        if (values.size() == 1) return values.get(0);
        operationLoss(state, "SLPC_ENDPOINT_UNRESOLVED", label + " requires exactly one endpoint; observed " + values.size() + ".");
        return null;
    }

    private List<String> refsAtLevel(State state, String level) {
        List<String> result = new ArrayList<String>();
        for (Map.Entry<String, SlpcObject> entry : state.endpointByRef.entrySet()) {
            if (level.equals(entry.getValue().string("endpointLevel"))) result.add(entry.getKey());
        }
        sortEndpointRefs(result, state); return distinct(result);
    }

    private List<String> refsByKind(dataflow legacy, State state, String kind) {
        List<String> result = new ArrayList<String>();
        for (table relation : dataflow.getAllTables(legacy)) {
            String ref = state.tableRefs.get(relation);
            if (ref != null && kind.equals(endpointKind(ref, state))) result.add(ref);
        }
        sortEndpointRefs(result, state); return distinct(result);
    }

    private List<String> refsByStorage(dataflow legacy, State state, boolean storage) {
        List<String> result = new ArrayList<String>();
        for (table relation : dataflow.getAllTables(legacy)) {
            String ref = state.tableRefs.get(relation); if (ref == null || isIntermediate(relation)) continue;
            if (isStorageKind(endpointKind(ref, state)) == storage) result.add(ref);
        }
        sortEndpointRefs(result, state); return distinct(result);
    }

    private List<String> nonStorageTargets(dataflow legacy, State state) {
        List<String> result = new ArrayList<String>();
        for (relationship relation : legacy.getRelationships()) {
            if (relation.getTarget() == null) continue;
            String ref = relationEndpoint(relation.getTarget(), state);
            if (ref != null && !isStorageKind(endpointKind(ref, state))) result.add(ref);
        }
        sortEndpointRefs(result, state); return distinct(result);
    }

    private List<String> physicalRelationshipTargets(dataflow legacy, State state) {
        List<String> physical = new ArrayList<String>();
        for (relationship relation : legacy.getRelationships()) {
            if (!"fdd".equals(relation.getType()) || "foreign_key".equals(relation.getEffectType())
                    || relation.getTarget() == null) continue;
            String ref = relationEndpoint(relation.getTarget(), state);
            if (ref != null && !isStorageKind(endpointKind(ref, state))
                    && !isIntermediateEndpoint(ref, state)) physical.add(ref);
        }
        sortEndpointRefs(physical, state); return distinct(physical);
    }

    private List<String> nonStorageSources(dataflow legacy, State state) {
        List<String> result = new ArrayList<String>();
        for (relationship relation : legacy.getRelationships()) for (sourceColumn source : relation.getSources()) {
            String ref = relationEndpoint(source, state);
            if (ref != null && !isStorageKind(endpointKind(ref, state)) && !isIntermediateEndpoint(ref, state)) result.add(ref);
        }
        sortEndpointRefs(result, state); return distinct(result);
    }

    private boolean isIntermediateEndpoint(String ref, State state) {
        String kind = endpointKind(ref, state);
        return equalsAny(kind, "RESULT_SET", "CTE", "DERIVED_TABLE");
    }

    private String[] operationPair(dataflow legacy, String effect, State state) {
        for (relationship relation : legacy.getRelationships()) {
            if (!effect.equals(relation.getEffectType()) || relation.getTarget() == null || relation.getSources().size() != 1) continue;
            String before = relationEndpoint(relation.getSources().get(0), state);
            String after = relationEndpoint(relation.getTarget(), state);
            if (before == null || after == null) continue;
            markDedicatedMapped(relation, state, effect);
            return new String[] {before, after};
        }
        return null;
    }

    private String[] firstRelationshipPair(Map<String, RelationshipGroup> groups, String kind) {
        for (RelationshipGroup group : groups.values()) {
            if (!kind.equals(group.semantic.string("relationshipKind"))) continue;
            List<Object> participants = group.semantic.array("participants");
            if (participants.size() == 2) return new String[] {
                    ((SlpcObject) participants.get(0)).string("endpointRef"),
                    ((SlpcObject) participants.get(1)).string("endpointRef")};
        }
        return null;
    }

    private List<String> affectedObjects(dataflow legacy, State state) {
        List<String> result = new ArrayList<String>();
        for (relationship relation : legacy.getRelationships()) {
            if (!"crud".equals(relation.getType()) && !isOperationEffect(relation.getEffectType())) continue;
            if (relation.getTarget() != null) {
                String ref = relationEndpoint(relation.getTarget(), state);
                if (ref == null) ref = endpointAtLevel(state.endpointByLegacyId.get(relation.getTarget().getId()), "RELATION", state);
                if (ref == null) ref = endpointAtLevel(state.endpointByLegacyId.get(relation.getTarget().getTarget_id()), "RELATION", state);
                if (ref != null) result.add(ref);
            }
            for (sourceColumn source : relation.getSources()) {
                String ref = relationEndpoint(source, state); if (ref != null) result.add(ref);
            }
        }
        if (result.isEmpty()) {
            for (table relation : dataflow.getAllTables(legacy)) if (relation.isTarget() && !isIntermediate(relation)) {
                String ref = state.tableRefs.get(relation); if (ref != null) result.add(ref);
            }
        }
        sortEndpointRefs(result, state); return distinct(result);
    }

    private boolean isOperationEffect(String effect) {
        return equalsAny(effect, "rename_table", "swap_table", "clone_table", "clone_schema", "clone_database",
                "unload", "copy", "drop_table", "drop_table_column", "add_table_column", "truncate_table");
    }

    private boolean createdInSql(table relation) {
        return "true".equalsIgnoreCase(nonEmpty(relation.getCreatedInSql()));
    }

    private void markEffects(dataflow legacy, State state, String target, String... effects) {
        for (relationship relation : legacy.getRelationships()) {
            if (equalsAny(relation.getEffectType(), effects)) markDedicatedMapped(relation, state, target);
        }
    }

    private void addParticipants(List<Object> target, String role, List<String> endpointRefs) {
        for (String ref : endpointRefs) target.add(SlpcObject.builder().put("role", role).put("endpointRef", ref).build());
    }

    private void sortEndpointRefs(List<String> refs, final State state) {
        Collections.sort(refs, new Comparator<String>() { @Override public int compare(String left, String right) {
            return utf8Compare(SlpcIdentity.candidateEndpointKey(state.endpointByRef.get(left)),
                    SlpcIdentity.candidateEndpointKey(state.endpointByRef.get(right)));
        }});
    }

    private List<String> distinct(List<String> values) {
        List<String> result = new ArrayList<String>();
        for (String value : values) if (!result.contains(value)) result.add(value);
        return result;
    }

    private boolean participantsCanonical(List<Object> participants, State state) {
        for (Object value : participants) {
            SlpcObject participant = (SlpcObject) value;
            if (state.endpointByRef.get(participant.string("endpointRef")).string("canonicalEndpointId") == null) return false;
        }
        return true;
    }

    private void materializeFactsAndOccurrences(State state, List<FactOccurrenceDraft> occurrenceDrafts) {
        List<FactGroup> canonical = new ArrayList<FactGroup>(), candidates = new ArrayList<FactGroup>();
        for (FactGroup group : state.factGroups.values()) { if (group.canonical) canonical.add(group); else candidates.add(group); }
        Collections.sort(canonical, factGroupComparator()); Collections.sort(candidates, factGroupComparator());
        for (FactGroup group : canonical) { group.ownerKind = "FACT"; group.ownerId = group.semanticKey; }
        for (int index = 0; index < candidates.size(); index++) { FactGroup group = candidates.get(index); group.ownerKind = "FACT_CANDIDATE"; group.ownerId = local("fact-cand-", index + 1); }

        Map<String, String> ownerSemanticKeys = new HashMap<String, String>();
        for (FactGroup group : canonical) ownerSemanticKeys.put(group.ownerKind + "\u0000" + group.ownerId, group.semanticKey);
        for (FactGroup group : candidates) ownerSemanticKeys.put(group.ownerKind + "\u0000" + group.ownerId, group.semanticKey);
        Map<String, SlpcObject> uniqueOccurrences = new TreeMap<String, SlpcObject>();
        for (FactOccurrenceDraft draft : occurrenceDrafts) {
            SlpcObject withoutId = occurrence(draft, state, "slocc1-" + zeros(64));
            String id = SlpcIdentity.occurrenceId(withoutId, ownerSemanticKeys);
            SlpcObject occurrence = withoutId.toBuilder().put("occurrenceId", id).build();
            SlpcObject previous = uniqueOccurrences.get(id);
            uniqueOccurrences.put(id, previous == null ? occurrence : mergeOccurrence(previous, occurrence));
        }
        state.occurrences.addAll(uniqueOccurrences.values());

        Map<String, Integer> evidenceCounts = new HashMap<String, Integer>();
        for (Object value : state.occurrences) {
            SlpcObject occurrence = (SlpcObject) value;
            SlpcObject owner = occurrence.object("ownerRef"); String key = owner.string("kind") + "\u0000" + owner.string("id");
            Integer old = evidenceCounts.get(key); evidenceCounts.put(key, old == null ? 1 : old + 1);
        }
        for (FactGroup group : canonical) state.facts.add(materializeFact(group, evidenceCounts));
        for (FactGroup group : candidates) state.factCandidates.add(materializeFact(group, evidenceCounts));
    }

    private SlpcObject materializeFact(FactGroup group, Map<String, Integer> counts) {
        int evidenceCount = counts.get(group.ownerKind + "\u0000" + group.ownerId);
        String resolution = group.canonical ? "RESOLVED" : "UNRESOLVED";
        SlpcObject quality = qualitySummary(group.canonical ? "ELIGIBLE" : "INELIGIBLE", resolution, evidenceCount);
        SlpcObject.Builder result = SlpcObject.builder();
        if (group.canonical) result.put("factId", group.semanticKey);
        else result.put("candidateId", group.ownerId).put("candidateFingerprint", group.semanticKey);
        result.put("sourceEndpointRef", group.semantic.get("sourceEndpointRef"))
                .put("targetEndpointRef", group.semantic.string("targetEndpointRef"))
                .put("axis", group.semantic.string("axis")).put("role", group.semantic.string("role"))
                .put("operationKind", group.semantic.string("operationKind"))
                .put("operationInputKind", group.semantic.string("operationInputKind"));
        if (!group.canonical) result.put("candidateReasons", Collections.singletonList(candidateReason(group.semantic)));
        return result.put("qualitySummary", quality).put("extensions", Collections.emptyList()).build();
    }

    private SlpcObject mergeOccurrence(SlpcObject left, SlpcObject right) {
        SlpcObject leftBase = left.toBuilder().remove("literalInputs").remove("supportPathRefs").remove("sourceLocations").build();
        SlpcObject rightBase = right.toBuilder().remove("literalInputs").remove("supportPathRefs").remove("sourceLocations").build();
        if (!leftBase.equals(rightBase)) throw new IllegalStateException("SLPC occurrence ID collision: " + left.string("occurrenceId"));
        Map<String, SlpcObject> literals = new TreeMap<String, SlpcObject>();
        addLiterals(literals, left.array("literalInputs")); addLiterals(literals, right.array("literalInputs"));
        List<Object> merged = new ArrayList<Object>(); int ordinal = 1;
        for (SlpcObject literal : literals.values()) merged.add(literal.toBuilder().put("inputOrdinal", ordinal++).build());
        SlpcObject.Builder result = left.toBuilder(); if (!merged.isEmpty()) result.put("literalInputs", merged);
        Map<String, SlpcObject> paths = new TreeMap<String, SlpcObject>();
        addSupportPaths(paths, left.array("supportPathRefs")); addSupportPaths(paths, right.array("supportPathRefs"));
        if (!paths.isEmpty()) result.put("supportPathRefs", new ArrayList<Object>(paths.values()));
        Map<String, SlpcObject> locations = new TreeMap<String, SlpcObject>();
        addSourceLocations(locations, left.array("sourceLocations")); addSourceLocations(locations, right.array("sourceLocations"));
        result.put("sourceLocations", new ArrayList<Object>(locations.values()));
        return result.build();
    }

    private void addSourceLocations(Map<String, SlpcObject> target, List<Object> values) {
        if (values == null) return;
        for (Object value : values) {
            SlpcObject location = (SlpcObject) value; target.put(sourceLocationKey(location), location);
        }
    }

    private String sourceLocationKey(SlpcObject location) {
        return location.string("artifactId") + ":" + location.get("startLine") + ":"
                + location.get("startColumn") + ":" + location.get("endLine") + ":" + location.get("endColumn");
    }

    private void addSupportPaths(Map<String, SlpcObject> target, List<Object> values) {
        if (values == null) return;
        for (Object value : values) {
            SlpcObject support = (SlpcObject) value;
            target.put(support.string("graphRef") + "\u0000" + support.string("pathRef"), support);
        }
    }

    private void addLiterals(Map<String, SlpcObject> target, List<Object> values) {
        if (values == null) return;
        for (Object value : values) { SlpcObject literal = (SlpcObject) value; SlpcObject fp = literal.object("fingerprint");
            target.put(fp.string("algorithm") + "\u0000" + fp.string("value"), literal); }
    }

    private SlpcObject occurrence(FactOccurrenceDraft draft, State state, String id) {
        SlpcObject owner = SlpcObject.builder().put("kind", draft.group.ownerKind).put("id", draft.group.ownerId).build();
        SlpcObject origin = SlpcObject.builder().put("engineKind", "LEGACY_DLINEAGE").put("adapterName", ADAPTER_NAME).build();
        SlpcObject quality = occurrenceQuality(draft.resolution);
        SlpcObject.Builder result = SlpcObject.builder().put("occurrenceId", id).put("ownerRef", owner)
                .put("artifactId", state.artifact.string("artifactId")).put("statementId", state.statementId)
                .put("evidenceKind", "STATIC_SQL").put("origin", origin)
                .putNull("procedureEndpointRef").putNull("procedureCanonicalEndpointId")
                .put("transformation", draft.transformation).put("predicate", draft.predicate)
                .put("quality", quality).put("sourceLocations", draft.sourceLocations)
                .put("extensions", Collections.emptyList());
        if (draft.procedureEndpointRef != null) {
            result.put("procedureEndpointRef", draft.procedureEndpointRef)
                    .put("procedureCanonicalEndpointId",
                            state.endpointByRef.get(draft.procedureEndpointRef).string("canonicalEndpointId"));
        }
        if (!draft.literalInputs.isEmpty()) result.put("literalInputs", draft.literalInputs);
        if (!draft.supportPathRefs.isEmpty()) result.put("supportPathRefs", draft.supportPathRefs);
        return result.build();
    }

    private void materializeObjectRelationships(State state) {
        List<RelationshipGroup> canonical = new ArrayList<RelationshipGroup>();
        List<RelationshipGroup> candidates = new ArrayList<RelationshipGroup>();
        for (RelationshipGroup group : state.relationshipGroups.values()) {
            if (group.canonical) canonical.add(group); else candidates.add(group);
        }
        Collections.sort(canonical, relationshipGroupComparator());
        Collections.sort(candidates, relationshipGroupComparator());
        for (RelationshipGroup group : canonical) {
            group.ownerKind = "OBJECT_RELATIONSHIP";
            group.ownerId = group.semanticKey;
        }
        for (int index = 0; index < candidates.size(); index++) {
            RelationshipGroup group = candidates.get(index);
            group.ownerKind = "OBJECT_RELATIONSHIP_CANDIDATE";
            group.ownerId = local("objrel-cand-", index + 1);
        }
        Map<String, String> semanticKeys = new HashMap<String, String>();
        for (RelationshipGroup group : canonical) semanticKeys.put(group.ownerKind + "\u0000" + group.ownerId, group.semanticKey);
        for (RelationshipGroup group : candidates) semanticKeys.put(group.ownerKind + "\u0000" + group.ownerId, group.semanticKey);
        Map<String, SlpcObject> newOccurrences = new TreeMap<String, SlpcObject>();
        for (RelationshipGroup group : canonical) addRelationshipOccurrence(group, semanticKeys, state, newOccurrences);
        for (RelationshipGroup group : candidates) addRelationshipOccurrence(group, semanticKeys, state, newOccurrences);
        state.occurrences.addAll(newOccurrences.values());
        Collections.sort(state.occurrences, new Comparator<Object>() { @Override public int compare(Object left, Object right) {
            return ((SlpcObject) left).string("occurrenceId").compareTo(((SlpcObject) right).string("occurrenceId"));
        }});
        for (RelationshipGroup group : canonical) state.objectRelationships.add(materializeRelationship(group, false));
        for (RelationshipGroup group : candidates) state.objectRelationshipCandidates.add(materializeRelationship(group, true));
    }

    private void addRelationshipOccurrence(RelationshipGroup group, Map<String, String> semanticKeys,
            State state, Map<String, SlpcObject> target) {
        SlpcObject owner = SlpcObject.builder().put("kind", group.ownerKind).put("id", group.ownerId).build();
        SlpcObject origin = SlpcObject.builder().put("engineKind", "LEGACY_DLINEAGE")
                .put("adapterName", ADAPTER_NAME).build();
        String resolution = group.canonical ? "RESOLVED" : "UNRESOLVED";
        SlpcObject withoutId = SlpcObject.builder().put("occurrenceId", "slocc1-" + zeros(64))
                .put("ownerRef", owner).put("artifactId", state.artifact.string("artifactId"))
                .put("statementId", state.statementId).put("evidenceKind", "STATIC_SQL")
                .put("origin", origin).putNull("procedureEndpointRef").putNull("procedureCanonicalEndpointId")
                .putNull("transformation").putNull("predicate").put("quality", occurrenceQuality(resolution))
                .put("sourceLocations", new ArrayList<Object>(group.sourceLocations.values()))
                .put("extensions", Collections.emptyList()).build();
        String id = SlpcIdentity.occurrenceId(withoutId, semanticKeys);
        target.put(id, withoutId.toBuilder().put("occurrenceId", id).build());
    }

    private SlpcObject materializeRelationship(RelationshipGroup group, boolean candidate) {
        SlpcObject.Builder result = SlpcObject.builder();
        if (candidate) {
            result.put("candidateId", group.ownerId).put("candidateFingerprint", group.semanticKey);
        } else {
            result.put("relationshipId", group.semanticKey);
        }
        result.put("relationshipKind", group.semantic.string("relationshipKind"))
                .put("participants", group.semantic.array("participants"));
        if (group.semantic.array("keyFields") != null) result.put("keyFields", group.semantic.array("keyFields"));
        if (group.semantic.array("keyPairs") != null) result.put("keyPairs", group.semantic.array("keyPairs"));
        if (candidate) result.put("candidateReasons", Collections.singletonList("IDENTITY_UNAVAILABLE"));
        return result.put("qualitySummary", qualitySummary(candidate ? "INELIGIBLE" : "ELIGIBLE",
                        candidate ? "UNRESOLVED" : "RESOLVED", 1))
                .put("extensions", Collections.emptyList()).build();
    }

    private void buildIntermediateGraph(dataflow legacy, State state) {
        List<table> intermediate = new ArrayList<table>();
        for (table relation : dataflow.getAllTables(legacy)) if (isIntermediate(relation)) intermediate.add(relation);
        if (intermediate.isEmpty()) {
            for (relationship relation : legacy.getRelationships()) if ("fddi".equals(relation.getType())) {
                accountDedicatedLoss(relation, state, "SLPC_INTERMEDIATE_HOP_UNCOLLAPSIBLE",
                        "Legacy fddi has no retained intermediate topology against which to verify a boundary path.");
            }
            return;
        }
        Collections.sort(intermediate, tableComparator());

        Map<String, table> tableById = new HashMap<String, table>();
        for (table relation : intermediate) if (relation.getId() != null) tableById.put(relation.getId(), relation);
        IdentityHashMap<table, table> parentByTable = new IdentityHashMap<table, table>();
        for (table relation : intermediate) {
            if (relation.getParent() == null) continue;
            table parent = tableById.get(relation.getParent());
            if (parent == null || parent == relation) {
                containmentLoss(relation, state,
                        "Legacy parent does not identify a distinct intermediate object; the node is retained as a root.");
            } else {
                parentByTable.put(relation, parent);
            }
        }
        breakContainmentCycles(intermediate, parentByTable, state);

        IdentityHashMap<table, List<table>> childrenByTable = new IdentityHashMap<table, List<table>>();
        for (table relation : intermediate) childrenByTable.put(relation, new ArrayList<table>());
        List<table> roots = new ArrayList<table>();
        for (table relation : intermediate) {
            table parent = parentByTable.get(relation);
            if (parent == null) roots.add(relation); else childrenByTable.get(parent).add(relation);
        }
        Collections.sort(roots, sourceTableComparator());
        for (List<table> children : childrenByTable.values()) Collections.sort(children, sourceTableComparator());

        List<NodeDraft> nodeDrafts = new ArrayList<NodeDraft>();
        Map<table, NodeDraft> tableNodes = new IdentityHashMap<table, NodeDraft>();
        Map<column, NodeDraft> fieldNodes = new IdentityHashMap<column, NodeDraft>();
        int ordinal = 1;
        ArrayDeque<PendingNode> stack = new ArrayDeque<PendingNode>();
        for (int index = roots.size() - 1; index >= 0; index--) stack.push(new PendingNode(roots.get(index), null, null));
        while (!stack.isEmpty()) {
            PendingNode pending = stack.pop();
            if (pending.field != null) {
                NodeDraft fieldNode = new NodeDraft(pending.relation, pending.field, ordinal++,
                        nodeKindForField(pending.relation), null, pending.parent);
                nodeDrafts.add(fieldNode); fieldNodes.put(pending.field, fieldNode);
                putNodeLegacyId(state.intermediateNodeByLegacyId, pending.field.getId(), fieldNode);
                continue;
            }
            NodeDraft relationNode = new NodeDraft(pending.relation, null, ordinal++, nodeKind(pending.relation),
                    provenLocalName(pending.relation), pending.parent);
            nodeDrafts.add(relationNode); tableNodes.put(pending.relation, relationNode);
            putNodeLegacyId(state.intermediateNodeByLegacyId, pending.relation.getId(), relationNode);

            List<PendingNode> children = new ArrayList<PendingNode>();
            for (column field : pending.relation.getColumns()) {
                if (isRelationRows(field)) {
                    putNodeLegacyId(state.intermediateNodeByLegacyId, field.getId(), relationNode);
                } else {
                    children.add(new PendingNode(pending.relation, field, relationNode));
                }
            }
            for (table child : childrenByTable.get(pending.relation)) children.add(new PendingNode(child, null, relationNode));
            Collections.sort(children, pendingNodeComparator());
            for (int index = children.size() - 1; index >= 0; index--) stack.push(children.get(index));
        }
        state.intermediateTableNodes.putAll(tableNodes); state.intermediateColumnNodes.putAll(fieldNodes);

        SlpcObject provisionalGraph = graphShell(state, "sliggfp1-" + zeros(64), Collections.<Object>emptyList(),
                Collections.<Object>emptyList());
        List<Object> provisionalNodes = new ArrayList<Object>();
        for (NodeDraft draft : nodeDrafts) {
            draft.provisionalRef = "tmp-node-" + draft.ordinal;
            SlpcObject node = draft.node(draft.provisionalRef, draft.parent == null ? null : draft.parent.provisionalRef, "slignfp2-" + zeros(64));
            provisionalNodes.add(node); draft.provisionalNode = node;
        }
        provisionalGraph = graphShell(state, "sliggfp1-" + zeros(64), provisionalNodes, Collections.<Object>emptyList());
        for (NodeDraft draft : nodeDrafts) {
            draft.fingerprint = SlpcIdentity.intermediateNodeFingerprint(draft.provisionalNode, provisionalGraph, state.endpointByRef);
        }
        Collections.sort(nodeDrafts, nodeFingerprintComparator());
        for (int index = 0; index < nodeDrafts.size(); index++) {
            NodeDraft draft = nodeDrafts.get(index); draft.finalRef = local("ign-", index + 1);
            if (draft.field == null) state.intermediateTableRefs.put(draft.relation, draft.finalRef);
            else state.intermediateColumnRefs.put(draft.field, draft.finalRef);
        }
        List<Object> nodes = new ArrayList<Object>();
        for (NodeDraft draft : nodeDrafts) nodes.add(draft.node(draft.finalRef, draft.parent == null ? null : draft.parent.finalRef, draft.fingerprint));

        List<EdgeDraft> edges = new ArrayList<EdgeDraft>();
        for (relationship relation : legacy.getRelationships()) {
            if (!"fdd".equals(relation.getType()) && !"fdr".equals(relation.getType())
                    && !"frd".equals(relation.getType())) continue;
            if (state.dedicatedRelationshipAccounting.contains(legacyId(relation))) continue;
            if (unsupportedFactEffect(relation.getEffectType())) continue;
            for (sourceColumn source : relation.getSources()) {
                if (hasCandidateParents(source)) continue;
                FactSemantics semantics = semantics(relation, source);
                if (!semantics.publish) continue;
                SlpcObject target = targetAnchor(relation.getTarget(), semantics, state);
                if (target == null) continue;
                SlpcObject sourceAnchor = sourceAnchor(source, semantics, state);
                if (sourceAnchor == null) continue;
                // Pure physical-to-physical edges belong to facts, not to the intermediate graph.
                if ("ENDPOINT".equals(sourceAnchor.string("kind")) && "ENDPOINT".equals(target.string("kind"))) continue;
                edges.add(new EdgeDraft(relation, source, sourceAnchor, target, semantics,
                        transformationEvidence(relation, source), evidence(predicateText(relation, semantics))));
            }
        }
        Map<String, SlpcObject> nodeIndex = SlpcIdentity.index(nodes, "nodeRef");
        for (EdgeDraft edge : edges) {
            SlpcObject provisional = edge.edge("ige-000001", "sligefp1-" + zeros(64));
            edge.fingerprint = SlpcIdentity.intermediateEdgeFingerprint(provisional, state.endpointByRef, nodeIndex);
        }
        Map<String, EdgeDraft> uniqueEdges = new TreeMap<String, EdgeDraft>();
        for (EdgeDraft edge : edges) {
            EdgeDraft previous = uniqueEdges.put(edge.fingerprint, edge);
            if (previous != null && !previous.sameSemantic(edge)) {
                throw new IllegalStateException("SLPC intermediate edge fingerprint collision: " + edge.fingerprint);
            }
        }
        edges = new ArrayList<EdgeDraft>(uniqueEdges.values());
        Collections.sort(edges, edgeFingerprintComparator());
        List<Object> edgeRecords = new ArrayList<Object>();
        for (int index = 0; index < edges.size(); index++) {
            EdgeDraft edge = edges.get(index); edge.finalRef = local("ige-", index + 1);
            edgeRecords.add(edge.edge(edge.finalRef, edge.fingerprint));
        }
        Map<String, SlpcObject> edgeIndex = SlpcIdentity.index(edgeRecords, "edgeRef");
        List<PathDraft> paths = enumeratePaths(edges, state);
        for (PathDraft path : paths) {
            SlpcObject provisional = path.path("igp-000001", "sligpfp1-" + zeros(64));
            path.fingerprint = SlpcIdentity.intermediatePathFingerprint(provisional, edgeIndex);
        }
        Collections.sort(paths, pathFingerprintComparator());
        List<Object> pathRecords = new ArrayList<Object>();
        for (int index = 0; index < paths.size(); index++) {
            PathDraft path = paths.get(index); path.finalRef = local("igp-", index + 1);
            pathRecords.add(path.path(path.finalRef, path.fingerprint));
        }
        SlpcObject graph = graphShell(state, "sliggfp1-" + zeros(64), nodes, edgeRecords)
                .toBuilder().put("paths", pathRecords).build();
        graph = graph.toBuilder().put("graphFingerprint", SlpcIdentity.intermediateGraphFingerprint(graph)).build();
        List<Object> graphExtensions = interactiveExplainExtensions(legacy, edges, graph, state);
        if (!graphExtensions.isEmpty()) graph = graph.toBuilder().put("extensions", graphExtensions).build();
        state.graphs.add(graph);
        collapsePhysicalPaths(paths, state);
        accountFddiAgainstPaths(legacy, paths, state);
        state.diagnostics.add(diagnostic("SLPC_INTERMEDIATE_GRAPH_INCOMPLETE", "WARN", "INTERMEDIATE_GRAPH", "graph-000001",
                "Legacy result-set containment, proven edges, and bounded acyclic boundary paths are preserved; the legacy POJO still does not prove globally exhaustive analysis."));
        if (graphExtensions.isEmpty()) {
            state.diagnostics.add(diagnostic("SLPC_ADAPTER_CAPABILITY_GAP", "INFO", "INTERMEDIATE_GRAPH", "graph-000001",
                    "No authoritative typed-operation/ordered-operand evidence was supplied, so no interactive explain profile is emitted."));
            state.differences.add(new IntentionalDiffLedger.Entry(IntentionalDiffLedger.Category.KNOWN_UNSUPPORTED_WITH_LOSS,
                    "graph-000001", "GSP_LEGACY_INTERACTIVE_EXPLAIN_UNAVAILABLE",
                    "Clickable topology is retained, but typed steps require producer evidence supplied through LegacyAdapterContext."));
        }
    }

    private List<PathDraft> enumeratePaths(List<EdgeDraft> edges, State state) {
        Map<String, List<EdgeDraft>> outgoing = new HashMap<String, List<EdgeDraft>>();
        List<EdgeDraft> starts = new ArrayList<EdgeDraft>();
        for (EdgeDraft edge : edges) {
            String key = anchorKey(edge.source);
            if (!outgoing.containsKey(key)) outgoing.put(key, new ArrayList<EdgeDraft>());
            outgoing.get(key).add(edge);
            if ("ENDPOINT".equals(edge.source.string("kind"))) starts.add(edge);
        }
        for (List<EdgeDraft> values : outgoing.values()) Collections.sort(values, edgeFingerprintComparator());
        Collections.sort(starts, edgeFingerprintComparator());
        Map<String, PathDraft> unique = new TreeMap<String, PathDraft>();
        ArrayDeque<PathWalk> stack = new ArrayDeque<PathWalk>();
        for (int index = starts.size() - 1; index >= 0; index--) stack.push(PathWalk.start(starts.get(index)));
        int expansions = 0;
        while (!stack.isEmpty()) {
            if (++expansions > 100000) { state.pathEnumerationTruncated = true; break; }
            PathWalk walk = stack.pop(); EdgeDraft last = walk.edges.get(walk.edges.size() - 1);
            if ("ENDPOINT".equals(last.target.string("kind"))) {
                String key = walk.edgeKey(); if (!unique.containsKey(key)) unique.put(key, new PathDraft(walk.edges));
                if (unique.size() >= 10000) { state.pathEnumerationTruncated = true; break; }
                continue;
            }
            List<EdgeDraft> next = outgoing.get(anchorKey(last.target));
            if (next == null) continue;
            for (int index = next.size() - 1; index >= 0; index--) {
                EdgeDraft edge = next.get(index);
                if (walk.used.contains(edge.finalRef)) { state.pathCycleObserved = true; continue; }
                stack.push(walk.append(edge));
            }
        }
        if (state.pathCycleObserved || state.pathEnumerationTruncated) {
            state.diagnostics.add(diagnostic("SLPC_INTERMEDIATE_HOP_UNCOLLAPSIBLE", "WARN", "DOCUMENT", null,
                    state.pathEnumerationTruncated
                            ? "Intermediate path enumeration reached its deterministic path/expansion safety cap."
                            : "A cycle was detected during path enumeration; cyclic continuations were not collapsed."));
        }
        return new ArrayList<PathDraft>(unique.values());
    }

    private String anchorKey(SlpcObject anchor) {
        String ref = "ENDPOINT".equals(anchor.string("kind")) ? anchor.string("endpointRef") : anchor.string("nodeRef");
        return anchor.string("kind") + "\u0000" + ref + "\u0000" + anchor.string("portCode");
    }

    private void collapsePhysicalPaths(List<PathDraft> paths, State state) {
        int collapsed = 0;
        for (PathDraft path : paths) {
            FactSemantics semantics = collapsedSemantics(path);
            if (semantics == null) continue;
            String sourceRef = path.sourceEndpointRef(), targetRef = path.targetEndpointRef();
            if (sourceRef == null || targetRef == null || sourceRef.equals(targetRef)) continue;
            SlpcObject semantic = semanticRecord(sourceRef, targetRef, semantics, state);
            FactGroup group = factGroup(semantic, state);
            List<Object> support = Collections.<Object>singletonList(SlpcObject.builder()
                    .put("graphRef", "graph-000001").put("pathRef", path.finalRef).build());
            FactOccurrenceDraft occurrence = new FactOccurrenceDraft(group, null, null,
                    group.canonical ? "RESOLVED" : "UNRESOLVED", Collections.<Object>emptyList(), support,
                    pathSourceLocations(path, state), null);
            group.occurrences.add(occurrence); state.factOccurrenceDrafts.add(occurrence); collapsed++;
        }
        if (collapsed > 0) {
            state.hasPhysicalHopCollapse = true;
            state.diagnostics.add(diagnostic("SLPC_INTERMEDIATE_HOP_COLLAPSED", "INFO", "DOCUMENT", null,
                    "Published " + collapsed + " physical-boundary lineage occurrence(s) with auditable supportPathRefs."));
        }
    }

    private List<Object> pathSourceLocations(PathDraft path, State state) {
        Map<String, SlpcObject> result = new TreeMap<String, SlpcObject>();
        for (EdgeDraft edge : path.edges) addSourceLocations(result, sourceLocations(edge.relation, state));
        return new ArrayList<Object>(result.values());
    }

    private FactGroup factGroup(SlpcObject semantic, State state) {
        boolean canonical = isCanonicalFact(semantic, state.endpointByRef);
        String key = canonical ? SlpcIdentity.factId(semantic, state.endpointByRef)
                : SlpcIdentity.factCandidateFingerprint(semantic, state.endpointByRef);
        FactGroup group = state.factGroups.get(key);
        if (group == null) { group = new FactGroup(semantic, canonical, key); state.factGroups.put(key, group); }
        else if (!group.sameSemantic(semantic)) throw new IllegalStateException("SLPC fact fingerprint collision: " + key);
        return group;
    }

    private FactSemantics collapsedSemantics(PathDraft path) {
        boolean changed = false, aggregate = false;
        for (EdgeDraft edge : path.edges) {
            if (!"VALUE".equals(edge.semantics.axis) || !"NONE".equals(edge.semantics.operationKind)) return null;
            if (!equalsAny(edge.semantics.role, "DIRECT", "TRANSFORM", "AGGREGATE")) return null;
            changed |= !"DIRECT".equals(edge.semantics.role); aggregate |= "AGGREGATE".equals(edge.semantics.role);
        }
        String role = !changed ? "DIRECT" : aggregate && "AGGREGATE".equals(path.edges.get(path.edges.size() - 1).semantics.role)
                ? "AGGREGATE" : "TRANSFORM";
        return FactSemantics.publish("VALUE", role, "NONE", "NONE", false);
    }

    private void accountFddiAgainstPaths(dataflow legacy, List<PathDraft> paths, State state) {
        for (relationship relation : legacy.getRelationships()) {
            if (!"fddi".equals(relation.getType())) continue;
            boolean matched = false;
            for (sourceColumn source : relation.getSources()) {
                for (String axis : new String[] {"VALUE", "ROW"}) {
                    FactSemantics semantics = FactSemantics.publish(axis,
                            "VALUE".equals(axis) ? "TRANSFORM" : "UNKNOWN", "NONE", "NONE", false);
                    String sourceRef = resolveSource(source, semantics, state);
                    String targetRef = resolveTarget(relation.getTarget(), semantics, state);
                    if (sourceRef == null || targetRef == null) continue;
                    for (PathDraft path : paths) {
                        if (sourceRef.equals(path.sourceEndpointRef()) && targetRef.equals(path.targetEndpointRef())
                                && axis.equals(path.axis())) { matched = true; break; }
                    }
                    if (matched) break;
                }
                if (matched) break;
            }
            if (matched) markDedicatedMapped(relation, state, "supportPathRefs");
            else accountDedicatedLoss(relation, state, "SLPC_INTERMEDIATE_HOP_UNCOLLAPSIBLE",
                    "Legacy fddi was not published by direction-by-name; no matching proven boundary path was found.");
        }
    }

    private List<Object> interactiveExplainExtensions(dataflow legacy, List<EdgeDraft> edges,
            SlpcObject graph, State state) {
        List<StepDraft> drafts = new ArrayList<StepDraft>();
        Set<String> globallyUsedEdges = new HashSet<String>();
        for (relationship relation : legacy.getRelationships()) {
            LegacyAdapterContext.TypedTransform typed = state.context.typedTransformResolver().resolve(relation);
            if (typed == null) continue;
            if (!equalsAny(typed.operationFamily(), "ARITHMETIC", "COMPARISON", "BOOLEAN", "FUNCTION", "CAST",
                    "CASE", "CONCAT", "AGGREGATE", "WINDOW", "CONSTRUCTOR", "CONTROL_FLOW", "OTHER")
                    || !typed.operationCode().matches("^[A-Z][A-Z0-9_]*$")) {
                accountSemanticGap(relation, "SLPC_EXTENSION_UNSUPPORTED",
                        "Typed transform resolver returned an operation family/code outside the v0.2 registry.", state);
                continue;
            }
            List<EdgeDraft> relationEdges = new ArrayList<EdgeDraft>();
            for (EdgeDraft edge : edges) if (edge.relation == relation) relationEdges.add(edge);
            List<Object> bindings = new ArrayList<Object>(); SlpcObject resultAnchor = null; boolean valid = true;
            Set<String> localEdges = new HashSet<String>(); int ordinal = 1;
            for (LegacyAdapterContext.TypedOperand operand : typed.operands()) {
                if (!operand.roleCode().matches("^[A-Z][A-Z0-9_]*$")) { valid = false; break; }
                EdgeDraft match = null;
                for (EdgeDraft edge : relationEdges) {
                    if (sourceMatches(edge.sourceColumn, operand.sourceId())) {
                        if (match != null) { valid = false; break; }
                        match = edge;
                    }
                }
                if (!valid || match == null || !localEdges.add(match.finalRef)
                        || globallyUsedEdges.contains(match.finalRef)
                        || (resultAnchor != null && !resultAnchor.equals(match.target))) { valid = false; break; }
                resultAnchor = match.target;
                bindings.add(SlpcObject.builder().put("ordinal", ordinal++).put("roleCode", operand.roleCode())
                        .put("edgeRef", match.finalRef).build());
            }
            if (!valid || bindings.isEmpty()) {
                accountSemanticGap(relation, "SLPC_EXTENSION_UNSUPPORTED",
                        "Typed operands did not bind one-to-one to this relationship's graph edges and common result anchor.", state);
                continue;
            }
            globallyUsedEdges.addAll(localEdges);
            drafts.add(new StepDraft(typed.operationFamily(), typed.operationCode(), bindings, resultAnchor,
                    relationEdges.isEmpty() ? null : relationEdges.get(0).transformation));
        }
        if (drafts.isEmpty()) return Collections.emptyList();
        Collections.sort(drafts, new Comparator<StepDraft>() { @Override public int compare(StepDraft left, StepDraft right) {
            return left.sortKey().compareTo(right.sortKey());
        }});
        Map<String, SlpcObject> nodeIndex = SlpcIdentity.index(graph.array("nodes"), "nodeRef");
        Map<String, SlpcObject> edgeIndex = SlpcIdentity.index(graph.array("edges"), "edgeRef");
        List<Object> steps = new ArrayList<Object>();
        for (int index = 0; index < drafts.size(); index++) {
            StepDraft draft = drafts.get(index); int ordinal = index + 1;
            SlpcObject provisional = draft.step(local("igs-", ordinal), "sligsfp1-" + zeros(64), ordinal);
            String fingerprint = SlpcIdentity.interactiveStepFingerprint(provisional, graph,
                    state.endpointByRef, nodeIndex, edgeIndex);
            steps.add(draft.step(local("igs-", ordinal), fingerprint, ordinal));
        }
        state.hasInteractiveExplain = true;
        return Collections.<Object>singletonList(SlpcObject.builder()
                .put("extensionType", "gsp.interactive-explain.v1").put("schemaVersion", "1.0.0")
                .put("criticality", "OPTIONAL").put("payload", SlpcObject.builder().put("steps", steps).build()).build());
    }

    private boolean sourceMatches(sourceColumn source, String sourceId) {
        return sourceId.equals(source.getId()) || sourceId.equals(source.getSource_id());
    }

    private void buildJoinSemantics(dataflow legacy, State state) {
        List<SlpcObject> records = new ArrayList<SlpcObject>(); int ordinal = 1;
        for (relationship relation : legacy.getRelationships()) {
            if (!"join".equals(relation.getType())) continue;
            if (relation.getTarget() == null || relation.getSources().size() != 1) {
                accountLoss(relation, state, "SLPC_JOIN_SEMANTICS_PARTIAL",
                        "Dedicated legacy join record does not contain exactly one typed source/target pair.");
                continue;
            }
            sourceColumn left = relation.getSources().get(0);
            String leftField = resolveSourceField(left, state), rightField = resolveTargetField(relation.getTarget(), state);
            String leftRelation = relationEndpoint(left.getParent_id(), state);
            String rightRelation = relationEndpoint(relation.getTarget().getParent_id(), state);
            if (leftField == null || rightField == null || leftRelation == null || rightRelation == null) {
                accountLoss(relation, state, "SLPC_ENDPOINT_UNRESOLVED",
                        "Dedicated join participants could not all be bound without endpoint-level coarsening.");
                continue;
            }
            String joinType = joinType(relation.getJoinType());
            if ("UNKNOWN".equals(joinType)) {
                state.differences.add(new IntentionalDiffLedger.Entry(IntentionalDiffLedger.Category.KNOWN_UNSUPPORTED_WITH_LOSS,
                        legacyId(relation), "SLPC_JOIN_SEMANTICS_PARTIAL",
                        "The dedicated join record proves its participants but its join-type wire code is outside the SLPC registry."));
            }
            List<Object> keyPairs = "CROSS".equals(joinType) ? Collections.<Object>emptyList()
                    : Collections.<Object>singletonList(SlpcObject.builder().put("ordinal", 1)
                            .put("leftFieldEndpointRef", leftField).put("rightFieldEndpointRef", rightField).put("operator", "OTHER").build());
            accountSemanticGap(relation, "SLPC_JOIN_SEMANTICS_PARTIAL",
                    "Dedicated join records do not carry a stable occurrence link to fdr records or a typed comparison operator; refinesFact arrays remain empty.", state);
            String conditionForm = conditionForm(relation.getClause(), relation.getJoinType(), joinType);
            SlpcObject provisional = SlpcObject.builder().put("joinSemanticsId", "sljoin1-" + zeros(64))
                    .put("statementId", state.statementId).put("joinOrdinal", ordinal++).put("joinType", joinType)
                    .put("conditionForm", conditionForm).put("leftRelationEndpointRef", leftRelation)
                    .put("rightRelationEndpointRef", rightRelation).put("leftSideSemantics", leftSide(joinType))
                    .put("rightSideSemantics", rightSide(joinType)).put("keyPairs", keyPairs)
                    .put("predicate", "CROSS".equals(joinType) ? null : evidence(nonEmpty(relation.getCondition())))
                    .put("refinesFactIds", Collections.emptyList())
                    .put("refinesFactCandidateFingerprints", Collections.emptyList())
                    .put("quality", quality(participantsCanonicalRefs(Arrays2(leftRelation, rightRelation, leftField, rightField), state) ? "PARTIAL" : "UNRESOLVED",
                            "HEURISTIC", "INFERRED", 900000))
                    .put("sourceLocations", sourceLocations(relation, state))
                    .put("extensions", Collections.emptyList()).build();
            SlpcObject record = provisional.toBuilder().put("joinSemanticsId", SlpcIdentity.joinSemanticsId(provisional, state.endpointByRef)).build();
            records.add(record);
            state.coverage.add(new LegacyCoverageReport.Entry("RELATIONSHIP", legacyId(relation),
                    LegacyCoverageReport.Outcome.CONDITIONAL,
                    record.string("joinSemanticsId"), "dedicated join record; operator/refinement correlation remains partial"));
        }
        Collections.sort(records, new Comparator<SlpcObject>() { @Override public int compare(SlpcObject left, SlpcObject right) {
            return left.string("joinSemanticsId").compareTo(right.string("joinSemanticsId"));
        }});
        state.joinSemantics.addAll(records);
    }

    private String joinType(String value) {
        if (value == null) return "UNKNOWN";
        String normalized = value.toLowerCase(java.util.Locale.ROOT);
        if (equalsAny(normalized, "left", "leftouter", "natural_left", "natural_leftouter")) return "LEFT";
        if (equalsAny(normalized, "right", "rightouter", "natural_right", "natural_rightouter")) return "RIGHT";
        if (equalsAny(normalized, "full", "fullouter", "natural_full", "natural_fullouter")) return "FULL";
        if ("cross".equals(normalized)) return "CROSS";
        if (equalsAny(normalized, "semi", "leftsemi", "rightsemi")) return "SEMI";
        if (equalsAny(normalized, "anti", "leftanti", "rightanti")) return "ANTI";
        if ("asof".equals(normalized)) return "ASOF";
        if (equalsAny(normalized, "inner", "join", "natural", "natural_inner", "straight")) return "INNER";
        return "UNKNOWN";
    }

    private String conditionForm(String clause, String legacyJoinType, String joinType) {
        if ("CROSS".equals(joinType)) return "NONE";
        String rawType = safe(legacyJoinType).toLowerCase(java.util.Locale.ROOT);
        if (rawType.equals("natural") || rawType.startsWith("natural_")) return "NATURAL";
        if ("on".equals(clause)) return "ON";
        return nonEmpty(clause) == null ? "NONE" : "OTHER";
    }

    private String leftSide(String joinType) {
        if ("LEFT".equals(joinType) || "SEMI".equals(joinType) || "ANTI".equals(joinType)) return "PRESERVED";
        if ("RIGHT".equals(joinType) || "FULL".equals(joinType)) return "NULL_EXTENDED";
        if ("INNER".equals(joinType)) return "FILTERED";
        if ("CROSS".equals(joinType)) return "NOT_APPLICABLE";
        return "UNKNOWN";
    }

    private String rightSide(String joinType) {
        if ("RIGHT".equals(joinType)) return "PRESERVED"; if ("LEFT".equals(joinType) || "FULL".equals(joinType)) return "NULL_EXTENDED";
        if ("INNER".equals(joinType) || "SEMI".equals(joinType) || "ANTI".equals(joinType)) return "FILTERED";
        if ("CROSS".equals(joinType)) return "NOT_APPLICABLE"; return "UNKNOWN";
    }

    private boolean participantsCanonicalRefs(List<String> refs, State state) {
        for (String ref : refs) if (state.endpointByRef.get(ref).string("canonicalEndpointId") == null) return false;
        return true;
    }

    private List<String> Arrays2(String... values) {
        List<String> result = new ArrayList<String>(); Collections.addAll(result, values); return result;
    }

    private SlpcObject graphShell(State state, String fingerprint, List<Object> nodes, List<Object> edges) {
        return SlpcObject.builder().put("graphRef", "graph-000001").put("graphFingerprint", fingerprint)
                .put("statementId", state.statementId).put("graphOrdinal", 1).put("graphKind", "QUERY_BLOCK")
                .put("analysisCompleteness", "PARTIAL").put("nodes", nodes).put("edges", edges)
                .put("paths", Collections.emptyList()).put("extensions", Collections.emptyList()).build();
    }

    private SlpcObject semanticRecord(String sourceRef, String targetRef, FactSemantics semantics, State state) {
        return SlpcObject.builder().put("sourceEndpointRef", sourceRef).put("targetEndpointRef", targetRef)
                .put("axis", semantics.axis).put("role", semantics.role).put("operationKind", semantics.operationKind)
                .put("operationInputKind", semantics.operationInputKind).build();
    }

    private FactSemantics semantics(relationship relation, sourceColumn source) {
        if ("fdd".equals(relation.getType())) {
            if ("constant".equals(source.getColumn_type())) return FactSemantics.publish("VALUE", "DERIVED", "NONE", "NONE", true);
            boolean transformed = (source.getTransforms() != null && !source.getTransforms().isEmpty()) || nonEmpty(relation.getFunction()) != null;
            return FactSemantics.publish("VALUE", transformed ? "TRANSFORM" : "DIRECT", "NONE", "NONE", false);
        }
        if ("frd".equals(relation.getType())) {
            targetColumn target = relation.getTarget();
            if (target != null && ("system".equals(target.getSource()) || "RelationRows".equals(target.getName()))) {
                return FactSemantics.publishWithGap("ROW", "UNKNOWN", "NONE", "NONE", false,
                        "SLPC_ROLE_UNKNOWN", "Legacy frd RelationRows target proves row influence but not a narrower row role.");
            }
            if (nonEmpty(relation.getFunction()) != null || "function".equals(relation.getEffectType())) {
                return FactSemantics.publish("VALUE", "AGGREGATE", "NONE", "NONE", false);
            }
            return FactSemantics.reject("SLPC_RELATIONSHIP_UNMAPPED",
                    "Legacy frd shape is neither an aggregate value result nor a RelationRows target; direction is quarantined.");
        }
        String clause = source.getClauseType();
        if (equalsAny(clause, "joinCondition", "join")) return FactSemantics.publish("ROW", "JOIN", "NONE", "NONE", false);
        if ("groupby".equals(clause)) return FactSemantics.publish("ROW", "UNKNOWN", "GROUP_BY", "GROUP_KEY", false);
        if (equalsAny(clause, "where", "having", "qualify", "top", "limit", "sample", "filter"))
            return FactSemantics.publish("ROW", "FILTER", "NONE", "NONE", false);
        if (equalsAny(clause, "orderby", "sortby")) {
            return FactSemantics.reject("SLPC_OPERATION_UNSUPPORTED",
                    "Legacy ORDER BY/SORT BY evidence requires DatasetOperationInfluence(SORT); it must not be published as a ROW fact.");
        }
        return FactSemantics.publishWithGap("ROW", "UNKNOWN", "NONE", "NONE", false,
                "SLPC_OPERATION_UNSUPPORTED", "Unrecognized or absent ESqlClause is retained only as ROW/UNKNOWN.");
    }

    private SlpcObject transformationEvidence(relationship relation, sourceColumn source) {
        if (source.getTransforms() != null && !source.getTransforms().isEmpty()) {
            List<String> values = new ArrayList<String>();
            for (transform value : source.getTransforms()) if (value.getCode() != null) values.add(value.getCode());
            if (!values.isEmpty()) {
                List<byte[]> frames = new ArrayList<byte[]>();
                for (String value : values) frames.add(SlpcIdentity.string(value));
                return evidence("GSP-LEGACY-TRANSFORM-SEQUENCE-SHA256-V1",
                        SlpcIdentity.framedList(frames));
            }
        }
        return evidence(nonEmpty(relation.getFunction()));
    }

    private String predicateText(relationship relation, FactSemantics semantics) {
        return "ROW".equals(semantics.axis) ? nonEmpty(relation.getCondition()) : null;
    }

    private SlpcObject evidence(String text) {
        if (text == null) return null;
        // Persist only the hash: legacy text may include literals or credentials and has no redaction provenance.
        return evidence("RAW-UTF8-SHA256-V1", text.getBytes(StandardCharsets.UTF_8));
    }

    private SlpcObject evidence(String algorithm, byte[] bytes) {
        SlpcObject fingerprint = SlpcObject.builder().put("algorithm", algorithm)
                .put("value", sha256(bytes)).build();
        return SlpcObject.builder().put("fingerprint", fingerprint).putNull("sourceLocation")
                .put("locationNullReason", "UNKNOWN").build();
    }

    private SlpcObject artifact(LegacyAdapterContext context) {
        SlpcObject hash = SlpcObject.builder().put("algorithm", "SHA256").put("value", context.contentSha256()).build();
        SlpcObject withoutId = SlpcObject.builder().put("artifactId", "slart1-" + zeros(64))
                .put("sourceKind", context.sourceKind()).put("logicalLocator", context.logicalLocator())
                .put("sqlDialect", context.sqlDialect()).put("contentHash", hash).put("mediaType", "application/sql").build();
        return withoutId.toBuilder().put("artifactId", SlpcIdentity.artifactId(withoutId)).build();
    }

    private SlpcObject statement(SlpcObject artifact, LegacyAdapterContext context, dataflow legacy) {
        SlpcObject.Builder builder = SlpcObject.builder().put("statementId", "slstmt1-" + zeros(64))
                .put("artifactId", artifact.string("artifactId")).put("statementIndex", 1)
                .put("kind", context.statementKind());
        SlpcObject location = statementSourceLocation(artifact.string("artifactId"), legacy);
        if (location != null) builder.put("sourceLocation", location);
        SlpcObject withoutId = builder.build();
        return withoutId.toBuilder().put("statementId", SlpcIdentity.statementId(withoutId)).build();
    }

    private List<Object> statementSourceLocations(SlpcObject statement) {
        Object value = statement.get("sourceLocation");
        return value == null ? Collections.<Object>emptyList() : Collections.singletonList(value);
    }

    private SlpcObject statementSourceLocation(String artifactId, dataflow legacy) {
        List<String> coordinates = new ArrayList<String>();
        for (table relation : dataflow.getAllTables(legacy)) {
            coordinates.add(relation.getCoordinate());
            for (column field : relation.getColumns()) coordinates.add(field.getCoordinate());
        }
        for (procedure routine : allProcedures(legacy)) {
            coordinates.add(routine.getCoordinate());
            for (argument parameter : routine.getArguments()) coordinates.add(parameter.getCoordinate());
        }
        for (gudusoft.gsqlparser.dlineage.dataflow.model.xml.process process : legacy.getProcesses()) {
            coordinates.add(process.getCoordinate());
        }
        for (relationship relation : legacy.getRelationships()) {
            if (relation.getTarget() != null) coordinates.add(relation.getTarget().getCoordinate());
            for (sourceColumn source : relation.getSources()) coordinates.add(source.getCoordinate());
            for (sourceColumn callee : relation.getCallees()) coordinates.add(callee.getCoordinate());
        }
        int startLine = Integer.MAX_VALUE, startColumn = Integer.MAX_VALUE, endLine = -1, endColumn = -1;
        for (String coordinate : coordinates) {
            int[] parsed = parsedCoordinate(coordinate);
            if (parsed == null) continue;
            if (parsed[0] < startLine || parsed[0] == startLine && parsed[1] < startColumn) {
                startLine = parsed[0]; startColumn = parsed[1];
            }
            if (parsed[2] > endLine || parsed[2] == endLine && parsed[3] > endColumn) {
                endLine = parsed[2]; endColumn = parsed[3];
            }
        }
        return startLine == Integer.MAX_VALUE ? null : sourceLocation(artifactId, startLine, startColumn, endLine, endColumn);
    }

    private List<Object> sourceLocations(relationship relation, State state) {
        Map<String, SlpcObject> unique = new TreeMap<String, SlpcObject>();
        if (relation.getTarget() != null) addSourceLocation(unique, relation.getTarget().getCoordinate(), state);
        for (sourceColumn source : relation.getSources()) addSourceLocation(unique, source.getCoordinate(), state);
        for (sourceColumn callee : relation.getCallees()) addSourceLocation(unique, callee.getCoordinate(), state);
        if (!unique.isEmpty()) state.hasSourceLocation = true;
        return new ArrayList<Object>(unique.values());
    }

    private List<Object> sourceLocations(String coordinate, State state) {
        Map<String, SlpcObject> unique = new TreeMap<String, SlpcObject>();
        addSourceLocation(unique, coordinate, state);
        if (!unique.isEmpty()) state.hasSourceLocation = true;
        return new ArrayList<Object>(unique.values());
    }

    private void indexLegacySourceLocations(dataflow legacy, State state) {
        for (table relation : dataflow.getAllTables(legacy)) {
            state.sourceLocationsByLegacyEvidence.put("table:" + safeId(relation.getId(), relation.getName()),
                    sourceLocations(relation.getCoordinate(), state));
            for (column field : relation.getColumns()) {
                state.sourceLocationsByLegacyEvidence.put("column:" + safeId(field.getId(), field.getName()),
                        sourceLocations(field.getCoordinate(), state));
            }
        }
        for (relationship relation : legacy.getRelationships()) {
            state.sourceLocationsByLegacyEvidence.put(legacyId(relation), sourceLocations(relation, state));
        }
    }

    private void addSourceLocation(Map<String, SlpcObject> target, String coordinate, State state) {
        int[] parsed = parsedCoordinate(coordinate);
        if (parsed == null) return;
        SlpcObject value = sourceLocation(state.artifact.string("artifactId"), parsed[0], parsed[1], parsed[2], parsed[3]);
        target.put(parsed[0] + ":" + parsed[1] + ":" + parsed[2] + ":" + parsed[3], value);
    }

    private int[] parsedCoordinate(String coordinate) {
        if (coordinate == null) return null;
        Matcher matcher = LEGACY_COORDINATE.matcher(coordinate);
        if (!matcher.find()) return null;
        int startLine, startColumn, startArtifact, endLine, endColumn, endArtifact;
        try {
            startLine = Integer.parseInt(matcher.group(1)); startColumn = Integer.parseInt(matcher.group(2));
            startArtifact = Integer.parseInt(matcher.group(3)); endLine = Integer.parseInt(matcher.group(4));
            endColumn = Integer.parseInt(matcher.group(5)); endArtifact = Integer.parseInt(matcher.group(6));
        } catch (NumberFormatException invalid) { return null; }
        if (startLine < 1 || startColumn < 1 || endLine < 1 || endColumn < 1
                || startArtifact != 0 || endArtifact != 0
                || endLine < startLine || endLine == startLine && endColumn < startColumn) return null;
        return new int[] {startLine, startColumn, endLine, endColumn};
    }

    private SlpcObject sourceLocation(String artifactId, int startLine, int startColumn, int endLine, int endColumn) {
        return SlpcObject.builder().put("artifactId", artifactId).put("startLine", startLine)
                .put("startColumn", startColumn).put("endLine", endLine).put("endColumn", endColumn).build();
    }

    private List<Object> capabilities(State state) {
        List<Object> result = new ArrayList<Object>();
        Set<String> partial = new LinkedHashSet<String>();
        Collections.addAll(partial, "FACT_VALUE", "FACT_ROW_FILTER", "FACT_ROW_JOIN", "FACT_GROUP_BY",
                "TRANSFORM_EVIDENCE", "EXACT_IDENTIFIER_IDENTITY", "INTERMEDIATE_GRAPH", "JOIN_SEMANTICS",
                "STATEMENT_OPERATION", "LITERAL_PROVENANCE", "OBJECT_RELATIONSHIP", "FOREIGN_KEY_RELATIONSHIP",
                "PHYSICAL_HOP_COLLAPSE", "STORAGE_ASSET_IDENTITY", "ROUTINE_CALL", "STREAM_DEFINITION",
                "OBJECT_RENAME_SWAP_CLONE");
        if (state.hasInteractiveExplain) partial.add("INTERACTIVE_EXPLAIN");
        if (state.hasSourceLocation) partial.add("SOURCE_LOCATION");
        if (state.hasRoutineBinding) {
            partial.add("SCOPED_OBJECTS"); partial.add("ROUTINE_OVERLOAD_IDENTITY");
        }
        if (state.hasRoutineParameterFlow) partial.add("ROUTINE_PARAMETER_FLOW");
        for (String code : SlpcSemanticValidator.CAPABILITIES) {
            String status = partial.contains(code) ? "PARTIAL" : "UNSUPPORTED";
            if ("SECRET_REDACTION".equals(code)) status = "SUPPORTED";
            result.add(SlpcObject.builder().put("code", code).put("status", status).build());
        }
        state.diagnostics.add(diagnostic("SLPC_ADAPTER_CAPABILITY_GAP", "INFO", "DOCUMENT", null,
                "PARTIAL capabilities are bounded by completed legacy POJO evidence and caller-supplied identity/typed-transform proof; unsupported shapes remain candidates or diagnostics."));
        return result;
    }

    private SlpcObject producer(State state) {
        return SlpcObject.builder().put("engineKind", "LEGACY_DLINEAGE").put("engineVersion", state.context.engineVersion())
                .put("adapterName", ADAPTER_NAME).put("adapterVersion", ADAPTER_VERSION).put("capabilities", capabilities(state)).build();
    }

    private void accountUnsupportedRelationship(relationship relation, State state) {
        accountLoss(relation, state, "SLPC_RELATIONSHIP_UNMAPPED",
                "Legacy relationship type '" + safe(relation.getType()) + "' has no proven v0.2 mapping in M1.");
    }

    private void accountSemanticGap(relationship relation, String code, String message, State state) {
        String key = legacyId(relation) + "\u0000" + code;
        if (!state.semanticGapKeys.add(key)) return;
        state.differences.add(new IntentionalDiffLedger.Entry(IntentionalDiffLedger.Category.KNOWN_UNSUPPORTED_WITH_LOSS,
                legacyId(relation), code, message));
        state.diagnostics.add(diagnostic(code, "WARN", "DOCUMENT", null, message));
    }

    private void accountLoss(relationship relation, State state, String code, String message) {
        state.coverage.add(new LegacyCoverageReport.Entry("RELATIONSHIP", legacyId(relation),
                LegacyCoverageReport.Outcome.UNSUPPORTED_WITH_LOSS, null, code));
        state.differences.add(new IntentionalDiffLedger.Entry(IntentionalDiffLedger.Category.KNOWN_UNSUPPORTED_WITH_LOSS,
                legacyId(relation), code, message));
        state.diagnostics.add(diagnostic(code, "WARN", "DOCUMENT", null, message));
    }

    private void accountErrors(dataflow legacy, State state) {
        int index = 0;
        for (gudusoft.gsqlparser.dlineage.dataflow.model.xml.error ignored : legacy.getErrors()) {
            index++;
            state.coverage.add(new LegacyCoverageReport.Entry("ERROR", "error-" + index,
                    LegacyCoverageReport.Outcome.CONDITIONAL, null, "represented by document diagnostic"));
            state.diagnostics.add(diagnostic("GSP_LEGACY_ANALYSIS_ERROR", "WARN", "DOCUMENT", null,
                    "The completed legacy analysis result contains an error record; its free text is intentionally not copied."));
        }
    }

    private int countLegacyRecords(dataflow legacy) {
        int count = legacy.getRelationships().size() + legacy.getErrors().size() + legacy.getProcesses().size();
        for (table relation : dataflow.getAllTables(legacy)) count += 1 + relation.getColumns().size();
        for (procedure routine : legacy.getProcedures()) count += 1 + routine.getArguments().size();
        for (oraclePackage pkg : legacy.getPackages()) {
            count += 1 + pkg.getArguments().size();
            for (procedure routine : pkg.getProcedures()) count += 1 + routine.getArguments().size();
        }
        return count;
    }

    private SlpcObject diagnostic(String code, String severity, String scope, String ref, String message) {
        return SlpcObject.builder().put("code", code).put("severity", severity).put("scope", scope).put("ref", ref)
                .put("message", message).putNull("sourceLocation").put("extensions", Collections.emptyList()).build();
    }

    private String resolveTarget(targetColumn target, FactSemantics semantics, State state) {
        if (target == null) return null;
        if ("ROW".equals(semantics.axis)) return relationEndpoint(target.getParent_id(), state);
        String result = state.endpointByLegacyId.get(target.getId());
        if (result == null) result = state.endpointByLegacyId.get(target.getTarget_id());
        return endpointAtValueLevel(result, state);
    }

    private String resolveTargetField(targetColumn target, State state) {
        String result = state.endpointByLegacyId.get(target.getId());
        if (result == null) result = state.endpointByLegacyId.get(target.getTarget_id());
        return endpointAtLevel(result, "FIELD", state);
    }

    private String resolveSource(sourceColumn source, FactSemantics semantics, State state) {
        String result = state.endpointByLegacyId.get(source.getId());
        if (result == null) result = state.endpointByLegacyId.get(source.getSource_id());
        result = endpointAtValueLevel(result, state);
        if (result == null && "system".equals(source.getSource())
                && ("ROW".equals(semantics.axis) || "AGGREGATE".equals(semantics.role))) {
            result = relationEndpoint(source.getParent_id(), state);
        }
        return result;
    }

    private String resolveSourceField(sourceColumn source, State state) {
        String result = state.endpointByLegacyId.get(source.getId());
        if (result == null) result = state.endpointByLegacyId.get(source.getSource_id());
        return endpointAtLevel(result, "FIELD", state);
    }

    private String relationEndpoint(String legacyId, State state) {
        return endpointAtLevel(state.endpointByLegacyId.get(legacyId), "RELATION", state);
    }

    private String relationEndpoint(targetColumn target, State state) {
        if (target == null) return null;
        String result = relationEndpoint(target.getParent_id(), state);
        if (result == null) result = relationEndpoint(target.getTarget_id(), state);
        if (result == null) result = relationEndpoint(target.getId(), state);
        return result;
    }

    private String relationEndpoint(sourceColumn source, State state) {
        if (source == null) return null;
        String result = relationEndpoint(source.getParent_id(), state);
        if (result == null) result = relationEndpoint(source.getSource_id(), state);
        if (result == null) result = relationEndpoint(source.getId(), state);
        return result;
    }

    private String endpointAtLevel(String ref, String level, State state) {
        SlpcObject endpoint = ref == null ? null : state.endpointByRef.get(ref);
        return endpoint != null && level.equals(endpoint.string("endpointLevel")) ? ref : null;
    }

    private String endpointAtValueLevel(String ref, State state) {
        SlpcObject endpoint = ref == null ? null : state.endpointByRef.get(ref);
        return endpoint != null && equalsAny(endpoint.string("endpointLevel"), "FIELD", "VARIABLE") ? ref : null;
    }

    private SlpcObject targetAnchor(targetColumn target, FactSemantics semantics, State state) {
        if (target == null) return null;
        boolean row = "ROW".equals(semantics.axis);
        NodeDraft node = row ? nodeByLegacyId(state, target.getParent_id())
                : nodeByLegacyId(state, target.getId(), target.getTarget_id());
        if (node != null) return nodeAnchor(node.finalRef, row ? "ROW" : "VALUE");
        String endpoint = resolveTarget(target, semantics, state);
        return endpoint == null ? null : endpointAnchor(endpoint, row ? "ROW" : "VALUE");
    }

    private SlpcObject sourceAnchor(sourceColumn source, FactSemantics semantics, State state) {
        if (semantics.derived) return null;
        NodeDraft node = nodeByLegacyId(state, source.getId(), source.getSource_id());
        if (node == null && "system".equals(source.getSource())
                && ("ROW".equals(semantics.axis) || "AGGREGATE".equals(semantics.role))) {
            node = nodeByLegacyId(state, source.getParent_id());
        }
        if (node != null) return nodeAnchor(node.finalRef, "ROW".equals(semantics.axis) ? "ROW" : "VALUE");
        String endpoint = resolveSource(source, semantics, state);
        return endpoint == null ? null : endpointAnchor(endpoint, "ROW".equals(semantics.axis) ? "ROW" : "VALUE");
    }

    private NodeDraft nodeByLegacyId(State state, String... ids) {
        for (String id : ids) if (id != null && state.intermediateNodeByLegacyId.containsKey(id)) return state.intermediateNodeByLegacyId.get(id);
        return null;
    }

    private SlpcObject endpointAnchor(String ref, String port) { return SlpcObject.builder().put("kind", "ENDPOINT").put("endpointRef", ref).put("portCode", port).build(); }
    private SlpcObject nodeAnchor(String ref, String port) { return SlpcObject.builder().put("kind", "NODE").put("nodeRef", ref).put("portCode", port).build(); }

    private List<Object> displaySegments(table relation, column field) {
        List<Object> result = new ArrayList<Object>();
        if (nonEmpty(relation.getServer()) != null) result.add(display("SERVER", relation.getServer()));
        if (nonEmpty(relation.getDatabase()) != null) result.add(display("DATABASE", relation.getDatabase()));
        if (nonEmpty(relation.getSchema()) != null) result.add(display("SCHEMA", relation.getSchema()));
        result.add(display("OBJECT", safe(relation.getName())));
        if (field != null) result.add(display("COLUMN", safe(field.getName())));
        return result;
    }

    private SlpcObject display(String kind, String value) {
        return SlpcObject.builder().put("kind", kind).put("display", value)
                .put("inputForm", "ENGINE_SYNTHETIC").put("provenance", "ENGINE_SYNTHETIC").build();
    }

    private String objectKind(table relation, State state) {
        if (relation.isResultSet()) {
            String type = safe(relation.getType());
            ResultSetType resultSetType = ResultSetType.of(type);
            if (resultSetType == ResultSetType.cte || "with_cte".equals(type)) return "CTE";
            if (resultSetType == ResultSetType.result_of) return "DERIVED_TABLE";
            return "RESULT_SET";
        }
        if (relation.isView()) return "VIEW";
        if (relation.isStream()) return "STREAM";
        if (relation.isStage()) return "STAGE";
        if (relation.isFile()) return "FILE";
        if (relation.isCursor()) return "CURSOR";
        if (relation.isVariable()) return "SCALAR_VARIABLE";
        if ("procedure".equalsIgnoreCase(relation.getType())) return "PROCEDURE";
        if ("CREATE_EXTERNAL_TABLE".equals(operationKind(state.context.statementKind()))
                && (relation.isTarget() || createdInSql(relation))) return "EXTERNAL_TABLE";
        if ("CREATE_MATERIALIZED_VIEW".equals(operationKind(state.context.statementKind()))
                && (relation.isTarget() || createdInSql(relation))) return "MATERIALIZED_VIEW";
        if (relation.isTable()) return "TABLE";
        return "UNKNOWN";
    }

    private String routineObjectKind(table relation) {
        return "function".equalsIgnoreCase(relation.getType()) ? "FUNCTION" : "PROCEDURE";
    }

    private String endpointLevel(table relation, String legacyKind) {
        if ("PROCEDURE".equals(legacyKind)) return "ROUTINE";
        if (relation.isVariable() || relation.isCursor()) return "VARIABLE";
        return "RELATION";
    }

    private String nodeKind(table relation) {
        String raw = safe(relation.getType());
        if ("with_cte".equals(raw)) return "CTE";
        ResultSetType type = ResultSetType.of(raw);
        if (type == null) return "OTHER";
        switch (type) {
            case select_list: return "SELECT_LIST";
            case cte: return "CTE";
            case insert_select: return "INSERT_SELECT";
            case update_select: return "UPDATE_SELECT";
            case update_set: return "UPDATE_SET";
            case merge_update: return "MERGE_UPDATE";
            case merge_insert: return "MERGE_INSERT";
            case output: return "OUTPUT";
            case pivot_table: return "PIVOT";
            case unpivot_table: return "UNPIVOT";
            case alias: return "ALIAS";
            case function: return "FUNCTION_RESULT";
            case array: return "ARRAY";
            case struct: return "STRUCT";
            case result_of: return "RESULT_OF";
            case variable: return "VARIABLE";
            default: return "OTHER";
        }
    }

    private String nodeKindForField(table relation) {
        // A projected field is not automatically a SQL alias.  The legacy
        // column POJO has no dedicated alias discriminator after the default
        // finish path, so retain the node without inventing ALIAS semantics.
        return "OTHER";
    }

    private boolean isIntermediate(table relation) {
        return relation.isResultSet();
    }

    private boolean isRelationRows(column field) {
        return "system".equals(field.getSource()) || "RelationRows".equals(field.getName());
    }

    private boolean hasCandidateTables(table relation) {
        return relation.getCandidateTables() != null && !relation.getCandidateTables().isEmpty();
    }

    private boolean hasCandidateParents(sourceColumn source) {
        return source.getCandidateParents() != null && !source.getCandidateParents().isEmpty();
    }

    /**
     * These legacy effect codes describe object/storage operations or an
     * assumed dependency.  Treating them as ordinary VALUE/ROW facts would be
     * a semantic invention; a later M1 slice must map them to the corresponding
     * statement operation, object relationship, or quality model.
     */
    private boolean unsupportedFactEffect(String value) {
        return equalsAny(value,
                "rename_table", "swap_table", "append_from", "like_table",
                "clone_database", "clone_schema", "clone_table", "unload", "copy",
                "foreign_key", "create_synonym", "exchange_partition", "synonym",
                "drop_table", "drop_table_column", "add_table_column", "truncate_table",
                "external_script_passthrough");
    }

    /** Data dependencies remain useful, but a second typed operation is owed. */
    private boolean effectNeedsAdditionalMapping(String value) {
        return equalsAny(value, "create_view", "create_table", "trigger", "expand_star");
    }

    private boolean hasUnavailableIdentity(List<EndpointDraft> drafts) {
        for (EndpointDraft draft : drafts) if (draft.canonical == null) return true;
        return false;
    }

    /** Only a dedicated alias field is accepted as SQL-proven local naming evidence. */
    private String provenLocalName(table relation) {
        return nonEmpty(relation.getAlias());
    }

    private void containmentLoss(table relation, State state, String message) {
        String owner = safeId(relation.getId(), safe(relation.getName()));
        state.differences.add(new IntentionalDiffLedger.Entry(IntentionalDiffLedger.Category.KNOWN_UNSUPPORTED_WITH_LOSS,
                owner, "GSP_LEGACY_CONTAINMENT_UNRESOLVED", message));
    }

    private void breakContainmentCycles(List<table> intermediate, IdentityHashMap<table, table> parentByTable, State state) {
        Set<table> settled = Collections.newSetFromMap(new IdentityHashMap<table, Boolean>());
        for (table start : intermediate) {
            if (settled.contains(start)) continue;
            List<table> path = new ArrayList<table>();
            IdentityHashMap<table, Integer> position = new IdentityHashMap<table, Integer>();
            table current = start;
            while (current != null && !settled.contains(current)) {
                Integer repeatedAt = position.get(current);
                if (repeatedAt != null) {
                    List<table> cycle = new ArrayList<table>(path.subList(repeatedAt, path.size()));
                    Collections.sort(cycle, tableComparator());
                    table detached = cycle.get(0);
                    parentByTable.remove(detached);
                    containmentLoss(detached, state,
                            "Legacy intermediate containment contains a cycle; one deterministic link was removed and the node retained as a root.");
                    break;
                }
                position.put(current, path.size()); path.add(current); current = parentByTable.get(current);
            }
            settled.addAll(path);
        }
    }

    private Comparator<table> sourceTableComparator() {
        return new Comparator<table>() { @Override public int compare(table left, table right) {
            int coordinate = compareCoordinates(left.getCoordinate(), right.getCoordinate());
            return coordinate != 0 ? coordinate : tableComparator().compare(left, right);
        }};
    }

    private Comparator<PendingNode> pendingNodeComparator() {
        return new Comparator<PendingNode>() { @Override public int compare(PendingNode left, PendingNode right) {
            String leftCoordinate = left.field == null ? left.relation.getCoordinate() : left.field.getCoordinate();
            String rightCoordinate = right.field == null ? right.relation.getCoordinate() : right.field.getCoordinate();
            int coordinate = compareCoordinates(leftCoordinate, rightCoordinate);
            if (coordinate != 0) return coordinate;
            String leftKey = (left.field == null ? "0" : "1") + "\u0000" + safe(left.relation.getId()) + "\u0000"
                    + safe(left.field == null ? null : left.field.getId()) + "\u0000" + safe(left.relation.getName()) + "\u0000"
                    + safe(left.field == null ? null : left.field.getName());
            String rightKey = (right.field == null ? "0" : "1") + "\u0000" + safe(right.relation.getId()) + "\u0000"
                    + safe(right.field == null ? null : right.field.getId()) + "\u0000" + safe(right.relation.getName()) + "\u0000"
                    + safe(right.field == null ? null : right.field.getName());
            return utf8Compare(leftKey, rightKey);
        }};
    }

    private int compareCoordinates(String left, String right) {
        long[] a = firstCoordinate(left), b = firstCoordinate(right);
        for (int index = 0; index < a.length; index++) {
            if (a[index] < b[index]) return -1;
            if (a[index] > b[index]) return 1;
        }
        return 0;
    }

    private long[] firstCoordinate(String value) {
        long unavailable = Long.MAX_VALUE;
        long[] result = {unavailable, unavailable, unavailable};
        if (value == null) return result;
        int open = value.indexOf('['), close = value.indexOf(']', open + 1);
        if (open < 0 || close < 0) return result;
        String[] parts = value.substring(open + 1, close).split(",", -1);
        for (int index = 0; index < result.length && index < parts.length; index++) {
            try {
                long parsed = Long.parseLong(parts[index].trim());
                result[index] = parsed < 0 ? unavailable : parsed;
            } catch (NumberFormatException ignored) {
                result[index] = unavailable;
            }
        }
        return result;
    }

    private void putNodeLegacyId(Map<String, NodeDraft> target, String id, NodeDraft node) {
        if (id == null) return;
        NodeDraft previous = target.put(id, node);
        if (previous != null && previous != node) throw new IllegalStateException("duplicate legacy intermediate identifier: " + id);
    }

    private boolean isCanonicalFact(SlpcObject semantic, Map<String, SlpcObject> endpoints) {
        String target = semantic.string("targetEndpointRef"); if (endpoints.get(target).string("canonicalEndpointId") == null) return false;
        String source = semantic.string("sourceEndpointRef"); return source == null || endpoints.get(source).string("canonicalEndpointId") != null;
    }

    private boolean isCanonicalIdentity(SlpcObject identity) {
        String kind = identity.string("kind"); return "COMPOSITE_EXACT".equals(kind) || "AUTHORITATIVE_EXTERNAL".equals(kind) || "URI_EXACT".equals(kind);
    }

    private String candidateReason(SlpcObject semantic) {
        return "IDENTITY_UNAVAILABLE";
    }

    private SlpcObject occurrenceQuality(String resolution) {
        return quality(resolution, "EXACT", "PROVEN", 1000000);
    }

    private SlpcObject quality(String resolution, String evaluation, String proof, int confidence) {
        return SlpcObject.builder().put("resolutionGrade", resolution).put("evaluationModel", evaluation)
                .put("semanticProof", proof).put("dynamic", false).put("confidenceMicros", confidence).build();
    }

    private SlpcObject redactedLiteral(State state, int redactionOrdinal) {
        String kind = "UNKNOWN";
        SlpcObject fingerprint = SlpcObject.builder().put("algorithm", "SLPC-REDACTED-LITERAL-V1")
                .put("value", SlpcIdentity.redactedLiteralHash(state.context.sqlDialect(), kind, redactionOrdinal)).build();
        return SlpcObject.builder().put("inputOrdinal", 1).put("literalKind", kind)
                .put("text", "<SLPC-REDACTED:" + kind + ":" + redactionOrdinal + ">")
                .put("redactionOrdinal", redactionOrdinal).put("fingerprint", fingerprint)
                .putNull("sourceLocation").put("locationNullReason", "UNKNOWN").build();
    }

    private SlpcObject qualitySummary(String eligibility, String resolution, int count) {
        return SlpcObject.builder().put("projectionEligibility", eligibility).put("resolutionGrade", resolution)
                .put("evaluationModel", "EXACT").put("semanticProof", "PROVEN").put("dynamic", false)
                .put("confidenceMicros", 1000000).put("evidenceCount", count).build();
    }

    private boolean allCanonical(List<String> keys, State state) { for (String key : keys) if (!state.factGroups.get(key).canonical) return false; return true; }

    private static Comparator<FactGroup> factGroupComparator() { return new Comparator<FactGroup>() { @Override public int compare(FactGroup left, FactGroup right) { return left.semanticKey.compareTo(right.semanticKey); }}; }
    private static Comparator<RelationshipGroup> relationshipGroupComparator() { return new Comparator<RelationshipGroup>() { @Override public int compare(RelationshipGroup left, RelationshipGroup right) { return left.semanticKey.compareTo(right.semanticKey); }}; }
    private static Comparator<NodeDraft> nodeFingerprintComparator() { return new Comparator<NodeDraft>() { @Override public int compare(NodeDraft left, NodeDraft right) { return left.fingerprint.compareTo(right.fingerprint); }}; }
    private static Comparator<EdgeDraft> edgeFingerprintComparator() { return new Comparator<EdgeDraft>() { @Override public int compare(EdgeDraft left, EdgeDraft right) { return left.fingerprint.compareTo(right.fingerprint); }}; }
    private static Comparator<PathDraft> pathFingerprintComparator() { return new Comparator<PathDraft>() { @Override public int compare(PathDraft left, PathDraft right) { return left.fingerprint.compareTo(right.fingerprint); }}; }
    private static Comparator<table> tableComparator() { return new Comparator<table>() { @Override public int compare(table left, table right) {
        return utf8Compare(safe(left.getId()) + "\u0000" + safe(left.getName()),
                safe(right.getId()) + "\u0000" + safe(right.getName()));
    }}; }

    private static void putLegacyRef(Map<String, String> refs, String id, String ref) { if (id != null && !refs.containsKey(id)) refs.put(id, ref); }
    private static String legacyId(relationship relation) { return safeId(relation.getId(), "relationship:" + safe(relation.getType())); }
    private static String safeId(String id, String fallback) { return id == null || id.isEmpty() ? fallback : id; }
    private static String safe(String value) { return value == null ? "" : value; }
    private static String nonEmpty(String value) { return value == null || value.isEmpty() ? null : value; }
    private static String local(String prefix, int ordinal) { return String.format("%s%06d", prefix, ordinal); }
    private static String zeros(int count) { StringBuilder result = new StringBuilder(); for (int index = 0; index < count; index++) result.append('0'); return result.toString(); }
    private static String join(List<String> values) { StringBuilder result = new StringBuilder(); for (String value : values) { if (result.length() > 0) result.append(','); result.append(value); } return result.toString(); }
    private static boolean equalsAny(String value, String... choices) { if (value == null) return false; for (String choice : choices) if (value.equals(choice)) return true; return false; }
    private static boolean equalValues(Object left, Object right) { return left == null ? right == null : left.equals(right); }
    private static int utf8Compare(String left, String right) { byte[] a = left.getBytes(StandardCharsets.UTF_8), b = right.getBytes(StandardCharsets.UTF_8); int common = Math.min(a.length, b.length); for (int index = 0; index < common; index++) { int difference = (a[index] & 255) - (b[index] & 255); if (difference != 0) return difference; } return a.length - b.length; }
    private static String sha256(byte[] value) { try { byte[] digest = MessageDigest.getInstance("SHA-256").digest(value); StringBuilder result = new StringBuilder(); for (byte item : digest) result.append(String.format("%02x", item & 255)); return result.toString(); } catch (NoSuchAlgorithmException impossible) { throw new IllegalStateException(impossible); } }

    private final class State {
        private final LegacyAdapterContext context;
        private SlpcObject artifact, statement; private String statementId;
        private final List<Object> endpoints = new ArrayList<Object>(), facts = new ArrayList<Object>(), factCandidates = new ArrayList<Object>(), occurrences = new ArrayList<Object>(), diagnostics = new ArrayList<Object>(), graphs = new ArrayList<Object>(), statementOperations = new ArrayList<Object>(), joinSemantics = new ArrayList<Object>(), objectRelationships = new ArrayList<Object>(), objectRelationshipCandidates = new ArrayList<Object>();
        private final Map<String, SlpcObject> endpointByRef = new LinkedHashMap<String, SlpcObject>();
        private final Map<String, String> endpointByLegacyId = new HashMap<String, String>();
        private final IdentityHashMap<table, EndpointDraft> tableDrafts = new IdentityHashMap<table, EndpointDraft>();
        private final IdentityHashMap<column, EndpointDraft> columnDrafts = new IdentityHashMap<column, EndpointDraft>();
        private final IdentityHashMap<procedure, EndpointDraft> routineDrafts = new IdentityHashMap<procedure, EndpointDraft>();
        private final IdentityHashMap<procedure, LegacyAdapterContext.RoutineBinding> routineBindings =
                new IdentityHashMap<procedure, LegacyAdapterContext.RoutineBinding>();
        private final IdentityHashMap<procedure, Map<String, EndpointDraft>> parameterDraftsByRoutine =
                new IdentityHashMap<procedure, Map<String, EndpointDraft>>();
        private final IdentityHashMap<EndpointDraft, LegacyAdapterContext.RoutineParameterBinding> parameterBindingByDraft =
                new IdentityHashMap<EndpointDraft, LegacyAdapterContext.RoutineParameterBinding>();
        private final Map<String, String> parameterRefByKey = new HashMap<String, String>();
        private final Map<String, List<Object>> sourceLocationsByLegacyEvidence =
                new HashMap<String, List<Object>>();
        private final Set<String> mappedArgumentIds = new HashSet<String>();
        private final IdentityHashMap<table, String> tableRefs = new IdentityHashMap<table, String>();
        private final IdentityHashMap<column, String> columnRefs = new IdentityHashMap<column, String>();
        private final IdentityHashMap<table, NodeDraft> intermediateTableNodes = new IdentityHashMap<table, NodeDraft>();
        private final IdentityHashMap<column, NodeDraft> intermediateColumnNodes = new IdentityHashMap<column, NodeDraft>();
        private final Map<String, NodeDraft> intermediateNodeByLegacyId = new HashMap<String, NodeDraft>();
        private final IdentityHashMap<table, String> intermediateTableRefs = new IdentityHashMap<table, String>();
        private final IdentityHashMap<column, String> intermediateColumnRefs = new IdentityHashMap<column, String>();
        private final Map<String, FactGroup> factGroups = new LinkedHashMap<String, FactGroup>();
        private final Map<String, RelationshipGroup> relationshipGroups = new LinkedHashMap<String, RelationshipGroup>();
        private final List<FactOccurrenceDraft> factOccurrenceDrafts = new ArrayList<FactOccurrenceDraft>();
        private final Set<String> dedicatedRelationshipAccounting = new HashSet<String>();
        private int nextRedactionOrdinal = 1;
        private int legacyInputCount;
        private boolean hasLegacyEndpointAmbiguity;
        private boolean hasStorageIdentityUnavailable, hasPhysicalHopCollapse, hasInteractiveExplain;
        private boolean hasRoutineBinding, hasRoutineParameterFlow, hasSourceLocation;
        private boolean pathCycleObserved, pathEnumerationTruncated;
        private final List<LegacyCoverageReport.Entry> coverage = new ArrayList<LegacyCoverageReport.Entry>();
        private final List<IntentionalDiffLedger.Entry> differences = new ArrayList<IntentionalDiffLedger.Entry>();
        private final Set<String> semanticGapKeys = new HashSet<String>();
        private State(LegacyAdapterContext context) { this.context = context; }

        private LegacyAdaptation finish() {
            SlpcObject root = SlpcDocument.rootBuilder().put("producer", producer(this))
                    .put("artifacts", Collections.singletonList(artifact)).put("statements", Collections.singletonList(statement))
                    .put("endpoints", endpoints).put("facts", facts).put("factCandidates", factCandidates)
                    .put("datasetOperationInfluences", Collections.emptyList()).put("datasetOperationCandidates", Collections.emptyList())
                    .put("occurrences", occurrences).put("diagnostics", diagnostics).put("extensions", Collections.emptyList())
                    .put("objectRelationships", objectRelationships).put("objectRelationshipCandidates", objectRelationshipCandidates)
                    .put("statementOperations", statementOperations).put("joinSemantics", joinSemantics)
                    .put("intermediateGraphs", graphs).build();
            return new LegacyAdaptation(new SlpcDocument(root), new LegacyCoverageReport(legacyInputCount, coverage), new IntentionalDiffLedger(differences));
        }
    }

    private static final class EndpointDraft {
        private final table relation; private final column field; private final SlpcObject provisional; private final String canonical, sortKey, stableTieBreaker, legacyKind, legacyId; private String endpointRef; private EndpointDraft representative; private procedure routine;
        private EndpointDraft(table relation, column field, SlpcObject provisional, String canonical, String sortKey, String stableTieBreaker, String legacyKind, String legacyId) { this.relation = relation; this.field = field; this.provisional = provisional; this.canonical = canonical; this.sortKey = sortKey; this.stableTieBreaker = stableTieBreaker; this.legacyKind = legacyKind; this.legacyId = legacyId; }
        private SlpcObject withRef() { return provisional.toBuilder().put("endpointRef", endpointRef).build(); }
        private boolean sameSemanticIdentity(EndpointDraft other) {
            if (canonical != null || other.canonical != null) {
                return canonical != null && canonical.equals(other.canonical)
                        && provisional.string("endpointLevel").equals(other.provisional.string("endpointLevel"))
                        && provisional.string("objectKind").equals(other.provisional.string("objectKind"))
                        && provisional.get("identity").equals(other.provisional.get("identity"))
                        && equalValues(provisional.get("scope"), other.provisional.get("scope"));
            }
            return provisional.toBuilder().remove("endpointRef").build()
                    .equals(other.provisional.toBuilder().remove("endpointRef").build());
        }
    }

    private static final class FactSemantics {
        private final String axis, role, operationKind, operationInputKind, diagnosticCode, diagnosticMessage;
        private final boolean derived, publish;
        private FactSemantics(String axis, String role, String operationKind, String operationInputKind, boolean derived,
                boolean publish, String diagnosticCode, String diagnosticMessage) {
            this.axis = axis; this.role = role; this.operationKind = operationKind; this.operationInputKind = operationInputKind;
            this.derived = derived; this.publish = publish; this.diagnosticCode = diagnosticCode; this.diagnosticMessage = diagnosticMessage;
        }
        private static FactSemantics publish(String axis, String role, String operationKind, String operationInputKind, boolean derived) {
            return new FactSemantics(axis, role, operationKind, operationInputKind, derived, true, null, null);
        }
        private static FactSemantics publishWithGap(String axis, String role, String operationKind, String operationInputKind,
                boolean derived, String diagnosticCode, String diagnosticMessage) {
            return new FactSemantics(axis, role, operationKind, operationInputKind, derived, true, diagnosticCode, diagnosticMessage);
        }
        private static FactSemantics reject(String diagnosticCode, String diagnosticMessage) {
            return new FactSemantics("ROW", "UNKNOWN", "NONE", "NONE", false, false, diagnosticCode, diagnosticMessage);
        }
    }

    private static final class SystemFieldDraft {
        private final table relation; private final column field;
        private SystemFieldDraft(table relation, column field) { this.relation = relation; this.field = field; }
    }

    private static final class PendingNode {
        private final table relation; private final column field; private final NodeDraft parent;
        private PendingNode(table relation, column field, NodeDraft parent) { this.relation = relation; this.field = field; this.parent = parent; }
    }

    private static final class FactGroup {
        private final SlpcObject semantic; private final boolean canonical; private final String semanticKey; private final List<FactOccurrenceDraft> occurrences = new ArrayList<FactOccurrenceDraft>(); private String ownerKind, ownerId;
        private FactGroup(SlpcObject semantic, boolean canonical, String semanticKey) { this.semantic = semantic; this.canonical = canonical; this.semanticKey = semanticKey; }
        private boolean sameSemantic(SlpcObject other) { return semantic.equals(other); }
    }

    private static final class FactOccurrenceDraft {
        private final FactGroup group; private final SlpcObject transformation, predicate; private final String resolution;
        private final List<Object> literalInputs, supportPathRefs, sourceLocations; private final String procedureEndpointRef;
        private FactOccurrenceDraft(FactGroup group, SlpcObject transformation, SlpcObject predicate, String resolution,
                List<Object> literalInputs, List<Object> supportPathRefs) {
            this(group, transformation, predicate, resolution, literalInputs, supportPathRefs,
                    Collections.<Object>emptyList(), null);
        }
        private FactOccurrenceDraft(FactGroup group, SlpcObject transformation, SlpcObject predicate, String resolution,
                List<Object> literalInputs, List<Object> supportPathRefs, List<Object> sourceLocations,
                String procedureEndpointRef) {
            this.group = group; this.transformation = transformation; this.predicate = predicate;
            this.resolution = resolution; this.literalInputs = literalInputs; this.supportPathRefs = supportPathRefs;
            this.sourceLocations = sourceLocations; this.procedureEndpointRef = procedureEndpointRef;
        }
    }

    private static final class RelationshipGroup {
        private final SlpcObject semantic; private final boolean canonical; private final String semanticKey;
        private final Set<String> legacyEvidence = new LinkedHashSet<String>(); private String ownerKind, ownerId;
        private final Map<String, SlpcObject> sourceLocations = new TreeMap<String, SlpcObject>();
        private RelationshipGroup(SlpcObject semantic, boolean canonical, String semanticKey) {
            this.semantic = semantic; this.canonical = canonical; this.semanticKey = semanticKey;
        }
    }

    private static final class NodeDraft {
        private final table relation; private final column field; private final int ordinal; private final String kind, localName; private final NodeDraft parent;
        private String provisionalRef, finalRef, fingerprint; private SlpcObject provisionalNode;
        private NodeDraft(table relation, column field, int ordinal, String kind, String localName, NodeDraft parent) { this.relation = relation; this.field = field; this.ordinal = ordinal; this.kind = kind; this.localName = localName; this.parent = parent; }
        private SlpcObject node(String ref, String parentRef, String fingerprint) { return SlpcObject.builder().put("nodeRef", ref).put("nodeFingerprint", fingerprint).put("nodeOrdinal", ordinal).put("nodeKind", kind).put("localName", localName).put("parentNodeRef", parentRef).putNull("boundaryEndpointRef").putNull("nodeEvidence").put("extensions", Collections.emptyList()).build(); }
    }

    private static final class EdgeDraft {
        private final relationship relation; private final sourceColumn sourceColumn;
        private final SlpcObject source, target; private final FactSemantics semantics; private final SlpcObject transformation, predicate; private String fingerprint, finalRef;
        private EdgeDraft(relationship relation, sourceColumn sourceColumn, SlpcObject source, SlpcObject target,
                FactSemantics semantics, SlpcObject transformation, SlpcObject predicate) { this.relation = relation; this.sourceColumn = sourceColumn; this.source = source; this.target = target; this.semantics = semantics; this.transformation = transformation; this.predicate = predicate; }
        private SlpcObject edge(String ref, String fingerprint) { return SlpcObject.builder().put("source", source).put("target", target).put("edgeRef", ref).put("edgeFingerprint", fingerprint).put("axis", semantics.axis).put("role", semantics.role).put("operationKind", semantics.operationKind).put("operationInputKind", semantics.operationInputKind).put("transformation", transformation).put("predicate", predicate).put("extensions", Collections.emptyList()).build(); }
        private boolean sameSemantic(EdgeDraft other) { return source.equals(other.source) && target.equals(other.target)
                && semantics.axis.equals(other.semantics.axis) && semantics.role.equals(other.semantics.role)
                && semantics.operationKind.equals(other.semantics.operationKind)
                && semantics.operationInputKind.equals(other.semantics.operationInputKind)
                && (transformation == null ? other.transformation == null : transformation.equals(other.transformation))
                && (predicate == null ? other.predicate == null : predicate.equals(other.predicate)); }
    }

    private static final class PathDraft {
        private final List<EdgeDraft> edges; private String fingerprint, finalRef;
        private PathDraft(List<EdgeDraft> edges) { this.edges = new ArrayList<EdgeDraft>(edges); }
        private SlpcObject path(String ref, String fp) {
            List<Object> refs = new ArrayList<Object>(); for (EdgeDraft edge : edges) refs.add(edge.finalRef);
            return SlpcObject.builder().put("pathRef", ref).put("pathFingerprint", fp)
                    .put("edgeRefs", refs).put("extensions", Collections.emptyList()).build();
        }
        private String sourceEndpointRef() { return "ENDPOINT".equals(edges.get(0).source.string("kind"))
                ? edges.get(0).source.string("endpointRef") : null; }
        private String targetEndpointRef() { EdgeDraft last = edges.get(edges.size() - 1); return "ENDPOINT".equals(last.target.string("kind"))
                ? last.target.string("endpointRef") : null; }
        private String axis() { return edges.get(0).semantics.axis; }
    }

    private static final class PathWalk {
        private final List<EdgeDraft> edges; private final Set<String> used;
        private PathWalk(List<EdgeDraft> edges, Set<String> used) { this.edges = edges; this.used = used; }
        private static PathWalk start(EdgeDraft edge) {
            List<EdgeDraft> edges = new ArrayList<EdgeDraft>(); edges.add(edge);
            Set<String> used = new HashSet<String>(); used.add(edge.finalRef); return new PathWalk(edges, used);
        }
        private PathWalk append(EdgeDraft edge) {
            List<EdgeDraft> copy = new ArrayList<EdgeDraft>(edges); copy.add(edge);
            Set<String> copyUsed = new HashSet<String>(used); copyUsed.add(edge.finalRef); return new PathWalk(copy, copyUsed);
        }
        private String edgeKey() { StringBuilder result = new StringBuilder(); for (EdgeDraft edge : edges) result.append(edge.finalRef).append('\u0000'); return result.toString(); }
    }

    private static final class StepDraft {
        private final String family, code; private final List<Object> bindings; private final SlpcObject result, evidence;
        private StepDraft(String family, String code, List<Object> bindings, SlpcObject result, SlpcObject evidence) {
            this.family = family; this.code = code; this.bindings = bindings; this.result = result; this.evidence = evidence;
        }
        private SlpcObject step(String ref, String fingerprint, int ordinal) {
            return SlpcObject.builder().put("stepRef", ref).put("stepFingerprint", fingerprint)
                    .put("stepOrdinal", ordinal).put("operationFamily", family).put("operationCode", code)
                    .put("inputBindings", bindings).put("resultAnchor", result).put("expressionEvidence", evidence)
                    .put("extensions", Collections.emptyList()).build();
        }
        private String sortKey() {
            StringBuilder resultKey = new StringBuilder(family).append('\u0000').append(code).append('\u0000');
            for (Object value : bindings) resultKey.append(((SlpcObject) value).string("edgeRef")).append('\u0000');
            return resultKey.toString();
        }
    }
}