@deftai/directive-core 0.103.0 → 0.105.0

package/dist/scope-provenance/json-tokenizer.js

@@ -0,0 +1,225 @@
+/**
+ * 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.
+ */
+class Scanner {
+    s;
+    i = 0;
+    constructor(s) {
+        this.s = s;
+    }
+    parseDocument() {
+        this.skipWs();
+        const value = this.parseValue();
+        this.skipWs();
+        if (this.i < this.s.length) {
+            throw new Error(`trailing content at ${this.i}`);
+        }
+        return value;
+    }
+    peek() {
+        return this.s[this.i] ?? "";
+    }
+    next() {
+        const ch = this.s[this.i] ?? "";
+        this.i += 1;
+        return ch;
+    }
+    skipWs() {
+        while (this.i < this.s.length) {
+            const c = this.s[this.i];
+            if (c === " " || c === "\t" || c === "\n" || c === "\r") {
+                this.i += 1;
+                continue;
+            }
+            break;
+        }
+    }
+    parseValue() {
+        this.skipWs();
+        const c = this.peek();
+        if (c === '"')
+            return this.parseString();
+        if (c === "{")
+            return this.parseObject();
+        if (c === "[")
+            return this.parseArray();
+        if (c === "t" || c === "f")
+            return this.parseLiteralBool();
+        if (c === "n")
+            return this.parseNull();
+        if (c === "-" || (c >= "0" && c <= "9"))
+            return this.parseNumber();
+        throw new Error(`unexpected token at ${this.i}`);
+    }
+    parseObject() {
+        this.next(); // {
+        this.skipWs();
+        const out = {};
+        const seen = new Set();
+        if (this.peek() === "}") {
+            this.next();
+            return out;
+        }
+        while (true) {
+            this.skipWs();
+            if (this.peek() !== '"') {
+                throw new Error(`expected object key at ${this.i}`);
+            }
+            const key = this.parseString();
+            if (seen.has(key)) {
+                throw new Error(`duplicate key ${JSON.stringify(key)}`);
+            }
+            seen.add(key);
+            this.skipWs();
+            if (this.next() !== ":") {
+                throw new Error(`expected ':' after key at ${this.i}`);
+            }
+            out[key] = this.parseValue();
+            this.skipWs();
+            const sep = this.next();
+            if (sep === "}")
+                return out;
+            if (sep !== ",") {
+                throw new Error(`expected ',' or '}' at ${this.i}`);
+            }
+        }
+    }
+    parseArray() {
+        this.next(); // [
+        this.skipWs();
+        const out = [];
+        if (this.peek() === "]") {
+            this.next();
+            return out;
+        }
+        while (true) {
+            out.push(this.parseValue());
+            this.skipWs();
+            const sep = this.next();
+            if (sep === "]")
+                return out;
+            if (sep !== ",") {
+                throw new Error(`expected ',' or ']' at ${this.i}`);
+            }
+        }
+    }
+    parseString() {
+        this.next(); // "
+        let out = "";
+        while (this.i < this.s.length) {
+            const c = this.next();
+            if (c === '"')
+                return out;
+            if (c === "\\") {
+                out += this.parseEscape();
+                continue;
+            }
+            if (c.charCodeAt(0) < 0x20) {
+                throw new Error(`unescaped control in string at ${this.i}`);
+            }
+            out += c;
+        }
+        throw new Error("unterminated string");
+    }
+    parseEscape() {
+        const c = this.next();
+        switch (c) {
+            case '"':
+            case "\\":
+            case "/":
+                return c;
+            case "b":
+                return "\b";
+            case "f":
+                return "\f";
+            case "n":
+                return "\n";
+            case "r":
+                return "\r";
+            case "t":
+                return "\t";
+            case "u": {
+                const hex = this.s.slice(this.i, this.i + 4);
+                if (!/^[0-9a-fA-F]{4}$/.test(hex)) {
+                    throw new Error(`invalid unicode escape at ${this.i}`);
+                }
+                this.i += 4;
+                return String.fromCharCode(parseInt(hex, 16));
+            }
+            default:
+                throw new Error(`invalid escape at ${this.i}`);
+        }
+    }
+    parseNumber() {
+        const start = this.i;
+        if (this.peek() === "-")
+            this.next();
+        if (this.peek() === "0") {
+            this.next();
+        }
+        else {
+            if (this.peek() < "1" || this.peek() > "9") {
+                throw new Error(`invalid number at ${start}`);
+            }
+            while (this.peek() >= "0" && this.peek() <= "9")
+                this.next();
+        }
+        if (this.peek() === ".") {
+            this.next();
+            if (this.peek() < "0" || this.peek() > "9") {
+                throw new Error(`invalid fraction at ${this.i}`);
+            }
+            while (this.peek() >= "0" && this.peek() <= "9")
+                this.next();
+        }
+        if (this.peek() === "e" || this.peek() === "E") {
+            this.next();
+            if (this.peek() === "+" || this.peek() === "-")
+                this.next();
+            if (this.peek() < "0" || this.peek() > "9") {
+                throw new Error(`invalid exponent at ${this.i}`);
+            }
+            while (this.peek() >= "0" && this.peek() <= "9")
+                this.next();
+        }
+        const n = Number(this.s.slice(start, this.i));
+        if (!Number.isFinite(n)) {
+            throw new Error(`invalid number at ${start}`);
+        }
+        return n;
+    }
+    parseLiteralBool() {
+        if (this.s.startsWith("true", this.i)) {
+            this.i += 4;
+            return true;
+        }
+        if (this.s.startsWith("false", this.i)) {
+            this.i += 5;
+            return false;
+        }
+        throw new Error(`invalid literal at ${this.i}`);
+    }
+    parseNull() {
+        if (this.s.startsWith("null", this.i)) {
+            this.i += 4;
+            return null;
+        }
+        throw new Error(`invalid literal at ${this.i}`);
+    }
+}
+/** Parse JSON and reject duplicate object keys (nested included). */
+export function parseJsonRejectingDuplicateKeys(text) {
+    try {
+        const value = new Scanner(text).parseDocument();
+        return { ok: true, value };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: msg };
+    }
+}
+//# sourceMappingURL=json-tokenizer.js.map

