tracegrove 0.0.0-stage → 0.3.0

package/dist/core/source-analysis.js

@@ -0,0 +1,99 @@
+import { z } from 'zod';
+import { ChangeModel, PlanSourceValidation, RefSchema, RevisionMatrix, ScopeSchema, SourcePlan, digestOfBytes, freeze, parseAs, refKey, refList, sameDigest, sameRef, sameScope, verifySelfDigest } from "../protocol/index.js";
+import { SourceCitation, verifySourceCitation } from "./source-citation.js";
+import { Conflict } from "./errors.js";
+import { newId } from "./clock.js";
+export const MAX_SOURCE_DIFF_BYTES = 4 * 1024 * 1024;
+const keys = (refs) => refs.map(refKey).sort().join('\n');
+/** Checks selected immutable source facts and derivations; supplies no execution authority. */
+export async function validatePlanSources(ports, input, policy) {
+    const plan = SourcePlan.parse(input);
+    if (new Set(plan.candidates.map(candidate => candidate.id)).size !== plan.candidates.length)
+        throw new Conflict('duplicate plan candidate identity');
+    const policyRef = RefSchema.parse(policy);
+    const scope = ScopeSchema.parse(plan.scope);
+    if (!verifySelfDigest(plan))
+        throw new Conflict('source plan digest mismatch');
+    const resolve = async (schema, ref) => {
+        const result = parseAs(schema, await ports.resolveDocument(structuredClone(ref), structuredClone(scope)), 'source document');
+        if (!sameRef(result.ref, ref) || !sameScope(result.scope, scope) || !verifySelfDigest(result))
+            throw new Conflict('source document digest or scope mismatch');
+        return result;
+    };
+    const model = await resolve(ChangeModel, plan.changeModelRef);
+    const matrix = await resolve(RevisionMatrix, plan.revisionMatrixRef);
+    if (!sameRef(model.revisionMatrixRef, matrix.ref))
+        throw new Conflict('change model revision matrix mismatch');
+    const repositories = new Map(matrix.repositories.map(repository => [refKey(repository.repositoryRef), repository]));
+    if (repositories.size !== matrix.repositories.length)
+        throw new Conflict('duplicate repository in revision matrix');
+    for (const repository of matrix.repositories) {
+        if ((repository.mergeBaseCommit === null) !== (repository.mergeBaseAbsentReason !== null))
+            throw new Conflict('missing merge base needs an explicit reason');
+        await ports.authorize(structuredClone(scope), structuredClone(repository.repositoryRef));
+        const diff = await ports.readDiff(structuredClone(scope), structuredClone(repository));
+        if (!(diff instanceof Uint8Array) || diff.byteLength > MAX_SOURCE_DIFF_BYTES || !sameDigest(digestOfBytes(Buffer.from(diff)), repository.diffRef.digest)) {
+            throw new Conflict('full diff bytes are unavailable, oversized or changed');
+        }
+    }
+    await ports.verifyRevisionPolicy(structuredClone(scope), structuredClone(matrix), structuredClone(policyRef));
+    const elements = new Map(model.elements.map(element => [element.id, element]));
+    if (elements.size !== model.elements.length)
+        throw new Conflict('duplicate source element identity');
+    const diagnostics = model.extractorReports.filter(report => report.status !== 'complete').flatMap(report => {
+        if (!report.diagnosticRefs.length)
+            throw new Conflict('incomplete extraction needs retained diagnostics');
+        return report.diagnosticRefs;
+    });
+    const gaps = new Set(plan.gapRefs.map(refKey));
+    if (diagnostics.some(ref => !gaps.has(refKey(ref))) || (model.unresolvedQuestions.length && !plan.gapRefs.length)) {
+        throw new Conflict('source plan discarded required extraction gaps');
+    }
+    const runnable = new Map();
+    for (const candidate of plan.candidates) {
+        if (candidate.sourceElementIds.some(id => !elements.has(id)))
+            throw new Conflict('candidate cites an unknown source element');
+        if (candidate.disposition !== 'runnable') {
+            if (!candidate.reasonRefs.length)
+                throw new Conflict('withheld candidate needs retained reasons');
+            continue;
+        }
+        if (!candidate.caseRef || !candidate.sourceElementIds.length)
+            throw new Conflict('runnable candidate needs a case and source elements');
+        for (const id of candidate.sourceElementIds)
+            runnable.set(id, elements.get(id));
+    }
+    const citations = new Map();
+    for (const element of runnable.values()) {
+        if (element.verification !== 'confirmed' || !element.citationRefs.length || !element.verificationEvidenceRefs.length) {
+            throw new Conflict('runnable derivation lacks confirmed independent source evidence');
+        }
+        const selected = [];
+        for (const ref of element.citationRefs) {
+            let citation = citations.get(refKey(ref));
+            if (!citation) {
+                if (citations.size >= 500)
+                    throw new Conflict('source validation exceeds the citation bound');
+                citation = SourceCitation.parse(await ports.resolveDocument(structuredClone(ref), structuredClone(scope)));
+                if (!sameRef(citation.ref, ref))
+                    throw new Conflict('citation resolver substituted its reference');
+                const repository = repositories.get(refKey(citation.repositoryRef));
+                if (!repository || ![repository.headCommit, repository.baseCommit, repository.mergeBaseCommit].includes(citation.resolvedCommit)) {
+                    throw new Conflict('citation is outside selected repository revisions');
+                }
+                citation = (await verifySourceCitation(ports, citation, scope)).citation;
+                citations.set(refKey(ref), citation);
+            }
+            selected.push(citation);
+        }
+        const checked = z.object({ verified: z.boolean(), evidenceRefs: refList().min(1) }).strict().parse(await ports.verifyElement(structuredClone(scope), structuredClone(element), structuredClone(selected), structuredClone(policyRef)));
+        if (!checked.verified || keys(checked.evidenceRefs) !== keys(element.verificationEvidenceRefs))
+            throw new Conflict('independent element confirmation disagrees');
+    }
+    await ports.verifyCoverage(structuredClone(scope), structuredClone(plan), structuredClone(model), structuredClone(policyRef));
+    return PlanSourceValidation.parse(freeze({ schemaVersion: 'workflow.source-validation/v1', ref: { id: newId('source-validation'), revision: '1' },
+        scope, sourcePlanRef: plan.ref, changeModelRef: model.ref, revisionMatrixRef: matrix.ref, policyRef,
+        verifiedCitationRefs: [...citations.values()].map(citation => citation.ref), runnableElementIds: [...runnable.keys()], retainedDiagnosticRefs: diagnostics,
+    }));
+}
+//# sourceMappingURL=source-analysis.js.map

