wendkeep 0.78.0 → 0.79.0

package/hooks/spec-core.mjs

@@ -1,11 +1,12 @@
 // hooks/spec-core.mjs — living spec (07-Specs) + change delta merge (OpenSpec native).
-// Pure parsing/merge + promoteSpecs (fs). No import from change-core (avoids a cycle).
-import { createHash } from 'node:crypto';
+// Pure parsing/merge + read-only promotion planning. No import from change-core (avoids a cycle).
+import { createHash, randomUUID } from 'node:crypto';
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, relative } from 'node:path';
 import { getLocale } from './locale.mjs';
 import {
-  assertVaultPathSafe, assertVaultPathsSafe, mkdirVaultPath, writeVaultFileAtomic, writeVaultFileSync,
+  assertVaultPathSafe, assertVaultPathsSafe, mkdirVaultPath,
+  writeVaultFileAtomic, writeVaultFileSync,
 } from './vault-path-safety.mjs';
 
 // Canonical SHA-256 fingerprint of tarefas.md — freshness binding between package/verdict and gate.
@@ -148,9 +149,20 @@ export function checkSpecsState(vaultBase) {
   return { ok: changed.length === 0, missing: false, changed, current, recorded };
 }
 
-function recordPromotedSpecs(vaultBase, capabilities) {
+function recordPromotedSpecs(vaultBase, capabilities, { writeAtomic = writeVaultFileSync } = {}) {
   const existing = readSpecsState(vaultBase);
-  if (!existing) return adoptSpecsState(vaultBase);
+  if (!existing) {
+    const state = { version: 1, generatedAt: new Date().toISOString(), specs: readLivingSpecs(vaultBase) };
+    mkdirVaultPath(vaultBase, join(vaultBase, '.brain'), { label: 'raiz do estado de specs' });
+    writeAtomic(
+      vaultBase,
+      join(vaultBase, SPECS_STATE_FILE),
+      `${JSON.stringify(state, null, 2)}\n`,
+      'utf8',
+      { label: 'estado consolidado de specs' },
+    );
+    return state;
+  }
   const current = readLivingSpecs(vaultBase);
   const specs = { ...(existing.specs || {}) };
   for (const capability of capabilities) {
@@ -158,7 +170,7 @@ function recordPromotedSpecs(vaultBase, capabilities) {
     else delete specs[capability];
   }
   const state = { version: 1, generatedAt: new Date().toISOString(), specs };
-  writeVaultFileSync(
+  writeAtomic(
     vaultBase,
     join(vaultBase, SPECS_STATE_FILE),
     `${JSON.stringify(state, null, 2)}\n`,
@@ -348,12 +360,10 @@ export function discoverSpecDeltas(changeDir) {
 // per-change (many changes promote into the same file; the per-change record lives in
 // _arquivo). Generated + read-only. Written on init and refreshed on every archive so
 // existing vaults self-heal. Bilingual by vault locale.
-export function ensureSpecsReadme(vaultBase) {
+function specsReadmeBody(vaultBase) {
   const loc = getLocale(vaultBase);
   const en = loc.id === 'en';
-  const dir = join(vaultBase, loc.folders.specs);
-  mkdirVaultPath(vaultBase, dir, { label: 'raiz de specs consolidadas' });
-  const body = en
+  return en
     ? `# Specs — generated living contract
 
 **One file per _capability_, not per change.** Each file is the current, cumulative contract
@@ -382,7 +392,18 @@ Pense como código-fonte vs commits: esta pasta é o *código atual* de cada cap
   \`wendkeep change archive\` promove para esta pasta.
 - Histórico por mudança → \`${loc.folders.changes}/_arquivo/\`. Contrato atual → aqui.
 `;
-  writeVaultFileSync(vaultBase, join(dir, 'README.md'), body, 'utf8', { label: 'README de specs' });
+}
+
+export function renderSpecsReadme(vaultBase) {
+  return specsReadmeBody(vaultBase);
+}
+
+export function ensureSpecsReadme(vaultBase, { writeAtomic = writeVaultFileSync } = {}) {
+  const loc = getLocale(vaultBase);
+  const dir = join(vaultBase, loc.folders.specs);
+  mkdirVaultPath(vaultBase, dir, { label: 'raiz de specs consolidadas' });
+  const body = specsReadmeBody(vaultBase);
+  writeAtomic(vaultBase, join(dir, 'README.md'), body, 'utf8', { label: 'README de specs' });
 }
 
 export function assertSpecPromotionTargetsSafe(vaultBase, changeDir, specs) {
@@ -426,8 +447,14 @@ export function assertSpecPromotionTargetsSafe(vaultBase, changeDir, specs) {
   return { specsRoot: checkedRoot.target };
 }
 
-// Merge each capability's delta (in the change) into the living spec in 07-Specs.
-export function promoteSpecs(vaultBase, changeDir, specs, { changeWikilink, dateStr } = {}) {
+// Derive the immutable before/postimage plan used by the archive CLI. This helper
+// is deliberately read-only: publication is private to src/change.mjs, after the
+// provenance gate, receipt, recapture, and operation lock have all succeeded.
+export function buildSpecPromotionPlan(vaultBase, changeDir, specs, {
+  changeWikilink,
+  dateStr,
+  recoveryRoot,
+} = {}) {
   const loc = getLocale(vaultBase);
   const specsDir = loc.folders.specs;
   const promoted = [];
@@ -459,25 +486,62 @@ export function promoteSpecs(vaultBase, changeDir, specs, { changeWikilink, date
       content: renderSpec(cap, applied.reqs, { footer, reqHeading: loc.reqHeading }),
     });
   }
-  mkdirVaultPath(vaultBase, specsRoot, { label: 'raiz de specs consolidadas' });
+  const statePath = join(vaultBase, SPECS_STATE_FILE);
+  const readmePath = join(specsRoot, 'README.md');
+  const existingState = readSpecsState(vaultBase);
+  const nextSpecs = existingState ? { ...(existingState.specs || {}) } : readLivingSpecs(vaultBase);
   for (const item of materialized) {
-    writeVaultFileSync(
-      vaultBase,
-      item.livePath,
-      item.content,
-      'utf8',
-      { label: `spec consolidada ${item.capability}` },
-    );
-    promoted.push(item.capability);
+    nextSpecs[item.capability] = {
+      hash: contentHashOf(item.content),
+      requirements: Object.fromEntries(parseRequirements(item.content)
+        .map((requirement) => [requirement.id || requirement.name, contentHashOf(JSON.stringify(requirement))])),
+    };
   }
-  recordPromotedSpecs(vaultBase, promoted);
-  ensureSpecsReadme(vaultBase); // self-heal the explainer so existing vaults get it on archive
-  return { promoted, warnings };
+  const stateContent = `${JSON.stringify({
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    specs: nextSpecs,
+  }, null, 2)}\n`;
+  const planned = [
+    ...materialized.map((item) => ({
+      kind: 'capability', capability: item.capability, path: item.livePath, content: item.content,
+    })),
+    { kind: 'state', path: statePath, content: stateContent },
+    { kind: 'readme', path: readmePath, content: specsReadmeBody(vaultBase) },
+  ];
+  const image = (content, exists = true) => ({
+    exists,
+    content_base64: Buffer.from(content, 'utf8').toString('base64'),
+    digest: `sha256:${contentHashOf(content)}`,
+  });
+  const promotionRecoveryRoot = recoveryRoot
+    || join(vaultBase, '.brain', 'runtime', 'spec-promotion-plans', randomUUID());
+  const plan = {
+    schema_version: 1,
+    entries: planned.map((entry, index) => {
+      const beforeExists = existsSync(entry.path);
+      const beforeContent = beforeExists ? readFileSync(entry.path, 'utf8') : '';
+      return {
+        kind: entry.kind,
+        capability: entry.capability || null,
+        target: relative(vaultBase, entry.path).replaceAll('\\', '/'),
+        claim_target: relative(vaultBase, join(promotionRecoveryRoot, `${index}-${randomUUID()}.before`)).replaceAll('\\', '/'),
+        candidate_target: relative(vaultBase, join(promotionRecoveryRoot, `${index}-${randomUUID()}.candidate`)).replaceAll('\\', '/'),
+        before: image(beforeContent, beforeExists),
+        after: image(entry.content, true),
+      };
+    }),
+  };
+  const changes = materialized.map((item) => ({
+    capability: item.capability,
+    before_digest: plan.entries.find((entry) => entry.capability === item.capability).before.digest,
+    after_digest: `sha256:${contentHashOf(item.content)}`,
+  }));
+  plan.changes = changes;
+  promoted.push(...materialized.map((item) => item.capability));
+  return { promoted, warnings, changes, plan };
 }
 
-// Gate check for the independent verdict (Wave A). A requirement-bearing change must have
-// a verdict that is ok and covers every declared req id. A requirement-less change passes:
-// nothing for an independent verifier to check — the sensor gate is already the proof.
 export function evaluateVerdict(verdict, reqIds, {
   tasksHash,
   effectiveSpecHash,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.78.0",
+  "version": "0.79.0",
   "description": "Vault-first persistent memory for AI coding agents, with an optional profile-aware governance runtime: OFF, FLOW, GUIDE, GOVERN, or ASSURE. Local-first and agent-agnostic (Claude Code, Codex, Cursor…).",
   "type": "module",
   "workspaces": [
@@ -41,7 +41,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "precheck": "node --check src/worktree.mjs && node --check src/worktree-cleanup.mjs && node --check src/evidence-envelope.mjs && node --check src/context.mjs && node --check src/active-context-health.mjs && node --check src/active-context-runtime.mjs && node --check hooks/active-context-store.mjs && node --check hooks/change-core.mjs && node --check hooks/brain-inject.mjs && node --check hooks/change-context.mjs && node --check packages/vault/src/worktree-metadata.mjs && node --check packages/vault/src/evidence-envelope.mjs",
+    "precheck": "node --check src/change.mjs && node --check src/archive-operation-lock.mjs && node --check src/worktree.mjs && node --check src/worktree-cleanup.mjs && node --check src/provenance-gate.mjs && node --check src/provenance-sources.mjs && node --check src/receipt-ledger.mjs && node --check src/evidence-envelope.mjs && node --check src/context.mjs && node --check src/active-context-health.mjs && node --check src/active-context-runtime.mjs && node --check hooks/active-context-store.mjs && node --check hooks/change-core.mjs && node --check hooks/brain-inject.mjs && node --check hooks/change-context.mjs && node --check packages/vault/src/worktree-metadata.mjs && node --check packages/vault/src/evidence-envelope.mjs",
     "check": "node --check scripts/release.mjs && node --check scripts/release-plan.mjs && node --check scripts/release-provenance.mjs && node --check scripts/run-scope.mjs && node --check src/release-provenance.mjs && node --check bin/wendkeep.mjs && node --check packages/cli/src/index.mjs && node --check src/init.mjs && node --check src/doctor.mjs && node --check src/active-context-health.mjs && node --check src/project-vault.mjs && node --check src/observer-auth.mjs && node --check src/observer-privacy.mjs && node --check src/observer-snapshot.mjs && node --check src/observer-store.mjs && node --check src/observer-memory.mjs && node --check src/observer-memory-publish.mjs && node --check src/observer-sql-store.mjs && node --check src/observer-sql-migrate.mjs && node --check src/observer-sql-publish.mjs && node --check src/observer-transcript-store.mjs && node --check src/observer-server.mjs && node --check src/observer.mjs && node --check src/observer-publish.mjs && node --check src/operating-profile.mjs && node --check src/profile.mjs && node --check src/flow.mjs && node --check src/work-kind.mjs && node --check src/delivery.mjs && node --check web/observer/app.mjs && node --check hooks/observer-publish.mjs && node --check hooks/evidence-context.mjs && node --check hooks/active-context-handoff-evidence.mjs && node --check hooks/evidence-recall.mjs && node --check hooks/memory-scope.mjs && node --check hooks/operating-profile-runtime.mjs && node --check hooks/operating-profile-task-store.mjs && node --check hooks/flow-core.mjs && node --check hooks/flow-protected-policy.mjs && node --check hooks/git-snapshot.mjs && node --check hooks/vault-path-safety.mjs && node --check hooks/vault-runtime-store.mjs && node --check packages/harness/src/index.mjs && node --check packages/harness/src/flow-store.mjs && node --check packages/harness/src/operating-profile.mjs && node --check packages/harness/src/sensors-core.mjs && node --check packages/integrations/src/host-hooks.mjs && node --check packages/integrations/src/hook-envelope.mjs && node --check packages/integrations/src/prompt-content.mjs && node --check packages/integrations/src/transcript-usage.mjs && node --check packages/integrations/src/transcripts.mjs && node --check packages/integrations/src/session-identity.mjs && node --check packages/integrations/src/index.mjs && node --check packages/mcp/src/config.mjs && node --check packages/mcp/src/index.mjs && node --check packages/vault/src/index.mjs && node --check packages/vault/src/project-vault.mjs && node --check packages/vault/src/vault-path-safety.mjs && node --check packages/vault/src/locale.mjs && node --check packages/vault/src/memory-schema.mjs && node --check packages/vault/src/memory-mode.mjs && node --check packages/vault/src/memory-scope.mjs && node --check packages/vault/src/memory-candidate-policy.mjs && node --check packages/vault/src/evidence-recall.mjs && node --check packages/vault/src/memory-handoff.mjs && node --check packages/vault/src/memory-store.mjs && node --check packages/vault/src/validate-core.mjs && node --check packages/vault/src/validate-memory.mjs",
     "test": "node --test --test-concurrency=2",
     "test:core": "node scripts/run-scope.mjs core",

package/schema/wendkeep.provenance-receipt-v2.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/rogersialves/wendkeep/blob/main/schema/wendkeep.provenance-receipt-v2.schema.json",
+  "title": "WendKeep Provenance Receipt v2",
+  "description": "A canonical, hash-chained receipt for a provenance-gated operation.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "sequence",
+    "receipt_id",
+    "previous_hash",
+    "receipt_hash",
+    "kind",
+    "subject",
+    "claims",
+    "observations",
+    "recorded_at"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": 2
+    },
+    "sequence": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "receipt_id": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "previous_hash": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$",
+      "description": "Hash of the previous v2 receipt, or the canonical legacy/empty prefix for genesis."
+    },
+    "receipt_hash": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$",
+      "description": "SHA-256 of the canonical receipt without receipt_hash."
+    },
+    "kind": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9._-]{1,63}$"
+    },
+    "subject": {
+      "type": "object",
+      "description": "Sanitized identity and current operation target.",
+      "additionalProperties": true
+    },
+    "claims": {
+      "type": "object",
+      "description": "Sanitized claims made by the operation.",
+      "additionalProperties": true
+    },
+    "observations": {
+      "type": "object",
+      "description": "Sanitized source observations keyed by adapter/kind.",
+      "additionalProperties": true
+    },
+    "recorded_at": {
+      "type": "string",
+      "format": "date-time"
+    }
+  }
+}

package/src/archive-operation-lock.mjs

@@ -0,0 +1,235 @@
+import { randomUUID } from 'node:crypto';
+import {
+  closeSync, constants, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync,
+  readFileSync, readdirSync, realpathSync, renameSync, rmdirSync, unlinkSync, writeFileSync,
+} from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+
+function archiveLockError(code, details = {}) {
+  const error = new Error(code);
+  error.code = code;
+  Object.assign(error, details);
+  return error;
+}
+
+function samePhysicalFile(left, right) {
+  if (!left?.isFile() || !right?.isFile() || left.ino !== right.ino) return false;
+  if (left.dev === right.dev) return true;
+  return process.platform === 'win32' && (left.dev === 0 || right.dev === 0);
+}
+
+function ownerProcessAlive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return !['ESRCH', 'EINVAL'].includes(error?.code); }
+}
+
+function assertLockDirectory(target) {
+  const stat = lstatSync(target);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) {
+    throw archiveLockError('WENDKEEP_ARCHIVE_LOCK_UNAVAILABLE');
+  }
+  return stat;
+}
+
+function readOwnerMarker(markerPath) {
+  const stat = lstatSync(markerPath);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) {
+    throw archiveLockError('WENDKEEP_ARCHIVE_LOCK_UNAVAILABLE');
+  }
+  let record;
+  try { record = JSON.parse(readFileSync(markerPath, 'utf8')); }
+  catch { throw archiveLockError('WENDKEEP_ARCHIVE_LOCK_UNAVAILABLE'); }
+  if (record?.schema_version !== 1
+    || typeof record.owner_token !== 'string' || !record.owner_token
+    || !Number.isSafeInteger(record.owner_pid) || record.owner_pid <= 0
+    || typeof record.acquired_at !== 'string' || !Number.isFinite(Date.parse(record.acquired_at))) {
+    throw archiveLockError('WENDKEEP_ARCHIVE_LOCK_UNAVAILABLE');
+  }
+  return { stat, record };
+}
+
+function inspectExistingLock(target) {
+  try { assertLockDirectory(target); }
+  catch (error) {
+    if (error?.code === 'ENOENT') return;
+    throw archiveLockError('WENDKEEP_ARCHIVE_LOCK_UNAVAILABLE');
+  }
+  const entries = readdirSync(target);
+  if (entries.length === 0) {
+    try { rmdirSync(target); } catch { /* re-observe on the next bounded attempt */ }
+    return;
+  }
+  if (entries.length !== 1 || !/^owner\.[0-9a-f-]+\.json$/i.test(entries[0])) {
+    throw archiveLockError('WENDKEEP_ARCHIVE_LOCK_UNAVAILABLE');
+  }
+  const markerPath = join(target, entries[0]);
+  const observed = readOwnerMarker(markerPath);
+  if (basename(markerPath) !== `owner.${observed.record.owner_token}.json`) {
+    throw archiveLockError('WENDKEEP_ARCHIVE_LOCK_UNAVAILABLE');
+  }
+  if (ownerProcessAlive(observed.record.owner_pid)) {
+    throw archiveLockError('WENDKEEP_ARCHIVE_BUSY', { owner_state: 'live' });
+  }
+  const confirmed = readOwnerMarker(markerPath);
+  if (!samePhysicalFile(observed.stat, confirmed.stat)
+    || confirmed.record.owner_token !== observed.record.owner_token
+    || confirmed.record.owner_pid !== observed.record.owner_pid) {
+    throw archiveLockError('WENDKEEP_ARCHIVE_LOCK_UNAVAILABLE');
+  }
+  try { unlinkSync(markerPath); }
+  catch { throw archiveLockError('WENDKEEP_ARCHIVE_LOCK_UNAVAILABLE'); }
+  try { rmdirSync(target); } catch { /* replacement/nonempty directory remains authoritative */ }
+}
+
+export function acquireArchiveOperationLock({
+  lockPath,
+  now = () => Date.now(),
+  maxAcquireAttempts = 3,
+  faultInjection = {},
+}) {
+  if (!lockPath || !Number.isSafeInteger(maxAcquireAttempts) || maxAcquireAttempts < 1) {
+    throw archiveLockError('WENDKEEP_ARCHIVE_LOCK_INVALID');
+  }
+  const runtime = resolve(dirname(lockPath));
+  const target = resolve(lockPath);
+  mkdirSync(runtime, { recursive: true });
+  const runtimeStat = lstatSync(runtime);
+  if (!runtimeStat.isDirectory() || runtimeStat.isSymbolicLink()
+    || resolve(realpathSync(runtime)).toLowerCase() !== runtime.toLowerCase()) {
+    throw archiveLockError('WENDKEEP_ARCHIVE_LOCK_UNAVAILABLE');
+  }
+
+  const token = randomUUID();
+  const markerName = `owner.${token}.json`;
+  const pending = `${target}.pending.${process.pid}.${token}`;
+  const pendingMarker = join(pending, markerName);
+  let descriptor;
+  let descriptorIdentity;
+  let pendingExists = false;
+  let published = false;
+  try {
+    mkdirSync(pending);
+    pendingExists = true;
+    descriptor = openSync(
+      pendingMarker,
+      constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0),
+      0o600,
+    );
+    writeFileSync(descriptor, `${JSON.stringify({
+      schema_version: 1,
+      owner_token: token,
+      owner_pid: process.pid,
+      acquired_at: new Date(now()).toISOString(),
+    })}\n`, 'utf8');
+    fsyncSync(descriptor);
+    closeSync(descriptor);
+    descriptor = undefined;
+
+    for (let attempt = 1; attempt <= maxAcquireAttempts; attempt += 1) {
+      try {
+        if (typeof faultInjection?.beforePublishRename === 'function') {
+          faultInjection.beforePublishRename({ attempt, pending, lockPath: target });
+        }
+        // The pending directory is already nonempty and durable. Rename publishes metadata and
+        // exclusivity together; the canonical namespace never observes a partial marker/hardlink.
+        renameSync(pending, target);
+        pendingExists = false;
+        published = true;
+        if (typeof faultInjection?.afterPublishRename === 'function') {
+          faultInjection.afterPublishRename({ attempt, lockPath: target });
+        }
+        break;
+      } catch (error) {
+        if (published) throw error;
+        if (existsSync(target)) inspectExistingLock(target);
+        if (attempt === maxAcquireAttempts) {
+          throw archiveLockError('WENDKEEP_ARCHIVE_LOCK_UNAVAILABLE');
+        }
+      }
+    }
+
+    const markerPath = join(target, markerName);
+    descriptor = openSync(
+      markerPath,
+      constants.O_RDONLY | (constants.O_NOFOLLOW || 0),
+    );
+    const identity = readOwnerMarker(markerPath);
+    descriptorIdentity = fstatSync(descriptor);
+    if (!samePhysicalFile(descriptorIdentity, identity.stat)
+      || identity.record.owner_token !== token) {
+      throw archiveLockError('WENDKEEP_ARCHIVE_LOCK_OWNERSHIP_LOST');
+    }
+  } catch (error) {
+    if (descriptor !== undefined) {
+      try { closeSync(descriptor); } catch { /* original code remains authoritative */ }
+      descriptor = undefined;
+    }
+    if (pendingExists) {
+      try { unlinkSync(pendingMarker); } catch { /* marker may be absent */ }
+      try { rmdirSync(pending); } catch { /* private pending state is recoverable */ }
+    }
+    if (error?.code?.startsWith('WENDKEEP_ARCHIVE_')) throw error;
+    throw archiveLockError('WENDKEEP_ARCHIVE_LOCK_UNAVAILABLE');
+  }
+
+  const markerPath = join(target, markerName);
+  let terminal = false;
+  let assertionCount = 0;
+  const closeHandle = () => {
+    if (descriptor === undefined) return;
+    try { closeSync(descriptor); } finally { descriptor = undefined; }
+  };
+  const assertOwned = () => {
+    if (terminal || descriptor === undefined) {
+      throw archiveLockError('WENDKEEP_ARCHIVE_LOCK_OWNERSHIP_LOST');
+    }
+    try { assertLockDirectory(target); }
+    catch { throw archiveLockError('WENDKEEP_ARCHIVE_LOCK_OWNERSHIP_LOST'); }
+    let identity;
+    try { identity = readOwnerMarker(markerPath); }
+    catch { throw archiveLockError('WENDKEEP_ARCHIVE_LOCK_OWNERSHIP_LOST'); }
+    const currentDescriptorIdentity = fstatSync(descriptor);
+    if (!samePhysicalFile(currentDescriptorIdentity, identity.stat)
+      || identity.record.owner_token !== token) {
+      throw archiveLockError('WENDKEEP_ARCHIVE_LOCK_OWNERSHIP_LOST');
+    }
+    descriptorIdentity = currentDescriptorIdentity;
+    assertionCount += 1;
+    if (typeof faultInjection?.afterAssertOwned === 'function') {
+      faultInjection.afterAssertOwned({ count: assertionCount, lockPath: target, markerPath });
+    }
+    return true;
+  };
+
+  return Object.freeze({
+    token,
+    assertOwned,
+    release() {
+      if (terminal) return;
+      try {
+        assertOwned();
+        if (typeof faultInjection?.beforeReleaseCommit === 'function') {
+          faultInjection.beforeReleaseCommit({ lockPath: target, markerPath });
+        }
+        closeHandle();
+        const finalIdentity = readOwnerMarker(markerPath);
+        if (!samePhysicalFile(descriptorIdentity, finalIdentity.stat)
+          || finalIdentity.record.owner_token !== token) {
+          throw archiveLockError('WENDKEEP_ARCHIVE_LOCK_OWNERSHIP_LOST');
+        }
+        unlinkSync(markerPath);
+        rmdirSync(target);
+      } catch {
+        terminal = true;
+        closeHandle();
+        throw archiveLockError('WENDKEEP_ARCHIVE_LOCK_OWNERSHIP_LOST');
+      }
+      terminal = true;
+      closeHandle();
+    },
+    get active() {
+      if (terminal) return false;
+      try { return assertOwned(); } catch { return false; }
+    },
+  });
+}