package/dist/scope-provenance/known-machine.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Known-machine vs extracted classification for plan.* (#3376 R1 / #3385 F1).
+ *
+ * Seeded from the #3376 corpus inventory (capacity stamps, completion
+ * provenance, swarm readiness, tags-as-label-mirror). Growing this list MUST
+ * land with a writer annotation in KNOWN_MACHINE_WRITERS (same-PR CI rule)
+ * and MUST NOT change existing intent digests.
+ */
+export type KeyClass = "extract" | "extract-partial" | "machine" | "unknown";
+/** Recursive walk nodes (not pinned wholesale). */
+export declare const PARTIAL_NODES: Set<string>;
+/** plan.* keys that are machine space (never hash inputs). */
+export declare const PLAN_MACHINE_KEYS: Set<string>;
+/** plan.metadata.* machine keys / wholesale machine subtrees. */
+export declare const METADATA_MACHINE_KEYS: Set<string>;
+/** plan.metadata.swarm.* machine keys. */
+export declare const SWARM_MACHINE_KEYS: Set<string>;
+/** plan.items[] machine keys (raw planRef is machine; parentId is extracted). */
+export declare const ITEM_MACHINE_KEYS: Set<string>;
+/** reference fields that are never extracted. */
+export declare const REFERENCE_MACHINE_KEYS: Set<string>;
+/** Item fields copied into the preimage when present. */
+export declare const ITEM_EXTRACT_KEYS: readonly ["id", "title", "summary", "narrative", "type"];
+/** Swarm fields extracted as intent (prose + file_scope for review). */
+export declare const SWARM_EXTRACT_KEYS: Set<string>;
+/**
+ * Writer annotation for each known-machine key. Adding a key without an entry
+ * fails the same-PR writer-discipline test (#3385 F1).
+ */
+export declare const KNOWN_MACHINE_WRITERS: Readonly<Record<string, {
+    writer: string;
+}>>;
+export declare function classifyPlanPath(path: string): KeyClass;
+export declare function classifyItemKey(key: string): KeyClass;
+export declare function classifyReferenceKey(key: string): KeyClass;
+/** Every known-machine leaf that the writer-discipline test enumerates. */
+export declare function allKnownMachineLeaves(): string[];
+//# sourceMappingURL=known-machine.d.ts.map