package/dist/core/source-analysis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-analysis.js","sourceRoot":"","sources":["../../src/core/source-analysis.ts"],"names":[],"mappings":"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"}

package/dist/core/source-citation.d.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+import { type Ref, type Scope } from '../protocol/index.ts';
+export { RepositoryPath } from '../protocol/index.ts';
+/** Source facts only: this does not attest deployed behavior or execution admission. */
+export declare const SourceCitation: z.ZodObject<{
+    ref: z.ZodObject<{
+        id: z.ZodString;
+        revision: z.ZodString;
+        digest: z.ZodObject<{
+            algorithm: z.ZodLiteral<"sha256">;
+            hex: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    repositoryRef: z.ZodObject<{
+        id: z.ZodString;
+        revision: z.ZodString;
+        digest: z.ZodObject<{
+            algorithm: z.ZodLiteral<"sha256">;
+            hex: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    resolvedCommit: z.ZodString;
+    path: z.ZodString;
+    fileDigest: z.ZodObject<{
+        algorithm: z.ZodLiteral<"sha256">;
+        hex: z.ZodString;
+    }, z.core.$strict>;
+    lineStart: z.ZodNumber;
+    lineEnd: z.ZodNumber;
+    excerptDigest: z.ZodObject<{
+        algorithm: z.ZodLiteral<"sha256">;
+        hex: z.ZodString;
+    }, z.core.$strict>;
+    symbol: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type SourceCitation = z.infer<typeof SourceCitation>;
+export interface SourceCitationPorts {
+    /** Trusted host authorization, never supplied by a candidate or plugin. */
+    authorize(scope: Scope, repositoryRef: Ref): Promise<void>;
+    /** Fetch that immutable object; unavailable objects must fail without checkout fallback. */
+    readFile(scope: Scope, citation: SourceCitation): Promise<{
+        repositoryRef: Ref;
+        resolvedCommit: string;
+        path: string;
+        bytes: Uint8Array;
+    }>;
+}
+export declare const SOURCE_FILE_MAX_BYTES = 1048576;
+export declare function verifySourceCitation(ports: SourceCitationPorts, input: unknown, requestedScope: Scope): Promise<{
+    citation: SourceCitation;
+    fileBytes: number;
+    excerptBytes: number;
+}>;

package/dist/core/source-citation.js

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import { DigestSchema, PositiveInt, RefSchema, ScopeSchema, ShortText, GitObjectId, RepositoryPath, digestOfBytes, sameDigest, sameRef, verifySelfDigest, } from "../protocol/index.js";
+import { Conflict } from "./errors.js";
+export { RepositoryPath } from "../protocol/index.js";
+/** Source facts only: this does not attest deployed behavior or execution admission. */
+export const SourceCitation = z.object({
+    ref: RefSchema,
+    repositoryRef: RefSchema,
+    resolvedCommit: GitObjectId,
+    path: RepositoryPath,
+    fileDigest: DigestSchema,
+    lineStart: PositiveInt,
+    lineEnd: PositiveInt,
+    excerptDigest: DigestSchema,
+    symbol: ShortText.nullable(),
+}).strict();
+export const SOURCE_FILE_MAX_BYTES = 1_048_576;
+/** Inclusive LF-delimited lines; preserve all original bytes, including CRLF and terminators. */
+function excerpt(bytes, start, end) {
+    const boundaries = [0];
+    for (let index = 0; index < bytes.length; index += 1) {
+        if (bytes[index] === 10 && index + 1 < bytes.length)
+            boundaries.push(index + 1);
+    }
+    const lineCount = bytes.length === 0 ? 0 : boundaries.length;
+    if (end < start || end > lineCount)
+        throw new Conflict('citation line range is outside fetched source');
+    return bytes.subarray(boundaries[start - 1], boundaries[end] ?? bytes.length);
+}
+export async function verifySourceCitation(ports, input, requestedScope) {
+    const citation = SourceCitation.parse(input);
+    const scope = ScopeSchema.parse(requestedScope);
+    if (!verifySelfDigest(citation))
+        throw new Conflict('citation document digest mismatch');
+    if (citation.lineEnd < citation.lineStart)
+        throw new Conflict('citation line range is reversed');
+    // Copies keep a host callback from mutating the selected identity or parsed snapshot.
+    await ports.authorize(structuredClone(scope), structuredClone(citation.repositoryRef));
+    const file = await ports.readFile(structuredClone(scope), structuredClone(citation));
+    if (!sameRef(RefSchema.parse(file.repositoryRef), citation.repositoryRef)
+        || file.resolvedCommit !== citation.resolvedCommit || file.path !== citation.path) {
+        throw new Conflict('fetched source identity does not match citation');
+    }
+    if (!(file.bytes instanceof Uint8Array) || file.bytes.byteLength > SOURCE_FILE_MAX_BYTES) {
+        throw new Conflict('fetched source exceeds supported byte bound or is not bytes');
+    }
+    const bytes = Buffer.from(file.bytes);
+    // Reject binary/invalid UTF-8 instead of inventing replacement characters or line facts.
+    new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    if (bytes.includes(0))
+        throw new Conflict('binary source cannot supply a line citation');
+    if (!sameDigest(digestOfBytes(bytes), citation.fileDigest))
+        throw new Conflict('fetched file digest mismatch');
+    const selected = excerpt(bytes, citation.lineStart, citation.lineEnd);
+    if (!sameDigest(digestOfBytes(selected), citation.excerptDigest))
+        throw new Conflict('fetched excerpt digest mismatch');
+    return { citation, fileBytes: bytes.length, excerptBytes: selected.length };
+}
+//# sourceMappingURL=source-citation.js.map

package/dist/core/source-citation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-citation.js","sourceRoot":"","sources":["../../src/core/source-citation.ts"],"names":[],"mappings":"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"}