@deftai/directive-core 0.98.1 → 0.100.0

package/dist/authz/decompose-apply.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Human-origin structural apply gate for scope:decompose (#3239 / epic #3237 Q2).
+ *
+ * Apply requires a human-origin grant bound to:
+ *   project root identity (worktree and/or repo), parent path, draft/target path,
+ *   SHA-256 of exact draft bytes, and op scope.decompose.apply.structural.
+ *
+ * --check stays ungated (caller responsibility). Missing / expired / mismatched /
+ * agent-origin grants fail closed before any child story writes.
+ */
+import { type AuthzDecisionCode, type HumanOriginGrant } from "./types.js";
+export type DecomposeApplyDecisionCode = AuthzDecisionCode | "authz-grant-digest-mismatch" | "authz-grant-parent-mismatch" | "authz-grant-target-mismatch" | "authz-grant-project-mismatch" | "authz-grant-binding-incomplete";
+export interface DecomposeApplyDecision {
+    readonly allowed: boolean;
+    readonly code: DecomposeApplyDecisionCode;
+    readonly reason: string;
+    readonly humanApprovalRef: string | null;
+    readonly draftDigest: string;
+}
+export interface EvaluateDecomposeStructuralApplyInput {
+    readonly projectRoot: string;
+    /** Absolute or project-relative parent artifact path. */
+    readonly parentPath: string;
+    /** Absolute or project-relative draft path whose bytes were digested. */
+    readonly draftPath: string;
+    /** SHA-256 hex of the exact draft file bytes about to be applied. */
+    readonly draftDigest: string;
+    readonly grants?: readonly HumanOriginGrant[];
+    /** Optional GitHub-style repo identity (owner/name); compared when grant pins repo. */
+    readonly repo?: string | null;
+    readonly now?: Date;
+}
+/** SHA-256 hex of a buffer or utf8 string. */
+export declare function sha256Hex(data: Buffer | string): string;
+/** SHA-256 hex of file bytes at path (exact on-disk digest). */
+export declare function sha256FileHex(path: string): string;
+/**
+ * Normalize a path to project-relative POSIX form for grant binding compare.
+ * Returns null when the path escapes the project root.
+ */
+export declare function toProjectRelativePosix(projectRoot: string, path: string): string | null;
+/**
+ * Evaluate whether a human-origin grant covers structural decompose apply for
+ * the exact draft digest + parent + target + project identity.
+ */
+export declare function evaluateDecomposeStructuralApply(input: EvaluateDecomposeStructuralApplyInput): DecomposeApplyDecision;
+export interface MintDecomposeStructuralApplyGrantInput {
+    readonly projectRoot: string;
+    readonly parentPath: string;
+    readonly draftPath: string;
+    /** When omitted, digest is computed from draftPath on-disk bytes. */
+    readonly contentDigest?: string;
+    readonly actor?: string;
+    readonly repo?: string | null;
+    readonly expiresAt?: string | null;
+    readonly singleUse?: boolean;
+    readonly grantId?: string;
+    readonly now?: Date;
+    readonly pinActive?: boolean;
+    readonly eventRef?: string | null;
+}
+/**
+ * Operator mint helper: human-origin grant bound to exact draft bytes + paths.
+ * Sole mint path remains mintHumanOriginGrant (operator-cli origin).
+ */
+export declare function mintDecomposeStructuralApplyGrant(input: MintDecomposeStructuralApplyGrantInput): HumanOriginGrant;
+//# sourceMappingURL=decompose-apply.d.ts.map

package/dist/authz/decompose-apply.js

@@ -0,0 +1,302 @@
+/**
+ * Human-origin structural apply gate for scope:decompose (#3239 / epic #3237 Q2).
+ *
+ * Apply requires a human-origin grant bound to:
+ *   project root identity (worktree and/or repo), parent path, draft/target path,
+ *   SHA-256 of exact draft bytes, and op scope.decompose.apply.structural.
+ *
+ * --check stays ungated (caller responsibility). Missing / expired / mismatched /
+ * agent-origin grants fail closed before any child story writes.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { mintHumanOriginGrant } from "./actions.js";
+import { evidenceSatisfiesImplementationApproval, isHumanOriginGrant, isRejectedOriginKind, } from "./origin.js";
+import { listGrants } from "./store.js";
+import { SCOPE_DECOMPOSE_APPLY_STRUCTURAL, } from "./types.js";
+/** SHA-256 hex of a buffer or utf8 string. */
+export function sha256Hex(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+/** SHA-256 hex of file bytes at path (exact on-disk digest). */
+export function sha256FileHex(path) {
+    return sha256Hex(readFileSync(path));
+}
+/**
+ * Normalize a path to project-relative POSIX form for grant binding compare.
+ * Returns null when the path escapes the project root.
+ */
+export function toProjectRelativePosix(projectRoot, path) {
+    const root = resolve(projectRoot);
+    const abs = isAbsolute(path) ? resolve(path) : resolve(root, path);
+    const rel = relative(root, abs);
+    if (rel.startsWith("..") || rel === "..")
+        return null;
+    // Windows absolute on different drive yields absolute rel — treat as escape.
+    if (isAbsolute(rel))
+        return null;
+    return rel.split(sep).join("/");
+}
+function normalizeDigest(raw) {
+    if (raw === null || raw === undefined)
+        return null;
+    const t = raw.trim().toLowerCase();
+    if (t.length === 0)
+        return null;
+    // Accept optional sha256: prefix.
+    return t.startsWith("sha256:") ? t.slice("sha256:".length) : t;
+}
+/**
+ * Exact path equality for grant binding (POSIX separators only).
+ * Case-sensitive: case-variant paths are distinct on case-sensitive filesystems
+ * (#3239 Greptile P1). Windows operators mint with the same relative form
+ * produce via toProjectRelativePosix.
+ */
+function pathsEqual(a, b) {
+    return a.replace(/\\/g, "/") === b.replace(/\\/g, "/");
+}
+function grantValidity(grant, now) {
+    if (!isHumanOriginGrant(grant)) {
+        const kind = grant.origin.kind;
+        if (isRejectedOriginKind(kind)) {
+            return {
+                ok: false,
+                code: "authz-grant-origin-reject",
+                reason: `Directive denied scope:decompose apply: grant ${grant.id} origin.kind=${kind} is ` +
+                    "agent/self-authored and cannot approve a decomposition draft. " +
+                    "Human action required: mint via `deft authz:grant` (operator-cli) bound to the draft digest.",
+            };
+        }
+        return {
+            ok: false,
+            code: "authz-grant-origin-reject",
+            reason: `Directive denied scope:decompose apply: grant ${grant.id} lacks human-origin provenance. ` +
+                "Human action required: `deft authz:grant` with operator-cli origin.",
+        };
+    }
+    if (grant.semantics.revokedAt !== null) {
+        return {
+            ok: false,
+            code: "authz-grant-revoked",
+            reason: `Directive denied scope:decompose apply: grant ${grant.id} was revoked at ${grant.semantics.revokedAt}.`,
+        };
+    }
+    if (grant.semantics.singleUse && grant.semantics.usedAt !== null) {
+        return {
+            ok: false,
+            code: "authz-grant-single-use-spent",
+            reason: `Directive denied scope:decompose apply: single-use grant ${grant.id} already spent at ${grant.semantics.usedAt}.`,
+        };
+    }
+    if (grant.semantics.expiresAt !== null) {
+        const exp = Date.parse(grant.semantics.expiresAt);
+        if (!Number.isNaN(exp) && exp <= now.getTime()) {
+            return {
+                ok: false,
+                code: "authz-grant-expired",
+                reason: `Directive denied scope:decompose apply: grant ${grant.id} expired at ${grant.semantics.expiresAt}. ` +
+                    "Human action required: re-mint a grant for the current draft digest.",
+            };
+        }
+    }
+    return { ok: true };
+}
+function grantHasStructuralOp(grant) {
+    return grant.scope.operations.includes(SCOPE_DECOMPOSE_APPLY_STRUCTURAL);
+}
+/**
+ * Evaluate whether a human-origin grant covers structural decompose apply for
+ * the exact draft digest + parent + target + project identity.
+ */
+export function evaluateDecomposeStructuralApply(input) {
+    const now = input.now ?? new Date();
+    const digest = normalizeDigest(input.draftDigest) ?? "";
+    const parentRel = toProjectRelativePosix(input.projectRoot, input.parentPath);
+    const targetRel = toProjectRelativePosix(input.projectRoot, input.draftPath);
+    const projectAbs = resolve(input.projectRoot);
+    const grants = input.grants ?? listGrants(input.projectRoot);
+    if (parentRel === null || targetRel === null) {
+        return {
+            allowed: false,
+            code: "authz-grant-scope-deny",
+            reason: "Directive denied scope:decompose apply: parent or draft path is outside the project root.",
+            humanApprovalRef: null,
+            draftDigest: digest,
+        };
+    }
+    let lastReject = null;
+    for (const grant of grants) {
+        if (!evidenceSatisfiesImplementationApproval({ grant })) {
+            const validity = grantValidity(grant, now);
+            if (!validity.ok) {
+                lastReject = { code: validity.code, reason: validity.reason, grantId: grant.id };
+                continue;
+            }
+            lastReject = {
+                code: "authz-grant-origin-reject",
+                reason: `Directive denied scope:decompose apply: grant ${grant.id} does not satisfy ` +
+                    "human-origin implementation approval. Human action required: `deft authz:grant`.",
+                grantId: grant.id,
+            };
+            continue;
+        }
+        const validity = grantValidity(grant, now);
+        if (!validity.ok) {
+            lastReject = { code: validity.code, reason: validity.reason, grantId: grant.id };
+            continue;
+        }
+        if (!grantHasStructuralOp(grant)) {
+            lastReject = {
+                code: "authz-grant-scope-deny",
+                reason: `Directive denied scope:decompose apply: grant ${grant.id} does not include operation ` +
+                    `'${SCOPE_DECOMPOSE_APPLY_STRUCTURAL}'. Human action required: mint with that operation.`,
+                grantId: grant.id,
+            };
+            continue;
+        }
+        const boundDigest = normalizeDigest(grant.scope.contentDigest ?? null);
+        const boundParent = grant.scope.parentPath?.trim() ?? "";
+        const boundTarget = grant.scope.targetPath?.trim() ?? "";
+        const boundRepo = grant.scope.repo?.trim() ?? "";
+        const boundWorktree = grant.scope.worktree?.trim() ?? "";
+        if (boundDigest === null || boundParent.length === 0 || boundTarget.length === 0) {
+            lastReject = {
+                code: "authz-grant-binding-incomplete",
+                reason: `Directive denied scope:decompose apply: grant ${grant.id} is missing required ` +
+                    "structural bindings (contentDigest, parentPath, targetPath). " +
+                    "Human action required: re-mint bound to the exact draft.",
+                grantId: grant.id,
+            };
+            continue;
+        }
+        if (boundRepo.length === 0 && boundWorktree.length === 0) {
+            lastReject = {
+                code: "authz-grant-binding-incomplete",
+                reason: `Directive denied scope:decompose apply: grant ${grant.id} does not bind project ` +
+                    "identity (repo and/or worktree). Human action required: re-mint with --repo or worktree.",
+                grantId: grant.id,
+            };
+            continue;
+        }
+        if (boundDigest !== digest) {
+            lastReject = {
+                code: "authz-grant-digest-mismatch",
+                reason: `Directive denied scope:decompose apply: grant ${grant.id} is bound to draft digest ` +
+                    `${boundDigest.slice(0, 12)}… but the draft bytes hash to ${digest.slice(0, 12)}…. ` +
+                    "Any content change after approval invalidates the grant. Re-mint for the current draft.",
+                grantId: grant.id,
+            };
+            continue;
+        }
+        if (!pathsEqual(boundParent, parentRel)) {
+            lastReject = {
+                code: "authz-grant-parent-mismatch",
+                reason: `Directive denied scope:decompose apply: grant ${grant.id} is bound to parent ` +
+                    `'${boundParent}' but apply targets '${parentRel}'.`,
+                grantId: grant.id,
+            };
+            continue;
+        }
+        if (!pathsEqual(boundTarget, targetRel)) {
+            lastReject = {
+                code: "authz-grant-target-mismatch",
+                reason: `Directive denied scope:decompose apply: grant ${grant.id} is bound to draft path ` +
+                    `'${boundTarget}' but apply uses '${targetRel}'.`,
+                grantId: grant.id,
+            };
+            continue;
+        }
+        // Project identity: when grant pins repo and/or worktree, attempt must match.
+        if (boundRepo.length > 0) {
+            const attemptRepo = (input.repo ?? "").trim();
+            if (attemptRepo.length === 0 || attemptRepo.toLowerCase() !== boundRepo.toLowerCase()) {
+                lastReject = {
+                    code: "authz-grant-project-mismatch",
+                    reason: `Directive denied scope:decompose apply: grant ${grant.id} is bound to repo ` +
+                        `'${boundRepo}' which does not match the apply context.`,
+                    grantId: grant.id,
+                };
+                continue;
+            }
+        }
+        if (boundWorktree.length > 0) {
+            const grantWt = resolve(boundWorktree);
+            // Worktree compare is path-normalize only (resolve); keep exact string match of
+            // resolved absolute paths without case-folding (same rule as parent/target paths).
+            if (grantWt !== projectAbs) {
+                lastReject = {
+                    code: "authz-grant-project-mismatch",
+                    reason: `Directive denied scope:decompose apply: grant ${grant.id} is bound to worktree ` +
+                        `'${boundWorktree}' which does not match project root '${projectAbs}'.`,
+                    grantId: grant.id,
+                };
+                continue;
+            }
+        }
+        return {
+            allowed: true,
+            code: "authz-allow",
+            reason: `Directive allowed scope:decompose apply via human-origin grant ${grant.id} ` +
+                `bound to draft digest ${digest.slice(0, 12)}….`,
+            humanApprovalRef: grant.id,
+            draftDigest: digest,
+        };
+    }
+    if (lastReject !== null) {
+        return {
+            allowed: false,
+            code: lastReject.code,
+            reason: lastReject.reason,
+            humanApprovalRef: lastReject.grantId,
+            draftDigest: digest,
+        };
+    }
+    return {
+        allowed: false,
+        code: "authz-grant-missing",
+        reason: "Directive denied scope:decompose apply: no human-origin grant covers " +
+            `'${SCOPE_DECOMPOSE_APPLY_STRUCTURAL}' for this draft digest. ` +
+            "Human action required: mint a grant bound to the exact draft SHA-256 " +
+            "(self-authored lifecycle/dispatch tokens do not count). --check remains ungated.",
+        humanApprovalRef: null,
+        draftDigest: digest,
+    };
+}
+/**
+ * Operator mint helper: human-origin grant bound to exact draft bytes + paths.
+ * Sole mint path remains mintHumanOriginGrant (operator-cli origin).
+ */
+export function mintDecomposeStructuralApplyGrant(input) {
+    const parentRel = toProjectRelativePosix(input.projectRoot, input.parentPath);
+    const targetRel = toProjectRelativePosix(input.projectRoot, input.draftPath);
+    if (parentRel === null || targetRel === null) {
+        throw new Error("mintDecomposeStructuralApplyGrant: parentPath and draftPath must resolve inside projectRoot");
+    }
+    const digest = input.contentDigest !== undefined
+        ? (normalizeDigest(input.contentDigest) ?? "")
+        : sha256FileHex(isAbsolute(input.draftPath)
+            ? input.draftPath
+            : resolve(input.projectRoot, input.draftPath));
+    if (digest.length === 0) {
+        throw new Error("mintDecomposeStructuralApplyGrant: contentDigest must be non-empty");
+    }
+    const mintInput = {
+        projectRoot: input.projectRoot,
+        actor: input.actor,
+        operations: [SCOPE_DECOMPOSE_APPLY_STRUCTURAL],
+        contentDigest: digest,
+        parentPath: parentRel,
+        targetPath: targetRel,
+        worktree: resolve(input.projectRoot),
+        repo: input.repo ?? null,
+        expiresAt: input.expiresAt ?? null,
+        singleUse: input.singleUse === true,
+        grantId: input.grantId,
+        now: input.now,
+        pinActive: input.pinActive,
+        eventRef: input.eventRef ?? null,
+    };
+    return mintHumanOriginGrant(mintInput);
+}
+//# sourceMappingURL=decompose-apply.js.map

package/dist/authz/index.d.ts

@@ -1,10 +1,12 @@
 /**
  * Human-origin approval grants + UAT mutation lease (#2944 Wave 1)
- * + closed-verb release gates / AFK templates (#1095 Wave 4).
+ * + closed-verb release gates / AFK templates (#1095 Wave 4)
+ * + structural scope:decompose apply digest gate (#3239).
  */
 export * from "./actions.js";
 export * from "./classify.js";
 export * from "./closed-verb.js";
+export * from "./decompose-apply.js";
 export * from "./evaluate.js";
 export * from "./origin.js";
 export * from "./paths.js";

package/dist/authz/index.js

@@ -1,10 +1,12 @@
 /**
  * Human-origin approval grants + UAT mutation lease (#2944 Wave 1)
- * + closed-verb release gates / AFK templates (#1095 Wave 4).
+ * + closed-verb release gates / AFK templates (#1095 Wave 4)
+ * + structural scope:decompose apply digest gate (#3239).
  */
 export * from "./actions.js";
 export * from "./classify.js";
 export * from "./closed-verb.js";
+export * from "./decompose-apply.js";
 export * from "./evaluate.js";
 export * from "./origin.js";
 export * from "./paths.js";

package/dist/authz/store.d.ts

@@ -25,6 +25,59 @@ export declare function loadAuthzStateResult(projectRoot: string): AuthzStateLoa
 export declare function loadAuthzState(projectRoot: string): AuthzState;
 /** Persist single-use grant consumption after an allow decision (#2944). */
 export declare function markGrantUsed(projectRoot: string, grantId: string, now?: Date): HumanOriginGrant | null;
+/** Exclusive claim lock body under `.deft/authz/locks/<id>.lock` (#3239). */
+export interface GrantClaimLockRecord {
+    readonly pid: number;
+    readonly startedAt: string;
+    readonly token: string;
+}
+/**
+ * Whether a claim lock may be reclaimed after a crashed holder (#3239).
+ * Live owner PIDs are never reclaimed (no mtime-only steal of a live critical section).
+ * Corrupt / unreadable records are reclaimable; PID-reuse residual needs manual delete.
+ */
+export declare function isGrantClaimLockReclaimable(rec: GrantClaimLockRecord | null): boolean;
+export interface ClaimSingleUseGrantOptions {
+    readonly now?: Date;
+    /**
+     * Re-check grant after exclusive lock (revocation/expiry/origin/bindings).
+     * Called before protected apply / single-use mark so an invalidated grant cannot authorize writes.
+     */
+    readonly revalidate?: (grant: HumanOriginGrant) => {
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    };
+    /**
+     * Protected work under the exclusive claim (#3239 residual).
+     * Order: lock → revalidate → mark single-use usedAt → apply → release lock.
+     * If apply throws, usedAt is rolled back (grant reusable) and the lock is released.
+     * Concurrent claimants fail closed while the lock is held.
+     */
+    readonly apply?: (grant: HumanOriginGrant) => void;
+}
+/**
+ * Claim a single-use grant for structural apply (#3239).
+ *
+ * Concurrent-safe + failure-safe order when `apply` is provided:
+ *   exclusive lock → re-load → revalidate → mark single-use usedAt → apply (writes)
+ *   → on apply throw: rollback usedAt + release lock (grant reusable for retry).
+ * Multi-use grants run apply (if any) without mutating usedAt.
+ * Without `apply`, single-use is marked under the lock (claim-only / test path).
+ *
+ * Crash after mark + before rollback: grant stays spent (no double-apply); operator remints.
+ * Dead-PID / corrupt locks reclaim via **rename-away** of the old lock path (only one
+ * renamer wins) then exclusive create — never blind rmSync of a live winner's lock.
+ * Live PIDs are never reclaimed. PID-reuse residual: operator deletes the lock file.
+ */
+export declare function claimSingleUseGrantForApply(projectRoot: string, grantId: string, options?: ClaimSingleUseGrantOptions | Date): {
+    ok: true;
+    grant: HumanOriginGrant;
+} | {
+    ok: false;
+    reason: string;
+};
 export declare function saveAuthzState(projectRoot: string, state: AuthzState): void;
 export declare function loadGrant(projectRoot: string, grantId: string): HumanOriginGrant | null;
 export declare function saveGrant(projectRoot: string, grant: HumanOriginGrant): void;