package/dist/scope-provenance/known-machine.js

@@ -0,0 +1,157 @@
+/**
+ * Known-machine vs extracted classification for plan.* (#3376 R1 / #3385 F1).
+ *
+ * Seeded from the #3376 corpus inventory (capacity stamps, completion
+ * provenance, swarm readiness, tags-as-label-mirror). Growing this list MUST
+ * land with a writer annotation in KNOWN_MACHINE_WRITERS (same-PR CI rule)
+ * and MUST NOT change existing intent digests.
+ */
+/** Recursive walk nodes (not pinned wholesale). */
+export const PARTIAL_NODES = new Set(["", "metadata", "metadata.swarm"]);
+/** plan.* keys that are machine space (never hash inputs). */
+export const PLAN_MACHINE_KEYS = new Set([
+    "status",
+    "updated",
+    "created",
+    "createdAt",
+    "updatedAt",
+    "completed",
+    "percentComplete",
+    "tags",
+    "planRef",
+    "plan_ref",
+]);
+/** plan.metadata.* machine keys / wholesale machine subtrees. */
+export const METADATA_MACHINE_KEYS = new Set([
+    "capacityBucket",
+    "capacityBucketSource",
+    "completionProvenance",
+    "deliveryDisposition",
+    "handoffState",
+    "parent_lineage",
+    "parentLineage",
+    "x-migrator",
+]);
+/** plan.metadata.swarm.* machine keys. */
+export const SWARM_MACHINE_KEYS = new Set([
+    "readiness",
+    "parallel_safe",
+    "verify_commands",
+    "expected_outputs",
+    "depends_on",
+    "conflict_group",
+    "size",
+    "file_scope_confidence",
+    "model_tier",
+]);
+/** plan.items[] machine keys (raw planRef is machine; parentId is extracted). */
+export const ITEM_MACHINE_KEYS = new Set([
+    "status",
+    "completed",
+    "percentComplete",
+    "effort",
+    "updated",
+    "created",
+    "planRef",
+    "plan_ref",
+]);
+/** reference fields that are never extracted. */
+export const REFERENCE_MACHINE_KEYS = new Set(["TrustLevel", "trustLevel"]);
+/** Item fields copied into the preimage when present. */
+export const ITEM_EXTRACT_KEYS = ["id", "title", "summary", "narrative", "type"];
+/** Swarm fields extracted as intent (prose + file_scope for review). */
+export const SWARM_EXTRACT_KEYS = new Set([
+    "file_scope",
+    "missing_traces_justification",
+    "acceptance_criteria_justification",
+    "notes",
+]);
+/**
+ * Writer annotation for each known-machine key. Adding a key without an entry
+ * fails the same-PR writer-discipline test (#3385 F1).
+ */
+export const KNOWN_MACHINE_WRITERS = {
+    "plan.status": { writer: "packages/core/src/scope/transition.ts" },
+    "plan.updated": { writer: "packages/core/src/scope/transition.ts" },
+    "plan.created": { writer: "packages/core/src/scope/transition.ts" },
+    "plan.createdAt": { writer: "packages/core/src/scope/transition.ts" },
+    "plan.updatedAt": { writer: "packages/core/src/scope/transition.ts" },
+    "plan.completed": { writer: "packages/core/src/scope/transition.ts" },
+    "plan.percentComplete": { writer: "packages/core/src/scope/transition.ts" },
+    "plan.tags": { writer: "packages/core/src/intake/issue-ingest.ts" },
+    "plan.planRef": { writer: "packages/core/src/scope/decomposed-refs.ts" },
+    "plan.plan_ref": { writer: "packages/core/src/scope/decomposed-refs.ts" },
+    "plan.metadata.capacityBucket": { writer: "packages/core/src/scope/capacity-stamp.ts" },
+    "plan.metadata.capacityBucketSource": { writer: "packages/core/src/scope/capacity-stamp.ts" },
+    "plan.metadata.completionProvenance": { writer: "packages/core/src/scope/delivery-evidence.ts" },
+    "plan.metadata.deliveryDisposition": { writer: "packages/core/src/scope/delivery-evidence.ts" },
+    "plan.metadata.handoffState": { writer: "packages/core/src/scope/delivery-evidence.ts" },
+    "plan.metadata.parent_lineage": { writer: "packages/core/src/scope/parent-lineage.ts" },
+    "plan.metadata.parentLineage": { writer: "packages/core/src/scope/parent-lineage.ts" },
+    "plan.metadata.x-migrator": { writer: "packages/core/src/xbrief-migrate" },
+    "plan.metadata.swarm.readiness": { writer: "packages/core/src/swarm/complete-cohort.ts" },
+    "plan.metadata.swarm.parallel_safe": { writer: "packages/core/src/swarm/complete-cohort.ts" },
+    "plan.metadata.swarm.verify_commands": { writer: "packages/core/src/swarm/launch.ts" },
+    "plan.metadata.swarm.expected_outputs": { writer: "packages/core/src/swarm/launch.ts" },
+    "plan.metadata.swarm.depends_on": { writer: "packages/core/src/swarm/launch.ts" },
+    "plan.metadata.swarm.conflict_group": { writer: "packages/core/src/swarm/launch.ts" },
+    "plan.metadata.swarm.size": { writer: "packages/core/src/swarm/launch.ts" },
+    "plan.metadata.swarm.file_scope_confidence": { writer: "packages/core/src/swarm/launch.ts" },
+    "plan.metadata.swarm.model_tier": { writer: "packages/core/src/swarm/launch.ts" },
+    "plan.items[].status": { writer: "packages/core/src/scope/transition.ts" },
+    "plan.items[].completed": { writer: "packages/core/src/scope/transition.ts" },
+    "plan.items[].percentComplete": { writer: "packages/core/src/scope/transition.ts" },
+    "plan.items[].effort": { writer: "packages/core/src/scope/transition.ts" },
+    "plan.items[].updated": { writer: "packages/core/src/scope/transition.ts" },
+    "plan.items[].created": { writer: "packages/core/src/scope/transition.ts" },
+    "plan.items[].planRef": { writer: "packages/core/src/scope/decomposed-refs.ts" },
+    "plan.items[].plan_ref": { writer: "packages/core/src/scope/decomposed-refs.ts" },
+    "plan.references[].TrustLevel": { writer: "packages/core/src/intake/issue-ingest.ts" },
+    "plan.references[].trustLevel": { writer: "packages/core/src/intake/issue-ingest.ts" },
+};
+export function classifyPlanPath(path) {
+    if (PARTIAL_NODES.has(path))
+        return "extract-partial";
+    if (path === "items" ||
+        path === "references" ||
+        path === "metadata" ||
+        path === "metadata.swarm") {
+        return "extract-partial";
+    }
+    if (PLAN_MACHINE_KEYS.has(path))
+        return "machine";
+    if (path.startsWith("metadata.") && METADATA_MACHINE_KEYS.has(path.slice("metadata.".length))) {
+        return "machine";
+    }
+    if (path.startsWith("metadata.swarm.")) {
+        const leaf = path.slice("metadata.swarm.".length);
+        if (SWARM_MACHINE_KEYS.has(leaf))
+            return "machine";
+        if (SWARM_EXTRACT_KEYS.has(leaf))
+            return "extract";
+        return "unknown";
+    }
+    if (path === "edges" || path === "title" || path === "narratives" || path === "acceptance") {
+        return "extract";
+    }
+    if (path === "architecture" || path === "id")
+        return "extract";
+    return "unknown";
+}
+export function classifyItemKey(key) {
+    if (ITEM_MACHINE_KEYS.has(key))
+        return "machine";
+    if (ITEM_EXTRACT_KEYS.includes(key))
+        return "extract";
+    return "unknown";
+}
+export function classifyReferenceKey(key) {
+    if (REFERENCE_MACHINE_KEYS.has(key))
+        return "machine";
+    return "extract";
+}
+/** Every known-machine leaf that the writer-discipline test enumerates. */
+export function allKnownMachineLeaves() {
+    return Object.keys(KNOWN_MACHINE_WRITERS).sort((a, b) => a.localeCompare(b));
+}
+//# sourceMappingURL=known-machine.js.map

