@deftai/directive-core 0.103.0 → 0.105.0

package/dist/scope-provenance/extract-intent.js

@@ -0,0 +1,262 @@
+/**
+ * Extract intent preimage from a live xBRIEF (#3376 R1–R5 / #3385 F1–F2).
+ *
+ * Unknown plan.* keys are extracted (pinned), not rejected. Known-machine keys
+ * are omitted. plan.tags is machine; plan.edges is extracted.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { GITHUB_ISSUE_REF_TYPES } from "../intake/reconcile-issues.js";
+import { stripArtifactSuffix } from "../layout/resolve.js";
+import { resolveParentPathFromRef } from "../scope/parent-lineage.js";
+import { extractPlanId } from "./digest.js";
+import { INTENT_DIGEST_ALGO } from "./intent-digest.js";
+import { parseJsonRejectingDuplicateKeys } from "./json-tokenizer.js";
+import { classifyItemKey, classifyPlanPath, classifyReferenceKey, ITEM_EXTRACT_KEYS, } from "./known-machine.js";
+export const INTENT_PREIMAGE_SCHEMA = 1;
+const ISSUE_URL_RE = /https?:\/\/(?:www\.)?github\.com\/([^/\s]+)\/([^/\s]+)\/issues\/(\d+)/i;
+export function slugFromGithubIssueUri(uri) {
+    const m = ISSUE_URL_RE.exec(uri);
+    if (m === null)
+        return null;
+    return `${m[1]}/${m[2]}`.toLowerCase();
+}
+function asRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return null;
+    return value;
+}
+function itemId(item) {
+    return typeof item.id === "string" ? item.id : "";
+}
+function readText(abs, reader) {
+    if (reader !== undefined)
+        return reader(abs);
+    if (!existsSync(abs))
+        return null;
+    try {
+        return readFileSync(abs, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+export function resolveParentPlanId(planRef, projectRoot, readFile) {
+    const roots = [join(projectRoot, "xbrief"), join(projectRoot, "vbrief")];
+    for (const lifecycleRoot of roots) {
+        const resolved = resolveParentPathFromRef(planRef, lifecycleRoot);
+        if (resolved.path === null)
+            continue;
+        const raw = readText(resolved.path, readFile);
+        if (raw === null)
+            continue;
+        let payload;
+        try {
+            payload = JSON.parse(raw);
+        }
+        catch {
+            return { error: `unresolvable parent at mint: ${planRef} is not valid JSON` };
+        }
+        const id = extractPlanId(payload) ?? stripArtifactSuffix(basename(resolved.path));
+        if (id.trim().length === 0) {
+            return { error: `unresolvable parent at mint: ${planRef} has no plan.id` };
+        }
+        return { id: id.trim() };
+    }
+    return { error: `unresolvable parent at mint: ${planRef}` };
+}
+function extractReferences(refs) {
+    if (!Array.isArray(refs))
+        return { refs: [] };
+    const out = [];
+    for (const ref of refs) {
+        const rec = asRecord(ref);
+        if (rec === null)
+            continue;
+        const extracted = {};
+        for (const [key, value] of Object.entries(rec)) {
+            const cls = classifyReferenceKey(key);
+            if (cls === "machine")
+                continue;
+            extracted[key] = value;
+        }
+        out.push(extracted);
+    }
+    return { refs: out };
+}
+function extractItems(items, projectRoot, readFile, unknownPaths) {
+    if (!Array.isArray(items))
+        return { items: [] };
+    const out = [];
+    const ids = new Set();
+    for (const item of items) {
+        const rec = asRecord(item);
+        if (rec === null)
+            continue;
+        const extracted = {};
+        for (const key of ITEM_EXTRACT_KEYS) {
+            if (rec[key] !== undefined)
+                extracted[key] = rec[key];
+        }
+        for (const [key, value] of Object.entries(rec)) {
+            if (ITEM_EXTRACT_KEYS.includes(key))
+                continue;
+            const cls = classifyItemKey(key);
+            if (cls === "machine")
+                continue;
+            extracted[key] = value;
+            unknownPaths.push(`items[].${key}`);
+        }
+        if (typeof rec.planRef === "string" && rec.planRef.trim().length > 0) {
+            if (projectRoot === undefined) {
+                return { items: [], error: `unresolvable parent at mint: ${rec.planRef}` };
+            }
+            const parent = resolveParentPlanId(rec.planRef, projectRoot, readFile);
+            if ("error" in parent)
+                return { items: [], error: parent.error };
+            extracted.parentId = parent.id;
+        }
+        const id = itemId(extracted);
+        if (id.length > 0) {
+            if (ids.has(id)) {
+                return { items: [], error: `duplicate items[].id ${JSON.stringify(id)}` };
+            }
+            ids.add(id);
+        }
+        out.push(extracted);
+    }
+    out.sort((a, b) => itemId(a).localeCompare(itemId(b)));
+    return { items: out };
+}
+function copyUnknownSubtree(value) {
+    return value;
+}
+function extractMetadata(metadata, unknownPaths) {
+    const out = {};
+    for (const [key, value] of Object.entries(metadata)) {
+        const path = `metadata.${key}`;
+        const cls = classifyPlanPath(path);
+        if (cls === "machine")
+            continue;
+        if (key === "swarm") {
+            const swarm = asRecord(value);
+            if (swarm === null)
+                continue;
+            const swarmOut = {};
+            for (const [sKey, sVal] of Object.entries(swarm)) {
+                const sPath = `metadata.swarm.${sKey}`;
+                const sCls = classifyPlanPath(sPath);
+                if (sCls === "machine")
+                    continue;
+                swarmOut[sKey] = sVal;
+                if (sCls === "unknown")
+                    unknownPaths.push(sPath);
+            }
+            if (Object.keys(swarmOut).length > 0)
+                out.swarm = swarmOut;
+            continue;
+        }
+        if (cls === "unknown") {
+            out[key] = copyUnknownSubtree(value);
+            unknownPaths.push(path);
+            continue;
+        }
+        out[key] = value;
+    }
+    return out;
+}
+function seedApprovedRepos(seed, refs) {
+    const out = new Set();
+    for (const s of seed ?? []) {
+        const t = s.trim().toLowerCase();
+        if (t.includes("/"))
+            out.add(t);
+    }
+    for (const ref of refs) {
+        if (typeof ref.uri !== "string")
+            continue;
+        const slug = slugFromGithubIssueUri(ref.uri);
+        if (slug !== null)
+            out.add(slug);
+    }
+    return [...out].sort((a, b) => a.localeCompare(b));
+}
+/** Extract from a parsed payload (tokenizer already applied). */
+export function extractIntentFromPayload(payload, options = {}) {
+    const root = asRecord(payload);
+    if (root === null)
+        return { ok: false, error: "xBRIEF is not an object" };
+    const plan = asRecord(root.plan);
+    if (plan === null)
+        return { ok: false, error: "xBRIEF plan is missing" };
+    const unknownPaths = [];
+    const extracted = {};
+    if (typeof plan.planRef === "string" && plan.planRef.trim().length > 0) {
+        if (options.projectRoot === undefined) {
+            return { ok: false, error: `unresolvable parent at mint: ${plan.planRef}` };
+        }
+        const parent = resolveParentPlanId(plan.planRef, options.projectRoot, options.readFile);
+        if ("error" in parent)
+            return { ok: false, error: parent.error };
+        extracted.parentId = parent.id;
+    }
+    for (const [key, value] of Object.entries(plan)) {
+        const cls = classifyPlanPath(key);
+        if (cls === "machine")
+            continue;
+        if (key === "items") {
+            const items = extractItems(value, options.projectRoot, options.readFile, unknownPaths);
+            if (items.error !== undefined)
+                return { ok: false, error: items.error };
+            extracted.items = items.items;
+            continue;
+        }
+        if (key === "references") {
+            const refs = extractReferences(value);
+            if (refs.error !== undefined)
+                return { ok: false, error: refs.error };
+            extracted.references = refs.refs;
+            continue;
+        }
+        if (key === "metadata") {
+            const meta = asRecord(value);
+            if (meta === null)
+                continue;
+            const extractedMeta = extractMetadata(meta, unknownPaths);
+            if (Object.keys(extractedMeta).length > 0)
+                extracted.metadata = extractedMeta;
+            continue;
+        }
+        if (cls === "unknown") {
+            extracted[key] = copyUnknownSubtree(value);
+            unknownPaths.push(key);
+            continue;
+        }
+        extracted[key] = value;
+    }
+    const refs = Array.isArray(extracted.references)
+        ? extracted.references
+        : [];
+    const approvedRepos = seedApprovedRepos(options.approvedReposSeed, refs);
+    const uniqueUnknown = [...new Set(unknownPaths)].sort((a, b) => a.localeCompare(b));
+    return {
+        ok: true,
+        preimage: {
+            schemaVersion: INTENT_PREIMAGE_SCHEMA,
+            algo: INTENT_DIGEST_ALGO,
+            plan: extracted,
+            approvedRepos,
+            unknownPaths: uniqueUnknown,
+        },
+    };
+}
+/** Parse raw text (duplicate-key reject) then extract. */
+export function extractIntentFromRaw(raw, options = {}) {
+    const parsed = parseJsonRejectingDuplicateKeys(raw);
+    if (!parsed.ok) {
+        return { ok: false, error: parsed.error };
+    }
+    return extractIntentFromPayload(parsed.value, options);
+}
+export { GITHUB_ISSUE_REF_TYPES };
+//# sourceMappingURL=extract-intent.js.map

