rea-agents 6.4.0 → 6.5.0

package/dist/domain/reconstructionObligationLedgerIntegrity.js

@@ -0,0 +1,114 @@
+import { digestCanonicalValue } from "./canonicalDigest.js";
+import { canonicalJson } from "./comparisonSemantics.js";
+import { compareUnicodeCodePoints } from "./unicodeCodePointOrder.js";
+/** Derive the ledger summary from the obligation facts. */
+export const summarizeReconstructionObligations = (obligations) => ({
+    total: obligations.length,
+    required: obligations.filter(({ required }) => required).length,
+    verified: obligations.filter(({ status }) => status === "verified").length,
+    required_open: obligations.filter(({ required, status }) => required && status !== "verified").length,
+    by_status: countBy(obligations, [
+        "unowned",
+        "characterized",
+        "implemented",
+        "verified",
+        "contradicted",
+        "blocked",
+        "out-of-scope",
+        "unknown",
+    ], ({ status }) => status),
+    by_application_layer: countBy(obligations, [
+        "cli",
+        "protocol",
+        "electron",
+        "persistence",
+        "process",
+        "runtime",
+        "packaging",
+        "native-abi",
+        "application",
+        "other",
+    ], ({ application_layer }) => application_layer),
+    by_evidence_authority: countBy(obligations, ["candidate", "observed", "reviewed", "unknown"], ({ source_state }) => source_state),
+});
+/** Derive closure status from required obligations and their diagnostic facts. */
+export const reconstructionObligationLedgerStatus = (obligations, limitations) => {
+    if (obligations.length === 0)
+        return "unknown";
+    const requiredOpen = obligations.filter(({ required, status }) => required && status !== "verified");
+    if (requiredOpen.some(({ status, diagnostics }) => status === "contradicted" ||
+        hasReconstructionObligationDiagnostic(diagnostics, "verifier-failed")))
+        return "failed";
+    if (limitations.length > 0)
+        return "unknown";
+    if (requiredOpen.some(({ status }) => status === "unknown"))
+        return "unknown";
+    return requiredOpen.length === 0 ? "ready" : "open";
+};
+export const reconstructionObligationCoverage = (limitations) => ({
+    status: limitations.length === 0 ? "complete" : "partial",
+});
+export const reconstructionObligationReports = (obligations) => ({
+    missing_owner_obligation_ids: obligationIdsWith(obligations, "missing-owner"),
+    missing_verifier_obligation_ids: obligationIdsWith(obligations, "missing-verifier"),
+    contradicted_obligation_ids: obligationIdsWith(obligations, "contradiction"),
+    residual_unknown_ids: [
+        ...new Set(obligations.flatMap(({ residual_unknown_ids: ids }) => ids)),
+    ].sort(compareUnicodeCodePoints),
+});
+export const reconstructionObligationOwnershipGraph = (obligations) => obligations
+    .flatMap((obligation) => obligation.binding === null
+    ? []
+    : [
+        {
+            obligation_id: obligation.obligation_id,
+            module_path: obligation.binding.owner.module_path,
+            symbol: obligation.binding.owner.symbol,
+        },
+    ])
+    .sort(obligationEdgeOrder);
+export const reconstructionObligationDependencyGraph = (obligations) => obligations
+    .flatMap((obligation) => obligation.dependency_obligation_ids.map((dependencyId) => ({
+    obligation_id: obligation.obligation_id,
+    depends_on_obligation_id: dependencyId,
+})))
+    .sort(obligationEdgeOrder);
+/** Evidence attached to facts serialized on an obligation. */
+export const reconstructionObligationEvidenceIds = (obligations) => [
+    ...new Set(obligations.flatMap((obligation) => [
+        ...obligation.authority_references.map(({ evidence_id: id }) => id),
+        ...obligation.observed_cases.map(({ evidence_id: id }) => id),
+        ...(obligation.binding === null
+            ? []
+            : [
+                ...obligation.binding.original_cases.map(({ evidence_id: id }) => id),
+                ...obligation.binding.fixtures.flatMap(({ evidence_ids: ids }) => ids),
+                ...(obligation.binding.verifier === null
+                    ? []
+                    : [obligation.binding.verifier.result_evidence_id]),
+            ]),
+    ])),
+].sort(compareUnicodeCodePoints);
+const obligationEdgeOrder = (left, right) => compareUnicodeCodePoints(canonicalJson(left), canonicalJson(right));
+const obligationIdsWith = (obligations, code) => obligations
+    .filter(({ diagnostics }) => hasReconstructionObligationDiagnostic(diagnostics, code))
+    .map(({ obligation_id: id }) => id)
+    .sort(compareUnicodeCodePoints);
+export const hasReconstructionObligationDiagnostic = (diagnostics, code) => diagnostics.some((diagnostic) => diagnostic.code === code);
+/** Recompute the closure commitment from the fields carried by a ledger. */
+export const reconstructionObligationLedgerClosureDigest = (ledger) => digestCanonicalValue({
+    schema: "ReconstructionObligationClosure",
+    status: ledger.status,
+    coverage: ledger.coverage,
+    summary: ledger.summary,
+    reports: ledger.reports,
+    ownership_graph: ledger.ownership_graph,
+    dependency_graph: ledger.dependency_graph,
+    obligations: ledger.obligations,
+    evidence_links: ledger.evidence_links,
+    limitations: ledger.limitations,
+}, "Reconstruction obligation ledger");
+const countBy = (items, values, valueFor) => values.map((value) => ({
+    key: value,
+    count: items.filter((item) => valueFor(item) === value).length,
+}));

