akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/commands/proposal/repository.js

@@ -21,20 +21,12 @@
  * is a status flip, and the full audit trail (review outcome, reason, backup
  * content for revert) lives on the row.
  *
- * ## Legacy filesystem import
- *
- * Before 0.9.0 proposals lived as per-uuid JSON directories under
- * `<stashDir>/.akm/proposals/`. The first proposal operation against a stash
- * imports any legacy `proposal.json` files into the table — see
- * `./legacy-import.ts` (`importLegacyProposalFiles`), funnelled through
- * {@link withProposalsDb}.
- *
  * # Why the queue bypasses `writeAssetToSource`
  *
  * The architectural rule "all writes go through `writeAssetToSource`" applies
  * to *assets*. Proposals are **not** assets — they live outside the asset
  * tree (in state.db, parallel to how events do). Routing them through
- * `writeAssetToSource` would force them into a `TYPE_DIRS` slot, would commit
+ * `writeAssetToSource` would force them into a placement stash-subdir slot, would commit
  * them to git, and would leak unaccepted drafts through the normal indexer.
  * The {@link promoteProposal} step is the bridge: it routes the accepted
  * payload through `writeAssetToSource` so the actual asset write still
@@ -42,88 +34,84 @@
  */
 import { createHash, randomUUID } from "node:crypto";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
-import { makeAssetRef, parseAssetRef } from "../../core/asset/asset-ref.js";
-import { resolveAssetPathFromName, TYPE_DIRS } from "../../core/asset/asset-spec.js";
-import { NotFoundError, UsageError } from "../../core/errors.js";
+import { parse as parseYaml } from "yaml";
+import { ensureAkmMarkdownType } from "../../core/asset/akm-markdown.js";
+import { assetPathForName, placementTypes, stashDirFor } from "../../core/asset/asset-placement.js";
+import { isBundleSlug, parseBundleRef } from "../../core/asset/asset-ref.js";
+import { assembleAsset, serializeFrontmatter } from "../../core/asset/asset-serialize.js";
+import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { conceptIdFromTypeName, parseRefInput } from "../../core/asset/resolve-ref.js";
+import { isWithin } from "../../core/common.js";
+import { loadConfig } from "../../core/config/config.js";
+import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
+import { proposalContent } from "../../core/file-change.js";
+import { _setTxnMutationHookForTests, advanceTxn, beginTxn, canonicalTxnRoot, cleanupTxn, fsyncTxnDir, fsyncTxnFile, listTxnJournals, mintTxnId, registerTxnKind, sweepJournallessTxnDir, txnDirFor, txnMutationHook, txnNamespaceDir, } from "../../core/fs-txn.js";
+import { canonicalBundleIdForTarget, resolveBundleWriteTarget } from "../../core/mutation-target.js";
 import { withImmediateTransaction, withStateDb } from "../../core/state-db.js";
 import { warn } from "../../core/warn.js";
-import { commitWriteTargetBoundary, formatRefForMessage, resolveWriteTarget, writeAssetToSource, } from "../../core/write-source.js";
-import { getStateProposal, listStateProposalIdsByPrefix, listStateProposals, upsertProposal, } from "../../storage/repositories/proposals-repository.js";
-import { importLegacyProposalFiles } from "./legacy-import.js";
+import { assertAkmAssetWrite, assertWriteTargetPathsClean, captureGitPublication, captureWriteTargetPathSnapshot, prepareWriteTargetForMutation, publishWriteTargetTransaction, resolveWriteTarget, } from "../../core/write-source.js";
+import { withAssetMutationLease } from "../../indexer/index-writer-lock.js";
+import { indexWrittenAssets } from "../../indexer/index-written-assets.js";
+import { deriveInstallations } from "../../indexer/installations.js";
+import { resolveSourceEntries } from "../../indexer/search/search-source.js";
+import { insertEventOnce } from "../../storage/repositories/events-repository.js";
+import { getStateProposal, getStateProposalLenient, listStateProposalIdsByPrefix, listStateProposals, upsertProposal, } from "../../storage/repositories/proposals-repository.js";
+import { pkgVersion } from "../../version.js";
+import { runBaseChecks } from "../lint/base-linter.js";
+import { formatNewAssetDiff, formatUnifiedDiff } from "./diff-format.js";
+import { isAutomatedProposalSource, isValidProposalSource, PROPOSAL_SOURCES, } from "./proposal-types.js";
+import { hasCanonicalProposalValidator } from "./validators/proposal-validators.js";
 import { repairProposalContent, validateProposal } from "./validators/proposals.js";
-// ── Source allow-list (F-4 / #385) ──────────────────────────────────────────
-/**
- * Curated allow-list of valid `source` values for proposals (F-4 / #385).
- *
- * Rationale (W3C PROV-DM 2013): Provenance records require typed, validated
- * sources for meaningful aggregation. Accept-rate-per-source is the core
- * self-measurement metric for recursive self-improvement: if reflect proposals
- * are accepted at 20% and distill proposals at 60%, that guides resource
- * allocation. Free-text typos (`"reflct"`) produce unaggregatable events.
- *
- * Automated sources (those in {@link AUTOMATED_PROPOSAL_SOURCES}) require a
- * `sourceRun` field for full PROV-DM traceability.
- */
-export const PROPOSAL_SOURCES = [
-    // Automated sources — require sourceRun for traceability.
-    "reflect",
-    "distill",
-    "consolidate",
-    "extract",
-    "improve",
-    "recombine",
-    "procedural",
-    // Semi-automated / tool-driven.
-    "feedback",
-    // Human-initiated / CLI-driven.
-    "propose",
-    "remember",
-    "import",
-    // Internal / system.
-    "distill_quality_rejected",
-    "schema-repair",
-];
-/** Automated sources that SHOULD include a `sourceRun` for PROV-DM traceability. */
-export const AUTOMATED_PROPOSAL_SOURCES = [
-    "reflect",
-    "distill",
-    "consolidate",
-    "extract",
-    "improve",
-    "recombine",
-    "procedural",
-    "schema-repair",
-];
-/**
- * Check whether a string is a valid {@link ProposalSource}.
- * Unknown source values are accepted with a runtime warning rather than a hard
- * error, to allow extensions without breaking existing callers.
- */
-export function isValidProposalSource(source) {
-    return PROPOSAL_SOURCES.includes(source);
-}
+const PROMOTION_LINT_BLOCKERS = new Set(["unquoted-colon", "missing-ref", "stale-path"]);
+// ── Proposal domain types (moved to ./proposal-types.ts, WI-9.8 KILL 1) ─────
+//
+// Proposal / ProposalStatus / ProposalPayload / ProposalReview /
+// ProposalGateDecision(Outcome) / ProposalSource / PROPOSAL_SOURCES /
+// AUTOMATED_PROPOSAL_SOURCES / isValidProposalSource / isAutomatedProposalSource
+// moved to the dependency-free leaf so validators/proposals.ts,
+// validators/proposal-validators.ts, storage/repositories/proposals-repository.ts,
+// and storage repositories can import the `Proposal` type without importing
+// this heavier transaction-engine module back. That back-edge was the
+// repository↔validators import cycle (plan §10.7 D.3). Every symbol this
+// module used to export directly is re-exported here verbatim so existing
+// import sites (`from "../proposal/repository.js"`) are unchanged.
+export { AUTOMATED_PROPOSAL_SOURCES, isAutomatedProposalSource, isValidProposalSource, PROPOSAL_SOURCES, } from "./proposal-types.js";
+// The envelope's primary-content accessor lives in the dependency-free
+// core/file-change module; re-exported here so proposal consumers get it
+// alongside the repository API.
+export { proposalContent };
 /**
- * Check whether a source value is an automated source requiring `sourceRun`.
+ * Copy of `p` with `content` replacing BOTH the payload's content and the
+ * primary change's `after` — every in-memory content mutation must keep the
+ * WI-6.2 invariant (`changes[0].after === payload.content`) intact.
  */
