@withtruing/companion 0.0.0-stage → 0.13.0

package/dist/observed-sources.js

@@ -0,0 +1,85 @@
+import { createSandbox } from './sandbox.js';
+/** Resolve every immutable identity before exposing any worktree for reading. This prevents an
+ * earlier source from being inspected before a later required source proves unavailable. */
+export async function obtainRequestedSources(request, connections) {
+    const sourceEntryIds = new Set();
+    for (const source of request.requestedSources) {
+        if (sourceEntryIds.has(source.sourceEntryId)) {
+            throw new Error(`Investigation repeats sourceEntryId ${source.sourceEntryId}`);
+        }
+        sourceEntryIds.add(source.sourceEntryId);
+    }
+    const observedSources = [];
+    const sandboxes = new Map();
+    const cleanup = async () => {
+        const pending = [...sandboxes.values()];
+        sandboxes.clear();
+        await Promise.all(pending.map((sandbox) => sandbox.cleanup()));
+    };
+    try {
+        for (const source of request.requestedSources) {
+            const connection = connections.find((candidate) => candidate.connectionId === source.connectionId);
+            if (!connection) {
+                observedSources.push({
+                    sourceEntryId: source.sourceEntryId,
+                    role: source.role,
+                    connectionId: source.connectionId,
+                    sourceIdentity: `unavailable:no configured checkout for connection ${source.connectionId}`,
+                    obtainedBy: 'unavailable',
+                });
+                continue;
+            }
+            const sandbox = await createSandbox(connection.repoPath, source.commit);
+            if (sandbox.obtainedBy === 'unavailable') {
+                observedSources.push({
+                    sourceEntryId: source.sourceEntryId,
+                    role: source.role,
+                    connectionId: source.connectionId,
+                    sourceIdentity: sandbox.sourceIdentity,
+                    obtainedBy: sandbox.obtainedBy,
+                    ...(sandbox.fetchOk === undefined ? {} : { fetchOk: sandbox.fetchOk }),
+                });
+                continue;
+            }
+            sandboxes.set(source.sourceEntryId, sandbox);
+            observedSources.push({
+                sourceEntryId: source.sourceEntryId,
+                role: source.role,
+                connectionId: source.connectionId,
+                sourceIdentity: sandbox.sourceIdentity,
+                obtainedBy: sandbox.obtainedBy,
+                ...(sandbox.fetchOk === undefined ? {} : { fetchOk: sandbox.fetchOk }),
+            });
+        }
+    }
+    catch (error) {
+        await cleanup();
+        throw error;
+    }
+    return {
+        observedSources,
+        sandboxes,
+        unavailable: observedSources.some((source) => source.obtainedBy === 'unavailable'),
+        cleanup,
+    };
+}
+/** Obtain each requested immutable source, optionally inspect it while its worktree is alive, and
+ * return the observed-source half of a reader result. Every created worktree is cleaned in a
+ * finally block, including when the inspection callback crashes. */
+export async function buildObservedSources(request, connections, inspectSource = async () => { }) {
+    const obtained = await obtainRequestedSources(request, connections);
+    try {
+        if (!obtained.unavailable) {
+            for (const source of request.requestedSources) {
+                const sandbox = obtained.sandboxes.get(source.sourceEntryId);
+                if (!sandbox)
+                    throw new Error(`No sandbox obtained for ${source.sourceEntryId}`);
+                await inspectSource(source, sandbox);
+            }
+        }
+        return obtained.observedSources;
+    }
+    finally {
+        await obtained.cleanup();
+    }
+}

package/dist/reader-result-contract.js