package/dist/domain/reconstructionObligationLedgerSchemas.js

@@ -3,9 +3,31 @@ import { STABLE_IDENTIFIER_PATTERN } from "./stringPatterns.js";
 import { evidenceBundleSchema } from "./evidenceBundle.js";
 import { digestSchema } from "./../domain/digests.js";
 import { prefixedDigestSchema } from "./../domain/digests.js";
+import { canonicalJson } from "./comparisonSemantics.js";
+import { reconstructionObligationCoverage, reconstructionObligationDependencyGraph, reconstructionObligationLedgerClosureDigest, reconstructionObligationLedgerStatus, reconstructionObligationEvidenceIds, reconstructionObligationOwnershipGraph, reconstructionObligationReports, summarizeReconstructionObligations, } from "./reconstructionObligationLedgerIntegrity.js";
 const evidenceIdSchema = prefixedDigestSchema("ev");
 const stableIdSchema = z.string().regex(STABLE_IDENTIFIER_PATTERN);
 const textSchema = z.string().trim().min(1);
+const sameProjection = (actual, expected) => {
+    if (actual.length !== expected.length)
+        return false;
+    const counts = new Map();
+    for (const value of actual) {
+        const key = canonicalJson(value, "Reconstruction obligation ledger");
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    for (const value of expected) {
+        const key = canonicalJson(value, "Reconstruction obligation ledger");
+        const count = counts.get(key);
+        if (count === undefined)
+            return false;
+        if (count === 1)
+            counts.delete(key);
+        else
+            counts.set(key, count - 1);
+    }
+    return counts.size === 0;
+};
 export const obligationStatusSchema = z.enum([
     "unowned",
     "characterized",
@@ -201,7 +223,21 @@ const countBySchema = (key) => z.array(z.strictObject({
     key,
     count: z.number().int().min(0),
 }));
-export const reconstructionObligationLedgerSchema = z.strictObject({
+const countEntriesMatch = (actual, expected) => {
+    const actualCounts = new Map(actual.map(({ key, count }) => [key, count]));
+    return (actualCounts.size === actual.length &&
+        actual.length === expected.length &&
+        expected.every(({ key, count }) => actualCounts.get(key) === count));
+};
+const obligationSummariesMatch = (actual, expected) => actual.total === expected.total &&
+    actual.required === expected.required &&
+    actual.verified === expected.verified &&
+    actual.required_open === expected.required_open &&
+    countEntriesMatch(actual.by_status, expected.by_status) &&
+    countEntriesMatch(actual.by_application_layer, expected.by_application_layer) &&
+    countEntriesMatch(actual.by_evidence_authority, expected.by_evidence_authority);
+export const reconstructionObligationLedgerSchema = z
+    .strictObject({
     schema: z.literal("ReconstructionObligationLedger"),
     ledger_id: prefixedDigestSchema("rol"),
     closure_digest: digestSchema,
@@ -236,6 +272,73 @@ export const reconstructionObligationLedgerSchema = z.strictObject({
     obligations: z.array(reconstructionObligationSchema),
     evidence_links: z.array(evidenceIdSchema),
     limitations: z.array(textSchema),
+})
+    .superRefine((ledger, context) => {
+    if (ledger.status !==
+        reconstructionObligationLedgerStatus(ledger.obligations, ledger.limitations))
+        context.addIssue({
+            code: "custom",
+            path: ["status"],
+            message: "Ledger status does not match its obligations",
+        });
+    if (!obligationSummariesMatch(ledger.summary, summarizeReconstructionObligations(ledger.obligations)))
+        context.addIssue({
+            code: "custom",
+            path: ["summary"],
+            message: "Ledger summary does not match its obligations",
+        });
+    if (ledger.closure_digest !==
+        reconstructionObligationLedgerClosureDigest(ledger))
+        context.addIssue({
+            code: "custom",
+            path: ["closure_digest"],
+            message: "Ledger closure digest does not match its contents",
+        });
+    if (ledger.coverage.status !==
+        reconstructionObligationCoverage(ledger.limitations).status)
+        context.addIssue({
+            code: "custom",
+            path: ["coverage"],
+            message: "Ledger coverage does not match its limitations",
+        });
+    const expectedReports = reconstructionObligationReports(ledger.obligations);
+    for (const key of [
+        "missing_owner_obligation_ids",
+        "missing_verifier_obligation_ids",
+        "contradicted_obligation_ids",
+        "residual_unknown_ids",
+    ])
+        if (!sameProjection(ledger.reports[key], expectedReports[key]))
+            context.addIssue({
+                code: "custom",
+                path: ["reports", key],
+                message: "Ledger report does not match its obligations",
+            });
+    if (!sameProjection(ledger.ownership_graph, reconstructionObligationOwnershipGraph(ledger.obligations)))
+        context.addIssue({
+            code: "custom",
+            path: ["ownership_graph"],
+            message: "Ownership graph does not match its obligations",
+        });
+    if (!sameProjection(ledger.dependency_graph, reconstructionObligationDependencyGraph(ledger.obligations)))
+        context.addIssue({
+            code: "custom",
+            path: ["dependency_graph"],
+            message: "Dependency graph does not match its obligations",
+        });
+    const ledgerEvidenceIds = new Set(ledger.evidence_links);
+    if (ledgerEvidenceIds.size !== ledger.evidence_links.length)
+        context.addIssue({
+            code: "custom",
+            path: ["evidence_links"],
+            message: "Evidence links must be unique",
+        });
+    if (reconstructionObligationEvidenceIds(ledger.obligations).some((evidenceId) => !ledgerEvidenceIds.has(evidenceId)))
+        context.addIssue({
+            code: "custom",
+            path: ["evidence_links"],
+            message: "Evidence links omit Evidence referenced by an obligation",
+        });
 });
 export const reconstructionObligationLedgerInputSchema = z.strictObject({
     evidence_bundle: evidenceBundleSchema,

package/dist/domain/reconstructionReadiness.js

@@ -1,6 +1,5 @@
-import { createHash } from "node:crypto";
-import canonicalize from "canonicalize";
-import { parseEvidenceBundle } from "./evidenceBundle.js";
+import { digestCanonicalValue } from "./canonicalDigest.js";
+import { authenticateParsedEvidenceBundle } from "./evidenceBundle.js";
 import { readinessFindingOrder } from "./reconstructionReadinessFindingHelpers.js";
 import { READINESS_STAGE_IDS, readinessJourneyFindings, } from "./reconstructionReadinessJourneyFindings.js";
 import { readinessIntegrityFindings } from "./reconstructionReadinessIntegrityFindings.js";
@@ -9,7 +8,7 @@ import { reconstructionReadinessInputSchema, reconstructionReadinessReportSchema
 export const createReconstructionReadinessReport = (inputValue) => {
     const input = reconstructionReadinessInputSchema.parse(inputValue);
     const sourceDigest = digest(sourceValue(input));
-    const evidenceIds = new Set(parseEvidenceBundle(input.evidence_bundle).records.map(({ evidence_id: evidenceId }) => evidenceId));
+    const evidenceIds = new Set(authenticateParsedEvidenceBundle(input.evidence_bundle).records.map(({ evidence_id: evidenceId }) => evidenceId));
     const findings = [
         ...readinessJourneyFindings(input, evidenceIds),
         ...readinessIntegrityFindings(input, evidenceIds, sourceDigest),
@@ -113,8 +112,5 @@ const sourceValue = (input) => ({
 });
 const ratio = (numerator, denominator) => denominator === 0 ? 1 : numerator / denominator;
 const digest = (value) => {
-    const encoded = canonicalize(value);
-    if (encoded === undefined)
-        throw new TypeError("Reconstruction readiness value is not canonical JSON");
-    return createHash("sha256").update(encoded).digest("hex");
+    return digestCanonicalValue(value, "Reconstruction readiness");
 };

package/dist/domain/reconstructionReadinessJourneyFindings.js

@@ -102,6 +102,10 @@ const stageFindings = (input, evidenceIds) => {
         const checks = new Map(stage.checks.map((check) => [check.check_id, check]));
         if (checks.size !== stage.checks.length)
             findings.push(finding("duplicate-stage-check", stageId, "fail", "Stage check IDs must be unique."));
+        addMissingEvidenceFindings(findings, stageId, [
+            ...stage.evidence_ids,
+            ...stage.checks.flatMap((check) => check.evidence_ids),
+        ], evidenceIds);
         for (const checkId of READINESS_REQUIRED_CHECKS[stageId]) {
             const check = checks.get(checkId);
             if (check === undefined) {
@@ -112,7 +116,6 @@ const stageFindings = (input, evidenceIds) => {
                 findings.push(finding("stage-check-not-pass", stageId, check.status === "fail" ? "fail" : "unknown", `${checkId} is ${check.status}: ${check.detail}`, check.evidence_ids));
             if (check.evidence_ids.length === 0)
                 findings.push(finding("stage-check-evidence-missing", stageId, "unknown", `${checkId} has no attributable Evidence.`));
-            addMissingEvidenceFindings(findings, stageId, [...stage.evidence_ids, ...check.evidence_ids], evidenceIds);
         }
     }
     return findings;

package/dist/domain/reconstructionUnknowns.js

@@ -11,10 +11,18 @@ export const reconstructionUnknownHeads = (revisions) => {
     return heads;
 };
 /** Find active unknowns that affect a comparison or one of its sources. */
-export const reconstructionClaimUnknowns = (heads, comparisonId, sourceIds) => {
+export const reconstructionClaimUnknowns = (heads, comparisonId, sourceIds, dimension) => {
+    const appliesToClaim = (item) => {
+        const scope = item.comparison_conclusion_scope;
+        return (scope === undefined ||
+            (scope.comparison_evidence_id === comparisonId &&
+                (dimension === undefined ||
+                    scope.dimensions.some((scopedDimension) => scopedDimension === dimension))));
+    };
     const evidenceIds = new Set([comparisonId, ...sourceIds]);
     const relevantIds = new Set([...heads.values()]
         .filter((item) => item.status !== "resolved" &&
+        appliesToClaim(item) &&
         [
             ...item.supporting_evidence_ids,
             ...item.contradicting_evidence_ids,

package/dist/domain/reconstructionVerification.js

@@ -5,12 +5,13 @@ import { artifactComparisonResultSchema } from "./artifactComparison.js";
 import { artifactInventoryResultSchema } from "./artifactGraph.js";
 import { uniqueSorted } from "./canonicalOrdering.js";
 import { compareUnicodeCodePoints } from "./unicodeCodePointOrder.js";
-import { comparisonSourceEvidenceSides } from "./comparisonSourceEvidence.js";
+import { comparisonSourceEvidenceSides, assertComparisonFindingLinks, } from "./comparisonSourceEvidence.js";
 import { parseEvidence } from "./evidence.js";
 import { parseEvidenceBundle } from "./evidenceBundle.js";
 import { functionComparisonResultSchema } from "./functionComparisonSchemas.js";
 import { PROCESS_PROVIDER, isProcessEvidenceProvider, } from "./process/processEvidenceProvider.js";
 import { functionDossierSchema } from "./hopperValues.js";
+import { functionCallCoverageLimitations } from "./functionCallCoverage.js";
 import { deriveProcessComparisonStatus, PROCESS_COMPARISON_DIMENSIONS, processCaptureComparisonSchema, } from "./process/processComparison.js";
 import { parseProcessCapture } from "./process/processCaptureParsing.js";
 import { reconstructionClaimResultSchema, reconstructionSpecificationSchema, reconstructionVerificationResultSchema, } from "./reconstructionVerificationSchemas.js";
@@ -88,10 +89,15 @@ const evaluateClaim = (claim, records, heads) => {
             throw new TypeError(`Missing source Evidence ${id}`);
         return source;
     });
-    validateSourceKinds(claim, sources);
-    const observed = observedStatus(claim, comparison);
-    const limitations = authorityLimitations(claim, sources, sides);
-    const relevantUnknowns = reconstructionClaimUnknowns(heads, comparison.evidence_id, allSourceIds);
+    const functionSourceFacts = readValidatedSourceFacts(claim, sources);
+    const observation = comparisonObservation(claim, comparison);
+    const observed = observation.status;
+    const limitations = [
+        ...authorityLimitations(claim, sources, sides),
+        ...sourceCallCoverageLimitations(claim, functionSourceFacts, observation.hasIndependentFunctionChange === true),
+    ];
+    const relatedUnknowns = reconstructionClaimUnknowns(heads, comparison.evidence_id, allSourceIds, claim.dimension);
+    const relevantUnknowns = relatedUnknowns;
     const status = classify(observed, limitations, relevantUnknowns);
     const displayedUnknowns = relevantUnknowns;
     return reconstructionClaimResultSchema.parse({
@@ -107,12 +113,13 @@ const evaluateClaim = (claim, records, heads) => {
         unknown_ids: displayedUnknowns.map(({ unknown_id: id }) => id),
         limitations: uniqueSorted([
             ...comparison.limitations,
+            ...observation.limitations,
             ...limitations,
             ...displayedUnknowns.map(({ question }) => `Residual unknown: ${question}`),
         ]),
     });
 };
-const validateSourceKinds = (claim, sources) => {
+const readValidatedSourceFacts = (claim, sources) => {
     const expected = claim.kind === "behavioral"
         ? ["capture_process_scenario", "rea.process-capture"]
         : claim.kind === "structural-function"
@@ -121,14 +128,21 @@ const validateSourceKinds = (claim, sources) => {
     if (sources.some((source) => source.operation !== expected[0] ||
         source.predicate_type !== expected[1]))
         throw new TypeError("Comparison source Evidence has an unexpected observation type");
+    const functionSources = [];
     for (const source of sources) {
         if (claim.kind === "behavioral")
             parseProcessCapture(source.normalized_result);
-        else if (claim.kind === "structural-function")
-            functionDossierSchema.parse(source.normalized_result);
+        else if (claim.kind === "structural-function") {
+            const dossier = functionDossierSchema.parse(source.normalized_result);
+            functionSources.push({
+                evidence_id: source.evidence_id,
+                callCoverageLimitations: functionCallCoverageLimitations(source.relationship_coverage, dossier),
+            });
+        }
         else
             artifactInventoryResultSchema.parse(source.normalized_result);
     }
+    return functionSources;
 };
 const validateComparisonIdentity = (claim, evidence) => {
     parseEvidence(evidence);
@@ -145,29 +159,38 @@ const validateComparisonIdentity = (claim, evidence) => {
         evidence.subject !== null)
         throw new TypeError("Comparison Evidence identity or authority disagrees");
 };
-const observedStatus = (claim, evidence) => {
+const comparisonObservation = (claim, evidence) => {
     if (claim.kind === "behavioral") {
         const result = processCaptureComparisonSchema.parse(evidence.normalized_result);
         validateProcessStatus(result);
-        return claim.dimension === "overall"
-            ? result.status
-            : result[claim.dimension];
+        return {
+            status: claim.dimension === "overall" ? result.status : result[claim.dimension],
+            limitations: [],
+        };
     }
     if (claim.kind === "structural-function") {
         const result = functionComparisonResultSchema.parse(evidence.normalized_result);
+        assertComparisonFindingLinks(evidence, result.dimensions.flatMap(({ evidence_links }) => evidence_links));
         if (claim.dimension === "overall")
-            return result.status;
+            return {
+                status: result.status,
+                limitations: result.dimensions.flatMap(({ limitations }) => limitations),
+                // Historical overall changes can be caused only by incomplete call
+                // sets. Ignore that aggregate change when independently checking the
+                // source call-coverage limitations.
+                hasIndependentFunctionChange: result.function_match.status === "mismatched" ||
+                    (result.function_match.status === "matched" &&
+                        result.dimensions.some((dimension) => dimension.dimension !== "calls" &&
+                            dimension.status === "changed")),
+            };
         const dimension = result.dimensions.find((item) => item.dimension === claim.dimension);
         if (dimension === undefined)
             throw new TypeError("Function comparison dimension missing");
-        if (dimension.evidence_links.some((id) => !evidence.evidence_links.includes(id)))
-            throw new TypeError("Function dimension cites Evidence outside comparison closure");
-        return dimension.status;
+        return { status: dimension.status, limitations: dimension.limitations };
     }
     const result = artifactComparisonResultSchema.parse(evidence.normalized_result);
-    if (result.changes.some((item) => item.evidence_links.some((id) => !evidence.evidence_links.includes(id))))
-        throw new TypeError("Artifact change cites Evidence outside comparison closure");
-    return result.status;
+    assertComparisonFindingLinks(evidence, result.changes.flatMap(({ evidence_links }) => evidence_links));
+    return { status: result.status, limitations: [] };
 };
 const validateProcessStatus = (result) => {
     const expected = deriveProcessComparisonStatus(PROCESS_COMPARISON_DIMENSIONS.map((dimension) => result[dimension]));
@@ -188,16 +211,22 @@ const authorityLimitations = (claim, sources, sides) => {
         sources.some(({ subject }) => subject === null))
         limitations.push("Structural source artifact identity is unavailable.");
     if (claim.kind === "behavioral") {
-        const byId = new Map(sources.map((source) => [source.evidence_id, source]));
-        const left = byId.get(sides.left[0] ?? "");
-        const right = byId.get(sides.right[0] ?? "");
-        if (left?.environment === null ||
-            right?.environment === null ||
-            JSON.stringify(left?.environment) !== JSON.stringify(right?.environment))
+        const referenceEnvironment = sources[0]?.environment;
+        if (referenceEnvironment === null ||
+            referenceEnvironment === undefined ||
+            sources.some(({ environment }) => environment === null ||
+                JSON.stringify(environment) !== JSON.stringify(referenceEnvironment)))
             limitations.push("Controlled replay environments are unavailable or incompatible.");
     }
     return limitations;
 };
+const sourceCallCoverageLimitations = (claim, functionSources, hasIndependentFunctionChange) => {
+    if (claim.kind !== "structural-function" ||
+        (claim.dimension !== "calls" &&
+            !(claim.dimension === "overall" && !hasIndependentFunctionChange)))
+        return [];
+    return functionSources.flatMap(({ evidence_id, callCoverageLimitations }) => callCoverageLimitations.map((reason) => `Source ${evidence_id}: ${reason}`));
+};
 const classify = (observed, limitations, unknowns) => {
     if (limitations.length > 0)
         return "unknown";

package/dist/domain/recordedTransportUrl.js

@@ -0,0 +1,59 @@
+/**
+ * Interpret transport URL syntax once for credential exclusion and recorded-path
+ * projection. Never use URL.pathname: it removes observed dot segments.
+ * Noncanonical spellings may have parsed credentials but no safe raw span.
+ */
+export const parseRecordedTransportUrl = (value, options = {}) => {
+    const prefix = /^[\x00-\x20]*(?:([A-Za-z][A-Za-z0-9+.-]*):)?\/\//u.exec(value);
+    const absolute = URL.parse(value);
+    // Resolve references only to recognize credentials (including WHATWG's
+    // backslash/control-character spellings), never to supply a projected origin.
+    const parsed = absolute ?? URL.parse(value, "https://rea.invalid");
+    const hasCredentials = parsed !== null && (parsed.username !== "" || parsed.password !== "");
+    const origin = absolute !== null && absolute.origin !== "null" ? absolute.origin : null;
+    if (prefix === null)
+        return {
+            origin,
+            path: null,
+            credentials: hasCredentials ? "ambiguous" : null,
+        };
+    const authorityStart = prefix[0].length;
+    const protocol = parsed?.protocol ?? `${prefix[1]?.toLowerCase() ?? "https"}:`;
+    const special = ["ftp:", "file:", "http:", "https:", "ws:", "wss:"].includes(protocol);
+    let authorityEnd = authorityStart;
+    while (authorityEnd < value.length &&
+        !"/?#".includes(value[authorityEnd]) &&
+        !(special && value[authorityEnd] === "\\"))
+        authorityEnd += 1;
+    const authority = value.slice(authorityStart, authorityEnd);
+    const stableAuthority = authority.length > 0 && !/[\t\n\r]/u.test(authority);
+    const at = authority.lastIndexOf("@");
+    const credentials = !stableAuthority && hasCredentials
+        ? "ambiguous"
+        : at >= 0
+            ? { start: authorityStart, end: authorityStart + at + 1 }
+            : hasCredentials
+                ? "ambiguous"
+                : null;
+    // Only an explicit, unpadded scheme://authority has a recorded absolute path.
+    // Backslashes are authority/path separators for special schemes in WHATWG.
+    if (origin === null ||
+        !/^[A-Za-z][A-Za-z0-9+.-]*:\/\//u.test(value) ||
+        !stableAuthority ||
+        (special && value[authorityEnd] === "\\"))
+        return { origin, path: null, credentials };
+    const query = options.includeQuery === true ? { query: absolute.search } : {};
+    if (value[authorityEnd] !== "/")
+        return { origin, path: "/", credentials, ...query };
+    let pathEnd = authorityEnd;
+    while (pathEnd < value.length && !"?#".includes(value[pathEnd]))
+        pathEnd += 1;
+    return {
+        origin,
+        path: value.slice(authorityEnd, pathEnd),
+        credentials,
+        ...query,
+    };
+};
+/** WHATWG form-query name decoding; preserve order, repeats and empty names. */
+export const parseUrlQueryParameterNames = (query) => new URLSearchParams(query).keys();

package/dist/domain/referenceSourceClassification.js

@@ -22,6 +22,8 @@ const CODE_EXTENSIONS = new Set([
     "rs",
     "go",
     "java",
+    "kt",
+    "kts",
     "c",
     "h",
     "cpp",
@@ -32,6 +34,8 @@ const CODE_EXTENSIONS = new Set([
     "m",
     "mm",
     "sh",
+    "cs",
+    "php",
 ]);
 const LANGUAGE_BY_EXTENSION = new Map([
     ["js", "JavaScript"],
@@ -46,6 +50,8 @@ const LANGUAGE_BY_EXTENSION = new Map([
     ["rs", "Rust"],
     ["go", "Go"],
     ["java", "Java"],
+    ["kt", "Kotlin"],
+    ["kts", "Kotlin"],
     ["c", "C"],
     ["h", "C"],
     ["cpp", "C++"],
@@ -53,6 +59,8 @@ const LANGUAGE_BY_EXTENSION = new Map([
     ["cc", "C++"],
     ["cxx", "C++"],
     ["swift", "Swift"],
+    ["cs", "C#"],
+    ["php", "PHP"],
     ["m", "Objective-C"],
     ["mm", "Objective-C++"],
     ["sh", "Shell"],
@@ -198,7 +206,6 @@ const GENERATED_DIRECTORY_NAMES = new Set([
     ".svelte-kit",
     ".astro",
     "storybook-static",
-    "docs/api",
     ".codex",
     ".devin",
     ".factory",
@@ -209,6 +216,7 @@ const GENERATED_DIRECTORY_NAMES = new Set([
     ".tox",
     ".nyc_output",
 ]);
+const GENERATED_DIRECTORY_PATHS = [["docs", "api"]];
 const VENDOR_DIRECTORY_NAMES = new Set([
     "node_modules",
     "vendor",
@@ -301,15 +309,8 @@ const basenameMatch = (filename, set) => {
     const lower = filename.toLowerCase();
     return set.has(lower);
 };
-const isPathUnderAny = (path, names) => {
-    for (const segment of path.split("/")) {
-        if (segment === "")
-            continue;
-        if (names.has(segment.toLowerCase()))
-            return true;
-    }
-    return false;
-};
+const isPathUnderAny = (parts, names) => parts.some((segment) => names.has(segment));
+const containsDirectoryPath = (parts, directory) => parts.some((_, start) => directory.every((segment, offset) => parts[start + offset] === segment));
 /** Detect a source language from a POSIX path. */
 export const detectReferenceSourceLanguage = (path) => {
     const filename = posix.basename(path);
@@ -329,41 +330,44 @@ export const detectReferenceSourceLanguage = (path) => {
 /** Classify a reference source path deterministically. */
 export const classifyReferenceSourcePath = (path) => {
     const classifications = new Set();
-    const parts = path.split("/").filter((segment) => segment !== "");
+    const parts = path
+        .toLowerCase()
+        .split("/")
+        .filter((segment) => segment !== "");
     const filename = parts[parts.length - 1] ?? "";
-    const lower = filename.toLowerCase();
     if (parts.length === 0) {
         classifications.add("source");
         return [...classifications].sort();
     }
-    addDirectoryClassifications(path, classifications);
+    addDirectoryClassifications(parts, classifications);
     addFilenameClassifications(filename, classifications);
-    if (lower.endsWith(".json") ||
-        lower.endsWith(".yaml") ||
-        lower.endsWith(".yml")) {
+    if (filename.endsWith(".json") ||
+        filename.endsWith(".yaml") ||
+        filename.endsWith(".yml")) {
         if (!classifications.has("manifest") && !classifications.has("config"))
             classifications.add("config");
     }
-    if (isPathUnderAny(path, SOURCE_DIRECTORY_NAMES)) {
+    if (isPathUnderAny(parts, SOURCE_DIRECTORY_NAMES)) {
         if (!classifications.has("vendor") && !classifications.has("generated"))
             classifications.add("source");
     }
     if (classifications.size === 0) {
-        if (lower === "license" || lower === "copying")
+        if (filename === "license" || filename === "copying")
             classifications.add("documentation");
         else
             classifications.add("unknown");
     }
     return [...classifications].sort();
 };
-const addDirectoryClassifications = (path, classifications) => {
-    if (isPathUnderAny(path, TEST_DIRECTORY_NAMES))
+const addDirectoryClassifications = (parts, classifications) => {
+    if (isPathUnderAny(parts, TEST_DIRECTORY_NAMES))
         classifications.add("test");
-    if (isPathUnderAny(path, DOCUMENTATION_DIRECTORY_NAMES))
+    if (isPathUnderAny(parts, DOCUMENTATION_DIRECTORY_NAMES))
         classifications.add("documentation");
-    if (isPathUnderAny(path, VENDOR_DIRECTORY_NAMES))
+    if (isPathUnderAny(parts, VENDOR_DIRECTORY_NAMES))
         classifications.add("vendor");
-    if (isPathUnderAny(path, GENERATED_DIRECTORY_NAMES))
+    if (isPathUnderAny(parts, GENERATED_DIRECTORY_NAMES) ||
+        GENERATED_DIRECTORY_PATHS.some((directory) => containsDirectoryPath(parts, directory)))
         classifications.add("generated");
 };
 const addFilenameClassifications = (filename, classifications) => {