@davesheffer/hunch 1.20.0-rc.4 → 1.20.0-rc.5

package/dist/core/outcomeExperience.js

@@ -0,0 +1,223 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { findingId } from "./ids.js";
+import { FindingSchema, isCredentialFreeText } from "./types.js";
+export const USEFULNESS_OBSERVATION_SCHEMA_VERSION = "hunch.usefulness-observation/1";
+export const USEFULNESS_SIGNALS = [
+    "used",
+    "prevented",
+    "near_miss",
+    "contradicted",
+    "stale",
+    "unused",
+    "unknown",
+];
+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 OBSERVATION_ID = /^huo_[a-f0-9]{24}$/;
+const MAX_RETENTION_MS = 365 * 24 * 60 * 60 * 1_000;
+const EvidenceReferenceSchema = z.object({
+    kind: z.enum(["artifact", "event", "verification", "receipt", "observation"]),
+    ref: z.string().min(1).max(512),
+    hash: z.string().regex(SHA256),
+}).strict();
+export const UsefulnessObservationSchema = z.object({
+    schema: z.literal(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),
+        graphRevision: z.string().regex(GIT_OBJECT),
+        sourceRevision: z.string().regex(GIT_OBJECT),
+        sourceContentHash: z.string().regex(SHA256),
+    }).strict(),
+    record: z.object({
+        recordId: z.string().min(3).max(512),
+        recordKind: z.string().regex(/^[a-z][a-z0-9_-]{0,63}$/),
+        recordRevision: z.string().regex(SHA256),
+        contentHash: z.string().regex(SHA256),
+    }).strict(),
+    signal: z.enum(USEFULNESS_SIGNALS),
+    evidence: z.array(EvidenceReferenceSchema).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"),
+        rawTranscriptIncluded: z.literal(false),
+        rawProviderOutputIncluded: 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) => {
+    const timestamps = [
+        ["episode", "terminalAt", observation.episode.terminalAt],
+        ["observedAt", observation.observedAt],
+        ["retainUntil", observation.retainUntil],
+    ];
+    for (const path of timestamps) {
+        const value = path.at(-1);
+        if (!Number.isFinite(Date.parse(value)) || new Date(value).toISOString() !== value) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: path.slice(0, -1), message: "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: "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: "usefulness retention is invalid" });
+    }
+    if (observation.delivery.sourceRevision !== observation.delivery.graphRevision) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["delivery", "sourceRevision"], message: "usefulness source revision is inconsistent" });
+    }
+    if (observation.signal !== "unknown" && observation.evidence.length === 0) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["evidence"], message: "supported usefulness requires evidence" });
+    }
+    const evidenceIdentities = new Set();
+    for (const [index, evidence] of observation.evidence.entries()) {
+        const identity = `${evidence.kind}:${evidence.ref}:${evidence.hash}`;
+        if (evidenceIdentities.has(identity)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["evidence", index], message: "usefulness evidence is duplicated" });
+        }
+        evidenceIdentities.add(identity);
+        if (!isCredentialFreeText(evidence.ref)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["evidence", index, "ref"], message: "usefulness evidence contains credential material" });
+        }
+    }
+    for (const [path, value] of [
+        [["episode", "schemaVersion"], observation.episode.schemaVersion],
+        [["episode", "episodeId"], observation.episode.episodeId],
+        [["record", "recordId"], observation.record.recordId],
+    ]) {
+        if (!isCredentialFreeText(value)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: [...path], message: "usefulness identity contains credential material" });
+        }
+    }
+    const unsigned = usefulnessObservationUnsigned(observation);
+    const contentHash = usefulnessHash(unsigned);
+    if (observation.contentHash !== contentHash
+        || observation.observationId !== usefulnessObservationId(observation)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "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 usefulnessHash(value) {
+    return `sha256:${createHash("sha256").update(canonicalJson(value), "utf8").digest("hex")}`;
+}
+function usefulnessObservationId(observation) {
+    const identityHash = usefulnessHash({
+        episodeId: observation.episode.episodeId,
+        receiptRef: observation.delivery.receiptRef,
+        receiptHash: observation.delivery.receiptHash,
+        recordId: observation.record.recordId,
+    });
+    return `huo_${identityHash.slice(7, 31)}`;
+}
+function usefulnessObservationUnsigned(observation) {
+    return {
+        schema: observation.schema,
+        episode: { ...observation.episode },
+        delivery: { ...observation.delivery },
+        record: { ...observation.record },
+        signal: observation.signal,
+        evidence: observation.evidence.map((item) => ({ ...item })),
+        observedAt: observation.observedAt,
+        retainUntil: observation.retainUntil,
+        privacy: { ...observation.privacy },
+        authority: { ...observation.authority },
+    };
+}
+export function createUsefulnessObservation(input) {
+    const unsigned = usefulnessObservationUnsigned({
+        schema: USEFULNESS_OBSERVATION_SCHEMA_VERSION,
+        episode: { ...input.episode },
+        delivery: { ...input.delivery },
+        record: { ...input.record },
+        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,
+        },
+    });
+    const observationId = usefulnessObservationId(unsigned);
+    return UsefulnessObservationSchema.parse({
+        ...unsigned,
+        observationId,
+        contentHash: usefulnessHash(unsigned),
+    });
+}
+export function assertUsefulnessObservation(value) {
+    UsefulnessObservationSchema.parse(value);
+}
+/** Contradiction and staleness become open advisory review work, never truth. */
+export function usefulnessObservationFinding(value) {
+    const observation = UsefulnessObservationSchema.parse(value);
+    if (observation.signal !== "contradicted" && observation.signal !== "stale")
+        return null;
+    const title = `Outcome ${observation.signal}: ${observation.record.recordId} (${observation.observationId})`;
+    const evidence = [
+        `usefulness:${observation.observationId}`,
+        `usefulness-content:${observation.contentHash}`,
+        `episode:${observation.episode.episodeId}@${observation.episode.episodeHash}`,
+        `delivery:${observation.delivery.receiptRef}@${observation.delivery.receiptHash}`,
+        `record:${observation.record.recordId}@${observation.record.recordRevision}`,
+        ...observation.evidence.map((item) => `${item.kind}:${item.ref}@${item.hash}`),
+    ];
+    return FindingSchema.parse({
+        id: findingId(title),
+        title,
+        observation: observation.signal === "contradicted"
+            ? `Outcome evidence may conflict with delivered Hunch record ${observation.record.recordId}; review the record and its applicability before changing trusted knowledge.`
+            : `Outcome evidence may show that delivered Hunch record ${observation.record.recordId} was stale; review currentness before changing trusted knowledge.`,
+        evidence,
+        method: null,
+        severity: observation.signal === "contradicted" ? "high" : "medium",
+        triage: "open",
+        affected_files: [],
+        affected_symbols: [observation.record.recordId],
+        violates_constraint: null,
+        spawned_decision: null,
+        observed_at: observation.observedAt,
+        resolved_commit: null,
+        provenance: {
+            source: "outcome_experience+candidate",
+            confidence: 0.75,
+            evidence,
+            last_verified: observation.observedAt,
+        },
+    });
+}
+//# sourceMappingURL=outcomeExperience.js.map