package/dist/scope-provenance/index.d.ts

@@ -1,6 +1,12 @@
 /**
  * scope-provenance package surface (#3145).
  */
-export { APPROVED_SCOPE_DIR, type ApprovedScopeRecord, approvedScopeDir, approvedScopeRecordPath, buildApprovedScopeRecord, computeFileScopeDigest, computeTextDigest, extractFileScope, extractPlanId, isHumanApprovalStamp, listApprovedScopeRecords, normalizeFileScope, readApprovedScopeRecord, scopeExpansion, writeApprovedScopeRecord, } from "./digest.js";
+export { compareExtractedIntent } from "./compare-intent.js";
+export { APPROVED_SCOPE_DIR, type ApprovedScopeRecord, approvedScopeDir, approvedScopeIntentPath, approvedScopeIntentRel, approvedScopeRecordPath, buildApprovedScopeRecord, computeFileScopeDigest, computeTextDigest, extractFileScope, extractPlanId, isHumanApprovalStamp, listApprovedScopeRecords, normalizeFileScope, readApprovedScopeRecord, scopeExpansion, writeApprovedScopeRecord, } from "./digest.js";
 export { baseApprovalAuthorizesCurrent, evaluateOneScopeProvenance, evaluateScopeProvenance, parseApprovedScopeRecordRaw, resolveDefaultBaseRef, type ScopeProvenanceFinding, type ScopeProvenanceOptions, type ScopeProvenanceResult, type ScopeProvenanceViolationKind, } from "./evaluate.js";
