@davesheffer/hunch 1.22.2 → 1.23.1

package/dist/core/changeProofContract.js

@@ -0,0 +1,253 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { compareCodeUnits } from "./canonicalOrder.js";
+export const CHANGE_PROOF_SCHEMA_VERSION = "hunch.change-proof/1";
+export const CHANGE_PROOF_ALGORITHM = "hunch-change-proof-sha256/1";
+export const CHANGE_PROOF_VERDICTS = ["fail", "pass", "unknown"];
+export const CHANGE_PROOF_RELEVANCE = ["blast_radius", "changed_path", "conformance", "guard"];
+const GIT_OBJECT = /^[a-f0-9]{40,64}$/;
+const SHA1 = /^sha1:[a-f0-9]{40}$/;
+const SHA256 = /^sha256:[a-f0-9]{64}$/;
+const CHANGE_ID = /^hchg_[a-f0-9]{24}$/;
+const PROOF_ID = /^hproof_[a-f0-9]{24}$/;
+const PROFILE_ID = /^pdna_[a-f0-9]{24}$/;
+const REPOSITORY_ID = /^pdnar_[a-f0-9]{24}$/;
+const RepoPathSchema = z.string().min(1).max(4_096).refine((path) => {
+    if (path.includes("\0") || path.includes("\\") || path.startsWith("/") || /^[A-Za-z]:/.test(path))
+        return false;
+    return !path.split("/").some((segment) => segment === "" || segment === "." || segment === "..");
+}, "repository path must be canonical and relative");
+const HashGapSchema = z.object({
+    code: z.string().regex(/^[a-z][a-z0-9_.-]{2,127}$/),
+    count: z.number().int().positive().max(1_000_000),
+    evidence_hash: z.string().regex(SHA256),
+}).strict();
+const ChangeIdentitySchema = z.object({
+    schema: z.literal("hunch.change-identity/1"),
+    algorithm: z.literal("git-raw-tree-delta-sha256/1"),
+    change_id: z.string().regex(CHANGE_ID),
+    base_revision: z.string().regex(GIT_OBJECT),
+    head_revision: z.string().regex(GIT_OBJECT),
+    base_tree: z.string().regex(GIT_OBJECT),
+    head_tree: z.string().regex(GIT_OBJECT),
+    delta_hash: z.string().regex(SHA256),
+    patch_id: z.string().regex(GIT_OBJECT).nullable(),
+    file_count: z.number().int().positive().max(16_384),
+    paths_hash: z.string().regex(SHA256),
+    content_hash: z.string().regex(SHA256),
+}).strict();
+const GraphSealSchema = z.object({
+    source: z.literal("commit"),
+    revision: z.string().regex(GIT_OBJECT),
+    source_hash: z.string().regex(SHA1),
+    topology_hash: z.string().regex(SHA256),
+    files: z.number().int().nonnegative().max(1_000_000),
+    symbols: z.number().int().nonnegative().max(10_000_000),
+    edges: z.number().int().nonnegative().max(50_000_000),
+    components: z.number().int().nonnegative().max(1_000_000),
+    issue_count: z.number().int().nonnegative().max(1_000_000),
+}).strict();
+const BlastEntrySchema = z.object({
+    source_path: RepoPathSchema,
+    dependent_path: RepoPathSchema,
+    depth: z.number().int().min(1).max(4),
+    graphs: z.array(z.enum(["base", "result"])).min(1).max(2),
+}).strict();
+const DecisionRefSchema = z.object({
+    id: z.string().regex(/^dec_[A-Za-z0-9_.-]{3,}$/),
+    record_hash: z.string().regex(SHA256),
+    relevance: z.array(z.enum(CHANGE_PROOF_RELEVANCE)).min(1).max(4),
+    paths: z.array(RepoPathSchema).max(128),
+    path_count: z.number().int().nonnegative().max(1_000_000),
+    paths_hash: z.string().regex(SHA256),
+}).strict();
+const ConstraintRefSchema = z.object({
+    id: z.string().regex(/^con_[A-Za-z0-9_.-]{3,}$/),
+    record_hash: z.string().regex(SHA256),
+    severity: z.enum(["advisory", "warning", "blocking"]),
+    relevance: z.array(z.enum(["blast_radius", "changed_path"])).min(1).max(2),
+    paths: z.array(RepoPathSchema).max(128),
+    path_count: z.number().int().nonnegative().max(1_000_000),
+    paths_hash: z.string().regex(SHA256),
+}).strict();
+const ConformanceReceiptSchema = z.object({
+    decision_id: z.string().regex(/^dec_[A-Za-z0-9_.-]{3,}$/),
+    predicate_index: z.number().int().nonnegative().max(1_000_000),
+    predicate_hash: z.string().regex(SHA256),
+    satisfied: z.boolean(),
+    detail_hash: z.string().regex(SHA256),
+}).strict();
+export const ChangeProofSchema = z.object({
+    schema: z.literal(CHANGE_PROOF_SCHEMA_VERSION),
+    algorithm: z.literal(CHANGE_PROOF_ALGORITHM),
+    proof_id: z.string().regex(PROOF_ID),
+    engine: z.object({
+        package: z.literal("@davesheffer/hunch"),
+        version: z.string().min(1).max(64),
+    }).strict(),
+    repository: z.object({
+        repository_id: z.string().regex(REPOSITORY_ID),
+        base_revision: z.string().regex(GIT_OBJECT),
+        result_revision: z.string().regex(GIT_OBJECT),
+    }).strict(),
+    change: ChangeIdentitySchema,
+    project_dna: z.object({
+        schema: z.literal("hunch.project-dna/1"),
+        profile_id: z.string().regex(PROFILE_ID),
+        repository_id: z.string().regex(REPOSITORY_ID),
+        repository_revision: z.string().regex(GIT_OBJECT),
+        content_hash: z.string().regex(SHA256),
+        trait_ids: z.array(z.string().regex(/^pdnat_[a-f0-9]{20}$/)).max(64),
+    }).strict(),
+    graph: z.object({
+        base: GraphSealSchema,
+        result: GraphSealSchema,
+    }).strict(),
+    changed_files: z.array(RepoPathSchema).max(2_048),
+    changed_file_count: z.number().int().positive().max(16_384),
+    blast_radius: z.array(BlastEntrySchema).max(4_096),
+    blast_radius_count: z.number().int().nonnegative().max(10_000_000),
+    decisions: z.array(DecisionRefSchema).max(1_024),
+    decision_count: z.number().int().nonnegative().max(1_000_000),
+    constraints: z.array(ConstraintRefSchema).max(1_024),
+    constraint_count: z.number().int().nonnegative().max(1_000_000),
+    conformance: z.array(ConformanceReceiptSchema).max(1_024),
+    conformance_count: z.number().int().nonnegative().max(1_000_000),
+    guard: z.object({
+        verdict: z.enum(["pass", "fail"]),
+        strict_blocker_ids: z.array(z.string().min(1).max(256)).max(2_048),
+        regression_decision_ids: z.array(z.string().regex(/^dec_[A-Za-z0-9_.-]{3,}$/)).max(1_024),
+        veto_decision_ids: z.array(z.string().regex(/^dec_[A-Za-z0-9_.-]{3,}$/)).max(1_024),
+        report_hash: z.string().regex(SHA256),
+    }).strict(),
+    memory: z.object({
+        scope: z.enum(["public", "union"]),
+        records_hash: z.string().regex(SHA256),
+    }).strict(),
+    omissions: z.array(HashGapSchema).max(64),
+    unknowns: z.array(HashGapSchema).max(64),
+    verdict: z.enum(CHANGE_PROOF_VERDICTS),
+    authority: z.object({
+        execution: z.literal(false),
+        ci: z.literal(false),
+        deployment: z.literal(false),
+        merge: z.literal(false),
+        ranking: z.literal(false),
+        promotion: z.literal(false),
+        policy: z.literal(false),
+    }).strict(),
+    content_hash: z.string().regex(SHA256),
+}).strict();
+export function canonicalChangeProofJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalChangeProofJson).join(",")}]`;
+    if (value && typeof value === "object") {
+        return `{${Object.entries(value)
+            .filter(([, child]) => child !== undefined)
+            .sort(([left], [right]) => compareCodeUnits(left, right))
+            .map(([key, child]) => `${JSON.stringify(key)}:${canonicalChangeProofJson(child)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+export function changeProofHash(value) {
+    return `sha256:${createHash("sha256").update(canonicalChangeProofJson(value)).digest("hex")}`;
+}
+function canonicalArray(values) {
+    const rendered = values.map(canonicalChangeProofJson);
+    return rendered.every((value, index) => index === 0 || compareCodeUnits(rendered[index - 1], value) < 0);
+}
+function expectedChangeId(change) {
+    return `hchg_${changeProofHash({ algorithm: change.algorithm, delta_hash: change.delta_hash })
+        .slice("sha256:".length, "sha256:".length + 24)}`;
+}
+export function sealChangeProof(unsigned) {
+    const proofId = `hproof_${changeProofHash(unsigned).slice("sha256:".length, "sha256:".length + 24)}`;
+    const sealed = { ...unsigned, proof_id: proofId };
+    const proof = { ...sealed, content_hash: changeProofHash(sealed) };
+    assertChangeProof(proof);
+    return proof;
+}
+export function assertChangeProof(value) {
+    const proof = ChangeProofSchema.parse(value);
+    const sortedArrays = [
+        proof.changed_files,
+        proof.blast_radius,
+        proof.decisions,
+        proof.constraints,
+        proof.conformance,
+        proof.guard.strict_blocker_ids,
+        proof.guard.regression_decision_ids,
+        proof.guard.veto_decision_ids,
+        proof.omissions,
+        proof.unknowns,
+        proof.project_dna.trait_ids,
+    ];
+    if (sortedArrays.some((items) => !canonicalArray(items)))
+        throw new Error("change proof collections must be unique and canonically ordered");
+    for (const decision of proof.decisions) {
+        if (!canonicalArray(decision.relevance) || !canonicalArray(decision.paths)
+            || decision.path_count < decision.paths.length
+            || (decision.path_count === decision.paths.length && decision.paths_hash !== changeProofHash(decision.paths))) {
+            throw new Error("change proof decision reference is non-canonical");
+        }
+    }
+    for (const constraint of proof.constraints) {
+        if (!canonicalArray(constraint.relevance) || !canonicalArray(constraint.paths)
+            || constraint.path_count < constraint.paths.length
+            || (constraint.path_count === constraint.paths.length && constraint.paths_hash !== changeProofHash(constraint.paths))) {
+            throw new Error("change proof constraint reference is non-canonical");
+        }
+    }
+    for (const blast of proof.blast_radius) {
+        if (!canonicalArray(blast.graphs) || blast.source_path === blast.dependent_path) {
+            throw new Error("change proof blast radius is non-canonical");
+        }
+    }
+    const conformanceKeys = new Set();
+    for (const receipt of proof.conformance) {
+        const key = `${receipt.decision_id}\0${receipt.predicate_index}`;
+        if (conformanceKeys.has(key))
+            throw new Error("change proof conformance predicate identity is duplicated");
+        conformanceKeys.add(key);
+    }
+    const changeUnsigned = (({ content_hash: _contentHash, ...rest }) => rest)(proof.change);
+    if (proof.change.change_id !== expectedChangeId(proof.change)
+        || proof.change.content_hash !== changeProofHash(changeUnsigned)) {
+        throw new Error("change proof change identity seal is invalid");
+    }
+    if (proof.repository.base_revision !== proof.change.base_revision
+        || proof.repository.result_revision !== proof.change.head_revision
+        || proof.project_dna.repository_id !== proof.repository.repository_id
+        || proof.project_dna.repository_revision !== proof.repository.result_revision
+        || proof.graph.base.revision !== proof.repository.base_revision
+        || proof.graph.result.revision !== proof.repository.result_revision
+        || proof.changed_file_count !== proof.change.file_count
+        || proof.changed_file_count < proof.changed_files.length
+        || proof.blast_radius_count < proof.blast_radius.length
+        || proof.decision_count < proof.decisions.length
+        || proof.constraint_count < proof.constraints.length
+        || proof.conformance_count < proof.conformance.length) {
+        throw new Error("change proof exact-revision or count binding is invalid");
+    }
+    const recordsHash = changeProofHash({ decisions: proof.decisions, constraints: proof.constraints });
+    if (proof.memory.records_hash !== recordsHash)
+        throw new Error("change proof memory seal is invalid");
+    const guardFails = proof.guard.strict_blocker_ids.length > 0;
+    if (proof.guard.verdict !== (guardFails ? "fail" : "pass"))
+        throw new Error("change proof guard verdict is invalid");
+    const expectedVerdict = guardFails || proof.conformance.some((receipt) => !receipt.satisfied)
+        ? "fail"
+        : proof.omissions.length || proof.unknowns.length
+            ? "unknown"
+            : "pass";
+    if (proof.verdict !== expectedVerdict)
+        throw new Error("change proof verdict is invalid");
+    const { proof_id: _proofId, content_hash: _proofHash, ...unsigned } = proof;
+    const expectedProofId = `hproof_${changeProofHash(unsigned).slice("sha256:".length, "sha256:".length + 24)}`;
+    const sealed = { ...unsigned, proof_id: proof.proof_id };
+    if (proof.proof_id !== expectedProofId || proof.content_hash !== changeProofHash(sealed)) {
+        throw new Error("change proof seal is invalid");
+    }
+}
+//# sourceMappingURL=changeProofContract.js.map

package/dist/core/projectDnaOutcomeExperience.d.ts

@@ -0,0 +1,105 @@
+import { z } from "zod";
+import { type Finding } from "./types.js";
+export declare const PROJECT_DNA_USEFULNESS_OBSERVATION_SCHEMA_VERSION: "hunch.project-dna-usefulness-observation/1";
+export declare const PROJECT_DNA_USEFULNESS_SIGNALS: readonly ["used", "prevented", "near_miss", "contradicted", "stale", "unused", "unknown"];
+export declare const PROJECT_DNA_USEFULNESS_EVIDENCE_KINDS: readonly ["explicit_human_observation", "independent_review"];
+export declare const ProjectDnaUsefulnessObservationSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"hunch.project-dna-usefulness-observation/1">;
+    observationId: z.ZodString;
+    episode: z.ZodObject<{
+        provider: z.ZodString;
+        schemaVersion: z.ZodString;
+        episodeId: z.ZodString;
+        episodeHash: z.ZodString;
+        terminalAt: z.ZodString;
+        result: z.ZodEnum<{
+            fail: "fail";
+            pass: "pass";
+            uncertain: "uncertain";
+            abandoned: "abandoned";
+            rolled_back: "rolled_back";
+        }>;
+    }, z.core.$strict>;
+    delivery: z.ZodObject<{
+        receiptRef: z.ZodString;
+        receiptHash: z.ZodString;
+        repositoryId: z.ZodString;
+        repositoryRevision: z.ZodString;
+        profileId: z.ZodString;
+        profileContentHash: z.ZodString;
+        snapshotHash: z.ZodString;
+        retrievalHash: z.ZodString;
+    }, z.core.$strict>;
+    projection: z.ZodObject<{
+        role: z.ZodString;
+        categories: z.ZodArray<z.ZodEnum<{
+            communication: "communication";
+            engineering: "engineering";
+            review: "review";
+            culture: "culture";
+            vocabulary: "vocabulary";
+        }>>;
+        traitIds: z.ZodArray<z.ZodString>;
+        evidenceHashes: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+    artifact: z.ZodObject<{
+        kind: z.ZodEnum<{
+            message: "message";
+            commit: "commit";
+            pull_request: "pull_request";
+            issue: "issue";
+        }>;
+        ref: z.ZodString;
+        contentHash: z.ZodString;
+    }, z.core.$strict>;
+    assessment: z.ZodObject<{
+        schemaVersion: z.ZodString;
+        assessmentId: z.ZodString;
+        contentHash: z.ZodString;
+        projectMatchClassification: z.ZodEnum<{
+            unassessable: "unassessable";
+            conformant: "conformant";
+            mixed: "mixed";
+            nonconformant: "nonconformant";
+        }>;
+        causalInterpretation: z.ZodLiteral<"project_match_is_non_causal">;
+    }, z.core.$strict>;
+    signal: z.ZodEnum<{
+        unknown: "unknown";
+        stale: "stale";
+        used: "used";
+        prevented: "prevented";
+        near_miss: "near_miss";
+        contradicted: "contradicted";
+        unused: "unused";
+    }>;
+    evidence: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            explicit_human_observation: "explicit_human_observation";
+            independent_review: "independent_review";
+        }>;
+        ref: z.ZodString;
+        hash: z.ZodString;
+    }, z.core.$strict>>;
+    observedAt: z.ZodString;
+    retainUntil: z.ZodString;
+    privacy: z.ZodObject<{
+        payloadMode: z.ZodLiteral<"references_hashes_only">;
+        rawArtifactIncluded: z.ZodLiteral<false>;
+        rawFeedbackIncluded: z.ZodLiteral<false>;
+        rawProfileIncluded: z.ZodLiteral<false>;
+    }, z.core.$strict>;
+    authority: z.ZodObject<{
+        behavioralEffect: z.ZodLiteral<"none">;
+        mayChangeRanking: z.ZodLiteral<false>;
+        mayPromoteKnowledge: z.ZodLiteral<false>;
+        mayGrantAuthority: z.ZodLiteral<false>;
+    }, z.core.$strict>;
+    contentHash: z.ZodString;
+}, z.core.$strict>;
+export type ProjectDnaUsefulnessObservation = z.infer<typeof ProjectDnaUsefulnessObservationSchema>;
+export type CreateProjectDnaUsefulnessObservationInput = Omit<ProjectDnaUsefulnessObservation, "schema" | "observationId" | "authority" | "contentHash">;
+export declare function createProjectDnaUsefulnessObservation(input: CreateProjectDnaUsefulnessObservationInput): ProjectDnaUsefulnessObservation;
+export declare function assertProjectDnaUsefulnessObservation(value: unknown): asserts value is ProjectDnaUsefulnessObservation;
+/** Contradiction and staleness create review work, never a profile mutation or policy. */
+export declare function projectDnaUsefulnessObservationFinding(value: unknown): Finding | null;

package/dist/core/projectDnaOutcomeExperience.js

@@ -0,0 +1,271 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { findingId } from "./ids.js";
+import { PROJECT_DNA_CATEGORIES, } from "./projectDna.js";
+import { FindingSchema, isCredentialFreeText } from "./types.js";
+export const PROJECT_DNA_USEFULNESS_OBSERVATION_SCHEMA_VERSION = "hunch.project-dna-usefulness-observation/1";
+export const PROJECT_DNA_USEFULNESS_SIGNALS = [
+    "used",
+    "prevented",
+    "near_miss",
+    "contradicted",
+    "stale",
+    "unused",
+    "unknown",
+];
+export const PROJECT_DNA_USEFULNESS_EVIDENCE_KINDS = [
+    "explicit_human_observation",
+    "independent_review",
+];
+const SHA256 = /^sha256:[a-f0-9]{64}$/;
+const GIT_OBJECT = /^[a-f0-9]{40,64}$/;
+const RECEIPT_REF = /^hunch-memory:hmctx_[a-f0-9]{32}$/;
+const REPOSITORY_ID = /^pdnar_[a-f0-9]{24}$/;
+const PROFILE_ID = /^pdna_[a-f0-9]{24}$/;
+const TRAIT_ID = /^pdnat_[a-f0-9]{20}$/;
+const OBSERVATION_ID = /^pduo_[a-f0-9]{24}$/;
+const MAX_RETENTION_MS = 365 * 24 * 60 * 60 * 1_000;
+const ProjectDnaUsefulnessEvidenceSchema = z.object({
+    kind: z.enum(PROJECT_DNA_USEFULNESS_EVIDENCE_KINDS),
+    ref: z.string().min(1).max(512),
+    hash: z.string().regex(SHA256),
+}).strict();
+export const ProjectDnaUsefulnessObservationSchema = z.object({
+    schema: z.literal(PROJECT_DNA_USEFULNESS_OBSERVATION_SCHEMA_VERSION),
+    observationId: z.string().regex(OBSERVATION_ID),
+    episode: z.object({
+        provider: z.string().regex(/^[a-z][a-z0-9_-]{0,63}$/),
+        schemaVersion: z.string().min(3).max(128),
+        episodeId: z.string().min(3).max(256),
+        episodeHash: z.string().regex(SHA256),
+        terminalAt: z.string().min(1).max(64),
+        result: z.enum(["pass", "fail", "uncertain", "abandoned", "rolled_back"]),
+    }).strict(),
+    delivery: z.object({
+        receiptRef: z.string().regex(RECEIPT_REF),
+        receiptHash: z.string().regex(SHA256),
+        repositoryId: z.string().regex(REPOSITORY_ID),
+        repositoryRevision: z.string().regex(GIT_OBJECT),
+        profileId: z.string().regex(PROFILE_ID),
+        profileContentHash: z.string().regex(SHA256),
+        snapshotHash: z.string().regex(SHA256),
+        retrievalHash: z.string().regex(SHA256),
+    }).strict(),
+    projection: z.object({
+        role: z.string().regex(/^[a-z][a-z0-9_-]{0,63}$/),
+        categories: z.array(z.enum(PROJECT_DNA_CATEGORIES)).min(1).max(PROJECT_DNA_CATEGORIES.length),
+        traitIds: z.array(z.string().regex(TRAIT_ID)).min(1).max(64),
+        evidenceHashes: z.array(z.string().regex(SHA256)).min(1).max(512),
+    }).strict(),
+    artifact: z.object({
+        kind: z.enum(["commit", "pull_request", "issue", "message"]),
+        ref: z.string().min(3).max(512),
+        contentHash: z.string().regex(SHA256),
+    }).strict(),
+    assessment: z.object({
+        schemaVersion: z.string().min(3).max(128),
+        assessmentId: z.string().min(3).max(128),
+        contentHash: z.string().regex(SHA256),
+        projectMatchClassification: z.enum(["unassessable", "conformant", "mixed", "nonconformant"]),
+        causalInterpretation: z.literal("project_match_is_non_causal"),
+    }).strict(),
+    signal: z.enum(PROJECT_DNA_USEFULNESS_SIGNALS),
+    evidence: z.array(ProjectDnaUsefulnessEvidenceSchema).max(64),
+    observedAt: z.string().min(1).max(64),
+    retainUntil: z.string().min(1).max(64),
+    privacy: z.object({
+        payloadMode: z.literal("references_hashes_only"),
+        rawArtifactIncluded: z.literal(false),
+        rawFeedbackIncluded: z.literal(false),
+        rawProfileIncluded: z.literal(false),
+    }).strict(),
+    authority: z.object({
+        behavioralEffect: z.literal("none"),
+        mayChangeRanking: z.literal(false),
+        mayPromoteKnowledge: z.literal(false),
+        mayGrantAuthority: z.literal(false),
+    }).strict(),
+    contentHash: z.string().regex(SHA256),
+}).strict().superRefine((observation, ctx) => {
+    for (const [path, value] of [
+        [["episode", "terminalAt"], observation.episode.terminalAt],
+        [["observedAt"], observation.observedAt],
+        [["retainUntil"], observation.retainUntil],
+    ]) {
+        if (!Number.isFinite(Date.parse(value)) || new Date(value).toISOString() !== value) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: [...path], message: "Project DNA usefulness timestamp is invalid" });
+        }
+    }
+    const observedAt = Date.parse(observation.observedAt);
+    const terminalAt = Date.parse(observation.episode.terminalAt);
+    const retainUntil = Date.parse(observation.retainUntil);
+    if (Number.isFinite(observedAt) && Number.isFinite(terminalAt) && observedAt < terminalAt) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["observedAt"], message: "Project DNA usefulness cannot precede the terminal outcome" });
+    }
+    if (Number.isFinite(observedAt) && Number.isFinite(retainUntil)
+        && (retainUntil <= observedAt || retainUntil - observedAt > MAX_RETENTION_MS)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["retainUntil"], message: "Project DNA usefulness retention is invalid" });
+    }
+    if (observation.signal !== "unknown" && observation.evidence.length === 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["evidence"],
+            message: "classified Project DNA usefulness requires explicit human or independent review evidence",
+        });
+    }
+    const identities = new Set();
+    for (const [index, evidence] of observation.evidence.entries()) {
+        const identity = `${evidence.kind}:${evidence.ref}:${evidence.hash}`;
+        if (identities.has(identity)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["evidence", index], message: "Project DNA usefulness evidence is duplicated" });
+        }
+        identities.add(identity);
+        if (!isCredentialFreeText(evidence.ref)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["evidence", index, "ref"], message: "Project DNA usefulness evidence contains credential material" });
+        }
+    }
+    const categories = observation.projection.categories;
+    if (new Set(categories).size !== categories.length
+        || new Set(observation.projection.traitIds).size !== observation.projection.traitIds.length
+        || new Set(observation.projection.evidenceHashes).size !== observation.projection.evidenceHashes.length) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["projection"], message: "Project DNA usefulness projection contains duplicates" });
+    }
+    for (const [path, value] of [
+        [["episode", "schemaVersion"], observation.episode.schemaVersion],
+        [["episode", "episodeId"], observation.episode.episodeId],
+        [["projection", "role"], observation.projection.role],
+        [["artifact", "ref"], observation.artifact.ref],
+        [["assessment", "schemaVersion"], observation.assessment.schemaVersion],
+        [["assessment", "assessmentId"], observation.assessment.assessmentId],
+    ]) {
+        if (!isCredentialFreeText(value)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: [...path], message: "Project DNA usefulness identity contains credential material" });
+        }
+    }
+    const unsigned = projectDnaUsefulnessUnsigned(observation);
+    if (observation.contentHash !== projectDnaUsefulnessHash(unsigned)
+        || observation.observationId !== projectDnaUsefulnessObservationId(observation)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "Project DNA usefulness observation seal is invalid" });
+    }
+});
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (value && typeof value === "object") {
+        return `{${Object.entries(value)
+            .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+            .map(([key, child]) => `${JSON.stringify(key)}:${canonicalJson(child)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+function projectDnaUsefulnessHash(value) {
+    return `sha256:${createHash("sha256").update(canonicalJson(value), "utf8").digest("hex")}`;
+}
+function projectDnaUsefulnessObservationId(observation) {
+    const identityHash = projectDnaUsefulnessHash({
+        episodeId: observation.episode.episodeId,
+        receiptRef: observation.delivery.receiptRef,
+        receiptHash: observation.delivery.receiptHash,
+        profileId: observation.delivery.profileId,
+        artifactRef: observation.artifact.ref,
+        artifactContentHash: observation.artifact.contentHash,
+    });
+    return `pduo_${identityHash.slice(7, 31)}`;
+}
+function projectDnaUsefulnessUnsigned(observation) {
+    return {
+        schema: observation.schema,
+        episode: { ...observation.episode },
+        delivery: { ...observation.delivery },
+        projection: {
+            role: observation.projection.role,
+            categories: [...observation.projection.categories],
+            traitIds: [...observation.projection.traitIds],
+            evidenceHashes: [...observation.projection.evidenceHashes],
+        },
+        artifact: { ...observation.artifact },
+        assessment: { ...observation.assessment },
+        signal: observation.signal,
+        evidence: observation.evidence.map((item) => ({ ...item })),
+        observedAt: observation.observedAt,
+        retainUntil: observation.retainUntil,
+        privacy: { ...observation.privacy },
+        authority: { ...observation.authority },
+    };
+}
+export function createProjectDnaUsefulnessObservation(input) {
+    const unsigned = projectDnaUsefulnessUnsigned({
+        schema: PROJECT_DNA_USEFULNESS_OBSERVATION_SCHEMA_VERSION,
+        episode: { ...input.episode },
+        delivery: { ...input.delivery },
+        projection: {
+            role: input.projection.role,
+            categories: [...input.projection.categories],
+            traitIds: [...input.projection.traitIds],
+            evidenceHashes: [...input.projection.evidenceHashes],
+        },
+        artifact: { ...input.artifact },
+        assessment: { ...input.assessment },
+        signal: input.signal,
+        evidence: input.evidence.map((item) => ({ ...item })),
+        observedAt: input.observedAt,
+        retainUntil: input.retainUntil,
+        privacy: { ...input.privacy },
+        authority: {
+            behavioralEffect: "none",
+            mayChangeRanking: false,
+            mayPromoteKnowledge: false,
+            mayGrantAuthority: false,
+        },
+    });
+    return ProjectDnaUsefulnessObservationSchema.parse({
+        ...unsigned,
+        observationId: projectDnaUsefulnessObservationId(unsigned),
+        contentHash: projectDnaUsefulnessHash(unsigned),
+    });
+}
+export function assertProjectDnaUsefulnessObservation(value) {
+    ProjectDnaUsefulnessObservationSchema.parse(value);
+}
+/** Contradiction and staleness create review work, never a profile mutation or policy. */
+export function projectDnaUsefulnessObservationFinding(value) {
+    const observation = ProjectDnaUsefulnessObservationSchema.parse(value);
+    if (observation.signal !== "contradicted" && observation.signal !== "stale")
+        return null;
+    const title = `Project DNA outcome ${observation.signal}: ${observation.delivery.profileId}`;
+    const evidence = [
+        `project-dna-usefulness:${observation.observationId}`,
+        `project-dna-usefulness-content:${observation.contentHash}`,
+        `episode:${observation.episode.episodeId}@${observation.episode.episodeHash}`,
+        `delivery:${observation.delivery.receiptRef}@${observation.delivery.receiptHash}`,
+        `profile:${observation.delivery.profileId}@${observation.delivery.profileContentHash}`,
+        `artifact:${observation.artifact.ref}@${observation.artifact.contentHash}`,
+        `assessment:${observation.assessment.assessmentId}@${observation.assessment.contentHash}`,
+        ...observation.evidence.map((item) => `${item.kind}:${item.ref}@${item.hash}`),
+    ];
+    return FindingSchema.parse({
+        id: findingId(title),
+        title,
+        observation: observation.signal === "contradicted"
+            ? `Explicit outcome evidence may conflict with delivered Project DNA profile ${observation.delivery.profileId}; review the named traits and evidence before changing the profile.`
+            : `Explicit outcome evidence may show that delivered Project DNA profile ${observation.delivery.profileId} was stale; review currentness before changing the profile.`,
+        evidence,
+        method: null,
+        severity: observation.signal === "contradicted" ? "high" : "medium",
+        triage: "open",
+        affected_files: [],
+        affected_symbols: [...observation.projection.traitIds],
+        violates_constraint: null,
+        spawned_decision: null,
+        observed_at: observation.observedAt,
+        resolved_commit: null,
+        provenance: {
+            source: "project_dna_outcome_experience+candidate",
+            confidence: 0.75,
+            evidence,
+            last_verified: observation.observedAt,
+        },
+    });
+}
+//# sourceMappingURL=projectDnaOutcomeExperience.js.map

package/dist/mcp/server.js

@@ -27,6 +27,8 @@ import { compileVerifiedEvidenceMap, EvidenceExecutionSchema, EvidenceInterventi
 import { collectCorrectionStageSources } from "../extractors/correctionSources.js";
 import { buildDeliveryEnvelope, DELIVERY_PROFILE_POLICY_VERSION, DELIVERY_PROFILES, } from "../core/delivery.js";
 import { CHANGE_IDENTITY_ALGORITHM, CHANGE_IDENTITY_SCHEMA_VERSION, deriveChangeIdentity, } from "../core/changeIdentity.js";
+import { deriveChangeProof } from "../core/changeProof.js";
+import { ChangeProofSchema } from "../core/changeProofContract.js";
 import { PROJECT_DNA_CATEGORIES, PROJECT_DNA_MATCH_SCHEMA_VERSION, PROJECT_DNA_SCHEMA_VERSION, discoverProjectDna, evaluateProjectDnaMatch, } from "../core/projectDna.js";
 import { PROJECT_DNA_DELTA_SCHEMA_VERSION, diffProjectDna } from "../core/projectDnaDelta.js";
 import { projectDnaDeliverySupplement } from "../core/projectDnaDelivery.js";
@@ -905,6 +907,32 @@ export function buildServerWithRootControl(initialRoot) {
             return err(error.message);
         }
     });
+    // -- hunch_change_proof (exact-revision semantic evidence) ----------------
+    server.registerTool("hunch_change_proof", {
+        title: "Derive a sealed semantic proof for an exact change",
+        description: "Bind an exact committed Git transition to its change identity, Project DNA, base/result semantic graphs, current decisions and constraints, blast radius, conformance, guard verdict, and explicit gaps. Read-only and deterministic; grants no execution, CI, deployment, merge, ranking, promotion, or policy authority.",
+        inputSchema: {
+            base_ref: z.string().min(1).max(1_024).describe("Base commit or ref for the exact tree transition."),
+            result_ref: z.string().min(1).max(1_024).optional().describe("Result commit or ref (default HEAD)."),
+            public_only: z.boolean().optional().describe("Exclude the configured private-memory overlay. Required before publishing a proof."),
+            cwd: cwdHintField,
+        },
+        outputSchema: ChangeProofSchema,
+    }, async ({ base_ref, result_ref, public_only }) => {
+        try {
+            const proof = ChangeProofSchema.parse(deriveChangeProof(root, store, base_ref, result_ref ?? "HEAD", { publicOnly: public_only }));
+            return {
+                content: [{
+                        type: "text",
+                        text: `${proof.proof_id} — ${proof.verdict.toUpperCase()}; ${proof.changed_file_count} exact file delta(s), ${proof.blast_radius_count} dependent path(s), ${proof.omissions.length + proof.unknowns.length} explicit gap(s); sealed ${proof.content_hash}. Evidence only; no execution or merge authority.`,
+                    }],
+                structuredContent: proof,
+            };
+        }
+        catch (error) {
+            return err(error.message);
+        }
+    });
     // -- hunch_project_dna ----------------------------------------------------
     server.registerTool("hunch_project_dna", {
         title: "Inspect this repository's evidence-backed Project DNA",