@deftai/directive-core 0.99.0 → 0.100.0

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;

package/dist/authz/store.js

@@ -4,7 +4,7 @@
 import { randomBytes } from "node:crypto";
 import { existsSync, readdirSync, readFileSync, renameSync, rmSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
-import { containedWrite } from "../fs/contained-write.js";
+import { ContainedWriteError, containedWrite } from "../fs/contained-write.js";
 import { assertWriteTargetSafe } from "../fs/projection-containment.js";
 import { isHumanOrigin } from "./origin.js";
 import { authzAuditPath, authzGrantPath, authzGrantsDir, authzStatePath } from "./paths.js";
@@ -105,6 +105,13 @@ function parseScope(raw) {
         storyIds: readStringArray(rec.storyIds ?? rec.story_ids),
         issueIds: readNumberArray(rec.issueIds ?? rec.issue_ids),
         cohortId: readString(rec, "cohortId") ?? readString(rec, "cohort_id"),
+        // #3239 structural decompose apply bindings (snake_case accepted on load).
+        contentDigest: readString(rec, "contentDigest") ??
+            readString(rec, "content_digest") ??
+            readString(rec, "draftDigest") ??
+            readString(rec, "draft_digest"),
+        parentPath: readString(rec, "parentPath") ?? readString(rec, "parent_path"),
+        targetPath: readString(rec, "targetPath") ?? readString(rec, "target_path"),
     };
 }
 function parseSemantics(raw) {
@@ -233,6 +240,217 @@ export function markGrantUsed(projectRoot, grantId, now = new Date()) {
     saveGrant(projectRoot, used);
     return used;
 }
+function isProcessAlive(pid) {
+    if (!Number.isFinite(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        // ESRCH → dead. EPERM → exists but unsignalable — treat as alive (never reclaim).
+        if (code === "EPERM")
+            return true;
+        return false;
+    }
+}
+/**
+ * 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 function isGrantClaimLockReclaimable(rec) {
+    if (rec === null)
+        return true;
+    return !isProcessAlive(rec.pid);
+}
+function readGrantClaimLockRecord(lockPath) {
+    try {
+        const raw = readFileSync(lockPath, "utf8").trim();
+        // JSON form (current). Legacy: "pid\niso\n" lines from earlier #3239 revisions.
+        if (raw.startsWith("{")) {
+            const parsed = JSON.parse(raw);
+            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+                return null;
+            const o = parsed;
+            const pid = typeof o.pid === "number" ? o.pid : Number(o.pid);
+            const startedAt = typeof o.startedAt === "string" ? o.startedAt : "";
+            const token = typeof o.token === "string" ? o.token : "";
+            if (!Number.isFinite(pid) || token.length === 0)
+                return null;
+            return { pid, startedAt, token };
+        }
+        const lines = raw.split(/\r?\n/);
+        const pid = Number(lines[0]);
+        if (!Number.isFinite(pid))
+            return null;
+        return {
+            pid,
+            startedAt: typeof lines[1] === "string" ? lines[1] : "",
+            token: "legacy",
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 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 function claimSingleUseGrantForApply(projectRoot, grantId, options = {}) {
+    // Back-compat: second arg was `now: Date` in the first #3239 revision.
+    const opts = options instanceof Date ? { now: options } : options;
+    const now = opts.now ?? new Date();
+    const usedAtIso = utcIso(now);
+    const safe = grantId.replace(/[^a-zA-Z0-9._-]/g, "_");
+    const root = resolve(projectRoot);
+    const lockRel = join(".deft", "authz", "locks", `${safe}.lock`);
+    const lockPath = join(root, lockRel);
+    const lockToken = randomBytes(8).toString("hex");
+    const lockBody = `${JSON.stringify({
+        pid: process.pid,
+        startedAt: usedAtIso,
+        token: lockToken,
+    })}\n`;
+    const tryCreateLock = () => {
+        try {
+            containedWrite({
+                root,
+                target: lockPath,
+                data: lockBody,
+                mode: "create",
+            });
+            return true;
+        }
+        catch (err) {
+            if (err instanceof ContainedWriteError && err.code === "CONTAINED_WRITE_EXISTS") {
+                return false;
+            }
+            // Other containment/IO failures fail closed as reservation denial.
+            return false;
+        }
+    };
+    /** True when the on-disk lock still carries our token (not stolen mid-section). */
+    const stillOwnLock = () => {
+        const rec = readGrantClaimLockRecord(lockPath);
+        return rec !== null && rec.token === lockToken && rec.pid === process.pid;
+    };
+    let locked = tryCreateLock();
+    if (!locked) {
+        // Dead-PID / corrupt reclaim: rename the old lock aside (atomic contention) then create.
+        // Blind rmSync is forbidden — a second reclaimer must not delete a winner's new lock.
+        const existing = readGrantClaimLockRecord(lockPath);
+        if (isGrantClaimLockReclaimable(existing)) {
+            const side = `${lockPath}.reclaim.${randomBytes(6).toString("hex")}`;
+            try {
+                renameSync(lockPath, side);
+                try {
+                    rmSync(side, { force: true });
+                }
+                catch {
+                    /* best-effort side cleanup */
+                }
+            }
+            catch {
+                // Lost rename race or lock already gone — fall through to exclusive create.
+            }
+            locked = tryCreateLock();
+        }
+    }
+    if (!locked) {
+        return {
+            ok: false,
+            reason: `Directive denied scope:decompose apply: grant ${grantId} is already reserved ` +
+                "or spent by a concurrent apply. Human action required: remint if the prior apply failed " +
+                "(or remove a leftover `.deft/authz/locks/<id>.lock` after a dead-holder crash if reclaim fails).",
+        };
+    }
+    let markedUsedAt = null;
+    try {
+        const grant = loadGrant(projectRoot, grantId);
+        if (grant === null) {
+            return {
+                ok: false,
+                reason: `Directive denied scope:decompose apply: grant ${grantId} missing.`,
+            };
+        }
+        if (opts.revalidate !== undefined) {
+            const check = opts.revalidate(grant);
+            if (!check.ok) {
+                return { ok: false, reason: check.reason };
+            }
+        }
+        if (!grant.semantics.singleUse) {
+            if (opts.apply !== undefined) {
+                opts.apply(grant);
+            }
+            return { ok: true, grant };
+        }
+        if (grant.semantics.usedAt !== null) {
+            return {
+                ok: false,
+                reason: `Directive denied scope:decompose apply: single-use grant ${grantId} already spent at ` +
+                    `${grant.semantics.usedAt}.`,
+            };
+        }
+        // Spend under lock before protected writes so a post-write mark failure cannot
+        // leave completed mutations behind an unspent single-use grant (#3239 Greptile).
+        // Apply throw rolls usedAt back while the lock is still held (retry-safe).
+        const used = {
+            ...grant,
+            semantics: {
+                ...grant.semantics,
+                usedAt: usedAtIso,
+            },
+        };
+        saveGrant(projectRoot, used);
+        markedUsedAt = usedAtIso;
+        if (opts.apply !== undefined) {
+            try {
+                opts.apply(used);
+            }
+            catch (applyErr) {
+                // Rollback spend so a failed multi-file apply does not strand the approval.
+                const current = loadGrant(projectRoot, grantId);
+                if (current?.semantics.singleUse && current.semantics.usedAt === markedUsedAt) {
+                    const restored = {
+                        ...current,
+                        semantics: { ...current.semantics, usedAt: null },
+                    };
+                    saveGrant(projectRoot, restored);
+                    markedUsedAt = null;
+                }
+                throw applyErr;
+            }
+        }
+        if (!stillOwnLock()) {
+            return {
+                ok: false,
+                reason: `Directive denied scope:decompose apply: grant ${grantId} lock ownership lost mid-claim. ` +
+                    "Human action required: inspect partial outputs and remint if needed.",
+            };
+        }
+        return { ok: true, grant: used };
+    }
+    finally {
+        // Only remove the lock when we still own it — never delete a successor's claim.
+        if (stillOwnLock()) {
+            rmSync(lockPath, { force: true });
+        }
+    }
+}
 export function saveAuthzState(projectRoot, state) {
     writeJsonContained(projectRoot, authzStatePath(projectRoot), state);
 }

package/dist/authz/types.d.ts

@@ -5,8 +5,10 @@
  * agent authors must not independently satisfy implementation-approval gates.
  * Local-file forgery by a credential-compromised agent remains #983-class OOS.
  */
-/** Operation classes bound on a grant (Wave 1 structural binding + Wave 4 closed verbs). */
-export declare const AUTHZ_OPERATIONS: readonly ["edit", "push", "pr", "merge", "settings", "deployment", "issue_mutation", "release-cut", "release-publish", "release-rollback"];
+/** Structural apply op for scope:decompose (#3239 / epic #3237 Q2). Always gated. */
+export declare const SCOPE_DECOMPOSE_APPLY_STRUCTURAL: "scope.decompose.apply.structural";
+/** Operation classes bound on a grant (Wave 1 structural binding + Wave 4 closed verbs + #3239). */
+export declare const AUTHZ_OPERATIONS: readonly ["edit", "push", "pr", "merge", "settings", "deployment", "issue_mutation", "release-cut", "release-publish", "release-rollback", "scope.decompose.apply.structural"];
 export type AuthzOperation = (typeof AUTHZ_OPERATIONS)[number];
 /**
  * Human-origin kinds accepted as approval provenance.
@@ -41,6 +43,21 @@ export interface GrantScope {
      * for product mutations; approving one cohort does not clear UAT.
      */
     readonly cohortId: string | null;
+    /**
+     * SHA-256 hex of exact bound artifact bytes (decompose draft for #3239).
+     * Unset/null = unbound (cannot satisfy structural decompose apply).
+     */
+    readonly contentDigest?: string | null;
+    /**
+     * Project-relative parent artifact path for structural decompose apply (#3239).
+     * Unset/null = unbound.
+     */
+    readonly parentPath?: string | null;
+    /**
+     * Project-relative draft/target path for structural decompose apply (#3239).
+     * Unset/null = unbound.
+     */
+    readonly targetPath?: string | null;
 }
 export interface GrantSemantics {
     readonly expiresAt: string | null;