+export { extractIntentFromPayload, extractIntentFromRaw, GITHUB_ISSUE_REF_TYPES, type IntentPreimage, } from "./extract-intent.js";
+export { computeIntentDigest, INTENT_DIGEST_ALGO } from "./intent-digest.js";
+export { parseJsonRejectingDuplicateKeys } from "./json-tokenizer.js";
+export { allKnownMachineLeaves, KNOWN_MACHINE_WRITERS } from "./known-machine.js";
+export { mintApprovedScopeArtifacts, recoverApprovedScopePairs, recoverIncompleteApprovedScopePair, } from "./mint-artifacts.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/scope-provenance/index.js

@@ -1,6 +1,12 @@
 /**
  * scope-provenance package surface (#3145).
  */
-export { APPROVED_SCOPE_DIR, approvedScopeDir, approvedScopeRecordPath, buildApprovedScopeRecord, computeFileScopeDigest, computeTextDigest, extractFileScope, extractPlanId, isHumanApprovalStamp, listApprovedScopeRecords, normalizeFileScope, readApprovedScopeRecord, scopeExpansion, writeApprovedScopeRecord, } from "./digest.js";
+export { compareExtractedIntent } from "./compare-intent.js";
+export { APPROVED_SCOPE_DIR, approvedScopeDir, approvedScopeIntentPath, approvedScopeIntentRel, approvedScopeRecordPath, buildApprovedScopeRecord, computeFileScopeDigest, computeTextDigest, extractFileScope, extractPlanId, isHumanApprovalStamp, listApprovedScopeRecords, normalizeFileScope, readApprovedScopeRecord, scopeExpansion, writeApprovedScopeRecord, } from "./digest.js";
 export { baseApprovalAuthorizesCurrent, evaluateOneScopeProvenance, evaluateScopeProvenance, parseApprovedScopeRecordRaw, resolveDefaultBaseRef, } from "./evaluate.js";