-export function isAutomatedProposalSource(source) {
-    return AUTOMATED_PROPOSAL_SOURCES.includes(source);
+function withProposalContent(p, content) {
+    return {
+        ...p,
+        payload: { ...p.payload, content },
+        changes: p.changes.map((c, i) => 
+        // A delete-op primary change carries no `after` (file-change.ts contract).
+        i === 0 && c.op !== "delete" ? { ...c, after: content } : c),
+    };
 }
 /** Type guard: true when createProposal returned a skipped record. */
 export function isProposalSkipped(result) {
     return result.skipped === true;
 }
-// ── Dedup / cooldown constants ───────────────────────────────────────────────
+// ── Fingerprint / rejection-backoff constants ────────────────────────────────
 const MS_PER_DAY = 86_400_000;
 /**
- * Post-rejection cooldown windows by source. After a proposal is rejected,
- * `createProposal` silently skips new proposals for the same `ref+source`
- * until the window expires (unless `force: true` is passed).
+ * Post-rejection backoff windows by source (the RETAINED cooldown semantics,
+ * plan §4.5). After a proposal is rejected, `createProposal` silently skips
+ * new proposals for the same `ref+source` until the window expires (unless
+ * `force: true` is passed).
  *
  * Rationale (Settles 2009 active-learning survey; Argilla/Label Studio HITL):
- * Reviewer fatigue is a blocker for the human-in-the-loop guarantee. Cooldowns
- * prevent nightly improve runs from re-flooding the queue with near-identical
+ * Reviewer fatigue is a blocker for the human-in-the-loop guarantee. Backoff
+ * prevents nightly improve runs from re-flooding the queue with near-identical
  * proposals the reviewer just declined.
  *
  *   - reflect: 14 days (agent-based; slower feedback loops)
@@ -152,49 +140,170 @@ function newId(ctx) {
     return fn();
 }
 /**
- * Open the state database (honouring the `ctx.dbPath` test seam), run the
- * legacy filesystem import for `stashDir` if it has not happened yet, hand the
+ * Open the state database (honouring the `ctx.dbPath` test seam), hand the
  * connection to `fn`, and close it in a `finally`. Every public function in
- * this module funnels its store access through here so the legacy import is
- * guaranteed to have run before any read or write.
+ * this module funnels its store access through here.
+ *
+ * `stashDir` is threaded through the public API for the store's per-stash
+ * partition.
  */
-function withProposalsDb(stashDir, ctx, fn) {
-    return withStateDb((db) => {
-        importLegacyProposalFiles(db, stashDir);
-        return fn(db);
-    }, { path: ctx?.dbPath });
+function withProposalsDb(_stashDir, ctx, fn) {
+    return withStateDb(fn, { path: ctx?.dbPath });
+}
+function persistProposalUpdate(db, proposal, stashDir) {
+    // Only take the full re-serialize (upsertProposal -> proposalToRowValues)
+    // path when `changes` is well-formed enough to survive it — a non-empty
+    // path on every entry, matching proposalToRowValues' own validation. A
+    // legacy row with a present `proposedTarget` but an empty/missing
+    // `changes[].path` (e.g. a malformed 0.8-era row) would otherwise die in
+    // proposalToRowValues; falling through to the targeted UPDATE below keeps
+    // `changes`/`proposedTarget` untouched in metadata_json and only flips the
+    // status/review/etc. fields the terminal transition actually needs.
+    const changesAreWellFormed = proposal.changes.length > 0 && proposal.changes.every((change) => change.path.length > 0);
+    if (changesAreWellFormed && proposal.proposedTarget) {
+        upsertProposal(db, proposal, stashDir);
+        return;
+    }
+    const row = db
+        .prepare("SELECT metadata_json FROM proposals WHERE id = ? AND stash_dir = ?")
+        .get(proposal.id, stashDir);
+    if (!row)
+        throw new NotFoundError(`Proposal "${proposal.id}" not found.`, "FILE_NOT_FOUND");
+    const metadata = JSON.parse(row.metadata_json);
+    for (const field of [
+        "sourceRun",
+        "beforeHash",
+        "review",
+        "confidence",
+        "gateDecision",
+        "backupContent",
+        "acceptedTarget",
+        "eligibilitySource",
+    ]) {
+        const value = proposal[field];
+        if (value === undefined)
+            delete metadata[field];
+        else
+            metadata[field] = value;
+    }
+    db.prepare(`UPDATE proposals
+     SET ref = ?, status = ?, source = ?, updated_at = ?, content = ?, frontmatter_json = ?, metadata_json = ?
+     WHERE id = ? AND stash_dir = ?`).run(proposal.ref, proposal.status, proposal.source, proposal.updatedAt, proposal.payload.content, proposal.payload.frontmatter ? JSON.stringify(proposal.payload.frontmatter) : null, JSON.stringify(metadata), proposal.id, stashDir);
+}
+function proposalRefIdentity(ref) {
+    try {
+        const parsed = parseBundleRef(ref);
+        if (parsed.fragment !== undefined || isRetiredProposalConceptId(parsed.conceptId))
+            return undefined;
+        return {
+            conceptId: parsed.conceptId,
+            ...(parsed.bundle !== undefined ? { bundle: parsed.bundle } : {}),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function filterRefIdentity(ref) {
+    try {
+        const p = parseBundleRef(ref);
+        if (p.fragment !== undefined || isRetiredProposalConceptId(p.conceptId)) {
+            throw new Error("not a current proposal identity");
+        }
+        return {
+            conceptId: p.conceptId,
+            ...(p.bundle !== undefined ? { bundle: p.bundle } : {}),
+        };
+    }
+    catch {
+        throw new UsageError(`Invalid asset-ref filter "${ref}". Use the 0.9.0 grammar [bundle//]conceptId, e.g. knowledge/guide.md or lessons/deploy.`, "INVALID_FLAG_VALUE");
+    }
+}
+function isRetiredProposalConceptId(conceptId) {
+    const colon = conceptId.indexOf(":");
+    return colon > 0 && stashDirFor(conceptId.slice(0, colon)) !== undefined;
+}
+function proposalMatchesRef(proposalRef, filter) {
+    const proposal = proposalRefIdentity(proposalRef);
+    return (proposal !== undefined &&
+        proposal.conceptId === filter.conceptId &&
+        (filter.bundle === undefined || proposal.bundle === filter.bundle));
+}
+function proposalDurableRef(parsedRef, target) {
+    const conceptId = conceptIdFromTypeName(parsedRef.type, parsedRef.name);
+    const { origin } = parsedRef;
+    if (!isBundleSlug(target.source)) {
+        throw new UsageError(`Proposal target source "${target.source}" is not a valid bundle name.`, "INVALID_FLAG_VALUE");
+    }
+    if (origin !== undefined) {
+        if (target.source !== origin) {
+            throw new UsageError(`Proposal ref bundle "${origin}" conflicts with target source "${target.source}".`, "INVALID_FLAG_VALUE");
+        }
+        return `${origin}//${conceptId}`;
+    }
+    return `${target.source}//${conceptId}`;
+}
+function resolveCreateProposalTarget(stashDir, explicit, bundle) {
+    if (explicit) {
+        if (!isBundleSlug(explicit.source) || !explicit.root.trim()) {
+            throw new UsageError("Proposal targets require a current bundle name and materialized root.", "INVALID_FLAG_VALUE");
+        }
+        return { source: explicit.source, root: path.resolve(explicit.root) };
+    }
+    const config = loadConfig();
+    const local = resolveProposalQueueTarget(stashDir, config);
+    if (!bundle || bundle === local.source)
+        return local;
+    if (bundle) {
+        const target = resolveBundleWriteTarget(config, bundle);
+        return { source: target.source.name, root: target.source.path };
+    }
+    return local;
+}
+export function resolveProposalQueueTarget(stashDir, config = loadConfig()) {
+    const root = path.resolve(stashDir);
+    const sources = resolveSourceEntries(root, config);
+    const sourceIndex = sources.findIndex((source) => path.resolve(source.path) === root);
+    const source = sources[sourceIndex];
+    const bundleId = sourceIndex >= 0 ? deriveInstallations(sources)[sourceIndex]?.id : undefined;
+    if (!source || !bundleId) {
+        throw new ConfigError(`No bundle owns proposal queue ${root}.`, "INVALID_CONFIG_FILE");
+    }
+    if (!source.registryId && Object.keys(config.bundles ?? {}).length > 0) {
+        throw new ConfigError(`No configured bundle owns proposal queue ${root}.`, "INVALID_CONFIG_FILE");
+    }
+    if (source.writable !== true) {
+        throw new UsageError(`Proposal bundle "${bundleId}" is not writable.`, "INVALID_FLAG_VALUE");
+    }
+    return { source: bundleId, root };
 }
 // ── Public API ──────────────────────────────────────────────────────────────
 /**
  * Create a new pending proposal. The id is a stable random UUID, so two
  * proposals with the same `ref` never collide.
  *
- * **Dedup / cooldown guard** (F-2 / #363):
+ * **Input-fingerprint / rejection-backoff guard** (§23.6, WI-6.4):
  *
  * Before writing, this function checks:
- *   1. `duplicate_pending` — a pending proposal already exists for the same
- *      `ref+source`. Pass `input.force = true` to bypass.
- *   2. `content_hash_match` — an identical content hash is already pending or
- *      was recently rejected for this `ref+source`. Bypass with `force: true`.
- *   3. `cooldown` — a proposal for this `ref+source` was rejected within the
- *      source-specific cooldown window (reflect: 14 d, distill: 30 d,
- *      others: 7 d). Bypass with `force: true`.
+ *   1. `fingerprint_match` — the §23.6 input fingerprint (scheme version,
+ *      source, ref, target before-hash, model id) was already processed.
+ *      The row survives the proposal's lifecycle, so identical inputs stay
+ *      deduplicated until the target, model, or scheme changes. Pass
+ *      `input.force = true` to bypass.
+ *   2. `rejection_backoff` — a proposal for this `ref+source` was rejected
+ *      within the source-specific backoff window (reflect: 14 d, distill:
+ *      30 d, others: 7 d). Bypass with `force: true`.
  *
  * When a guard fires the function returns a `CreateProposalSkipped` record
  * instead of writing. Use {@link isProposalSkipped} to detect it.
  */
 export function createProposal(stashDir, input, ctx) {
-    // F-4 / #385: Validate source against the allow-list. Unknown values are
-    // warned (not rejected) for backward compatibility — extension callers
-    // that pass custom source strings must not break.
     if (!isValidProposalSource(input.source)) {
         warn(`[proposal] Unknown source "${input.source}". ` +
             `Expected one of: ${PROPOSAL_SOURCES.join(", ")}. ` +
             "Typos in source values produce unaggregatable accept-rate-per-source metrics.");
     }
     else if (isAutomatedProposalSource(input.source) && !input.sourceRun) {
-        // Advisory warning: automated sources should include sourceRun for PROV-DM
-        // traceability. This is not a hard error to avoid breaking existing callers.
         warn(`[proposal] Automated source "${input.source}" created a proposal without sourceRun. ` +
             "Add sourceRun to enable accept-rate-per-run aggregation (W3C PROV-DM).");
     }
@@ -212,17 +321,20 @@ export function createProposal(stashDir, input, ctx) {
     };
     let parsedRef;
     try {
-        parsedRef = parseAssetRef(input.ref);
+        parsedRef = parseRefInput(input.ref);
     }
     catch (err) {
         return rejectProposal("invalid_ref", `Invalid proposal ref "${input.ref}": ${err instanceof Error ? err.message : String(err)}`);
     }
-    if (!TYPE_DIRS[parsedRef.type]) {
-        return rejectProposal("unknown_type", `Unknown asset type "${parsedRef.type}" in proposal ref "${input.ref}". Known types: ${Object.keys(TYPE_DIRS).sort().join(", ")}.`);
+    if (!stashDirFor(parsedRef.type)) {
+        return rejectProposal("unknown_type", `Unknown asset type "${parsedRef.type}" in proposal ref "${input.ref}". Known types: ${[...placementTypes()].sort().join(", ")}.`);
     }
     if (!input.payload.content.trim()) {
         return rejectProposal("empty_content", `Proposal for "${input.ref}" has empty content.`);
     }
+    if (input.target && parsedRef.origin && input.target.source !== parsedRef.origin) {
+        return rejectProposal("invalid_ref", `Qualified proposal ref bundle "${parsedRef.origin}" conflicts with queue target "${input.target.source}".`);
+    }
     // Description check is only enforced for `consolidate` source — that's the
     // automated pipeline that historically produced proposals with missing or
     // malformed frontmatter, polluting the queue with hundreds of unusable
@@ -234,18 +346,73 @@ export function createProposal(stashDir, input, ctx) {
             return rejectProposal("missing_description", `Proposal for "${input.ref}" (source=consolidate) has empty or missing frontmatter description.`);
         }
     }
-    const normalizedRef = makeAssetRef(parsedRef.type, parsedRef.name, parsedRef.origin);
+    const proposalTarget = resolveCreateProposalTarget(stashDir, input.target, parsedRef.origin);
+    const normalizedRef = proposalDurableRef(parsedRef, proposalTarget);
+    const targetRoot = path.resolve(proposalTarget.root);
+    // WI-6.2: derive the FileChange[] envelope + mint-time beforeHash. The
+    // target is resolved against the proposal's OWN stash (a local snapshot —
+    // accept re-resolves the write target from config at apply time), and only
+    // the before-state's HASH is kept: the change's `before` body is a
+    // transaction-time capture that does not exist at mint time.
+    let targetRelPath;
+    let mintBeforeContent;
+    try {
+        const typeRoot = path.join(targetRoot, stashDirFor(parsedRef.type));
+        const targetAbs = assetPathForName(parsedRef.type, typeRoot, parsedRef.name);
+        targetRelPath = path.relative(targetRoot, targetAbs);
+        if (fs.existsSync(targetAbs))
+            mintBeforeContent = fs.readFileSync(targetAbs, "utf8");
+    }
+    catch {
+        // Resolution failure degrades to a best-effort create — never blocks the mint.
+        targetRelPath = path.join(stashDirFor(parsedRef.type), parsedRef.name);
+    }
+    const proposalContent = targetRelPath.toLowerCase().endsWith(".md")
+        ? ensureAkmMarkdownType(input.payload.content, parsedRef.type)
+        : input.payload.content;
+    const mintedChanges = [
+        {
+            path: targetRelPath,
+            after: proposalContent,
+            op: mintBeforeContent !== undefined ? "update" : "create",
+        },
+    ];
+    const mintedBeforeHash = mintBeforeContent !== undefined ? contentHash(mintBeforeContent) : undefined;
+    if (hasCanonicalProposalValidator(parsedRef.type)) {
+        const report = validateProposal({
+            id: "pending",
+            ref: normalizedRef,
+            status: "pending",
+            source: input.source,
+            createdAt: "",
+            updatedAt: "",
+            payload: { ...input.payload, content: proposalContent },
+            changes: mintedChanges,
+            proposedTarget: { source: proposalTarget.source, root: targetRoot },
+        });
+        if (!report.ok) {
+            return rejectProposal("invalid_canonical_structure", `Proposal for "${input.ref}" has invalid ${parsedRef.type} structure:\n${report.findings
+                .map((finding) => `[${finding.kind}] ${finding.message}`)
+                .join("\n")}`);
+        }
+    }
+    const fingerprint = computeProposalFingerprint({
+        ref: normalizedRef,
+        source: input.source,
+        ...(mintedBeforeHash !== undefined ? { beforeHash: mintedBeforeHash } : {}),
+        ...(input.modelId !== undefined ? { modelId: input.modelId } : {}),
+    });
     return withProposalsDb(stashDir, ctx, (db) => {
         return withImmediateTransaction(db, () => {
             if (!input.force) {
-                const skip = checkDedupAndCooldown(db, stashDir, normalizedRef, input, ctx);
+                const skip = checkFingerprintAndBackoff(db, stashDir, normalizedRef, input, fingerprint, ctx);
                 if (skip)
                     return skip;
             }
             const created = nowIso(ctx);
             // Phase 6A: validate confidence is a finite number in [0, 1]. Anything else
             // is dropped silently — we never store NaN, Infinity, or out-of-range values.
-            // Callers that mis-report confidence should not poison the auto-accept gate.
+            // Callers that mis-report confidence should not poison downstream readers.
             const sanitizedConfidence = typeof input.confidence === "number" &&
                 Number.isFinite(input.confidence) &&
                 input.confidence >= 0 &&
@@ -261,74 +428,98 @@ export function createProposal(stashDir, input, ctx) {
                 createdAt: created,
                 updatedAt: created,
                 payload: {
-                    content: input.payload.content,
+                    content: proposalContent,
                     ...(input.payload.frontmatter !== undefined ? { frontmatter: input.payload.frontmatter } : {}),
                 },
+                changes: mintedChanges,
+                proposedTarget: { source: proposalTarget.source, root: targetRoot },
+                ...(mintedBeforeHash !== undefined ? { beforeHash: mintedBeforeHash } : {}),
                 ...(sanitizedConfidence !== undefined ? { confidence: sanitizedConfidence } : {}),
                 // Attribution tagging: persist the eligibility lane so it survives to
                 // accept/reject/revert time. See EligibilitySource.
                 ...(input.eligibilitySource !== undefined ? { eligibilitySource: input.eligibilitySource } : {}),
             };
             upsertProposal(db, proposal, stashDir);
+            // Record the processed fingerprint (also on force — a forced enqueue is
+            // still "these inputs were processed"; future unforced identical inputs
+            // dedup against it).
+            recordProposalFingerprint(db, stashDir, fingerprint, normalizedRef, input, proposal.id, created);
             return proposal;
         });
     });
 }
+/** Version stamp of the input-fingerprint scheme; bump when terms change. */
+const PROPOSAL_FINGERPRINT_VERSION = 1;
 /**
- * Evaluate the F-2 dedup / cooldown guards against the store. Returns the
- * skip record when a guard fires, or undefined when the create may proceed.
+ * Compute the §23.6 input fingerprint for a proposal mint (+ the plan §4.5
+ * engine/model-id term). Terms, in order: scheme version, source (the recipe
+ * stand-in until Wave-2 recipes exist), target ref, target before-hash
+ * (empty for a create), evidence IDs/hashes (reserved — not yet modeled),
+ * guidance hashes (reserved), evaluator version (reserved), model id.
+ * Deliberately an INPUT fingerprint: the generated content is not a term —
+ * already-processed inputs skip re-processing regardless of what the model
+ * produced this time.
  */
-function checkDedupAndCooldown(db, stashDir, normalizedRef, input, ctx) {
-    const newHash = contentHash(input.payload.content);
+function computeProposalFingerprint(args) {
+    return contentHash([
+        `v${PROPOSAL_FINGERPRINT_VERSION}`,
+        args.source,
+        args.ref,
+        args.beforeHash ?? "",
+        "", // evidence IDs/hashes — reserved (Wave-2 recipes)
+        "", // guidance hashes — reserved
+        "", // evaluator version — reserved
+        args.modelId ?? "",
+    ].join("\0"));
+}
+/**
+ * Durably record a processed fingerprint (INSERT OR REPLACE — idempotent).
+ * `ref` must be the NORMALIZED ref — the same value the fingerprint was
+ * computed over — so future ref-keyed readers of the table never mismatch.
+ */
+function recordProposalFingerprint(db, stashDir, fingerprint, ref, input, proposalId, createdAt) {
+    db.prepare(`INSERT OR REPLACE INTO proposal_fingerprints
+       (stash_dir, fingerprint, ref, source, model_id, proposal_id, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`).run(stashDir, fingerprint, ref, input.source, input.modelId ?? "", proposalId, createdAt);
+}
+/**
+ * Evaluate the fingerprint + rejection-backoff guards. Returns the skip
+ * record when a guard fires, or undefined when the create may proceed.
+ */
+function checkFingerprintAndBackoff(db, stashDir, normalizedRef, input, fingerprint, ctx) {
     const nowMs = (ctx?.now ?? Date.now)();
-    const cooldownMs = cooldownMsForSource(input.source);
-    // Scan pending proposals for ref+source matches.
-    const pending = listStateProposals(db, { stashDir, ref: normalizedRef, status: "pending" }).filter((p) => p.source === input.source);
-    if (pending.length > 0) {
-        // Check for identical content hash first (silent skip).
-        const hashMatch = pending.find((p) => contentHash(p.payload.content) === newHash);
-        if (hashMatch) {
-            return {
-                skipped: true,
-                reason: "content_hash_match",
-                message: `Identical proposal for ${normalizedRef} already pending (id: ${hashMatch.id}).`,
-                existingProposalId: hashMatch.id,
-            };
-        }
-        // Duplicate pending for same ref+source (different content).
-        const firstPending = pending[0];
+    const backoffMs = cooldownMsForSource(input.source);
+    // §23.6: an already-processed fingerprint skips another model call's output
+    // unless explicitly forced. The row survives the proposal's lifecycle —
+    // identical inputs stay deduplicated until the target (before-hash), the
+    // model, or the scheme changes.
+    const existing = db
+        .prepare("SELECT proposal_id FROM proposal_fingerprints WHERE stash_dir = ? AND fingerprint = ?")
+        .get(stashDir, fingerprint);
+    if (existing) {
         return {
             skipped: true,
-            reason: "duplicate_pending",
-            message: `A pending proposal for ${normalizedRef} from source "${input.source}" already exists (id: ${firstPending?.id ?? "unknown"}). Pass force:true to enqueue alongside it.`,
-            existingProposalId: firstPending?.id,
+            reason: "fingerprint_match",
+            message: `These inputs were already processed into a proposal for ${normalizedRef} (fingerprint match). Pass force:true to enqueue anyway.`,
+            ...(existing.proposal_id ? { existingProposalId: existing.proposal_id } : {}),
         };
     }
-    // Check cooldown against recently rejected proposals.
+    // Rejection backoff (RETAINED cooldown semantics): a recent rejection for
+    // this ref+source suppresses new proposals until the window expires.
     const rejected = listStateProposals(db, { stashDir, ref: normalizedRef, status: "rejected" })
         .filter((p) => p.source === input.source)
         .sort((a, b) => new Date(b.updatedAt ?? 0).getTime() - new Date(a.updatedAt ?? 0).getTime());
     const mostRecent = rejected[0];
     if (mostRecent !== undefined) {
-        // Check content hash against recently rejected.
-        if (contentHash(mostRecent.payload.content) === newHash) {
-            return {
-                skipped: true,
-                reason: "content_hash_match",
-                message: `Identical proposal for ${normalizedRef} was already rejected (id: ${mostRecent.id}).`,
-                existingProposalId: mostRecent.id,
-            };
-        }
-        // Check cooldown window.
         const rejectedAt = new Date(mostRecent.updatedAt ?? 0).getTime();
-        if (nowMs - rejectedAt < cooldownMs) {
-            const cooldownDays = cooldownMs / MS_PER_DAY;
-            const remainingDays = Math.ceil((cooldownMs - (nowMs - rejectedAt)) / MS_PER_DAY);
+        if (nowMs - rejectedAt < backoffMs) {
+            const backoffDays = backoffMs / MS_PER_DAY;
+            const remainingDays = Math.ceil((backoffMs - (nowMs - rejectedAt)) / MS_PER_DAY);
             return {
                 skipped: true,
-                reason: "cooldown",
-                message: `Proposal for ${normalizedRef} from source "${input.source}" is in cooldown ` +
-                    `(${cooldownDays}d window, ~${remainingDays}d remaining). Pass force:true to bypass.`,
+                reason: "rejection_backoff",
+                message: `Proposal for ${normalizedRef} from source "${input.source}" is in rejection backoff ` +
+                    `(${backoffDays}d window, ~${remainingDays}d remaining). Pass force:true to bypass.`,
                 existingProposalId: mostRecent.id,
             };
         }
@@ -349,15 +540,21 @@ export function listProposals(stashDir, options = {}, ctx) {
             return [];
         }
         const status = options.includeArchive ? options.status : "pending";
+        // Short filters match by conceptId; qualified filters additionally retain
+        // bundle identity. Applied in JS because a short query does not equal the
+        // fully-qualified stored ref.
+        const wantRef = options.ref !== undefined ? filterRefIdentity(options.ref) : undefined;
         return listStateProposals(db, {
             stashDir,
             ...(status !== undefined ? { status } : {}),
-            ...(options.ref !== undefined ? { ref: options.ref } : {}),
         }).filter((p) => {
+            if (wantRef !== undefined && !proposalMatchesRef(p.ref, wantRef)) {
+                return false;
+            }
             if (!options.type)
                 return true;
             try {
-                return parseAssetRef(p.ref).type === options.type;
+                return parseRefInput(p.ref).type === options.type;
             }
             catch {
                 return false;
@@ -379,12 +576,31 @@ function requireProposal(db, stashDir, id) {
     }
     return proposal;
 }
+/**
+ * Lenient counterpart to {@link requireProposal} / {@link getProposal}, used
+ * ONLY on the terminal-status (reject/archive) read paths — `archiveProposal`
+ * and the reject-transaction machinery (`rejectProposalDurably`,
+ * `finalizeRejectTransaction`). Those paths must succeed even when the row's
+ * metadata fails strict decoding (see {@link proposalRowToProposalLenient});
+ * every other reader (accept, revert, show, list's pending branch) keeps
+ * strict decoding via `getProposal`/`requireProposal` unchanged.
+ */
+function requireProposalLenient(db, stashDir, id) {
+    const proposal = getStateProposalLenient(db, id, stashDir);
+    if (!proposal) {
+        throw new NotFoundError(`Proposal "${id}" not found.`, "FILE_NOT_FOUND");
+    }
+    return proposal;
+}
+function getProposalLenient(stashDir, id, ctx) {
+    return withProposalsDb(stashDir, ctx, (db) => requireProposalLenient(db, stashDir, id));
+}
 /**
  * Resolve a proposal by full UUID, UUID prefix, or asset ref.
  *
  * Resolution order:
  *   1. Exact UUID match (existing behaviour).
- *   2. Asset ref (contains `:`) — finds the most-recent pending proposal for
+ *   2. Asset ref (contains `/`) — finds the most-recent pending proposal for
  *      that ref; falls back to archived if nothing is pending.
  *   3. UUID prefix — matches any PENDING proposal whose id starts with the
  *      given string; throws if ambiguous.
@@ -395,14 +611,16 @@ export function resolveProposalId(stashDir, idOrRef, ctx) {
         const exact = getStateProposal(db, idOrRef, stashDir);
         if (exact)
             return exact;
-        // 2. Asset ref (e.g. "skill:akm-dream") — most recent pending, else most
-        // recent archived.
-        if (idOrRef.includes(":")) {
+        // 2. Asset ref — most recent pending, else most recent archived. Qualified
+        // refs retain bundle identity; short refs match by conceptId in this queue.
+        const wantRef = idOrRef.includes(":") || idOrRef.includes("/") ? filterRefIdentity(idOrRef) : undefined;
+        if (wantRef !== undefined) {
             const byRecency = (proposals) => proposals.sort((a, b) => new Date(b.createdAt ?? 0).getTime() - new Date(a.createdAt ?? 0).getTime())[0];
-            const pending = byRecency(listStateProposals(db, { stashDir, ref: idOrRef, status: "pending" }));
+            const forConcept = (status) => listStateProposals(db, { stashDir, ...(status !== undefined ? { status } : {}) }).filter((p) => proposalMatchesRef(p.ref, wantRef));
+            const pending = byRecency(forConcept("pending"));
             if (pending)
                 return pending;
-            const archived = byRecency(listStateProposals(db, { stashDir, ref: idOrRef }));
+            const archived = byRecency(forConcept());
             if (archived)
                 return archived;
             throw new NotFoundError(`No proposal found for ref "${idOrRef}".`, "FILE_NOT_FOUND");
@@ -417,15 +635,34 @@ export function resolveProposalId(stashDir, idOrRef, ctx) {
         throw new NotFoundError(`Proposal "${idOrRef}" not found.`, "FILE_NOT_FOUND");
     });
 }
+/**
+ * Resolve a reject target's id, tolerating a legacy row whose metadata fails
+ * strict decoding. `akm proposal reject` only needs the id — but
+ * {@link resolveProposalId}'s exact-UUID fast path decodes the FULL proposal
+ * just to hand it back, which throws on those rows before the
+ * terminal-status machinery (which reads leniently — see
+ * `requireProposalLenient`) ever runs. Falls back to `resolveProposalId`
+ * unchanged for ref / uuid-prefix inputs, where existing resolution
+ * (including its error semantics) is preserved.
+ */
+export function resolveProposalIdForReject(stashDir, idOrRef, ctx) {
+    const exact = withProposalsDb(stashDir, ctx, (db) => getStateProposalLenient(db, idOrRef, stashDir));
+    if (exact)
+        return exact.id;
+    return resolveProposalId(stashDir, idOrRef, ctx).id;
+}
 /**
  * Archive a proposal: flip its status to `accepted` / `rejected`, bump
  * `updatedAt`, and record the review block. Used by both accept and reject
  * paths so the live queue only contains pending entries.
  */
-export function archiveProposal(stashDir, id, status, reason, ctx) {
+export function archiveProposal(stashDir, id, status, reason, ctx, gateDecision) {
     return withProposalsDb(stashDir, ctx, (db) => {
         return withImmediateTransaction(db, () => {
-            const existing = requireProposal(db, stashDir, id);
+            // Lenient: archiving (accept OR reject) a legacy row with malformed
+            // changes/proposedTarget metadata must still be able to flip status —
+            // see requireProposalLenient.
+            const existing = requireProposalLenient(db, stashDir, id);
             if (existing.status !== "pending") {
                 throw new UsageError(`Proposal ${id} is not pending (current status: ${existing.status}). Only pending proposals can be ${status}.`, "INVALID_FLAG_VALUE");
             }
@@ -439,16 +676,18 @@ export function archiveProposal(stashDir, id, status, reason, ctx) {
                     ...(reason !== undefined ? { reason } : {}),
                     decidedAt,
                 },
+                ...(gateDecision ? { gateDecision: { ...gateDecision, decidedAt: gateDecision.decidedAt ?? decidedAt } } : {}),
             };
-            upsertProposal(db, updated, stashDir);
+            persistProposalUpdate(db, updated, stashDir);
             return updated;
         });
     });
 }
 /**
- * Record an automated gate's decision onto a proposal (#577).
+ * Record the drain/triage engine's decision onto a proposal (#577).
+ * Drain-owned audit machinery — the deterministic drain engine is the writer.
  *
- * Stamps `gateDecision` (decision / reason / confidence / thresholds) onto the
+ * Stamps `gateDecision` (decision / reason / measurement / thresholds) onto the
  * row so `akm proposal show` and `list` can explain why a proposal landed where
  * it did. The decision is metadata about the adjudication, so this does NOT
  * change `status` or bump `updatedAt` — a `deferred` proposal stays `pending`,
@@ -469,7 +708,7 @@ export function recordGateDecision(stashDir, id, decision, ctx) {
                 ...existing,
                 gateDecision: { ...decision, decidedAt: decision.decidedAt ?? nowIso(ctx) },
             };
-            upsertProposal(db, updated, stashDir);
+            persistProposalUpdate(db, updated, stashDir);
             return updated;
         });
     });
@@ -493,7 +732,7 @@ export function purgeOrphanProposals(stashDir, sourceDirs, ctx) {
     for (const p of reflectPending) {
         let parsed;
         try {
-            parsed = parseAssetRef(p.ref);
+            parsed = parseRefInput(p.ref);
         }
         catch {
             continue;
@@ -501,12 +740,12 @@ export function purgeOrphanProposals(stashDir, sourceDirs, ctx) {
         // Lessons are new-asset proposals by definition — they cannot be orphaned.
         if (parsed.type === "lesson")
             continue;
-        const spec = TYPE_DIRS[parsed.type];
+        const spec = stashDirFor(parsed.type);
         if (!spec)
             continue;
         const exists = sourceDirs.some((root) => {
             const typeRoot = path.join(root, spec);
-            const candidate = resolveAssetPathFromName(parsed.type, typeRoot, parsed.name);
+            const candidate = assetPathForName(parsed.type, typeRoot, parsed.name);
             return fs.existsSync(candidate);
         });
         if (!exists) {
@@ -596,6 +835,15 @@ export function expireStaleProposals(stashDir, config, ctx) {
             warn(`[proposals] expireStaleProposals: failed to expire ${p.id}: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    // Prune fingerprint rows past the same retention window (best-effort):
+    // ISO created_at strings compare lexicographically.
+    try {
+        const cutoffIso = new Date(nowMs - retentionMs).toISOString();
+        withProposalsDb(stashDir, ctx, (db) => db.prepare("DELETE FROM proposal_fingerprints WHERE stash_dir = ? AND created_at < ?").run(stashDir, cutoffIso));
+    }
+    catch (err) {
+        warn(`[proposals] expireStaleProposals: fingerprint prune failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
     return {
         checked: pending.length,
         expired: expiredProposals.length,
@@ -604,6 +852,676 @@ export function expireStaleProposals(stashDir, config, ctx) {
         expiredProposals,
     };
 }
+const PROPOSAL_TXN_KIND = "proposal";
+const PROPOSAL_TXN_PHASES = [
+    "prepared",
+    "asset-published",
+    "proposal-persisted",
+    "index-finalized",
+    "event-finalized",
+    "committed",
+];
+/** TEST-ONLY crash-window hook used by subprocess recovery tests. */
+export function _setProposalMutationHookForTests(hook) {
+    _setTxnMutationHookForTests(hook);
+}
+function proposalHash(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+function proposalFileHash(filePath) {
+    return proposalHash(fs.readFileSync(filePath));
+}
+function sameProposalFile(left, right) {
+    try {
+        const leftStat = fs.statSync(left);
+        const rightStat = fs.statSync(right);
+        return leftStat.dev === rightStat.dev && leftStat.ino === rightStat.ino;
+    }
+    catch {
+        return false;
+    }
+}
+function cleanupProposalPublication(p) {
+    for (const filePath of [p.publishPath, p.displacedPath]) {
+        try {
+            fs.rmSync(filePath, { force: true });
+        }
+        catch (error) {
+            warn(`[proposals] transaction publication cleanup failed at ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    fsyncTxnDir(path.dirname(p.assetPath));
+}
+function rollbackPreparedProposalTransaction(txn) {
+    const p = txn.journal.payload;
+    const currentHash = fs.existsSync(p.assetPath) ? proposalFileHash(p.assetPath) : null;
+    if (!fs.existsSync(p.displacedPath)) {
+        if (p.originalHash === null) {
+            if (currentHash === p.publishedHash && sameProposalFile(p.assetPath, p.publishPath)) {
+                fs.unlinkSync(p.assetPath);
+            }
+            else if (currentHash !== null) {
+                throw new Error(`Cannot roll back proposal transaction: target was created externally.`);
+            }
+        }
+        else if (currentHash !== p.originalHash) {
+            throw new Error(`Cannot roll back proposal transaction: ${p.assetPath} diverged.`);
+        }
+        cleanupProposalPublication(p);
+        return;
+    }
+    if (currentHash === p.publishedHash)
+        fs.unlinkSync(p.assetPath);
+    else if (currentHash !== null && currentHash !== p.originalHash) {
+        throw new Error(`Cannot roll back proposal transaction: ${p.assetPath} diverged.`);
+    }
+    if (fs.existsSync(p.displacedPath)) {
+        if (fs.existsSync(p.assetPath)) {
+            throw new Error(`Cannot restore proposal backup: ${p.assetPath} is occupied.`);
+        }
+        fs.linkSync(p.displacedPath, p.assetPath);
+    }
+    cleanupProposalPublication(p);
+}
+function validatePublishedProposal(p) {
+    if (!fs.existsSync(p.assetPath) || proposalFileHash(p.assetPath) !== p.publishedHash) {
+        throw new Error(`Cannot recover proposal ${p.proposalId}: published asset diverged.`);
+    }
+}
+function persistProposalTransactionState(txn, proposal, ctx) {
+    const p = txn.journal.payload;
+    const decidedAt = txn.journal.decidedAt;
+    const backupContent = p.backupPath ? fs.readFileSync(p.backupPath, "utf8") : undefined;
+    const publishedContent = fs.readFileSync(p.contentPath, "utf8");
+    return withProposalsDb(p.stashDir, ctx, (db) => withImmediateTransaction(db, () => {
+        const current = requireProposal(db, p.stashDir, p.proposalId);
+        if (p.operation === "accept") {
+            if (current.status === "accepted") {
+                if (current.acceptedTarget?.contentHash !== p.publishedHash) {
+                    throw new Error(`Accepted proposal ${p.proposalId} does not match its recovery journal.`);
+                }
+                return current;
+            }
+            if (current.status !== "pending") {
+                throw new Error(`Proposal ${p.proposalId} changed status during acceptance (${current.status}).`);
+            }
+            const persistedProposal = proposal.changes.length > 0 && proposal.changes.every((change) => change.path.length > 0)
+                ? withProposalContent(proposal, publishedContent)
+                : {
+                    ...proposal,
+                    payload: { ...proposal.payload, content: publishedContent },
+                    changes: [
+                        {
+                            path: path.relative(txn.journal.root, p.assetPath),
+                            op: p.originalHash === null ? "create" : "update",
+                            after: publishedContent,
+                        },
+                    ],
+                    proposedTarget: { source: p.targetSource, root: txn.journal.root },
+                };
+            const accepted = {
+                ...persistedProposal,
+                status: "accepted",
+                updatedAt: decidedAt,
+                review: { outcome: "accepted", decidedAt },
+                acceptedTarget: {
+                    source: p.targetSource,
+                    root: txn.journal.root,
+                    path: p.assetPath,
+                    contentHash: p.publishedHash,
+                },
+                ...(p.gateDecision
+                    ? { gateDecision: { ...p.gateDecision, decidedAt: p.gateDecision.decidedAt ?? decidedAt } }
+                    : {}),
+                ...(backupContent !== undefined ? { backupContent } : {}),
+            };
+            upsertProposal(db, accepted, p.stashDir);
+            return accepted;
+        }
+        if (current.status === "reverted")
+            return current;
+        if (current.status !== "accepted") {
+            throw new Error(`Proposal ${p.proposalId} changed status during reversion (${current.status}).`);
+        }
+        const reverted = {
+            ...current,
+            status: "reverted",
+            updatedAt: decidedAt,
+            review: {
+                outcome: "rejected",
+                reason: "reverted: prior content restored from backup",
+                decidedAt,
+            },
+        };
+        upsertProposal(db, reverted, p.stashDir);
+        return reverted;
+    }));
+}
+function persistProposalEvent(txn, proposal, ctx) {
+    const p = txn.journal.payload;
+    withProposalsDb(p.stashDir, ctx, (db) => withImmediateTransaction(db, () => {
+        const metadata = {
+            proposalId: proposal.id,
+            source: proposal.source,
+            ...(proposal.sourceRun !== undefined ? { sourceRun: proposal.sourceRun } : {}),
+            assetPath: p.assetPath,
+            ...(proposal.eligibilitySource !== undefined ? { eligibilitySource: proposal.eligibilitySource } : {}),
+            ...(p.eventMetadata ?? {}),
+            proposalTransactionId: txn.journal.transactionId,
+        };
+        insertEventOnce(db, {
+            eventType: p.operation === "accept" ? "promoted" : "proposal_reverted",
+            ts: txn.journal.decidedAt,
+            ref: p.ref,
+            metadata,
+            idempotencyKey: txn.journal.transactionId,
+        });
+    }));
+}
+async function finalizeProposalTransaction(txn, target, proposal, ctx) {
+    const p = txn.journal.payload;
+    validatePublishedProposal(p);
+    cleanupProposalPublication(p);
+    if (txn.journal.phase === "asset-published") {
+        const commitRoot = target.source.repoPath ?? target.source.path;
+        const commitPath = path.relative(commitRoot, p.assetPath).replaceAll(path.sep, "/");
+        publishWriteTargetTransaction(target, p.gitPublication, {
+            transactionId: txn.journal.transactionId,
+            message: `${p.operation === "accept" ? "Update" : "Revert"} ${p.ref}`,
+            paths: [commitPath],
+            snapshots: p.gitSnapshots ?? {},
+            onCommitRecorded: (commit) => {
+                // biome-ignore lint/style/noNonNullAssertion: publishWriteTargetTransaction throws when absent
+                const publication = p.gitPublication;
+                if (publication.commit !== commit) {
+                    publication.commit = commit;
+                    advanceTxn(txn, "asset-published");
+                }
+            },
+        });
+        persistProposalTransactionState(txn, proposal, ctx);
+        advanceTxn(txn, "proposal-persisted");
+    }
+    let accepted = getProposal(p.stashDir, p.proposalId, ctx);
+    if (txn.journal.phase === "proposal-persisted") {
+        if (!(await indexWrittenAssets(txn.journal.root, [p.assetPath], { bundleId: target.source.name }))) {
+            throw new Error(`Proposal ${p.proposalId} index finalization failed.`);
+        }
+        advanceTxn(txn, "index-finalized");
+    }
+    if (txn.journal.phase === "index-finalized") {
+        accepted = getProposal(p.stashDir, p.proposalId, ctx);
+        persistProposalEvent(txn, accepted, ctx);
+        txnMutationHook("event-persisted");
+        advanceTxn(txn, "event-finalized");
+    }
+    if (txn.journal.phase === "event-finalized")
+        advanceTxn(txn, "committed");
+    return accepted;
+}
+/**
+ * Kind-level safety fence for a `proposal` journal, run before any recovery
+ * action. The engine fences root binding and the uniform changes[] separately.
+ */
+function fenceProposalTxnJournal(journal, txnDir, root) {
+    const p = journal.payload;
+    const refIdentity = proposalRefIdentity(p.ref);
+    if (!["accept", "revert"].includes(p.operation) ||
+        !p.targetSource ||
+        !p.targetKind ||
+        refIdentity?.bundle === undefined ||
+        !isWithin(p.assetPath, root) ||
+        ![p.contentPath, p.backupPath]
+            .filter((candidate) => candidate !== null)
+            .every((candidate) => isWithin(candidate, txnDir)) ||
+        ![p.publishPath, p.displacedPath].every((candidate) => isWithin(candidate, root) && path.dirname(candidate) === path.dirname(p.assetPath))) {
+        throw new Error(`Refusing unsafe proposal transaction journal at ${path.join(txnDir, "journal.json")}.`);
+    }
+}
+function resolveProposalRecoveryTarget(config, journal) {
+    let target;
+    try {
+        target = resolveBundleWriteTarget(config, journal.payload.targetSource);
+    }
+    catch {
+        throw new UsageError(`Proposal transaction ${journal.transactionId} target is no longer configured.`, "INVALID_FLAG_VALUE");
+    }
+    const bundleId = canonicalBundleIdForTarget(config, target);
+    return { ...target, source: { ...target.source, name: bundleId } };
+}
+async function recoverProposalTransactions(target, stashDir, ctx) {
+    const completed = new Map();
+    const nsDir = txnNamespaceDir(target.source.path);
+    if (!fs.existsSync(nsDir))
+        return completed;
+    for (const entry of fs.readdirSync(nsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const transactionDir = path.join(nsDir, entry.name);
+        const journalPath = path.join(transactionDir, "journal.json");
+        if (!fs.existsSync(journalPath)) {
+            // Journal-less dirs may be a SIBLING kind's beginTxn window (shared
+            // per-root namespace) — sweep only when demonstrably stale.
+            sweepJournallessTxnDir(transactionDir);
+            continue;
+        }
+        const journal = JSON.parse(fs.readFileSync(journalPath, "utf8"));
+        if (journal.kind !== PROPOSAL_TXN_KIND)
+            continue;
+        if (path.resolve(journal.payload.stashDir) !== path.resolve(stashDir))
+            continue;
+        if (journal.version !== 1 ||
+            canonicalTxnRoot(journal.root) !== canonicalTxnRoot(target.source.path) ||
+            journal.payload.targetSource !== target.source.name ||
+            journal.payload.targetKind !== target.source.kind) {
+            throw new Error(`Refusing unsafe proposal transaction journal at ${journalPath}.`);
+        }
+        fenceProposalTxnJournal(journal, transactionDir, target.source.path);
+        const txn = { journal, journalPath, dir: transactionDir };
+        if (journal.phase === "prepared") {
+            rollbackPreparedProposalTransaction(txn);
+        }
+        else if (journal.phase !== "committed") {
+            const proposal = getProposal(stashDir, journal.payload.proposalId, ctx);
+            completed.set(journal.payload.proposalId, await finalizeProposalTransaction(txn, target, proposal, ctx));
+        }
+        else {
+            completed.set(journal.payload.proposalId, getProposal(stashDir, journal.payload.proposalId, ctx));
+        }
+        cleanupProposalPublication(journal.payload);
+        cleanupTxn(transactionDir);
+    }
+    return completed;
+}
+export async function recoverProposalTransactionsForStash(stashDir, config, ctx, proposalId) {
+    const completed = new Map();
+    const matches = listTxnJournals((j) => j.kind === PROPOSAL_TXN_KIND &&
+        path.resolve(j.payload.stashDir) === path.resolve(stashDir) &&
+        (proposalId === undefined || j.payload.proposalId === proposalId));
+    const irreversible = matches.filter((journal) => journal.phase !== "prepared" && journal.phase !== "committed");
+    if (proposalId !== undefined && irreversible.length > 1) {
+        throw new Error(`Conflicting durable proposal transactions exist for ${proposalId}; refusing recovery.`);
+    }
+    const recoveredRoots = new Set();
+    for (const journal of matches) {
+        let target = resolveProposalRecoveryTarget(config, journal);
+        const requiresGitPublication = matches.some((candidate) => candidate.phase === "asset-published" && canonicalTxnRoot(candidate.root) === canonicalTxnRoot(journal.root));
+        if (requiresGitPublication)
+            target = prepareWriteTargetForMutation(target, { allowAhead: true });
+        if (canonicalTxnRoot(target.source.path) !== canonicalTxnRoot(journal.root) ||
+            journal.payload.targetKind !== target.source.kind) {
+            throw new Error(`Proposal transaction ${journal.transactionId} is bound to a different target root.`);
+        }
+        const key = path.resolve(target.source.path);
+        if (recoveredRoots.has(key))
+            continue;
+        const recovered = await recoverProposalTransactions(target, stashDir, ctx);
+        for (const [id, proposal] of recovered)
+            completed.set(id, proposal);
+        recoveredRoots.add(key);
+    }
+    return completed;
+}
+const REJECT_TXN_KIND = "proposal-reject";
+const REJECT_TXN_PHASES = ["prepared", "state-persisted", "event-finalized", "committed"];
+function finalizeRejectTransaction(txn, ctx) {
+    const p = txn.journal.payload;
+    const decidedAt = txn.journal.decidedAt;
+    // Lenient: a reject transaction must run to completion even on a legacy
+    // row whose metadata fails strict decoding — see requireProposalLenient.
+    let proposal = getProposalLenient(p.stashDir, p.proposalId, ctx);
+    if (txn.journal.phase === "prepared") {
+        if (proposal.status === "pending") {
+            proposal = archiveProposal(p.stashDir, p.proposalId, "rejected", p.reason, { ...ctx, now: () => Date.parse(decidedAt) }, p.gateDecision);
+        }
+        else if (proposal.status !== "rejected") {
+            throw new Error(`Proposal ${p.proposalId} changed status during rejection (${proposal.status}).`);
+        }
+        advanceTxn(txn, "state-persisted");
+        txnMutationHook("reject-state-persisted");
+    }
+    if (txn.journal.phase === "state-persisted") {
+        proposal = getProposalLenient(p.stashDir, p.proposalId, ctx);
+        const eventRef = proposal.ref;
+        const eventMeta = {
+            proposalId: proposal.id,
+            source: proposal.source,
+            ...(proposal.sourceRun !== undefined ? { sourceRun: proposal.sourceRun } : {}),
+            ...(p.reason !== undefined ? { reason: p.reason } : {}),
+            proposalTransactionId: txn.journal.transactionId,
+        };
+        withProposalsDb(p.stashDir, ctx, (db) => withImmediateTransaction(db, () => {
+            insertEventOnce(db, {
+                eventType: "rejected",
+                ts: decidedAt,
+                ref: eventRef,
+                metadata: eventMeta,
+                idempotencyKey: txn.journal.transactionId,
+            });
+        }));
+        txnMutationHook("reject-event-persisted");
+        advanceTxn(txn, "event-finalized");
+    }
+    if (txn.journal.phase === "event-finalized")
+        advanceTxn(txn, "committed");
+    return proposal;
+}
+function recoverRejectTransaction(stashDir, proposalId, ctx) {
+    const nsDir = txnNamespaceDir(stashDir);
+    if (!fs.existsSync(nsDir))
+        return undefined;
+    for (const entry of fs.readdirSync(nsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const transactionDir = path.join(nsDir, entry.name);
+        const journalPath = path.join(transactionDir, "journal.json");
+        if (!fs.existsSync(journalPath))
+            continue;
+        const journal = JSON.parse(fs.readFileSync(journalPath, "utf8"));
+        if (journal.kind !== REJECT_TXN_KIND)
+            continue;
+        if (journal.payload.proposalId !== proposalId)
+            continue;
+        if (journal.version !== 1 || path.resolve(journal.payload.stashDir) !== path.resolve(stashDir)) {
+            throw new Error(`Refusing unsafe proposal rejection journal at ${journalPath}.`);
+        }
+        const proposal = finalizeRejectTransaction({ journal, journalPath, dir: transactionDir }, ctx);
+        cleanupTxn(transactionDir);
+        return proposal;
+    }
+    return undefined;
+}
+export function rejectProposalDurably(stashDir, proposalId, reason, ctx, gateDecision) {
+    const recovered = recoverRejectTransaction(stashDir, proposalId, ctx);
+    if (recovered)
+        return recovered;
+    // Lenient: see requireProposalLenient — the reject decision itself must not
+    // be blocked by a legacy row's malformed changes/proposedTarget metadata.
+    const proposal = getProposalLenient(stashDir, proposalId, ctx);
+    if (proposal.status !== "pending") {
+        throw new UsageError(`Proposal ${proposalId} is not pending (current status: ${proposal.status}). Only pending proposals can be rejected.`, "INVALID_FLAG_VALUE");
+    }
+    const txn = beginTxn({
+        kind: REJECT_TXN_KIND,
+        root: stashDir,
+        changes: [],
+        payload: {
+            proposalId,
+            stashDir,
+            ...(reason !== undefined ? { reason } : {}),
+            ...(gateDecision ? { gateDecision } : {}),
+        },
+        decidedAt: nowIso(ctx),
+    });
+    const rejected = finalizeRejectTransaction(txn, ctx);
+    cleanupTxn(txn.dir);
+    return rejected;
+}
+function prepareProposalTransaction(stashDir, target, proposal, ref, content, options, ctx) {
+    if (options.operation === "accept")
+        assertAkmAssetWrite(target.source);
+    const assetPath = resolveAssetFilePathSafe(target.source, ref);
+    if (!assetPath)
+        throw new Error(`Cannot resolve proposal target ${proposal.ref}.`);
+    fs.mkdirSync(path.dirname(assetPath), { recursive: true });
+    const normalized = content.endsWith("\n") ? content : `${content}\n`;
+    const publishedHash = proposalHash(normalized);
+    // Mint the id first: the payload embeds paths under the transaction dir,
+    // and the initial `prepared` journal must be written exactly ONCE with its
+    // final contents (crash runners intercept the first rename per phase).
+    const transactionId = mintTxnId();
+    const gitPublication = captureGitPublication(target);
+    const transactionDir = txnDirFor(target.source.path, transactionId);
+    fs.mkdirSync(transactionDir, { recursive: true, mode: 0o700 });
+    const contentPath = path.join(transactionDir, "published-content");
+    const publishPath = path.join(path.dirname(assetPath), `.akm-proposal-${transactionId}.publish`);
+    const displacedPath = path.join(path.dirname(assetPath), `.akm-proposal-${transactionId}.displaced`);
+    fs.writeFileSync(contentPath, normalized, { encoding: "utf8", mode: 0o600 });
+    fsyncTxnFile(contentPath);
+    let persistedBackupPath = null;
+    if (options.backup) {
+        const backupPath = path.join(transactionDir, "backup-content");
+        fs.writeFileSync(backupPath, options.backup, { mode: 0o600 });
+        fsyncTxnFile(backupPath);
+        persistedBackupPath = backupPath;
+    }
+    const txn = beginTxn({
+        kind: PROPOSAL_TXN_KIND,
+        root: target.source.path,
+        transactionId,
+        changes: [
+            {
+                path: assetPath,
+                op: options.originalHash === null ? "create" : "update",
+                beforeHash: options.originalHash,
+                afterHash: publishedHash,
+            },
+        ],
+        payload: {
+            operation: options.operation,
+            proposalId: proposal.id,
+            stashDir,
+            targetSource: target.source.name,
+            targetKind: target.source.kind,
+            assetPath,
+            ref: proposal.ref,
+            contentPath,
+            publishPath,
+            displacedPath,
+            backupPath: persistedBackupPath,
+            originalHash: options.originalHash,
+            publishedHash,
+            ...(gitPublication ? { gitPublication } : {}),
+            ...(options.eventMetadata ? { eventMetadata: options.eventMetadata } : {}),
+            ...(options.gateDecision ? { gateDecision: options.gateDecision } : {}),
+        },
+        decidedAt: nowIso(ctx),
+    });
+    try {
+        const mode = fs.existsSync(assetPath) ? fs.statSync(assetPath).mode & 0o777 : 0o644;
+        fs.writeFileSync(publishPath, normalized, { encoding: "utf8", flag: "wx", mode });
+        fsyncTxnFile(publishPath);
+        fsyncTxnDir(path.dirname(assetPath));
+    }
+    catch (error) {
+        rollbackPreparedProposalTransaction(txn);
+        cleanupTxn(txn.dir);
+        throw error;
+    }
+    return txn;
+}
+function publishProposalAsset(txn, target) {
+    const p = txn.journal.payload;
+    try {
+        if (p.originalHash !== null) {
+            fs.renameSync(p.assetPath, p.displacedPath);
+            if (proposalFileHash(p.displacedPath) !== p.originalHash) {
+                fs.renameSync(p.displacedPath, p.assetPath);
+                throw new Error(`Proposal target changed while its backup was being acquired.`);
+            }
+        }
+        fs.linkSync(p.publishPath, p.assetPath);
+        fsyncTxnDir(path.dirname(p.assetPath));
+        const snapshot = captureWriteTargetPathSnapshot(target, p.assetPath);
+        if (snapshot)
+            p.gitSnapshots = { [snapshot.path]: snapshot.state };
+        advanceTxn(txn, "asset-published");
+    }
+    catch (error) {
+        rollbackPreparedProposalTransaction(txn);
+        cleanupTxn(txn.dir);
+        throw error;
+    }
+}
+function resolveRecordedProposalTarget(config, proposalId, binding, explicitTarget) {
+    let target;
+    try {
+        target = explicitTarget
+            ? resolveWriteTarget(config, explicitTarget)
+            : resolveBundleWriteTarget(config, binding.source);
+    }
+    catch {
+        throw new UsageError(`Proposal ${proposalId} is bound to target "${binding.source}" at ${binding.root}, but that writable target is no longer configured.`, "INVALID_FLAG_VALUE");
+    }
+    const targetBundleId = canonicalBundleIdForTarget(config, target);
+    if (targetBundleId !== binding.source || path.resolve(target.source.path) !== path.resolve(binding.root)) {
+        throw new UsageError(`Proposal ${proposalId} is bound to target "${binding.source}" at ${binding.root}; ` +
+            `--target "${explicitTarget}" resolves to "${targetBundleId}" at ${target.source.path}.`, "INVALID_FLAG_VALUE");
+    }
+    return { ...target, source: { ...target.source, name: targetBundleId } };
+}
+function resolveProposalWriteTarget(config, proposal, explicitTarget, queueTarget) {
+    if (!proposal.proposedTarget) {
+        const identity = proposalRefIdentity(proposal.ref);
+        if (!identity)
+            throw new UsageError(`Proposal ${proposal.id} has an invalid ref.`, "INVALID_PROPOSAL");
+        if (identity.bundle !== undefined) {
+            const target = resolveBundleWriteTarget(config, identity.bundle);
+            const targetBundleId = canonicalBundleIdForTarget(config, target);
+            if (explicitTarget !== undefined) {
+                const explicit = resolveWriteTarget(config, explicitTarget);
+                if (canonicalBundleIdForTarget(config, explicit) !== identity.bundle) {
+                    throw new UsageError(`Proposal ${proposal.id} ref is bound to bundle "${identity.bundle}", which conflicts with --target "${explicitTarget}".`, "INVALID_FLAG_VALUE");
+                }
+            }
+            if (queueTarget && canonicalBundleIdForTarget(config, queueTarget) !== identity.bundle) {
+                throw new UsageError(`Proposal ${proposal.id} is bound to a different queue target.`, "INVALID_FLAG_VALUE");
+            }
+            return { ...target, source: { ...target.source, name: targetBundleId } };
+        }
+        const target = explicitTarget ? resolveWriteTarget(config, explicitTarget) : queueTarget;
+        if (!target) {
+            throw new UsageError(`Unbound short proposal ${proposal.id} requires an explicit --target or authenticated --queue context.`, "INVALID_PROPOSAL");
+        }
+        const targetBundleId = canonicalBundleIdForTarget(config, target);
+        return { ...target, source: { ...target.source, name: targetBundleId } };
+    }
+    if (queueTarget && explicitTarget === undefined) {
+        const queueBundleId = canonicalBundleIdForTarget(config, queueTarget);
+        if (queueBundleId !== proposal.proposedTarget.source ||
+            path.resolve(queueTarget.source.path) !== path.resolve(proposal.proposedTarget.root)) {
+            throw new UsageError(`Proposal ${proposal.id} is bound to a different queue target.`, "INVALID_FLAG_VALUE");
+        }
+    }
+    return resolveRecordedProposalTarget(config, proposal.id, proposal.proposedTarget, explicitTarget);
+}
+// ── D2 (#730) — OKF v0.2 provenance stamping on promotion ───────────────────
+//
+// The proposals system already tracks exactly what OKF v0.2 wants on disk —
+// `source`/`sourceRun` (PROV-DM modeled, `proposal-types.ts` §80-120),
+// `gateDecision` (`:200-237`), `review` (`:170-174`) — but none of it leaves
+// state.db. This section projects it onto the written asset's frontmatter at
+// promotion time, AKM-native assets only (an OKF-adapter target never reaches
+// this function — `assertAkmAssetWrite` rejects it earlier in
+// `promoteProposalWithLease`, before any of this runs).
+//
+// Two DISTINCT actors, deliberately not conflated (documented judgment call —
+// see the PR body for the alternative considered and rejected):
+//   - `generated.by` answers "what produced the CONTENT" — keyed on
+//     `isAutomatedProposalSource(proposal.source)`: an automated pipeline
+//     (reflect/distill/consolidate/extract/improve/schema-repair) stamps
+//     `akm/<pkgVersion>`; a human-initiated source (propose/remember/import)
+//     or the semi-automated `feedback` source stamps `human:<actorId>`.
+//   - `verified[0].by` answers "what accepted/reviewed THIS promotion" —
+//     keyed on whether a `gateDecision` was supplied to THIS call: present
+//     (the automated drain/triage path decided) stamps `akm/<pkgVersion>`;
+//     absent (a human explicitly ran `akm proposal accept`) stamps
+//     `human:<actorId>`. Every promotion reaches this function via exactly
+//     one of those two paths, so `verified` is always stamped — there is no
+//     third, unreviewed path to disk.
+/** Resolve the `human:<id>` actor id — the OS account, the least-surprising stand-in for "the human at this keyboard" in a system with no multi-user identity. */
+function resolveActorId(ctx) {
+    if (ctx?.actorId)
+        return ctx.actorId();
+    try {
+        const username = os.userInfo().username?.trim();
+        return username ? username : "local";
+    }
+    catch {
+        return "local";
+    }
+}
+/** `generated.by` — keyed on the SOURCE that produced the content (see file-header note above). */
+function generatedByActor(proposal, ctx) {
+    return isAutomatedProposalSource(proposal.source) ? `akm/${pkgVersion}` : `human:${resolveActorId(ctx)}`;
+}
+/** `verified[0].by` — keyed on whether THIS promotion was gated (automated) or a direct human accept (see file-header note above). */
+function verifiedByActor(gateDecision, ctx) {
+    return gateDecision !== undefined ? `akm/${pkgVersion}` : `human:${resolveActorId(ctx)}`;
+}
+/** True for a plain (non-null, non-array) object. */
+function isPlainRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Stamp OKF v0.2 provenance onto ONE promoted asset's frontmatter (D2.1/D2.2/
+ * D2.3), in the **hybrid** on-disk shape settled by the #730 review:
+ *
+ * - `generated: {by, at}` and `verified: [{by, at}]` are written **bare at the
+ *   top level**, exactly as OKF v0.2 spells them (SPEC §5.2/§5.3). Neither key
+ *   has any pre-existing AKM consumer, so spelling them the spec's way costs
+ *   nothing and makes `okf-support.md`'s "AKM Markdown is an OKF-compatible
+ *   superset" positioning actually true for trust metadata: a third-party OKF
+ *   v0.2 reader pointed at an AKM stash sees conformant provenance.
+ * - `sources` stays namespaced under `provenance:`, because a bare top-level
+ *   `sources:` genuinely collides with the pre-existing AKM-native wiki
+ *   citation-**string** convention
+ *   (`indexer/passes/metadata.ts#applyWikiFrontmatter`, which silently drops
+ *   non-strings) on a promoted wiki page.
+ *
+ * The read side back into `IndexDocument.provenance` is
+ * `metadata.ts#applyProvenanceFrontmatter` (which accepts both this shape and
+ * the older fully-nested one), carried through `akm-adapter.ts`'s
+ * `DOCUMENT_JSON_CARRIED_FIELDS` (D2.4).
+ *
+ * A no-op frontmatter mutation preserves the existing frontmatter block's raw
+ * body bytes (mirrors `frontmatter.ts#mutateFrontmatter`'s documented
+ * contract) rather than reshaping via `assembleAsset`, which would strip
+ * leading body blank lines / force a trailing newline. A file with no
+ * frontmatter block at all (non-conformant input) gains one via
+ * `assembleAsset`, exactly as any other first-frontmatter write would.
+ */
+function stampProposalProvenance(content, proposal, gateDecision, ctx, nowIsoStr) {
+    const parsed = parseFrontmatter(content);
+    const fm = { ...parsed.data };
+    const existingProvenance = isPlainRecord(fm.provenance) ? fm.provenance : {};
+    // Bare `generated:` — OKF v0.2's replacement for `timestamp` (SPEC §13).
+    fm.generated = { by: generatedByActor(proposal, ctx), at: nowIsoStr };
+    // Bare `verified:` — append, so independent confirmations accumulate rather
+    // than the newest overwriting the record. Both the bare list and the older
+    // nested spelling are absorbed, so a re-promotion never loses history.
+    const priorVerified = Array.isArray(fm.verified)
+        ? fm.verified
+        : Array.isArray(existingProvenance.verified)
+            ? existingProvenance.verified
+            : [];
+    fm.verified = [
+        ...priorVerified,
+        { by: verifiedByActor(gateDecision, ctx), at: gateDecision?.decidedAt ?? nowIsoStr },
+    ];
+    // `sources` alone stays namespaced — bare `sources:` is the wiki
+    // citation-string convention. Drop the nested provenance block entirely when
+    // it would otherwise be empty, so unrelated assets gain no dead key.
+    const provenance = { ...existingProvenance };
+    delete provenance.generatedBy;
+    delete provenance.generatedAt;
+    delete provenance.verified;
+    const evidenceSources = fm.evidenceSources;
+    if (Array.isArray(evidenceSources)) {
+        const sources = evidenceSources
+            .filter((s) => typeof s === "string" && s.trim().length > 0)
+            .map((resource) => ({ resource: resource.trim() }));
+        if (sources.length > 0)
+            provenance.sources = sources;
+    }
+    if (Object.keys(provenance).length > 0)
+        fm.provenance = provenance;
+    else
+        delete fm.provenance;
+    return parsed.frontmatter !== null
+        ? `---\n${serializeFrontmatter(fm)}\n---\n${parsed.content}`
+        : assembleAsset(fm, parsed.content);
+}
 /**
  * Validate a proposal, then promote it through the canonical
  * {@link writeAssetToSource} dispatch (the single place that branches on
@@ -617,20 +1535,53 @@ export function expireStaleProposals(stashDir, config, ctx) {
  * Genuinely-new assets carry no backup.
  */
 export async function promoteProposal(stashDir, config, id, options = {}, ctx) {
-    const proposal = getProposal(stashDir, id, ctx);
-    if (proposal.status !== "pending") {
-        throw new UsageError(`Proposal ${id} is not pending (current status: ${proposal.status}). Only pending proposals can be accepted.`, "INVALID_FLAG_VALUE");
+    return withAssetMutationLease("proposal-accept", () => promoteProposalWithLease(stashDir, config, id, options, ctx));
+}
+function promotionLintBlockers(raw, assetPath, targetRoot, refType, config) {
+    let data;
+    let body;
+    let frontmatter;
+    if (refType === "task") {
+        try {
+            const parsed = parseYaml(raw);
+            data = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+        }
+        catch {
+            data = {};
+        }
+        body = raw;
+        frontmatter = null;
+    }
+    else {
+        ({ data, content: body, frontmatter } = parseFrontmatter(raw));
     }
+    const resolvedRoot = path.resolve(targetRoot);
+    const extraStashRoots = resolveSourceEntries(targetRoot, config)
+        .map((source) => source.path)
+        .filter((sourcePath) => path.resolve(sourcePath) !== resolvedRoot);
+    return runBaseChecks({
+        filePath: assetPath,
+        relPath: path.relative(targetRoot, assetPath),
+        raw,
+        data,
+        body,
+        frontmatter,
+        fix: false,
+        stashRoot: targetRoot,
+        extraStashRoots,
+    }).filter((finding) => PROMOTION_LINT_BLOCKERS.has(finding.issue));
+}
+async function promoteProposalWithLease(stashDir, config, id, options, ctx) {
+    recoverRejectTransaction(stashDir, id, ctx);
+    let proposal = getProposal(stashDir, id, ctx);
     // Attempt bounded auto-repair of mechanically-fixable structural defects
     // (pseudo-frontmatter-in-body, stray `---` fences, truncated description)
     // BEFORE running validation. If the repair produces valid content, we
     // promote the repaired version; if validation still fails, the original
     // error path throws as before. The repair is content-preserving and
     // deterministic — it never invents text.
-    const repairedContent = repairProposalContent(proposal.payload.content);
-    const proposalToValidate = repairedContent !== proposal.payload.content
-        ? { ...proposal, payload: { ...proposal.payload, content: repairedContent } }
-        : proposal;
+    const repairedContent = repairProposalContent(proposalContent(proposal));
+    const proposalToValidate = repairedContent !== proposalContent(proposal) ? withProposalContent(proposal, repairedContent) : proposal;
     const report = validateProposal(proposalToValidate);
     if (!report.ok) {
         const message = report.findings.map((f) => `[${f.kind}] ${f.message}`).join("\n");
@@ -639,47 +1590,101 @@ export async function promoteProposal(stashDir, config, id, options = {}, ctx) {
     // Use the (possibly repaired) payload for the promotion write. Persist the
     // repaired content back onto the DB row so the audit trail reflects the
     // final promoted payload (not the defective original).
-    if (repairedContent !== proposal.payload.content) {
+    if (repairedContent !== proposalContent(proposal)) {
         withProposalsDb(stashDir, ctx, (db) => {
-            const updated = { ...proposal, payload: { ...proposal.payload, content: repairedContent } };
-            upsertProposal(db, updated, stashDir);
+            persistProposalUpdate(db, withProposalContent(proposal, repairedContent), stashDir);
         });
     }
-    const ref = parseAssetRef(proposalToValidate.ref);
-    if (!TYPE_DIRS[ref.type]) {
+    const ref = parseRefInput(proposalToValidate.ref);
+    if (!stashDirFor(ref.type)) {
         throw new UsageError(`Proposal ${id} targets unknown asset type "${ref.type}".`, "INVALID_FLAG_VALUE");
     }
-    const target = resolveWriteTarget(config, options.target);
-    // Phase 6C: capture the prior content (if any) BEFORE writing the new
-    // asset. We use the resolved write target to compute the exact path the
-    // asset would land at — same resolver `writeAssetToSource` uses — so the
-    // backup always mirrors what would be overwritten.
-    let backupContent;
-    try {
-        const targetFilePath = resolveAssetFilePathSafe(target.source, ref);
-        if (targetFilePath && fs.existsSync(targetFilePath)) {
-            backupContent = fs.readFileSync(targetFilePath, "utf8");
+    await recoverProposalTransactionsForStash(stashDir, config, ctx, id);
+    proposal = getProposal(stashDir, id, ctx);
+    const target = resolveProposalWriteTarget(config, proposal, options.target, options.queueTarget);
+    if (proposal.status === "accepted") {
+        if (!proposal.acceptedTarget) {
+            throw new UsageError(`Accepted proposal ${id} has no recorded target.`, "INVALID_PROPOSAL");
+        }
+        const assetPath = resolveAssetFilePathSafe(target.source, ref);
+        if (proposal.acceptedTarget.source !== target.source.name ||
+            path.resolve(proposal.acceptedTarget.root) !== path.resolve(target.source.path) ||
+            !assetPath ||
+            path.resolve(proposal.acceptedTarget.path) !== path.resolve(assetPath)) {
+            throw new UsageError(`proposal ${id} is bound to a different accepted target`, "INVALID_FLAG_VALUE");
+        }
+        if (!assetPath ||
+            !fs.existsSync(assetPath) ||
+            proposalFileHash(assetPath) !== proposal.acceptedTarget.contentHash) {
+            throw new UsageError(`Accepted proposal ${id} does not match the current asset content.`, "INVALID_FLAG_VALUE");
         }
+        return { proposal, assetPath, ref: proposal.ref };
     }
-    catch (err) {
-        // Backup capture is best-effort. A failure here must not block promotion
-        // (the user explicitly asked to accept); we surface a warning so the
-        // missing-revert path is visible.
-        warn(`[proposals] promoteProposal: failed to capture backup for ${id}: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    const written = await writeAssetToSource(target.source, target.config, ref, repairedContent);
-    // 0.9.0 (issue #507): single batch commit at the write boundary for git
-    // targets. No-op for filesystem/primary-stash targets.
-    commitWriteTargetBoundary(target, `Update ${formatRefForMessage(ref)}`);
-    const archived = archiveProposal(stashDir, id, "accepted", undefined, ctx);
-    // Persist the backup content on the archived proposal record so the revert
-    // flow can restore the prior asset state.
-    if (backupContent !== undefined) {
-        const withBackup = { ...archived, backupContent };
-        withProposalsDb(stashDir, ctx, (db) => upsertProposal(db, withBackup, stashDir));
-        return { proposal: withBackup, assetPath: written.path, ref: written.ref };
-    }
-    return { proposal: archived, assetPath: written.path, ref: written.ref };
+    if (proposal.status !== "pending") {
+        throw new UsageError(`Proposal ${id} is not pending (current status: ${proposal.status}). Only pending proposals can be accepted.`, "INVALID_FLAG_VALUE");
+    }
+    const mutationTarget = prepareWriteTargetForMutation(target);
+    const assetPath = resolveAssetFilePathSafe(mutationTarget.source, ref);
+    if (!assetPath)
+        throw new UsageError(`Cannot resolve proposal target ${proposal.ref}.`, "INVALID_PROPOSAL");
+    assertWriteTargetPathsClean(mutationTarget.source, [assetPath]);
+    let backup;
+    if (fs.existsSync(assetPath)) {
+        try {
+            backup = fs.readFileSync(assetPath);
+        }
+        catch (error) {
+            throw new Error(`Proposal backup read failed for ${assetPath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if (proposal.beforeHash !== undefined && (!backup || proposalHash(backup) !== proposal.beforeHash)) {
+        throw new UsageError(`Proposal target changed after proposal ${id} was created; refusing to overwrite newer content.`, "INVALID_FLAG_VALUE");
+    }
+    if (proposal.beforeHash === undefined &&
+        backup !== undefined &&
+        proposal.changes.some((change) => change.op === "create")) {
+        throw new UsageError(`Proposal target was created after proposal ${id}; refusing to overwrite newer content.`, "INVALID_FLAG_VALUE");
+    }
+    assertAkmAssetWrite(mutationTarget.source);
+    // D2 (#730): stamp OKF v0.2 provenance onto the promoted content BEFORE
+    // lint/write — reaching this point already proves the target is AKM-native
+    // (assertAkmAssetWrite above rejects an OKF-adapter target first), so the
+    // OKF write-rejection contract (runbook §10) is untouched: this code never
+    // runs for it. Markdown-only: a task/env/script/other non-markdown target
+    // has no frontmatter block to stamp into.
+    //
+    // workflow-format-unification removed the re-validation fallback that used
+    // to live here: every AKM-native markdown type (workflow included) now
+    // validates its frontmatter against a schema whose closed key set is
+    // `envelope ∪ type-keys` (`schemas/akm-workflow.json` $ref's
+    // `schemas/akm-asset-envelope.json`, which already admits `generated`/
+    // `verified`/`provenance`/`status`/`stale_after`). A validator rejecting the
+    // machine-stamped keys it is contractually required to admit is structurally
+    // impossible now, so falling back to unstamped content on rejection would
+    // only silently hide a real regression instead of promoting stamped content.
+    const stampedContent = assetPath.toLowerCase().endsWith(".md")
+        ? stampProposalProvenance(repairedContent, proposalToValidate, options.gateDecision, ctx, nowIso(ctx))
+        : repairedContent;
+    const lintBlockers = promotionLintBlockers(stampedContent, assetPath, mutationTarget.source.path, ref.type, config);
+    if (lintBlockers.length > 0) {
+        const message = lintBlockers.map((finding) => `[${finding.issue}] ${finding.detail}`).join("\n");
+        throw new UsageError(`Proposal ${id} failed lint:\n${message}`, "INVALID_PROPOSAL", "Fix or explicitly suppress the reported lint findings, then retry.");
+    }
+    const refIdentity = proposalRefIdentity(proposalToValidate.ref);
+    const proposalForMutation = refIdentity?.bundle === undefined
+        ? { ...proposalToValidate, ref: `${target.source.name}//${refIdentity?.conceptId ?? ""}` }
+        : proposalToValidate;
+    const transaction = prepareProposalTransaction(stashDir, mutationTarget, proposalForMutation, ref, stampedContent, {
+        operation: "accept",
+        originalHash: backup ? proposalHash(backup) : null,
+        backup,
+        eventMetadata: options.eventMetadata,
+        gateDecision: options.gateDecision,
+    }, ctx);
+    publishProposalAsset(transaction, mutationTarget);
+    const accepted = await finalizeProposalTransaction(transaction, mutationTarget, proposalForMutation, ctx);
+    cleanupTxn(transaction.dir);
+    return { proposal: accepted, assetPath: transaction.journal.payload.assetPath, ref: accepted.ref };
 }
 /**
  * Restore the prior content of an accepted proposal from the backup captured
@@ -702,37 +1707,64 @@ export async function promoteProposal(stashDir, config, id, options = {}, ctx) {
  * wrapper.
  */
 export async function revertProposal(stashDir, config, id, options = {}, ctx) {
-    const proposal = getProposal(stashDir, id, ctx);
+    return withAssetMutationLease("proposal-revert", () => revertProposalWithLease(stashDir, config, id, options, ctx));
+}
+async function revertProposalWithLease(stashDir, config, id, options, ctx) {
+    let proposal = getProposal(stashDir, id, ctx);
+    const ref = parseRefInput(proposal.ref);
+    if (!stashDirFor(ref.type)) {
+        throw new UsageError(`Proposal ${id} targets unknown asset type "${ref.type}".`, "INVALID_FLAG_VALUE");
+    }
+    await recoverProposalTransactionsForStash(stashDir, config, ctx, id);
+    proposal = getProposal(stashDir, id, ctx);
+    if (proposal.status === "reverted") {
+        if (!proposal.acceptedTarget) {
+            throw new UsageError(`Reverted proposal ${id} has no recorded target.`, "INVALID_PROPOSAL");
+        }
+        const target = resolveRecordedProposalTarget(config, id, proposal.acceptedTarget, options.target);
+        const requestedAssetPath = resolveAssetFilePathSafe(target.source, ref);
+        if (!requestedAssetPath ||
+            proposal.acceptedTarget.source !== target.source.name ||
+            path.resolve(proposal.acceptedTarget.root) !== path.resolve(target.source.path) ||
+            path.resolve(proposal.acceptedTarget.path) !== path.resolve(requestedAssetPath)) {
+            throw new UsageError(`proposal ${id} is bound to a different accepted target`, "INVALID_FLAG_VALUE");
+        }
+        return {
+            proposal,
+            assetPath: requestedAssetPath,
+            ref: proposal.ref,
+        };
+    }
     if (proposal.status !== "accepted") {
         throw new UsageError(`only accepted proposals can be reverted (proposal ${id} status: ${proposal.status})`, "INVALID_FLAG_VALUE");
     }
-    if (proposal.backupContent === undefined) {
+    const backupContent = proposal.backupContent;
+    if (backupContent === undefined) {
         throw new UsageError(`no backup available for this proposal (id: ${id})`, "MISSING_REQUIRED_ARGUMENT", "Backups are only captured when a proposal overwrites an existing asset — new-asset proposals cannot be reverted via this path; delete the asset directly instead.");
     }
-    const ref = parseAssetRef(proposal.ref);
-    if (!TYPE_DIRS[ref.type]) {
-        throw new UsageError(`Proposal ${id} targets unknown asset type "${ref.type}".`, "INVALID_FLAG_VALUE");
+    if (!proposal.acceptedTarget) {
+        throw new UsageError(`Accepted proposal ${id} has no recorded target.`, "INVALID_PROPOSAL");
     }
-    const target = resolveWriteTarget(config, options.target);
-    const written = await writeAssetToSource(target.source, target.config, ref, proposal.backupContent);
-    // 0.9.0 (issue #507): single batch commit at the write boundary for git
-    // targets. No-op for filesystem/primary-stash targets.
-    commitWriteTargetBoundary(target, `Revert ${formatRefForMessage(ref)}`);
-    // Update the proposal record to status: "reverted" and bump updatedAt +
-    // review so the audit trail reflects the second decision.
-    const now = nowIso(ctx);
-    const reverted = {
-        ...proposal,
-        status: "reverted",
-        updatedAt: now,
-        review: {
-            outcome: "rejected",
-            reason: "reverted: prior content restored from backup",
-            decidedAt: now,
-        },
-    };
-    withProposalsDb(stashDir, ctx, (db) => upsertProposal(db, reverted, stashDir));
-    return { proposal: reverted, assetPath: written.path, ref: written.ref };
+    let target = resolveRecordedProposalTarget(config, id, proposal.acceptedTarget, options.target);
+    const requestedAssetPath = resolveAssetFilePathSafe(target.source, ref);
+    if (proposal.acceptedTarget.source !== target.source.name ||
+        path.resolve(proposal.acceptedTarget.root) !== path.resolve(target.source.path) ||
+        !requestedAssetPath ||
+        path.resolve(proposal.acceptedTarget.path) !== path.resolve(requestedAssetPath)) {
+        throw new UsageError(`proposal ${id} is bound to a different accepted target`, "INVALID_FLAG_VALUE");
+    }
+    const assetPath = requestedAssetPath;
+    const acceptedHash = proposal.acceptedTarget.contentHash;
+    target = prepareWriteTargetForMutation(target);
+    if (!fs.existsSync(assetPath) || proposalFileHash(assetPath) !== acceptedHash) {
+        throw new UsageError(`asset content changed after proposal ${id} was accepted; refusing to clobber the newer content`, "INVALID_FLAG_VALUE");
+    }
+    assertWriteTargetPathsClean(target.source, [assetPath]);
+    const transaction = prepareProposalTransaction(stashDir, target, proposal, ref, backupContent, { operation: "revert", originalHash: acceptedHash }, ctx);
+    publishProposalAsset(transaction, target);
+    const reverted = await finalizeProposalTransaction(transaction, target, proposal, ctx);
+    cleanupTxn(transaction.dir);
+    return { proposal: reverted, assetPath, ref: proposal.ref };
 }
 /**
  * Compute a diff between a proposal payload and the existing on-disk asset.
@@ -742,21 +1774,17 @@ export async function revertProposal(stashDir, config, id, options = {}, ctx) {
  */
 export function diffProposal(stashDir, config, id, options = {}, ctx) {
     const proposal = getProposal(stashDir, id, ctx);
-    const ref = parseAssetRef(proposal.ref);
+    const ref = parseRefInput(proposal.ref);
     let targetPath;
     let existing = null;
-    try {
-        const target = resolveWriteTarget(config, options.target);
+    const readTarget = (target) => {
         targetPath = resolveAssetFilePathSafe(target.source, ref);
         if (targetPath && fs.existsSync(targetPath)) {
             existing = fs.readFileSync(targetPath, "utf8");
         }
-    }
-    catch {
-        // No writable target configured — still return a "new asset" diff so
-        // callers can see the proposed payload without erroring out.
-    }
-    const proposed = proposal.payload.content;
+    };
+    readTarget(resolveProposalWriteTarget(config, proposal, options.target, options.queueTarget));
+    const proposed = proposalContent(proposal);
     if (existing === null) {
         return {
             existing: null,
@@ -775,55 +1803,52 @@ export function diffProposal(stashDir, config, id, options = {}, ctx) {
     };
 }
 function resolveAssetFilePathSafe(source, ref) {
-    const typeDir = TYPE_DIRS[ref.type];
+    const typeDir = stashDirFor(ref.type);
     if (!typeDir)
         return undefined;
     const typeRoot = path.join(source.path, typeDir);
     try {
-        return resolveAssetPathFromName(ref.type, typeRoot, ref.name);
+        return assetPathForName(ref.type, typeRoot, ref.name);
     }
     catch {
         return undefined;
     }
 }
-/**
- * Minimal unified-diff renderer. We deliberately avoid pulling a runtime
- * dependency just for this — proposals diffs are usually small (a single
- * lesson / skill file), so the LCS-free greedy renderer below is plenty for
- * humans to review. The output mirrors `git diff --no-index` for the first
- * `@@ … @@` hunk: enough to be familiar, not so detailed that we re-implement
- * a full LCS table.
- */
-export function formatUnifiedDiff(left, right, label) {
-    if (left === right)
-        return "";
-    const leftLines = left.split("\n");
-    const rightLines = right.split("\n");
-    const lines = [`--- ${label} (existing)`, `+++ ${label} (proposed)`];
-    // Pad to the longer side so alignment is one-to-one. Real diff tools use
-    // LCS to align matching runs; we don't need that fidelity for a review
-    // surface — both halves are visible regardless.
-    const max = Math.max(leftLines.length, rightLines.length);
-    lines.push(`@@ 1,${leftLines.length} 1,${rightLines.length} @@`);
-    for (let i = 0; i < max; i += 1) {
-        const l = leftLines[i];
-        const r = rightLines[i];
-        if (l === r && l !== undefined) {
-            lines.push(` ${l}`);
-            continue;
+// Register the proposal transaction kinds with the unified engine so ANY
+// recovery entry point (mv pre-flight, indexer, write-path indexer) can
+// finish or roll back an interrupted proposal mutation for a root it
+// touches. The proposal-owned entry points below keep their richer,
+// ctx-threaded recovery paths over the same journals.
+registerTxnKind(PROPOSAL_TXN_KIND, {
+    phases: PROPOSAL_TXN_PHASES,
+    commitPhase: "asset-published",
+    validate: (journal, txnDir, root) => fenceProposalTxnJournal(journal, txnDir, root),
+    rollback: (txn) => {
+        rollbackPreparedProposalTransaction(txn);
+    },
+    finalize: async (txn) => {
+        const p = txn.journal.payload;
+        const config = loadConfig();
+        let target = resolveProposalRecoveryTarget(config, txn.journal);
+        if (txn.journal.phase === "asset-published") {
+            target = prepareWriteTargetForMutation(target, { allowAhead: true });
         }
-        if (l !== undefined)
-            lines.push(`-${l}`);
-        if (r !== undefined)
-            lines.push(`+${r}`);
-    }
-    return lines.join("\n");
-}
-function formatNewAssetDiff(ref, content) {
-    const lines = [`--- /dev/null`, `+++ ${ref} (proposed, new asset)`];
-    lines.push(`@@ 0,0 1,${content.split("\n").length} @@`);
-    for (const line of content.split("\n")) {
-        lines.push(`+${line}`);
-    }
-    return lines.join("\n");
-}
+        if (canonicalTxnRoot(target.source.path) !== canonicalTxnRoot(txn.journal.root) ||
+            p.targetKind !== target.source.kind) {
+            throw new Error(`Proposal transaction ${txn.journal.transactionId} is bound to a different target root.`);
+        }
+        const proposal = getProposal(p.stashDir, p.proposalId);
+        await finalizeProposalTransaction(txn, target, proposal);
+        cleanupProposalPublication(p);
+    },
+});
+registerTxnKind(REJECT_TXN_KIND, {
+    phases: REJECT_TXN_PHASES,
+    // A reject is roll-forward from its very first phase (DB-only; the archive
+    // decision is durable the moment the journal exists).
+    commitPhase: "prepared",
+    rollback: () => { },
+    finalize: (txn) => {
+        finalizeRejectTransaction(txn);
+    },
+});