package/dist/extractors/adrImport.js

@@ -35,6 +35,17 @@ export const ADR_DIR_CANDIDATES = [
 /** An ADR file is NNNN-slug.md (adr-tools / MADR convention). Templates and
  *  indexes (adr-template.md, README.md, index.md) never match. */
 export const ADR_FILE_RE = /^(\d{1,5})-([a-z0-9@][a-z0-9@._-]*)\.md$/i;
+/** A structurally valid ADR filename can still name corpus scaffolding rather
+ * than a decision. Keep this classification separate from parse failure so the
+ * CLI can exclude templates quietly instead of falsely calling their filename
+ * malformed. */
+export function isAdrCorpusTemplate(relPath) {
+    const base = relPath.split("/").pop() ?? relPath;
+    const match = ADR_FILE_RE.exec(base);
+    return match !== null
+        && Number(match[1]) === 0
+        && /^(?:adr[-_.]?)?template(?:[-_.]|$)/i.test(match[2]);
+}
 /** Decision.date is required even when an ADR has no date and no Git history is
  * available (for example, a copied corpus outside a repository). Use an honest,
  * deterministic sentinel instead of the import clock: re-importing the same
@@ -180,7 +191,7 @@ export function parseAdrMarkdown(text, relPath) {
         return null;
     const number = Number(nameMatch[1]);
     const slug = nameMatch[2].toLowerCase();
-    if (number === 0 && /^(?:adr[-_.]?)?template(?:[-_.]|$)/i.test(slug))
+    if (isAdrCorpusTemplate(relPath))
         return null;
     const fmMatch = FRONTMATTER_RE.exec(text);
     const fm = fmMatch ? fmMatch[1] : "";
@@ -253,7 +264,9 @@ export function mapAdrCorpus(sources) {
     for (const src of sources) {
         const p = parseAdrMarkdown(src.text, src.relPath);
         if (!p) {
-            warnings.push(`${src.relPath}: filename does not follow NNNN-slug.md — skipped`);
+            if (!isAdrCorpusTemplate(src.relPath)) {
+                warnings.push(`${src.relPath}: filename does not follow NNNN-slug.md — skipped`);
+            }
             continue;
         }
         parsed.push(p);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.20.0-rc.4",
+  "version": "1.20.0-rc.5",
   "mcpName": "io.github.davesheffer/hunch",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",

package/server.json

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