+export { extractIntentFromPayload, extractIntentFromRaw, GITHUB_ISSUE_REF_TYPES, } from "./extract-intent.js";
+export { computeIntentDigest, INTENT_DIGEST_ALGO } from "./intent-digest.js";
+export { parseJsonRejectingDuplicateKeys } from "./json-tokenizer.js";
+export { allKnownMachineLeaves, KNOWN_MACHINE_WRITERS } from "./known-machine.js";
+export { mintApprovedScopeArtifacts, recoverApprovedScopePairs, recoverIncompleteApprovedScopePair, } from "./mint-artifacts.js";
 //# sourceMappingURL=index.js.map

package/dist/scope-provenance/intent-digest.d.ts

@@ -0,0 +1,12 @@
+/**
+ * intent-extract-v1 digest (#3376 R2 / #3385).
+ *
+ * sortKeysDeep, items[] by id (done at extract), NFC, compact stringify, sha256.
+ */
+export declare const INTENT_DIGEST_ALGO: "intent-extract-v1";
+export declare function nfcString(value: string): string;
+/** Deep-sort object keys and NFC-normalize strings. Arrays keep order. */
+export declare function sortKeysDeep(value: unknown): unknown;
+/** sha256 hex of the canonical preimage. */
+export declare function computeIntentDigest(preimage: unknown): string;
+//# sourceMappingURL=intent-digest.d.ts.map

package/dist/scope-provenance/intent-digest.js

@@ -0,0 +1,33 @@
+/**
+ * intent-extract-v1 digest (#3376 R2 / #3385).
+ *
+ * sortKeysDeep, items[] by id (done at extract), NFC, compact stringify, sha256.
+ */
+import { createHash } from "node:crypto";
+export const INTENT_DIGEST_ALGO = "intent-extract-v1";
+export function nfcString(value) {
+    return value.normalize("NFC");
+}
+/** Deep-sort object keys and NFC-normalize strings. Arrays keep order. */
+export function sortKeysDeep(value) {
+    if (typeof value === "string")
+        return nfcString(value);
+    if (Array.isArray(value))
+        return value.map(sortKeysDeep);
+    if (value !== null && typeof value === "object") {
+        const rec = value;
+        const out = {};
+        for (const key of Object.keys(rec).sort((a, b) => a.localeCompare(b))) {
+            out[key] = sortKeysDeep(rec[key]);
+        }
+        return out;
+    }
+    return value;
+}
+/** sha256 hex of the canonical preimage. */
+export function computeIntentDigest(preimage) {
+    const canonical = sortKeysDeep(preimage);
+    const payload = JSON.stringify(canonical);
+    return createHash("sha256").update(payload, "utf8").digest("hex");
+}
+//# sourceMappingURL=intent-digest.js.map

