@withtruing/companion 0.13.3 → 0.14.0

package/dist/reader-result-contract.js

@@ -1,6 +1,32 @@
+const PRD_FIDELITY_POLICY_VERSION = 'prd-fidelity@1';
+export const isPrdSource = (source) => 'kind' in source && source.kind === 'prd';
+export const prdSourceIdentityKey = (source) => JSON.stringify([
+    source.prdVersionId,
+    source.textSha256,
+    source.parserVersion,
+]);
 const contributes = (assessment) => assessment.outcome === 'supported' || assessment.outcome === 'contradicted';
 const breadth = { element: 0, named_paths: 1, module_surface: 2 };
+const byteRangeKey = (range) => `${range.startByte}:${range.endByte}`;
+const scopedEvidenceKey = (evidence) => JSON.stringify([
+    evidence.evidenceId,
+    evidence.sourceEntryId,
+    evidence.connectionId,
+    evidence.blobId,
+    evidence.locator,
+    byteRangeKey(evidence.byteRangeRequested),
+    byteRangeKey(evidence.byteRangeReturned),
+]);
 export function scopeCovers(covering, declared) {
+    if (covering.document !== undefined || declared.document !== undefined) {
+        if (covering.document === undefined || declared.document === undefined)
+            return false;
+        if (covering.document.sourceEntryId !== declared.document.sourceEntryId
+            || covering.document.prdVersionId !== declared.document.prdVersionId
+            || JSON.stringify([...covering.document.sectionIds].sort())
+                !== JSON.stringify([...declared.document.sectionIds].sort()))
+            return false;
+    }
     const coveringHasSurface = covering.surfaceId !== undefined || covering.surfaceHash !== undefined;
     const declaredHasSurface = declared.surfaceId !== undefined || declared.surfaceHash !== undefined;
     if (coveringHasSurface || declaredHasSurface) {
@@ -13,6 +39,15 @@ export function scopeCovers(covering, declared) {
     if ((declared.operations ?? []).some((operation) => !coveredOperations.has(operation))) {
         return false;
     }
+    if (covering.evidence !== undefined || declared.evidence !== undefined) {
+        if (covering.evidence === undefined || declared.evidence === undefined)
+            return false;
+        const coveringEvidence = new Set(covering.evidence.map(scopedEvidenceKey));
+        const declaredEvidence = new Set(declared.evidence.map(scopedEvidenceKey));
+        if (coveringEvidence.size !== declaredEvidence.size
+            || [...declaredEvidence].some((entry) => !coveringEvidence.has(entry)))
+            return false;
+    }
     if (declared.breadth !== 'named_paths' || covering.breadth !== 'named_paths')
         return true;
     const covered = new Set(covering.paths || []);
@@ -26,7 +61,7 @@ const inventoryAccess = {
 };
 function evidenceRepositoryPath(evidence, sourceEntries) {
     const source = sourceEntries.find((entry) => entry.sourceEntryId === evidence.sourceEntryId);
-    if (!source)
+    if (!source || isPrdSource(source))
         return null;
     const prefix = `repo:${source.connectionId}@${source.commit}:`;
     return evidence.locator.startsWith(prefix) ? evidence.locator.slice(prefix.length) : null;
@@ -68,11 +103,109 @@ function parseRange(value) {
     const end = Number(match[2]);
     return start <= end ? [start, end] : null;
 }
+function validByteRange(value) {
+    return Boolean(value
+        && Number.isSafeInteger(value.startByte)
+        && Number.isSafeInteger(value.endByte)
+        && value.startByte >= 0
+        && value.startByte < value.endByte);
+}
+function validDeliveryMap(segments, returned) {
+    if (!segments?.length || !segments.every((segment) => 'canonicalStartByte' in segment) || segments[0]?.deliveredStart !== 0
+        || segments[0]?.canonicalStartByte !== returned.startByte
+        || segments.at(-1)?.canonicalEndByte !== returned.endByte)
+        return false;
+    let priorDeliveredEnd = 0;
+    let priorCanonicalEnd = returned.startByte;
+    for (const segment of segments) {
+        if (!Number.isSafeInteger(segment.deliveredStart)
+            || !Number.isSafeInteger(segment.deliveredEnd)
+            || !Number.isSafeInteger(segment.canonicalStartByte)
+            || !Number.isSafeInteger(segment.canonicalEndByte)
+            || segment.deliveredStart !== priorDeliveredEnd
+            || segment.deliveredStart >= segment.deliveredEnd
+            || segment.canonicalStartByte !== priorCanonicalEnd
+            || segment.canonicalStartByte >= segment.canonicalEndByte
+            || segment.canonicalEndByte > returned.endByte)
+            return false;
+        if (segment.kind === 'source') {
+            const offsets = segment.canonicalByteOffsets;
+            if (!offsets
+                || offsets.length !== segment.deliveredEnd - segment.deliveredStart + 1
+                || offsets[0] !== segment.canonicalStartByte
+                || offsets.at(-1) !== segment.canonicalEndByte
+                || offsets.some((offset, index) => index > 0 && offset <= offsets[index - 1]))
+                return false;
+        }
+        else if (!segment.ruleId)
+            return false;
+        priorDeliveredEnd = segment.deliveredEnd;
+        priorCanonicalEnd = segment.canonicalEndByte;
+    }
+    return true;
+}
+function validPrdDeliveryMap(segments, returned) {
+    if (!segments?.length || !segments.every((segment) => 'sourceStartChar' in segment) || segments[0]?.deliveredStart !== 0
+        || segments[0]?.sourceStartChar !== returned.startChar
+        || segments.at(-1)?.sourceEndChar !== returned.endChar)
+        return false;
+    let deliveredEnd = 0;
+    let sourceEnd = returned.startChar;
+    for (const segment of segments) {
+        if (!Number.isSafeInteger(segment.deliveredStart)
+            || !Number.isSafeInteger(segment.deliveredEnd)
+            || !Number.isSafeInteger(segment.sourceStartChar)
+            || !Number.isSafeInteger(segment.sourceEndChar)
+            || segment.deliveredStart !== deliveredEnd
+            || segment.deliveredStart >= segment.deliveredEnd
+            || segment.sourceStartChar !== sourceEnd
+            || segment.sourceStartChar >= segment.sourceEndChar
+            || segment.sourceEndChar > returned.endChar)
+            return false;
+        if (segment.kind === 'source') {
+            const offsets = segment.sourceCharOffsets;
+            if (!offsets
+                || offsets.length !== segment.deliveredEnd - segment.deliveredStart + 1
+                || offsets[0] !== segment.sourceStartChar
+                || offsets.at(-1) !== segment.sourceEndChar
+                || offsets.some((offset, index) => index > 0 && offset <= offsets[index - 1]))
+                return false;
+        }
+        else if (!segment.ruleId)
+            return false;
+        deliveredEnd = segment.deliveredEnd;
+        sourceEnd = segment.sourceEndChar;
+    }
+    return true;
+}
+const validPrdRange = (range) => Boolean(range
+    && range.prdVersionId.length > 0
+    && range.sectionId.length > 0
+    && Number.isSafeInteger(range.startChar)
+    && Number.isSafeInteger(range.endChar)
+    && range.startChar >= 0
+    && range.startChar < range.endChar);
+const samePrdLocation = (left, right) => left.prdVersionId === right.prdVersionId && left.sectionId === right.sectionId;
+const prdRangeWithin = (inner, outer) => samePrdLocation(inner, outer)
+    && inner.startChar >= outer.startChar && inner.endChar <= outer.endChar;
+const sameByteRange = (left, right) => validByteRange(left) && validByteRange(right)
+    && left.startByte === right.startByte && left.endByte === right.endByte;
 export const result_binds_request = (result, context) => {
     if (result.investigationId !== context.request.investigationId)
         return `result claims ${result.investigationId}; the request is ${context.request.investigationId}`;
     if (result.attempt !== context.request.attempt)
         return `result claims attempt ${result.attempt}; the request issued attempt ${context.request.attempt}`;
+    if (context.request.policyVersion === 'build-citation-check@1'
+        && result.policyVersion !== context.request.policyVersion) {
+        return `build result claims policy ${result.policyVersion ?? '<missing>'}; the request issued ${context.request.policyVersion}`;
+    }
+    if (context.request.policyVersion === PRD_FIDELITY_POLICY_VERSION
+        && result.policyVersion !== context.request.policyVersion) {
+        return `PRD fidelity result claims policy ${result.policyVersion ?? '<missing>'}; the request issued ${context.request.policyVersion}`;
+    }
+    if (result.policyVersion !== undefined && result.policyVersion !== context.request.policyVersion) {
+        return `result claims policy ${result.policyVersion}; the request issued ${context.request.policyVersion}`;
+    }
     return null;
 };
 export const identifiers_unique = (result, context) => {
@@ -111,6 +244,7 @@ export const policy4_surface_complete = (result, context) => {
         return 'policy-4 result has no execution metadata';
     const requested = context.sourceEntry(surface.sourceEntryId);
     if (!requested
+        || isPrdSource(requested)
         || requested.role !== 'current'
         || requested.commit !== surface.commit) {
         return 'sealed surface source does not match the requested current source';
@@ -147,6 +281,88 @@ export const policy4_surface_complete = (result, context) => {
     }
     return null;
 };
+export const prd_source_mismatch = (result, context) => {
+    for (const actual of result.observedSources) {
+        const expected = context.sourceEntry(actual.sourceEntryId);
+        if (!expected || (!isPrdSource(expected) && !isPrdSource(actual)))
+            continue;
+        if (!isPrdSource(expected) || !isPrdSource(actual)) {
+            return `${actual.sourceEntryId}: requested and observed source branches differ`;
+        }
+        if (actual.role !== expected.role
+            || prdSourceIdentityKey(actual) !== prdSourceIdentityKey(expected)) {
+            return `${actual.sourceEntryId}: observed document identity does not match the request`;
+        }
+    }
+    return null;
+};
+export const prd_evidence_not_code = (result, context) => {
+    for (const evidence of result.evidence) {
+        if (evidence.kind !== 'prd_excerpt')
+            continue;
+        const source = context.sourceEntry(evidence.sourceEntryId);
+        if (context.request.policyVersion !== PRD_FIDELITY_POLICY_VERSION || !source || !isPrdSource(source)) {
+            return `${evidence.evidenceId}: PRD evidence cannot establish repository conformance`;
+        }
+    }
+    return null;
+};
+export const prd_fidelity_scope = (result, context) => {
+    if (context.request.policyVersion !== PRD_FIDELITY_POLICY_VERSION)
+        return null;
+    if (context.request.requestedSources.length === 0
+        || context.request.requestedSources.some((source) => !isPrdSource(source))) {
+        return 'PRD fidelity must use document sources only';
+    }
+    for (const obligation of context.request.obligations) {
+        const document = obligation.scope.document;
+        const source = document ? context.sourceEntry(document.sourceEntryId) : undefined;
+        if (obligation.question !== 'describes_current' || !document || !source || !isPrdSource(source)
+            || source.prdVersionId !== document.prdVersionId || document.sectionIds.length === 0) {
+            return `${obligation.obligationId}: PRD fidelity is not explicitly scoped to document statements`;
+        }
+    }
+    const evidenceById = new Map(result.evidence.map((evidence) => [evidence.evidenceId, evidence]));
+    for (const evidence of result.evidence) {
+        const source = context.sourceEntry(evidence.sourceEntryId);
+        const requested = evidence.prdRangeRequested;
+        const returned = evidence.prdRangeReturned;
+        if (evidence.kind !== 'prd_excerpt' || !source || !isPrdSource(source)
+            || !validPrdRange(requested) || !validPrdRange(returned)
+            || requested.prdVersionId !== source.prdVersionId
+            || returned.prdVersionId !== source.prdVersionId
+            || !prdRangeWithin(requested, returned)
+            || evidence.delivery !== 'excerpt'
+            || evidence.access !== 'read_ok'
+            || evidence.complete !== 1
+            || !/^sha256:[0-9a-f]{64}$/.test(evidence.originalSpanSha256 ?? '')
+            || !/^sha256:[0-9a-f]{64}$/.test(evidence.contentHash ?? '')
+            || evidence.serverReceivedContent !== 1
+            || evidence.localRetention !== 'workspace_cache'
+            || !validPrdDeliveryMap(evidence.deliveryMap, returned)) {
+            return `${evidence.evidenceId}: invalid PRD excerpt delivery metadata`;
+        }
+    }
+    for (const assessment of result.assessments) {
+        const obligation = context.obligation(assessment.obligationId);
+        if (!obligation || assessment.question !== 'describes_current'
+            || !scopeCovers(assessment.scope, obligation.scope)
+            || !scopeCovers(obligation.scope, assessment.scope)) {
+            return `${assessment.obligationId}: fidelity must answer describes_current at the issued document scope`;
+        }
+        const sections = new Set(obligation.scope.document?.sectionIds ?? []);
+        for (const citation of assessment.citations) {
+            const evidence = evidenceById.get(citation.evidenceId);
+            const cited = citation.citedPrdRange;
+            if (!evidence || !validPrdRange(cited) || !validPrdRange(evidence.prdRangeReturned)
+                || !prdRangeWithin(cited, evidence.prdRangeReturned)
+                || !sections.has(cited.sectionId)) {
+                return `${citation.evidenceId}: invalid PRD citation coordinates`;
+            }
+        }
+    }
+    return null;
+};
 export const evidence_source_entry_requested = (result, context) => {
     const entries = new Set(context.request.requestedSources.map((source) => source.sourceEntryId));
     for (const evidence of result.evidence) {
@@ -236,6 +452,13 @@ export const observed_sources_satisfy_obligation = (result, context) => {
                 continue;
             if (actual.role !== expected.role)
                 return `${entryId}: requested role '${expected.role}', observed '${actual.role}'`;
+            if (isPrdSource(expected) || isPrdSource(actual)) {
+                if (!isPrdSource(expected) || !isPrdSource(actual)
+                    || prdSourceIdentityKey(actual) !== prdSourceIdentityKey(expected)) {
+                    return `${entryId}: observed document identity does not match the request`;
+                }
+                continue;
+            }
             if (actual.connectionId !== expected.connectionId)
                 return `${entryId}: requested repository '${expected.connectionId}', observed '${actual.connectionId}'`;
             if (actual.sourceIdentity !== `commit:${expected.commit}`)
@@ -307,7 +530,57 @@ export const changed_since_two_roles = (result, context) => {
     }
     return null;
 };
-export const cited_range_within_returned = (result) => {
+export const build_citation_scope_matches = (result, context) => {
+    if (context.request.policyVersion !== 'build-citation-check@1')
+        return null;
+    const evidenceById = new Map(result.evidence.map((evidence) => [evidence.evidenceId, evidence]));
+    for (const obligation of context.request.obligations) {
+        if (obligation.question !== 'describes_current' || !obligation.scope.evidence?.length) {
+            return `${obligation.obligationId} has no named build evidence scope`;
+        }
+        const allowed = new Set(obligation.requiredSourceEntryIds);
+        for (const scoped of obligation.scope.evidence) {
+            const source = context.sourceEntry(scoped.sourceEntryId);
+            if (!allowed.has(scoped.sourceEntryId) || !source
+                || source.connectionId !== scoped.connectionId) {
+                return `${obligation.obligationId} scopes ${scoped.evidenceId} to an unbound repository connection`;
+            }
+            if (!validByteRange(scoped.byteRangeRequested)
+                || !validByteRange(scoped.byteRangeReturned)
+                || scoped.byteRangeRequested.startByte < scoped.byteRangeReturned.startByte
+                || scoped.byteRangeRequested.endByte > scoped.byteRangeReturned.endByte) {
+                return `${obligation.obligationId} has an invalid delivered span contract for ${scoped.evidenceId}`;
+            }
+        }
+    }
+    for (const assessment of result.assessments) {
+        const obligation = context.obligation(assessment.obligationId);
+        if (!obligation)
+            continue;
+        if (!scopeCovers(assessment.scope, obligation.scope)
+            || !scopeCovers(obligation.scope, assessment.scope)) {
+            return `${assessment.obligationId} does not preserve its named build evidence scope`;
+        }
+        for (const scoped of obligation.scope.evidence ?? []) {
+            const evidence = evidenceById.get(scoped.evidenceId);
+            if (!evidence
+                || evidence.sourceEntryId !== scoped.sourceEntryId
+                || evidence.locator !== scoped.locator
+                || evidence.blobId !== scoped.blobId
+                || !sameByteRange(evidence.byteRangeRequested, scoped.byteRangeRequested)
+                || !sameByteRange(evidence.byteRangeReturned, scoped.byteRangeReturned)
+                || !/^sha256:[0-9a-f]{64}$/.test(evidence.originalSpanSha256 ?? '')
+                || !/^sha256:[0-9a-f]{64}$/.test(evidence.contentHash ?? '')
+                || evidence.delivery !== 'excerpt'
+                || evidence.localRetention !== 'none'
+                || !validDeliveryMap(evidence.deliveryMap, scoped.byteRangeReturned)) {
+                return `${assessment.obligationId} did not deliver the sealed metadata for ${scoped.evidenceId}`;
+            }
+        }
+    }
+    return null;
+};
+export const cited_range_within_returned = (result, context) => {
     const evidenceById = new Map(result.evidence.map((evidence) => [evidence.evidenceId, evidence]));
     for (const assessment of result.assessments) {
         if (!contributes(assessment))
@@ -316,6 +589,19 @@ export const cited_range_within_returned = (result) => {
             const evidence = evidenceById.get(citation.evidenceId);
             if (!evidence)
                 continue;
+            if (context.request.policyVersion === 'build-citation-check@1') {
+                if (!validByteRange(evidence.byteRangeReturned)) {
+                    return `${citation.evidenceId} has no usable canonical byteRangeReturned`;
+                }
+                if (!validByteRange(citation.citedByteRange)) {
+                    return `${citation.evidenceId} has no usable citedByteRange`;
+                }
+                if (citation.citedByteRange.startByte < evidence.byteRangeReturned.startByte
+                    || citation.citedByteRange.endByte > evidence.byteRangeReturned.endByte) {
+                    return `cited bytes [${citation.citedByteRange.startByte},${citation.citedByteRange.endByte}) lie outside delivered bytes [${evidence.byteRangeReturned.startByte},${evidence.byteRangeReturned.endByte})`;
+                }
+                continue;
+            }
             if (evidence.access !== 'truncated') {
                 if (citation.citedRange !== null
                     && citation.citedRange !== undefined
@@ -418,11 +704,15 @@ export const resultCheckNames = [
     'assessment_question_matches',
     'assessment_scope_covers',
     'policy4_surface_complete',
+    'prd_source_mismatch',
+    'prd_evidence_not_code',
+    'prd_fidelity_scope',
     'observed_sources_satisfy_obligation',
     'citation_source_allowed_by_obligation',
     'citation_evidence_delivered',
     'support_citation_usable',
     'changed_since_two_roles',
+    'build_citation_scope_matches',
     'cited_range_within_returned',
     'automatic_claim_shape_required',
     'automatic_claim_shape_abstains',
@@ -437,11 +727,15 @@ export const resultChecks = {
     assessment_question_matches,
     assessment_scope_covers,
     policy4_surface_complete,
+    prd_source_mismatch,
+    prd_evidence_not_code,
+    prd_fidelity_scope,
     observed_sources_satisfy_obligation,
     citation_source_allowed_by_obligation,
     citation_evidence_delivered,
     support_citation_usable,
     changed_since_two_roles,
+    build_citation_scope_matches,
     cited_range_within_returned,
     automatic_claim_shape_required,
     automatic_claim_shape_abstains,