@@ -0,0 +1,467 @@
+const contributes = (assessment) => assessment.outcome === 'supported' || assessment.outcome === 'contradicted';
+const breadth = { element: 0, named_paths: 1, module_surface: 2 };
+export function scopeCovers(covering, declared) {
+    const coveringHasSurface = covering.surfaceId !== undefined || covering.surfaceHash !== undefined;
+    const declaredHasSurface = declared.surfaceId !== undefined || declared.surfaceHash !== undefined;
+    if (coveringHasSurface || declaredHasSurface) {
+        if (covering.surfaceId !== declared.surfaceId || covering.surfaceHash !== declared.surfaceHash)
+            return false;
+    }
+    if (breadth[covering.breadth] < breadth[declared.breadth])
+        return false;
+    const coveredOperations = new Set(covering.operations ?? []);
+    if ((declared.operations ?? []).some((operation) => !coveredOperations.has(operation))) {
+        return false;
+    }
+    if (declared.breadth !== 'named_paths' || covering.breadth !== 'named_paths')
+        return true;
+    const covered = new Set(covering.paths || []);
+    return (declared.paths || []).every((path) => covered.has(path));
+}
+const inventoryAccess = {
+    read: ['read_ok'],
+    missing: ['read_failed', 'not_found'],
+    truncated: ['truncated'],
+    skipped: ['skipped_size'],
+};
+function evidenceRepositoryPath(evidence, sourceEntries) {
+    const source = sourceEntries.find((entry) => entry.sourceEntryId === evidence.sourceEntryId);
+    if (!source)
+        return null;
+    const prefix = `repo:${source.connectionId}@${source.commit}:`;
+    return evidence.locator.startsWith(prefix) ? evidence.locator.slice(prefix.length) : null;
+}
+/**
+ * Checks only factual access metadata. It deliberately does not judge whether the delivered
+ * evidence is sufficient for the assessment's declared semantic scope.
+ */
+export function factualInventoryError(scope, evidence, sourceEntries, allowedSourceEntryIds) {
+    if (!scope.investigated)
+        return null;
+    const allowed = new Set(allowedSourceEntryIds);
+    const eligible = evidence
+        .filter((row) => allowed.has(row.sourceEntryId))
+        .map((row) => ({ row, path: evidenceRepositoryPath(row, sourceEntries) }))
+        .filter((item) => item.path !== null);
+    for (const bucket of Object.keys(inventoryAccess)) {
+        for (const claimedPath of scope.investigated[bucket]) {
+            if (!eligible.some(({ row, path }) => path === claimedPath && inventoryAccess[bucket].includes(row.access))) {
+                return `${bucket} inventory claims '${claimedPath}' without matching ${inventoryAccess[bucket].join(' or ')} evidence from an allowed repository snapshot`;
+            }
+        }
+    }
+    for (const claimedSearch of scope.investigated.searched) {
+        if (!eligible.some(({ row }) => row.kind === 'search_result'
+            && row.delivery === 'search_result'
+            && (row.access === 'read_ok' || row.access === 'truncated')
+            && row.query === claimedSearch)) {
+            return `searched inventory claims '${claimedSearch}' without matching delivered search evidence from an allowed repository snapshot`;
+        }
+    }
+    return null;
+}
+function parseRange(value) {
+    const match = /^L(\d+)-L(\d+)$/.exec(String(value || ''));
+    if (!match)
+        return null;
+    const start = Number(match[1]);
+    const end = Number(match[2]);
+    return start <= end ? [start, end] : null;
+}
+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}`;
+    return null;
+};
+export const identifiers_unique = (result, context) => {
+    const duplicate = (values) => values.find((value, index) => values.indexOf(value) !== index);
+    let found = duplicate(result.evidence.map((evidence) => evidence.evidenceId));
+    if (found)
+        return `evidence id ${found} appears twice`;
+    found = duplicate(result.assessments.map((assessment) => assessment.obligationId));
+    if (found)
+        return `two assessments answer ${found}`;
+    found = duplicate(result.observedSources.map((source) => source.sourceEntryId));
+    if (found)
+        return `source entry ${found} observed twice`;
+    found = duplicate(context.request.requestedSources.map((source) => source.sourceEntryId));
+    if (found)
+        return `request lists source entry ${found} twice`;
+    for (const assessment of result.assessments) {
+        const citations = new Set();
+        for (const citation of assessment.citations) {
+            const key = JSON.stringify([citation.evidenceId, citation.use]);
+            if (citations.has(key)) {
+                return `${assessment.obligationId} cites evidence ${citation.evidenceId} as ${citation.use} twice`;
+            }
+            citations.add(key);
+        }
+    }
+    return null;
+};
+export const policy4_surface_complete = (result, context) => {
+    if (context.request.policyVersion !== 'policy-4')
+        return null;
+    const surface = context.request.surface;
+    if (!surface)
+        return 'policy-4 request has no sealed surface';
+    if (!result.execution)
+        return 'policy-4 result has no execution metadata';
+    const requested = context.sourceEntry(surface.sourceEntryId);
+    if (!requested
+        || requested.role !== 'current'
+        || requested.commit !== surface.commit) {
+        return 'sealed surface source does not match the requested current source';
+    }
+    for (const obligation of context.request.obligations) {
+        if (obligation.scope.surfaceId !== surface.surfaceId
+            || obligation.scope.surfaceHash !== surface.surfaceHash) {
+            return `${obligation.obligationId} does not carry the sealed surface identity`;
+        }
+    }
+    const expectedLocator = (path) => `repo:${requested.connectionId}@${surface.commit}:${path}`;
+    for (const assessment of result.assessments) {
+        if (assessment.scope.surfaceId !== surface.surfaceId
+            || assessment.scope.surfaceHash !== surface.surfaceHash) {
+            return `${assessment.obligationId} does not report the sealed surface identity`;
+        }
+        if (!contributes(assessment))
+            continue;
+        if (assessment.scope.breadth !== 'module_surface'
+            || assessment.scope.surfaceId !== surface.surfaceId
+            || assessment.scope.surfaceHash !== surface.surfaceHash) {
+            return `${assessment.obligationId} is positive without the complete sealed surface scope`;
+        }
+        for (const path of surface.entries) {
+            const rows = result.evidence.filter((row) => row.sourceEntryId === surface.sourceEntryId && row.locator === expectedLocator(path));
+            if (rows.length !== 1
+                || rows[0].kind !== 'source_file'
+                || rows[0].access !== 'read_ok'
+                || rows[0].delivery !== 'full_file'
+                || rows[0].complete !== 1) {
+                return `${assessment.obligationId} is positive without complete delivery of ${path}`;
+            }
+        }
+    }
+    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) {
+        if (!entries.has(evidence.sourceEntryId))
+            return `evidence ${evidence.evidenceId} cites source entry ${evidence.sourceEntryId}, which was never requested`;
+    }
+    for (const source of result.observedSources) {
+        if (!entries.has(source.sourceEntryId))
+            return `observed source ${source.sourceEntryId} was never requested`;
+    }
+    return null;
+};
+export const assessment_obligation_issued = (result, context) => {
+    const issued = new Set(context.request.obligations.map((obligation) => obligation.obligationId));
+    for (const assessment of result.assessments) {
+        if (!issued.has(assessment.obligationId))
+            return `assessment answers ${assessment.obligationId}, which this investigation never issued`;
+    }
+    return null;
+};
+export const assessment_question_matches = (result, context) => {
+    for (const assessment of result.assessments) {
+        if (!contributes(assessment))
+            continue;
+        const obligation = context.obligation(assessment.obligationId);
+        if (!obligation)
+            continue;
+        if (assessment.question !== obligation.question)
+            return `${assessment.obligationId} asks '${obligation.question}'; the assessment answers '${assessment.question}'`;
+        if (assessment.finding && assessment.finding.question !== assessment.question)
+            return `${assessment.obligationId}: finding answers '${assessment.finding.question}', assessment claims '${assessment.question}'`;
+    }
+    return null;
+};
+export const assessment_scope_covers = (result, context) => {
+    const evidenceById = new Map(result.evidence.map((row) => [row.evidenceId, row]));
+    for (const assessment of result.assessments) {
+        const obligation = context.obligation(assessment.obligationId);
+        if (!obligation)
+            continue;
+        const hasUnusableSupport = assessment.citations.some((citation) => {
+            if (citation.use !== 'support')
+                return false;
+            const row = evidenceById.get(citation.evidenceId);
+            return row && row.access !== 'read_ok' && row.access !== 'truncated';
+        });
+        if (!hasUnusableSupport) {
+            const inventoryError = factualInventoryError(assessment.scope, result.evidence, context.request.requestedSources, obligation.requiredSourceEntryIds);
+            if (inventoryError)
+                return `${assessment.obligationId}: ${inventoryError}`;
+        }
+        if (!contributes(assessment))
+            continue;
+        if (!scopeCovers(assessment.scope, obligation.scope)) {
+            if (breadth[assessment.scope.breadth] < breadth[obligation.scope.breadth])
+                return `${assessment.obligationId} declares '${obligation.scope.breadth}'; the assessment investigated only '${assessment.scope.breadth}'`;
+            const coveredOperations = new Set(assessment.scope.operations ?? []);
+            const missingOperations = (obligation.scope.operations ?? [])
+                .filter((operation) => !coveredOperations.has(operation));
+            if (missingOperations.length) {
+                return `${assessment.obligationId}: declared operations not covered — ${missingOperations.join(', ')}`;
+            }
+        }
+        if (obligation.scope.breadth === 'named_paths' && assessment.scope.breadth === 'named_paths') {
+            const covered = new Set(assessment.scope.paths || []);
+            const missing = (obligation.scope.paths || []).filter((path) => !covered.has(path));
+            if (missing.length)
+                return `${assessment.obligationId}: declared paths not covered — ${missing.join(', ')}`;
+        }
+    }
+    return null;
+};
+export const observed_sources_satisfy_obligation = (result, context) => {
+    const observed = new Map(result.observedSources.map((source) => [source.sourceEntryId, source]));
+    for (const assessment of result.assessments) {
+        if (!contributes(assessment))
+            continue;
+        const obligation = context.obligation(assessment.obligationId);
+        if (!obligation)
+            continue;
+        for (const entryId of obligation.requiredSourceEntryIds) {
+            const expected = context.sourceEntry(entryId);
+            const actual = observed.get(entryId);
+            if (!actual)
+                return `${assessment.obligationId} requires ${entryId}, which was never observed`;
+            if (!expected)
+                continue;
+            if (actual.role !== expected.role)
+                return `${entryId}: requested role '${expected.role}', observed '${actual.role}'`;
+            if (actual.connectionId !== expected.connectionId)
+                return `${entryId}: requested repository '${expected.connectionId}', observed '${actual.connectionId}'`;
+            if (actual.sourceIdentity !== `commit:${expected.commit}`)
+                return `${entryId}: requested commit:${expected.commit}, observed '${actual.sourceIdentity}'`;
+        }
+    }
+    return null;
+};
+export const citation_source_allowed_by_obligation = (result, context) => {
+    const evidenceById = new Map(result.evidence.map((evidence) => [evidence.evidenceId, evidence]));
+    for (const assessment of result.assessments) {
+        const obligation = context.obligation(assessment.obligationId);
+        if (!obligation)
+            continue;
+        const allowed = new Set(obligation.requiredSourceEntryIds);
+        for (const citation of assessment.citations) {
+            const evidence = evidenceById.get(citation.evidenceId);
+            if (!evidence)
+                continue;
+            if (!allowed.has(evidence.sourceEntryId))
+                return `${assessment.obligationId} cites ${citation.evidenceId} from ${evidence.sourceEntryId}, which is not one of its required sources`;
+        }
+    }
+    return null;
+};
+export const citation_evidence_delivered = (result) => {
+    const delivered = new Set(result.evidence.map((evidence) => evidence.evidenceId));
+    for (const assessment of result.assessments) {
+        for (const citation of assessment.citations) {
+            if (!delivered.has(citation.evidenceId))
+                return `citation of ${citation.evidenceId}, not delivered in this result`;
+        }
+    }
+    return null;
+};
+export const support_citation_usable = (result) => {
+    const evidenceById = new Map(result.evidence.map((evidence) => [evidence.evidenceId, evidence]));
+    for (const assessment of result.assessments) {
+        for (const citation of assessment.citations) {
+            if (citation.use !== 'support')
+                continue;
+            const evidence = evidenceById.get(citation.evidenceId);
+            if (!evidence)
+                continue;
+            if (evidence.access !== 'read_ok' && evidence.access !== 'truncated')
+                return `${citation.evidenceId} has access '${evidence.access}' and may be cited only as a limitation`;
+        }
+    }
+    return null;
+};
+export const changed_since_two_roles = (result, context) => {
+    const evidenceById = new Map(result.evidence.map((evidence) => [evidence.evidenceId, evidence]));
+    for (const assessment of result.assessments) {
+        const obligation = context.obligation(assessment.obligationId);
+        if (!obligation || obligation.question !== 'changed_since')
+            continue;
+        if (!contributes(assessment))
+            continue;
+        const roles = obligation.requiredSourceEntryIds.map((id) => context.sourceEntry(id)?.role);
+        if (!roles.includes('base') || !roles.includes('current'))
+            return `${assessment.obligationId}: changed_since needs a base AND a current entry; got ${roles.join(', ')}`;
+        const cited = new Set(assessment.citations
+            .filter((citation) => citation.use === 'support')
+            .map((citation) => evidenceById.get(citation.evidenceId))
+            .filter((evidence) => Boolean(evidence))
+            .map((evidence) => context.sourceEntry(evidence.sourceEntryId)?.role));
+        if (!cited.has('base') || !cited.has('current'))
+            return `${assessment.obligationId}: a resolved historical conclusion cites support from [${[...cited].join(', ') || 'nothing'}]; both base and current are required`;
+    }
+    return null;
+};
+export const cited_range_within_returned = (result) => {
+    const evidenceById = new Map(result.evidence.map((evidence) => [evidence.evidenceId, evidence]));
+    for (const assessment of result.assessments) {
+        if (!contributes(assessment))
+            continue;
+        for (const citation of assessment.citations) {
+            const evidence = evidenceById.get(citation.evidenceId);
+            if (!evidence)
+                continue;
+            if (evidence.access !== 'truncated') {
+                if (citation.citedRange !== null
+                    && citation.citedRange !== undefined
+                    && !parseRange(citation.citedRange)) {
+                    return `${citation.evidenceId} has an unparsable citedRange ('${citation.citedRange}')`;
+                }
+                continue;
+            }
+            if (citation.use !== 'support'
+                && (citation.citedRange === null || citation.citedRange === undefined))
+                continue;
+            const returned = parseRange(evidence.rangeReturned);
+            if (!returned)
+                return `${citation.evidenceId} was truncated but reports no usable rangeReturned ('${evidence.rangeReturned}')`;
+            const cited = parseRange(citation.citedRange);
+            if (!cited)
+                return `${citation.evidenceId} is truncated support with a missing or unparsable citedRange ('${citation.citedRange}')`;
+            if (cited[0] < returned[0] || cited[1] > returned[1])
+                return `cited ${citation.citedRange} lies outside delivered ${evidence.rangeReturned}`;
+        }
+    }
+    return null;
+};
+const AUTOMATIC_SURFACE_REASONS = new Set([
+    'depends_on_unmapped_absence',
+    'absent_from_automatic_surface',
+]);
+const automaticSurface = (context) => context.request.surface?.surfaceOrigin === 'automatic' ? context.request.surface : null;
+/** Automatic-surface rule 1: the assessor states the shape of every claim it judged. */
+export const automatic_claim_shape_required = (result, context) => {
+    if (!automaticSurface(context))
+        return null;
+    for (const assessment of result.assessments) {
+        if (assessment.claimShape === undefined)
+            return `${assessment.obligationId} has no claimShape on an automatic surface`;
+    }
+    return null;
+};
+/**
+ * Automatic-surface rule 2: a negative or universal claim depends on code the map might have
+ * missed, so it may only abstain with depends_on_unmapped_absence.
+ */
+export const automatic_claim_shape_abstains = (result, context) => {
+    if (!automaticSurface(context))
+        return null;
+    for (const assessment of result.assessments) {
+        if (assessment.claimShape === undefined || assessment.claimShape === 'positive')
+            continue;
+        if (assessment.outcome !== 'not_established'
+            || assessment.outcomeReason !== 'depends_on_unmapped_absence') {
+            return `${assessment.obligationId} is a ${assessment.claimShape} claim on an automatic surface; only not_established / depends_on_unmapped_absence is legal`;
+        }
+    }
+    return null;
+};
+/** Automatic-surface rule 4: the automatic-surface reasons explain an abstention, nothing else. */
+export const automatic_reason_requires_not_established = (result, context) => {
+    if (!automaticSurface(context))
+        return null;
+    for (const assessment of result.assessments) {
+        if (AUTOMATIC_SURFACE_REASONS.has(assessment.outcomeReason)
+            && assessment.outcome !== 'not_established') {
+            return `${assessment.obligationId} carries ${assessment.outcomeReason} with outcome '${assessment.outcome}'; only not_established may`;
+        }
+    }
+    return null;
+};
+/**
+ * Automatic-surface rule 3: supported or contradicted needs at least one support citation of a
+ * path inside the surface. A citation outside the map does not count.
+ */
+export const automatic_verdict_cites_surface = (result, context) => {
+    const surface = automaticSurface(context);
+    if (!surface)
+        return null;
+    const entries = new Set(surface.entries);
+    const evidenceById = new Map(result.evidence.map((evidence) => [evidence.evidenceId, evidence]));
+    for (const assessment of result.assessments) {
+        if (!contributes(assessment))
+            continue;
+        const citesSurface = assessment.citations.some((citation) => {
+            if (citation.use !== 'support')
+                return false;
+            const evidence = evidenceById.get(citation.evidenceId);
+            if (!evidence || evidence.sourceEntryId !== surface.sourceEntryId)
+                return false;
+            const path = evidenceRepositoryPath(evidence, context.request.requestedSources);
+            return path !== null && entries.has(path);
+        });
+        if (!citesSurface)
+            return `${assessment.obligationId} is ${assessment.outcome} on an automatic surface without a support citation inside the surface`;
+    }
+    return null;
+};
+export const resultCheckNames = [
+    'result_binds_request',
+    'identifiers_unique',
+    'evidence_source_entry_requested',
+    'assessment_obligation_issued',
+    'assessment_question_matches',
+    'assessment_scope_covers',
+    'policy4_surface_complete',
+    'observed_sources_satisfy_obligation',
+    'citation_source_allowed_by_obligation',
+    'citation_evidence_delivered',
+    'support_citation_usable',
+    'changed_since_two_roles',
+    'cited_range_within_returned',
+    'automatic_claim_shape_required',
+    'automatic_claim_shape_abstains',
+    'automatic_reason_requires_not_established',
+    'automatic_verdict_cites_surface',
+];
+export const resultChecks = {
+    result_binds_request,
+    identifiers_unique,
+    evidence_source_entry_requested,
+    assessment_obligation_issued,
+    assessment_question_matches,
+    assessment_scope_covers,
+    policy4_surface_complete,
+    observed_sources_satisfy_obligation,
+    citation_source_allowed_by_obligation,
+    citation_evidence_delivered,
+    support_citation_usable,
+    changed_since_two_roles,
+    cited_range_within_returned,
+    automatic_claim_shape_required,
+    automatic_claim_shape_abstains,
+    automatic_reason_requires_not_established,
+    automatic_verdict_cites_surface,
+};
+export function createWireContext(request, result) {
+    return {
+        request,
+        result,
+        obligation: (id) => request.obligations.find((obligation) => obligation.obligationId === id),
+        sourceEntry: (id) => request.requestedSources.find((source) => source.sourceEntryId === id),
+    };
+}
+export function validateReaderResult(request, result) {
+    const context = createWireContext(request, result);
+    for (const check of resultCheckNames) {
+        const message = resultChecks[check](result, context);
+        if (message)
+            return { ok: false, check, message };
+    }
+    return { ok: true };
+}