package/dist/scope-provenance/mint-artifacts.d.ts

@@ -0,0 +1,102 @@
+/**
+ * One mint writes record + preimage + both digests (#3376 R7 / #3385).
+ * Dest publish is two-phase under a per-plan lock: both dests land as
+ * `.next` first, then dests are copied from that pair. A crash leaves
+ * `.next` and/or a bak journal; recover finishes the flip or restores
+ * the prior pair (or neither dest) without waiting for a remint.
+ * Caught write failures still restore or clear dests.
+ */
+import { type ApprovedScopeRecord, approvedScopeIntentPath, approvedScopeRecordPath } from "./digest.js";
+import { type ExtractIntentOptions, type IntentPreimage } from "./extract-intent.js";
+export { approvedScopeIntentPath, approvedScopeRecordPath };
+export interface MintPublishDestInput {
+    readonly root: string;
+    readonly target: string;
+    readonly data: string;
+}
+export interface MintRestoreDestInput {
+    readonly root: string;
+    readonly target: string;
+    readonly snapshot: string | null;
+}
+export interface MintRemoveDestInput {
+    readonly root: string;
+    readonly target: string;
+}
+export declare class MintPairRollbackError extends Error {
+    readonly writeError: unknown;
+    readonly restoreError: unknown;
+    readonly clearError: unknown | undefined;
+    constructor(writeError: unknown, restoreError: unknown, clearError?: unknown);
+}
+export interface MintArtifactsInput {
+    readonly xbriefRelPath: string;
+    readonly payload: unknown;
+    readonly rawText: string;
+    readonly projectRoot: string;
+    readonly humanApproval?: ApprovedScopeRecord["humanApproval"];
+    readonly approvedAt?: string;
+    readonly extract?: ExtractIntentOptions;
+    /**
+     * Test-only dest publish after both temp payloads exist.
+     * Production uses containedWrite replace.
+     */
+    readonly publishDest?: (input: MintPublishDestInput) => void;
+    /**
+     * Test-only dest restore after a dest-publish failure.
+     * Production restores via containedWrite replace / rmSync.
+     */
+    readonly restoreDest?: (input: MintRestoreDestInput) => void;
+    /**
+     * Test-only dest remove during rollback cleanup.
+     * Production uses rmSync.
+     */
+    readonly removeDest?: (input: MintRemoveDestInput) => void;
+    /** Test-only lock wait. Production waits 30s. */
+    readonly lockWaitMs?: number;
+}
+export interface MintArtifactsResult {
+    readonly record: ApprovedScopeRecord;
+    readonly preimage: IntentPreimage;
+    readonly recordPath: string;
+    readonly intentPath: string;
+}
+export declare function approvedScopePairLockPath(dir: string, recordPath: string): string;
+export declare function approvedScopePairJournalPaths(dir: string, intentPath: string, recordPath: string): {
+    readonly publishing: string;
+    readonly intentBak: string;
+    readonly recordBak: string;
+};
+export declare function approvedScopePairNextPaths(dir: string, intentPath: string, recordPath: string): {
+    readonly intentNext: string;
+    readonly recordNext: string;
+};
+/**
+ * Finish a staged dest flip from `.next`, or restore the bak pair / clear dests.
+ * Does not wait for a remint.
+ */
+export declare function recoverIncompleteApprovedScopePair(input: {
+    readonly projectRoot: string;
+    readonly intentPath: string;
+    readonly recordPath: string;
+}): boolean;
+/** Recover every incomplete pair under `.deft/approved-scope/`. */
+export declare function recoverApprovedScopePairs(projectRoot: string): number;
+/**
+ * Write record + preimage as one fail-closed pair.
+ * Phase 1 writes both dests to `.next`. Phase 2 copies dests from that pair.
+ * Recover finishes the flip or restores the bak pair without a remint.
+ */
+export declare function writeApprovedScopePair(input: {
+    readonly projectRoot: string;
+    readonly intentPath: string;
+    readonly recordPath: string;
+    readonly intentData: string;
+    readonly recordData: string;
+    readonly publishDest?: (input: MintPublishDestInput) => void;
+    readonly restoreDest?: (input: MintRestoreDestInput) => void;
+    readonly removeDest?: (input: MintRemoveDestInput) => void;
+    readonly lockWaitMs?: number;
+}): void;
+export declare function mintApprovedScopeArtifacts(input: MintArtifactsInput): MintArtifactsResult;
+//# sourceMappingURL=mint-artifacts.d.ts.map