@davesheffer/hunch 1.21.1 → 1.22.0

package/README.md

@@ -174,7 +174,7 @@ repository, separate from the code repository. Hunch does not host it. Create a
 that every teammate can access, install Hunch on team machines and CI, then have one maintainer run:
 
 ```bash
-npm i -g @davesheffer/hunch@1.21.1
+npm i -g @davesheffer/hunch@1.22.0
 hunch shared --repo git@github.com:acme/project-hunch-memory.git
 git add .gitignore .hunch/team.json
 git commit -m "chore: connect shared Hunch memory"
@@ -189,7 +189,7 @@ printed by Hunch. Omit `--migrate` for a new setup.
 After the pointer commit lands, teammates need Hunch installed and Git access to the memory repo:
 
 ```bash
-npm i -g @davesheffer/hunch@1.21.1
+npm i -g @davesheffer/hunch@1.22.0
 git pull
 hunch init
 hunch doctor

package/dist/core/projectDna.d.ts

@@ -0,0 +1,81 @@
+import { type ProjectDnaHostEvidence } from "./projectDnaHostEvidence.js";
+export declare const PROJECT_DNA_SCHEMA_VERSION: "hunch.project-dna/1";
+export declare const PROJECT_DNA_MATCH_SCHEMA_VERSION: "hunch.project-dna-match/1";
+export declare const PROJECT_DNA_CATEGORIES: readonly ["communication", "engineering", "review", "culture", "vocabulary"];
+export type ProjectDnaCategory = (typeof PROJECT_DNA_CATEGORIES)[number];
+export type ProjectDnaEvidenceKind = "git-history" | "committed-file" | "host-evidence";
+export interface ProjectDnaEvidence {
+    kind: ProjectDnaEvidenceKind;
+    ref: string;
+    revision: string;
+    content_hash: string;
+    sample_count: number;
+    provenance: "committed-repository" | "host-provided";
+    visibility: "repository";
+}
+export interface ProjectDnaTrait {
+    id: string;
+    category: ProjectDnaCategory;
+    key: string;
+    claim: string;
+    confidence: number;
+    observation_state: "observed";
+    freshness: "current";
+    contradiction: "none";
+    evidence: ProjectDnaEvidence[];
+}
+export interface ProjectDnaProfile {
+    schema: typeof PROJECT_DNA_SCHEMA_VERSION;
+    profile_id: string;
+    /** Clone-stable identity for the repository lineage, derived from its root commits. */
+    repository_id: string;
+    repository_revision: string;
+    history_sample_count: number;
+    source_files: string[];
+    traits: ProjectDnaTrait[];
+    content_hash: string;
+}
+export interface ProjectDnaDiscoveryOptions {
+    /** A sealed batch selected and authorized by the host for this exact revision. */
+    hostEvidence?: ProjectDnaHostEvidence;
+}
+export interface ProjectDnaArtifact {
+    kind: "commit" | "pull_request" | "issue" | "message";
+    title: string;
+    body?: string;
+}
+export interface ProjectDnaMatchCheck {
+    trait_id: string;
+    key: string;
+    applicable: boolean;
+    passed: boolean | null;
+    weight: number;
+    detail: string;
+}
+export interface ProjectDnaMatch {
+    schema: typeof PROJECT_DNA_MATCH_SCHEMA_VERSION;
+    match_id: string;
+    profile_id: string;
+    repository_id: string;
+    repository_revision: string;
+    artifact_kind: ProjectDnaArtifact["kind"];
+    score: number | null;
+    applicable_checks: number;
+    checks: ProjectDnaMatchCheck[];
+    content_hash: string;
+}
+/**
+ * Derive a deterministic repository DNA profile from one exact Git revision.
+ *
+ * This is intentionally observation, not authority: it reads bounded committed
+ * history and bounded committed convention files. A host may additionally pass a
+ * sealed, revision-bound evidence batch that it already authorized; discovery
+ * never fetches a provider itself. It does not read the worktree, network, model
+ * output, credentials, or private user state, and it never writes into the durable
+ * Hunch graph by itself.
+ */
+export declare function discoverProjectDna(root: string, ref?: string, options?: ProjectDnaDiscoveryOptions): ProjectDnaProfile;
+export declare function assertProjectDnaProfile(value: unknown): asserts value is ProjectDnaProfile;
+/** Score only traits that have a deterministic check for the supplied artifact. */
+export declare function evaluateProjectDnaMatch(profileValue: unknown, artifact: ProjectDnaArtifact): ProjectDnaMatch;
+export declare function assertProjectDnaMatch(value: unknown): asserts value is ProjectDnaMatch;