package/dist/scope-provenance/intent-evaluate.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Verify-time intent pin evaluation (#3376 R2–R6 / #3385).
+ *
+ * Reads base-committed record + preimage (never working-tree copies).
+ * Legacy records (no intentDigest) authorize paths only; intent edits warn.
+ * xbriefBodyDigest is never authority.
+ */
+import { type ApprovedScopeRecord } from "./digest.js";
+import { type IntentPreimage } from "./extract-intent.js";
+export type IntentViolationKind = "intent-drift" | "unclassified-key" | "intent-digest-mismatch" | "duplicate-key" | "duplicate-item-id" | "same-pr-intent-rewrite" | "first-activation-missing-intent-pin" | "legacy-intent-edit" | "intent-parse-error";
+export interface IntentFinding {
+    readonly kind: IntentViolationKind;
+    readonly planId: string;
+    readonly xbriefRelPath: string;
+    readonly detail: string;
+    readonly remediation: string;
+    readonly warnOnly: boolean;
+}
+export interface IntentEvaluateInput {
+    readonly projectRoot: string;
+    readonly xbriefRelPath: string;
+    readonly liveRaw: string;
+    readonly livePayload: unknown;
+    readonly planId: string;
+    readonly approved: ApprovedScopeRecord | null;
+    readonly xbriefModified: boolean;
+    readonly approvalRewritten: boolean;
+    readonly preimageRewritten: boolean;
+    readonly currentScopeNonEmpty: boolean;
+    readonly baseRef: string | null;
+    readonly changedFiles: readonly string[];
+    readonly readAtBase?: (relPath: string) => string | null;
+    readonly approvedReposSeed?: readonly string[];
+}
+export declare function parseIntentPreimageRaw(raw: string): IntentPreimage | null;
+/**
+ * Evaluate intent pin for one modified active xBRIEF.
+ * Returns [] when intent is not in play (unmodified, or nothing to check).
+ */
+export declare function evaluateIntentForXbrief(input: IntentEvaluateInput): IntentFinding[];
+/** Explicit: never treat xbriefBodyDigest as authority. */
+export declare function bodyDigestIsAuthority(_rec: ApprovedScopeRecord | null): false;
+//# sourceMappingURL=intent-evaluate.d.ts.map

package/dist/scope-provenance/intent-evaluate.js

@@ -0,0 +1,149 @@
+/**
+ * Verify-time intent pin evaluation (#3376 R2–R6 / #3385).
+ *
+ * Reads base-committed record + preimage (never working-tree copies).
+ * Legacy records (no intentDigest) authorize paths only; intent edits warn.
+ * xbriefBodyDigest is never authority.
+ */
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { compareExtractedIntent } from "./compare-intent.js";
+import { approvedScopeIntentRel } from "./digest.js";
+import { extractIntentFromPayload, extractIntentFromRaw, } from "./extract-intent.js";
+import { computeIntentDigest, INTENT_DIGEST_ALGO } from "./intent-digest.js";
+import { parseJsonRejectingDuplicateKeys } from "./json-tokenizer.js";
+export function parseIntentPreimageRaw(raw) {
+    try {
+        const data = JSON.parse(raw);
+        if (data === null || typeof data !== "object" || Array.isArray(data))
+            return null;
+        const rec = data;
+        if (rec.schemaVersion !== 1)
+            return null;
+        if (rec.algo !== INTENT_DIGEST_ALGO)
+            return null;
+        if (rec.plan === null || typeof rec.plan !== "object" || Array.isArray(rec.plan))
+            return null;
+        if (!Array.isArray(rec.approvedRepos))
+            return null;
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+function remint() {
+    return ("Remint via `task scope:record-approved-scope -- <xbrief-path> --actor <you> --confirm` " +
+        "and commit `.deft/approved-scope/<plan-id>.json` plus `.intent.json` on the merge base. " +
+        "Read the preimage before committing (#3385).");
+}
+function mapCompare(f) {
+    if (f.kind === "unclassified-key")
+        return "unclassified-key";
+    return "intent-drift";
+}
+function finding(input, kind, detail, warnOnly = false) {
+    return {
+        kind,
+        planId: input.planId,
+        xbriefRelPath: input.xbriefRelPath,
+        detail,
+        remediation: remint(),
+        warnOnly,
+    };
+}
+function readBase(input, rel) {
+    if (input.readAtBase !== undefined)
+        return input.readAtBase(rel);
+    return null;
+}
+function decisionExists(input, rel) {
+    const fromBase = readBase(input, rel);
+    if (fromBase !== null)
+        return true;
+    const full = join(resolve(input.projectRoot), ...rel.split("/"));
+    return existsSync(full);
+}
+/**
+ * Evaluate intent pin for one modified active xBRIEF.
+ * Returns [] when intent is not in play (unmodified, or nothing to check).
+ */
+export function evaluateIntentForXbrief(input) {
+    if (!input.xbriefModified)
+        return [];
+    const parsed = parseJsonRejectingDuplicateKeys(input.liveRaw);
+    if (!parsed.ok) {
+        return [finding(input, "duplicate-key", parsed.error)];
+    }
+    const liveExtract = extractIntentFromPayload(parsed.value, {
+        projectRoot: input.projectRoot,
+        approvedReposSeed: input.approvedReposSeed,
+    });
+    if (!liveExtract.ok) {
+        if (liveExtract.error.includes("duplicate items[].id")) {
+            return [finding(input, "duplicate-item-id", liveExtract.error)];
+        }
+        return [finding(input, "intent-parse-error", liveExtract.error)];
+    }
+    if (input.approvalRewritten || input.preimageRewritten) {
+        return [
+            finding(input, "same-pr-intent-rewrite", "approved-scope record or preimage rewritten in the same change set; " +
+                "cannot self-authorize intent"),
+        ];
+    }
+    const hasIntent = input.approved !== null &&
+        typeof input.approved.intentDigest === "string" &&
+        input.approved.intentDigest.length > 0;
+    if (!hasIntent) {
+        return evaluateLegacyIntent(input, liveExtract.preimage);
+    }
+    const preimageRel = approvedScopeIntentRel(input.planId);
+    const basePreimageRaw = readBase(input, preimageRel);
+    if (basePreimageRaw === null) {
+        if (input.currentScopeNonEmpty) {
+            return [
+                finding(input, "first-activation-missing-intent-pin", "first activation with nonempty scope requires a base-committed record + preimage"),
+            ];
+        }
+        return [];
+    }
+    const basePreimage = parseIntentPreimageRaw(basePreimageRaw);
+    if (basePreimage === null) {
+        return [finding(input, "intent-digest-mismatch", "base preimage is malformed")];
+    }
+    const expected = computeIntentDigest(basePreimage);
+    if (expected !== input.approved?.intentDigest) {
+        return [
+            finding(input, "intent-digest-mismatch", "base preimage digest does not match record intentDigest"),
+        ];
+    }
+    const compared = compareExtractedIntent(basePreimage, liveExtract.preimage, {
+        changedFiles: input.changedFiles,
+        decisionExists: (rel) => decisionExists(input, rel),
+    });
+    return compared.findings.map((f) => finding(input, mapCompare(f), f.detail));
+}
+function evaluateLegacyIntent(input, live) {
+    const baseRaw = readBase(input, input.xbriefRelPath);
+    if (baseRaw === null) {
+        return [];
+    }
+    const baseExtract = extractIntentFromRaw(baseRaw, {
+        projectRoot: input.projectRoot,
+        approvedReposSeed: input.approvedReposSeed,
+    });
+    if (!baseExtract.ok)
+        return [];
+    const compared = compareExtractedIntent(baseExtract.preimage, live, {
+        changedFiles: input.changedFiles,
+        decisionExists: (rel) => decisionExists(input, rel),
+    });
+    if (compared.ok)
+        return [];
+    return compared.findings.map((f) => finding(input, "legacy-intent-edit", f.detail, true));
+}
+/** Explicit: never treat xbriefBodyDigest as authority. */
+export function bodyDigestIsAuthority(_rec) {
+    return false;
+}
+//# sourceMappingURL=intent-evaluate.js.map

package/dist/scope-provenance/json-tokenizer.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Validating JSON tokenizer for scope-provenance intent parse (#3385 F3 / E9).
+ *
+ * JSON.parse collapses duplicate object keys; a reviver never sees them.
+ * This scanner rejects duplicate keys (including nested) and does not treat
+ * JSON-looking text inside string values as structure.
+ */
+export interface JsonParseOk {
+    readonly ok: true;
+    readonly value: unknown;
+}
+export interface JsonParseErr {
+    readonly ok: false;
+    readonly error: string;
+}
+export type JsonParseResult = JsonParseOk | JsonParseErr;
+/** Parse JSON and reject duplicate object keys (nested included). */
+export declare function parseJsonRejectingDuplicateKeys(text: string): JsonParseResult;
+//# sourceMappingURL=json-tokenizer.d.ts.map