package/dist/core/projectDna.js

@@ -1,6 +1,7 @@
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { compareCodeUnits } from "./canonicalOrder.js";
+import { assertProjectDnaHostEvidence, } from "./projectDnaHostEvidence.js";
 export const PROJECT_DNA_SCHEMA_VERSION = "hunch.project-dna/1";
 export const PROJECT_DNA_MATCH_SCHEMA_VERSION = "hunch.project-dna-match/1";
 const GIT_OBJECT = /^[a-f0-9]{40,64}$/;
@@ -155,6 +156,17 @@ function fileEvidence(revision, path, bytes) {
         visibility: "repository",
     };
 }
+function hostEvidenceEvidence(revision, hostEvidence, sampleCount) {
+    return {
+        kind: "host-evidence",
+        ref: `host:${hostEvidence.evidence_set_id}`,
+        revision,
+        content_hash: hostEvidence.content_hash,
+        sample_count: sampleCount,
+        provenance: "host-provided",
+        visibility: "repository",
+    };
+}
 function repositoryId(root, revision) {
     const roots = gitText(root, ["rev-list", "--max-parents=0", revision, "--"])
         .split("\n")
@@ -264,6 +276,70 @@ function collectFileTraits(revision, files) {
     }
     return [...byKey.values()].map(({ rule, evidence }) => makeTrait(rule.category, rule.key, rule.claim, Math.min(0.98, 0.8 + Math.min(3, evidence.length) * 0.05), evidence));
 }
+function collectHostEvidenceTraits(revision, hostEvidence) {
+    if (!hostEvidence)
+        return [];
+    assertProjectDnaHostEvidence(hostEvidence);
+    if (hostEvidence.repository_revision !== revision) {
+        throw new Error("Project DNA host evidence revision does not match the repository revision");
+    }
+    const traits = [];
+    const pullRequests = hostEvidence.items.filter((item) => item.kind === "pull_request" && item.disposition === "merged");
+    if (pullRequests.length >= MIN_HISTORY) {
+        const titles = pullRequests.map((item) => item.title);
+        const evidence = [hostEvidenceEvidence(revision, hostEvidence, pullRequests.length)];
+        const count = titles.length;
+        const conventional = titles.filter(conventionalSubject).length;
+        const noTerminalPeriod = titles.filter((title) => !/[.!?]$/.test(title.trim())).length;
+        const lowercase = titles.filter((title) => {
+            const first = firstAlphabetic(title.replace(/^(?:build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(?:\([^)]+\))?!?:\s*/, ""));
+            return first !== null && first === first.toLowerCase();
+        }).length;
+        const issueRefs = titles.filter((title) => /(?:^|\s)#\d+\b/.test(title)).length;
+        if (conventional / count >= 0.7) {
+            traits.push(makeTrait("communication", "pull_request.conventional_title", "Pull-request titles usually use Conventional Commit prefixes.", confidence(conventional / count, count), evidence));
+        }
+        if (noTerminalPeriod / count >= 0.8) {
+            traits.push(makeTrait("communication", "pull_request.no_terminal_punctuation", "Pull-request titles usually omit terminal punctuation.", confidence(noTerminalPeriod / count, count), evidence));
+        }
+        if (lowercase / count >= 0.7) {
+            traits.push(makeTrait("communication", "pull_request.lowercase_lead", "Pull-request titles usually begin their descriptive phrase with lowercase wording.", confidence(lowercase / count, count), evidence));
+        }
+        if (issueRefs / count >= 0.45) {
+            traits.push(makeTrait("communication", "pull_request.issue_reference", "Pull-request titles frequently reference an issue number.", confidence(issueRefs / count, count), evidence));
+        }
+        const words = new Map();
+        for (const title of titles) {
+            const seen = new Set((title
+                .replace(/^(?:build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(?:\([^)]+\))?!?:\s*/, "")
+                .toLowerCase()
+                .match(/[a-z][a-z0-9_-]{2,30}/g) ?? [])
+                .filter((token) => !STOP_WORDS.has(token) && !/^\d+$/.test(token)));
+            for (const token of seen)
+                words.set(token, (words.get(token) ?? 0) + 1);
+        }
+        const vocabulary = [...words.entries()]
+            .filter(([, occurrences]) => occurrences >= Math.max(3, Math.ceil(count * 0.2)))
+            .sort((left, right) => right[1] - left[1] || compareCodeUnits(left[0], right[0]))
+            .slice(0, 8);
+        for (const [word, occurrences] of vocabulary) {
+            traits.push(makeTrait("vocabulary", `term.${word}`, `The repository repeatedly uses the term “${word}” in merged pull-request titles.`, confidence(occurrences / count, count, 0.55), evidence));
+        }
+        const bodies = pullRequests.map((item) => item.body).filter((body) => body !== null);
+        const rationaleCount = bodies.filter((body) => FILE_RULES.find((rule) => rule.key === "pr.explain_why").pattern.test(body)).length;
+        if (rationaleCount >= 2 && rationaleCount / Math.max(1, bodies.length) >= 0.6) {
+            traits.push(makeTrait("communication", "pr.explain_why", "Pull requests are expected to explain motivation or rationale, not only the code change.", confidence(rationaleCount / bodies.length, bodies.length), [hostEvidenceEvidence(revision, hostEvidence, rationaleCount)]));
+        }
+    }
+    const maintainerReviews = hostEvidence.items.filter((item) => item.kind === "review_comment" && item.author_role === "maintainer");
+    for (const rule of FILE_RULES) {
+        const matching = maintainerReviews.filter((item) => rule.pattern.test(item.body));
+        if (matching.length < 2)
+            continue;
+        traits.push(makeTrait(rule.category, rule.key, rule.claim, confidence(matching.length / maintainerReviews.length, matching.length, 0.65), [hostEvidenceEvidence(revision, hostEvidence, matching.length)]));
+    }
+    return traits;
+}
 function dedupeTraits(traits) {
     const byKey = new Map();
     for (const trait of traits) {
@@ -279,11 +355,13 @@ function dedupeTraits(traits) {
  * Derive a deterministic repository DNA profile from one exact Git revision.
  *
  * This is intentionally observation, not authority: it reads bounded committed
- * history and bounded committed convention files. It does not read the worktree,
- * network, GitHub reviews, model output, or private user state, and it never writes
- * into the durable Hunch graph by itself.
+ * history and bounded committed convention files. A host may additionally pass a
+ * sealed, revision-bound evidence batch that it already authorized; discovery
+ * never fetches a provider itself. It does not read the worktree, network, model
+ * output, credentials, or private user state, and it never writes into the durable
+ * Hunch graph by itself.
  */
-export function discoverProjectDna(root, ref = "HEAD") {
+export function discoverProjectDna(root, ref = "HEAD", options = {}) {
     const repositoryRevision = exactCommit(root, ref);
     const repositoryIdentity = repositoryId(root, repositoryRevision);
     const historyRaw = gitText(root, [
@@ -299,6 +377,7 @@ export function discoverProjectDna(root, ref = "HEAD") {
     const traits = dedupeTraits([
         ...collectHistoryTraits(repositoryRevision, subjects),
         ...collectFileTraits(repositoryRevision, files),
+        ...collectHostEvidenceTraits(repositoryRevision, options.hostEvidence),
     ]);
     const unsigned = {
         schema: PROJECT_DNA_SCHEMA_VERSION,
@@ -360,10 +439,14 @@ export function assertProjectDnaProfile(value) {
             assertExactFields(evidence, [
                 "kind", "ref", "revision", "content_hash", "sample_count", "provenance", "visibility",
             ], "project DNA evidence");
-            if (!["git-history", "committed-file"].includes(evidence.kind) || !evidence.ref.trim() || evidence.ref.length > 512
+            const committedEvidence = evidence.kind === "git-history" || evidence.kind === "committed-file";
+            const hostEvidence = evidence.kind === "host-evidence";
+            if ((!committedEvidence && !hostEvidence) || !evidence.ref.trim() || evidence.ref.length > 512
                 || evidence.revision !== profile.repository_revision || !SHA256.test(evidence.content_hash)
                 || !Number.isSafeInteger(evidence.sample_count) || evidence.sample_count < 1 || evidence.sample_count > MAX_HISTORY
-                || evidence.provenance !== "committed-repository" || evidence.visibility !== "repository") {
+                || (committedEvidence && evidence.provenance !== "committed-repository")
+                || (hostEvidence && (evidence.provenance !== "host-provided" || !/^host:pdnah_[a-f0-9]{24}$/.test(evidence.ref)))
+                || evidence.visibility !== "repository") {
                 throw new Error("project DNA evidence fields are invalid");
             }
         }
@@ -390,6 +473,22 @@ function artifactCheck(trait, artifact) {
             return { trait_id: trait.id, key: trait.key, applicable: first !== null, passed: first === null ? null : first === first.toLowerCase(), weight, detail: "Descriptive title wording begins lowercase." };
         case "subject.issue_reference":
             return { trait_id: trait.id, key: trait.key, applicable: true, passed: /(?:^|\s)#\d+\b/.test(title), weight, detail: "Title carries an issue reference." };
+        case "pull_request.conventional_title":
+            return artifact.kind === "pull_request"
+                ? { trait_id: trait.id, key: trait.key, applicable: true, passed: conventionalSubject(title), weight, detail: "PR title follows the repository's observed Conventional Commit pattern." }
+                : { trait_id: trait.id, key: trait.key, applicable: false, passed: null, weight, detail: "This trait applies only to pull-request titles." };
+        case "pull_request.no_terminal_punctuation":
+            return artifact.kind === "pull_request"
+                ? { trait_id: trait.id, key: trait.key, applicable: true, passed: !/[.!?]$/.test(title), weight, detail: "PR title omits terminal punctuation." }
+                : { trait_id: trait.id, key: trait.key, applicable: false, passed: null, weight, detail: "This trait applies only to pull-request titles." };
+        case "pull_request.lowercase_lead":
+            return artifact.kind === "pull_request"
+                ? { trait_id: trait.id, key: trait.key, applicable: first !== null, passed: first === null ? null : first === first.toLowerCase(), weight, detail: "Descriptive PR-title wording begins lowercase." }
+                : { trait_id: trait.id, key: trait.key, applicable: false, passed: null, weight, detail: "This trait applies only to pull-request titles." };
+        case "pull_request.issue_reference":
+            return artifact.kind === "pull_request"
+                ? { trait_id: trait.id, key: trait.key, applicable: true, passed: /(?:^|\s)#\d+\b/.test(title), weight, detail: "PR title carries an issue reference." }
+                : { trait_id: trait.id, key: trait.key, applicable: false, passed: null, weight, detail: "This trait applies only to pull-request titles." };
         case "pr.explain_why": {
             const body = artifact.body?.trim() ?? "";
             const applicable = artifact.kind === "pull_request";

package/dist/core/projectDnaDelivery.d.ts

@@ -0,0 +1,15 @@
+export declare const PROJECT_DNA_SUPPLEMENT_KIND: "project-dna";
+export interface ProjectDnaDeliverySupplement {
+    id: string;
+    kind: typeof PROJECT_DNA_SUPPLEMENT_KIND;
+    text: string;
+    priority: number;
+}
+/**
+ * Render Project DNA through Hunch's existing DeliverySupplement seam.
+ *
+ * The caller still owns the final hard budget via buildDeliveryEnvelope(); this
+ * function only prepares compact, evidence-identifiable orientation text. The
+ * profile ID/revision remain visible so a host can preserve provider provenance.
+ */
+export declare function projectDnaDeliverySupplement(profileValue: unknown, traitCap?: number): ProjectDnaDeliverySupplement | null;

package/dist/core/projectDnaDelta.d.ts

@@ -0,0 +1,30 @@
+export declare const PROJECT_DNA_DELTA_SCHEMA_VERSION: "hunch.project-dna-delta/1";
+export type ProjectDnaChangeKind = "added" | "removed" | "evidence_changed" | "confidence_changed";
+export interface ProjectDnaTraitChange {
+    key: string;
+    kind: ProjectDnaChangeKind;
+    before_trait_id: string | null;
+    after_trait_id: string | null;
+    before_confidence: number | null;
+    after_confidence: number | null;
+}
+export interface ProjectDnaDelta {
+    schema: typeof PROJECT_DNA_DELTA_SCHEMA_VERSION;
+    delta_id: string;
+    repository_id: string;
+    from_profile_id: string;
+    to_profile_id: string;
+    from_revision: string;
+    to_revision: string;
+    changes: ProjectDnaTraitChange[];
+    changed: boolean;
+    content_hash: string;
+}
+/**
+ * Compare two already-sealed profiles without inferring causality.
+ *
+ * A delta says only that observed DNA changed between exact revisions. It does
+ * not promote the new trait, explain why the change happened, or grant policy.
+ */
+export declare function diffProjectDna(fromValue: unknown, toValue: unknown): ProjectDnaDelta;
+export declare function assertProjectDnaDelta(value: unknown): asserts value is ProjectDnaDelta;

package/dist/core/projectDnaHostEvidence.d.ts

@@ -0,0 +1,36 @@
+export declare const PROJECT_DNA_HOST_EVIDENCE_SCHEMA_VERSION: "hunch.project-dna-host-evidence/1";
+export declare const PROJECT_DNA_HOST_EVIDENCE_KINDS: readonly ["pull_request", "review_comment"];
+export declare const PROJECT_DNA_HOST_EVIDENCE_DISPOSITIONS: readonly ["merged", "approved", "changes_requested", "commented"];
+export declare const PROJECT_DNA_HOST_EVIDENCE_AUTHOR_ROLES: readonly ["maintainer", "contributor", "unknown"];
+export type ProjectDnaHostEvidenceKind = (typeof PROJECT_DNA_HOST_EVIDENCE_KINDS)[number];
+export type ProjectDnaHostEvidenceDisposition = (typeof PROJECT_DNA_HOST_EVIDENCE_DISPOSITIONS)[number];
+export type ProjectDnaHostEvidenceAuthorRole = (typeof PROJECT_DNA_HOST_EVIDENCE_AUTHOR_ROLES)[number];
+export interface ProjectDnaHostEvidenceCandidate {
+    kind: ProjectDnaHostEvidenceKind;
+    /** Credential-free, repository-local source identity such as github:pull-request:42. */
+    ref: string;
+    disposition: ProjectDnaHostEvidenceDisposition;
+    author_role: ProjectDnaHostEvidenceAuthorRole;
+    title: string | null;
+    body: string | null;
+}
+export interface ProjectDnaHostEvidenceItem extends ProjectDnaHostEvidenceCandidate {
+    item_id: string;
+    content_hash: string;
+}
+export interface ProjectDnaHostEvidence {
+    schema: typeof PROJECT_DNA_HOST_EVIDENCE_SCHEMA_VERSION;
+    repository_revision: string;
+    items: ProjectDnaHostEvidenceItem[];
+    evidence_set_id: string;
+    content_hash: string;
+}
+/**
+ * Seal an explicitly authorized, repository-visible host evidence batch.
+ *
+ * This function never fetches a provider and never grants the host evidence
+ * policy authority. The caller owns source authorization and may pass only
+ * credential-free refs plus bounded repository-visible text.
+ */
+export declare function sealProjectDnaHostEvidence(repositoryRevision: string, candidates: readonly ProjectDnaHostEvidenceCandidate[]): ProjectDnaHostEvidence;
+export declare function assertProjectDnaHostEvidence(value: unknown): asserts value is ProjectDnaHostEvidence;

package/dist/core/projectDnaHostEvidence.js

@@ -0,0 +1,174 @@
+import { createHash } from "node:crypto";
+import { compareCodeUnits } from "./canonicalOrder.js";
+export const PROJECT_DNA_HOST_EVIDENCE_SCHEMA_VERSION = "hunch.project-dna-host-evidence/1";
+const GIT_OBJECT = /^[a-f0-9]{40,64}$/;
+const SHA256 = /^sha256:[a-f0-9]{64}$/;
+const ITEM_ID = /^pdnahi_[a-f0-9]{20}$/;
+const SET_ID = /^pdnah_[a-f0-9]{24}$/;
+const SOURCE_REF = /^[A-Za-z0-9][A-Za-z0-9._:/#-]{0,255}$/;
+const MAX_ITEMS = 64;
+const MAX_TITLE = 500;
+const MAX_BODY = 8_000;
+export const PROJECT_DNA_HOST_EVIDENCE_KINDS = ["pull_request", "review_comment"];
+export const PROJECT_DNA_HOST_EVIDENCE_DISPOSITIONS = [
+    "merged", "approved", "changes_requested", "commented",
+];
+export const PROJECT_DNA_HOST_EVIDENCE_AUTHOR_ROLES = ["maintainer", "contributor", "unknown"];
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).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)}:${canonical(child)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+function sha256(value) {
+    return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+function exactFields(value, fields) {
+    return Object.keys(value).sort(compareCodeUnits).join("\0") === [...fields].sort(compareCodeUnits).join("\0");
+}
+function boundedText(value, maximum, label) {
+    if (value === null)
+        return null;
+    if (typeof value !== "string")
+        throw new Error(`Project DNA host evidence ${label} is invalid`);
+    const normalized = value.replace(/\r\n?/g, "\n").trim();
+    if (!normalized || normalized.length > maximum || normalized.includes("\0")) {
+        throw new Error(`Project DNA host evidence ${label} is invalid`);
+    }
+    return normalized;
+}
+function dispositionMatchesKind(kind, disposition) {
+    return kind === "pull_request"
+        ? disposition === "merged"
+        : disposition === "approved" || disposition === "changes_requested" || disposition === "commented";
+}
+function sealItem(candidate) {
+    if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)
+        || !exactFields(candidate, [
+            "kind", "ref", "disposition", "author_role", "title", "body",
+        ])
+        || !PROJECT_DNA_HOST_EVIDENCE_KINDS.includes(candidate.kind)
+        || !SOURCE_REF.test(candidate.ref)
+        || !PROJECT_DNA_HOST_EVIDENCE_DISPOSITIONS.includes(candidate.disposition)
+        || !PROJECT_DNA_HOST_EVIDENCE_AUTHOR_ROLES.includes(candidate.author_role)
+        || !dispositionMatchesKind(candidate.kind, candidate.disposition)) {
+        throw new Error("Project DNA host evidence candidate fields are invalid");
+    }
+    const unsigned = {
+        kind: candidate.kind,
+        ref: candidate.ref,
+        disposition: candidate.disposition,
+        author_role: candidate.author_role,
+        title: boundedText(candidate.title, MAX_TITLE, "title"),
+        body: boundedText(candidate.body, MAX_BODY, "body"),
+    };
+    if (unsigned.title === null && unsigned.body === null) {
+        throw new Error("Project DNA host evidence candidate has no observable content");
+    }
+    if (unsigned.kind === "pull_request" && unsigned.title === null) {
+        throw new Error("Project DNA pull-request evidence requires a title");
+    }
+    if (unsigned.kind === "review_comment" && (unsigned.title !== null || unsigned.body === null)) {
+        throw new Error("Project DNA review-comment evidence requires only a body");
+    }
+    const itemId = `pdnahi_${sha256(canonical(unsigned)).slice("sha256:".length, "sha256:".length + 20)}`;
+    const sealed = { ...unsigned, item_id: itemId };
+    return { ...sealed, content_hash: sha256(canonical(sealed)) };
+}
+/**
+ * Seal an explicitly authorized, repository-visible host evidence batch.
+ *
+ * This function never fetches a provider and never grants the host evidence
+ * policy authority. The caller owns source authorization and may pass only
+ * credential-free refs plus bounded repository-visible text.
+ */
+export function sealProjectDnaHostEvidence(repositoryRevision, candidates) {
+    if (!GIT_OBJECT.test(repositoryRevision) || !Array.isArray(candidates)
+        || candidates.length < 1 || candidates.length > MAX_ITEMS) {
+        throw new Error("Project DNA host evidence set fields are invalid");
+    }
+    const items = candidates.map(sealItem)
+        .sort((left, right) => compareCodeUnits(left.item_id, right.item_id));
+    if (new Set(items.map((item) => item.item_id)).size !== items.length
+        || new Set(items.map((item) => item.ref)).size !== items.length) {
+        throw new Error("Project DNA host evidence items must have unique source identities");
+    }
+    const unsigned = {
+        schema: PROJECT_DNA_HOST_EVIDENCE_SCHEMA_VERSION,
+        repository_revision: repositoryRevision,
+        items,
+    };
+    const evidenceSetId = `pdnah_${sha256(canonical(unsigned)).slice("sha256:".length, "sha256:".length + 24)}`;
+    const sealed = { ...unsigned, evidence_set_id: evidenceSetId };
+    const result = { ...sealed, content_hash: sha256(canonical(sealed)) };
+    assertProjectDnaHostEvidence(result);
+    return result;
+}
+export function assertProjectDnaHostEvidence(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Project DNA host evidence set is invalid");
+    }
+    const evidence = value;
+    if (!exactFields(value, [
+        "schema", "repository_revision", "items", "evidence_set_id", "content_hash",
+    ])
+        || evidence.schema !== PROJECT_DNA_HOST_EVIDENCE_SCHEMA_VERSION
+        || !GIT_OBJECT.test(evidence.repository_revision)
+        || !Array.isArray(evidence.items) || evidence.items.length < 1 || evidence.items.length > MAX_ITEMS
+        || !SET_ID.test(evidence.evidence_set_id) || !SHA256.test(evidence.content_hash)) {
+        throw new Error("Project DNA host evidence set fields are invalid");
+    }
+    const refs = new Set();
+    const ids = new Set();
+    let previous = "";
+    for (const item of evidence.items) {
+        if (!item || typeof item !== "object" || Array.isArray(item)
+            || !exactFields(item, [
+                "kind", "ref", "disposition", "author_role", "title", "body", "item_id", "content_hash",
+            ])
+            || !PROJECT_DNA_HOST_EVIDENCE_KINDS.includes(item.kind)
+            || !SOURCE_REF.test(item.ref)
+            || !PROJECT_DNA_HOST_EVIDENCE_DISPOSITIONS.includes(item.disposition)
+            || !PROJECT_DNA_HOST_EVIDENCE_AUTHOR_ROLES.includes(item.author_role)
+            || !dispositionMatchesKind(item.kind, item.disposition)
+            || !ITEM_ID.test(item.item_id) || !SHA256.test(item.content_hash)
+            || refs.has(item.ref) || ids.has(item.item_id) || (previous && compareCodeUnits(previous, item.item_id) >= 0)) {
+            throw new Error("Project DNA host evidence item fields are invalid");
+        }
+        const unsigned = {
+            kind: item.kind,
+            ref: item.ref,
+            disposition: item.disposition,
+            author_role: item.author_role,
+            title: boundedText(item.title, MAX_TITLE, "title"),
+            body: boundedText(item.body, MAX_BODY, "body"),
+        };
+        if (item.title !== unsigned.title || item.body !== unsigned.body
+            || (unsigned.title === null && unsigned.body === null)
+            || (unsigned.kind === "pull_request" && unsigned.title === null)
+            || (unsigned.kind === "review_comment" && (unsigned.title !== null || unsigned.body === null))) {
+            throw new Error("Project DNA host evidence item content is invalid");
+        }
+        const expectedId = `pdnahi_${sha256(canonical(unsigned)).slice("sha256:".length, "sha256:".length + 20)}`;
+        const sealed = { ...unsigned, item_id: item.item_id };
+        if (item.item_id !== expectedId || item.content_hash !== sha256(canonical(sealed))) {
+            throw new Error("Project DNA host evidence item seal is invalid");
+        }
+        refs.add(item.ref);
+        ids.add(item.item_id);
+        previous = item.item_id;
+    }
+    const { evidence_set_id: _setId, content_hash: _hash, ...base } = evidence;
+    const expectedSetId = `pdnah_${sha256(canonical(base)).slice("sha256:".length, "sha256:".length + 24)}`;
+    const sealed = { ...base, evidence_set_id: evidence.evidence_set_id };
+    if (evidence.evidence_set_id !== expectedSetId || evidence.content_hash !== sha256(canonical(sealed))) {
+        throw new Error("Project DNA host evidence set seal is invalid");
+    }
+}
+//# sourceMappingURL=projectDnaHostEvidence.js.map

package/dist/projectDna.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Stable public programmatic surface for the Project DNA Engine.
+ *
+ * Keep transport/orchestration consumers on this barrel so internal core file
+ * layout can evolve without changing the published contract entry point.
+ */
+export { PROJECT_DNA_CATEGORIES, PROJECT_DNA_MATCH_SCHEMA_VERSION, PROJECT_DNA_SCHEMA_VERSION, assertProjectDnaMatch, assertProjectDnaProfile, discoverProjectDna, evaluateProjectDnaMatch, type ProjectDnaArtifact, type ProjectDnaCategory, type ProjectDnaDiscoveryOptions, type ProjectDnaEvidence, type ProjectDnaEvidenceKind, type ProjectDnaMatch, type ProjectDnaMatchCheck, type ProjectDnaProfile, type ProjectDnaTrait, } from "./core/projectDna.js";
+export { PROJECT_DNA_HOST_EVIDENCE_AUTHOR_ROLES, PROJECT_DNA_HOST_EVIDENCE_DISPOSITIONS, PROJECT_DNA_HOST_EVIDENCE_KINDS, PROJECT_DNA_HOST_EVIDENCE_SCHEMA_VERSION, assertProjectDnaHostEvidence, sealProjectDnaHostEvidence, type ProjectDnaHostEvidence, type ProjectDnaHostEvidenceAuthorRole, type ProjectDnaHostEvidenceCandidate, type ProjectDnaHostEvidenceDisposition, type ProjectDnaHostEvidenceItem, type ProjectDnaHostEvidenceKind, } from "./core/projectDnaHostEvidence.js";
+export { PROJECT_DNA_DELTA_SCHEMA_VERSION, assertProjectDnaDelta, diffProjectDna, type ProjectDnaChangeKind, type ProjectDnaDelta, type ProjectDnaTraitChange, } from "./core/projectDnaDelta.js";
+export { PROJECT_DNA_SUPPLEMENT_KIND, projectDnaDeliverySupplement, type ProjectDnaDeliverySupplement, } from "./core/projectDnaDelivery.js";

package/dist/projectDna.js

@@ -5,6 +5,7 @@
  * layout can evolve without changing the published contract entry point.
  */
 export { PROJECT_DNA_CATEGORIES, PROJECT_DNA_MATCH_SCHEMA_VERSION, PROJECT_DNA_SCHEMA_VERSION, assertProjectDnaMatch, assertProjectDnaProfile, discoverProjectDna, evaluateProjectDnaMatch, } from "./core/projectDna.js";
+export { PROJECT_DNA_HOST_EVIDENCE_AUTHOR_ROLES, PROJECT_DNA_HOST_EVIDENCE_DISPOSITIONS, PROJECT_DNA_HOST_EVIDENCE_KINDS, PROJECT_DNA_HOST_EVIDENCE_SCHEMA_VERSION, assertProjectDnaHostEvidence, sealProjectDnaHostEvidence, } from "./core/projectDnaHostEvidence.js";
 export { PROJECT_DNA_DELTA_SCHEMA_VERSION, assertProjectDnaDelta, diffProjectDna, } from "./core/projectDnaDelta.js";
 export { PROJECT_DNA_SUPPLEMENT_KIND, projectDnaDeliverySupplement, } from "./core/projectDnaDelivery.js";
 //# sourceMappingURL=projectDna.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.21.1",
+  "version": "1.22.0",
   "mcpName": "io.github.davesheffer/hunch",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
@@ -27,6 +27,8 @@
   },
   "files": [
     "dist/**/*.js",
+    "dist/projectDna.d.ts",
+    "dist/core/projectDna*.d.ts",
     "server.json",
     "bench/constitution-exp03-v1.json",
     "tooling/competitive-watch.mjs",

package/server.json

@@ -7,13 +7,13 @@
     "source": "github"
   },
   "websiteUrl": "https://hunch-pi.vercel.app",
-  "version": "1.21.1",
+  "version": "1.22.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.21.1",
+      "version": "1.22.0",
       "runtimeHint": "npx",
       "packageArguments": [
         {