wendkeep 0.77.0 → 0.79.0

package/packages/vault/src/memory-handoff.mjs

@@ -5,6 +5,12 @@ import { basename, join, relative } from 'node:path';
 
 import { sanitizeMemoryText } from './memory-schema.mjs';
 import { scopeForMemoryKey } from './memory-scope.mjs';
+import {
+  evaluateEvidenceBinding,
+  evidenceCheckoutBinding,
+  evidenceCheckoutBindingMatches,
+  evidenceSensors,
+} from './evidence-envelope.mjs';
 
 const SHARED_HANDOFF_FIELDS = Object.freeze([
   ['objective', 'objective.current'],
@@ -177,9 +183,33 @@ export function collectLifecycleEvidence(vaultBase, { changeSlug = '', summary =
         };
       }
       const sensorPath = join(archivedDir, 'evidencia.json');
-      const sensors = readJson(sensorPath);
-      if (Array.isArray(sensors) && sensors.length && sensors.every((item) => item?.status === 'green')) {
+      const sensorEnvelope = readJson(sensorPath);
+      const sensors = evidenceSensors(sensorEnvelope);
+      if (sensors.length && sensors.every((item) => item?.status === 'green')) {
         evidence.sensors = [...new Set(sensors.map((item) => String(item.id || '')).filter(Boolean))].sort();
+        evidence.sensors_path = vaultRel(vaultBase, sensorPath);
+        const assessed = evaluateEvidenceBinding(sensorEnvelope, { change_slug: slug });
+        evidence.sensors_binding = assessed.state;
+        if (sensorEnvelope?.schema_version === 2 && assessed.state === 'bound') {
+          const checkoutBinding = evidenceCheckoutBinding(sensorEnvelope);
+          const verification = readJson(join(archivedDir, 'verificacao.json'));
+          const crossBound = verification?.evidenceEnvelopeId === sensorEnvelope.envelope_id
+            && verdict?.evidenceEnvelopeId === sensorEnvelope.envelope_id
+            && evidenceCheckoutBindingMatches(verification?.evidenceBinding, checkoutBinding)
+            && evidenceCheckoutBindingMatches(verdict?.evidenceBinding, checkoutBinding);
+          if (!crossBound) {
+            evidence.sensors_binding = 'stale';
+            evidence.sensors_binding_reasons = ['archived verification/verdict binding mismatch'];
+          }
+        } else if (assessed.reasons.length) {
+          evidence.sensors_binding_reasons = assessed.reasons;
+        }
+        if (sensorEnvelope?.schema_version === 2) {
+          evidence.sensors_envelope_id = sensorEnvelope.envelope_id;
+          evidence.sensors_tasks_hash = sensorEnvelope.tasks_sha256;
+          evidence.sensors_repository_id = sensorEnvelope.repository_id;
+          evidence.sensors_worktree_id = sensorEnvelope.worktree_id;
+        }
       }
     }
   }
@@ -279,12 +309,23 @@ export function buildSessionMemoryEvents({
   if (Array.isArray(evidence.sensors) && evidence.sensors.length) {
     events.push(makeEvent(context, {
       memoryKey: 'quality.latest-sensors',
-      value: [...new Set(evidence.sensors.map(String))].sort(),
-      authority: 'verified',
-      evidence: evidence.sensors,
+      value: {
+        ids: [...new Set(evidence.sensors.map(String))].sort(),
+        evidence_state: evidence.sensors_binding || 'legacy-unbound',
+        ...(evidence.sensors_envelope_id ? { envelope_id: evidence.sensors_envelope_id } : {}),
+        ...(evidence.sensors_binding && !['bound', 'legacy-unbound'].includes(evidence.sensors_binding)
+          ? { recovery: 'reabra a change e rode wendkeep verify --deep + wk-verify' }
+          : {}),
+      },
+      authority: evidence.sensors_binding === 'bound' ? 'verified' : 'reported',
+      evidence: [evidence.sensors_path].filter(Boolean),
       scopeContext: {
         changeSlug: evidence.change?.slug || normalizedShared?.change_slug,
         tasksHash: evidence.sensors_tasks_hash || normalizedShared?.tasks_hash,
+        repositoryId: evidence.sensors_repository_id,
+        worktreeId: evidence.sensors_worktree_id,
+        evidenceEnvelopeId: evidence.sensors_envelope_id,
+        evidenceState: evidence.sensors_binding,
       },
     }));
   }

package/packages/vault/src/vault-path-safety.mjs

@@ -225,10 +225,20 @@ export function writeVaultFileSync(vaultBase, targetPath, content, encoding = 'u
 export function writeVaultFileAtomic(vaultBase, targetPath, content, encoding = 'utf8', {
   label = 'arquivo atômico do Vault',
   code = 'VAULT_PATH_UNSAFE',
+  scopeRoot = '',
+  beforeRename,
 } = {}) {
   const checked = assertVaultPathSafe(vaultBase, targetPath, {
     expectedType: 'file', label, code,
   });
+  if (scopeRoot) {
+    const scope = assertVaultPathSafe(vaultBase, scopeRoot, {
+      allowMissing: false, expectedType: 'directory', label: `escopo de ${label}`, code,
+    });
+    if (!containedBy(scope.target, checked.target)) {
+      throw unsafe(`${label} escapa do escopo autorizado: ${checked.target}`, code);
+    }
+  }
   assertVaultPathSafe(vaultBase, dirname(checked.target), {
     allowMissing: false, expectedType: 'directory', label: `ancestral de ${label}`, code,
   });
@@ -245,6 +255,7 @@ export function writeVaultFileAtomic(vaultBase, targetPath, content, encoding =
       allowMissing: false, expectedType: 'file', label: `temporário de ${label}`, code,
     });
     assertVaultPathSafe(vaultBase, checked.target, { expectedType: 'file', label, code });
+    if (typeof beforeRename === 'function') beforeRename({ temporary: tmp, target: checked.target });
     renameSync(tmp, checked.target);
     tmpCreated = false;
     assertVaultPathSafe(vaultBase, checked.target, {

package/schema/wendkeep.evidence-envelope-v2.schema.json

@@ -0,0 +1,92 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/rogersialves/wendkeep/schema/wendkeep.evidence-envelope-v2.schema.json",
+  "title": "WendKeep Evidence Envelope v2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "project_id",
+    "repository_id",
+    "worktree_id",
+    "work_session_id",
+    "change_slug",
+    "branch",
+    "base_sha",
+    "head_sha",
+    "index_tree_sha",
+    "worktree_digest",
+    "dirty",
+    "tasks_sha256",
+    "effective_spec_sha256",
+    "sensor_config_sha256",
+    "wendkeep_version",
+    "platform",
+    "started_at",
+    "finished_at",
+    "sensors",
+    "envelope_id"
+  ],
+  "properties": {
+    "schema_version": { "const": 2 },
+    "project_id": { "type": "string", "minLength": 1 },
+    "repository_id": { "type": "string", "minLength": 1 },
+    "worktree_id": { "type": "string", "minLength": 1 },
+    "work_session_id": { "type": "string", "minLength": 1 },
+    "change_slug": { "type": "string", "minLength": 1 },
+    "branch": { "type": "string", "minLength": 1 },
+    "base_sha": { "$ref": "#/$defs/gitObject" },
+    "head_sha": { "$ref": "#/$defs/gitObject" },
+    "index_tree_sha": { "$ref": "#/$defs/gitObject" },
+    "worktree_digest": { "$ref": "#/$defs/sha256" },
+    "dirty": { "type": "boolean" },
+    "tasks_sha256": { "$ref": "#/$defs/sha256" },
+    "effective_spec_sha256": { "$ref": "#/$defs/sha256" },
+    "sensor_config_sha256": { "$ref": "#/$defs/sha256" },
+    "wendkeep_version": { "type": "string", "minLength": 1 },
+    "platform": { "type": "string", "minLength": 1 },
+    "started_at": { "type": "string", "format": "date-time" },
+    "finished_at": { "type": "string", "format": "date-time" },
+    "envelope_id": { "$ref": "#/$defs/sha256" },
+    "sensors": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/sensor" }
+    }
+  },
+  "$defs": {
+    "gitObject": { "type": "string", "pattern": "^[a-f0-9]{40,64}$" },
+    "sha256": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "sensor": {
+      "type": "object",
+      "required": [
+        "id",
+        "status",
+        "severity",
+        "command",
+        "command_sha256",
+        "started_at",
+        "finished_at",
+        "duration_ms",
+        "exit_code",
+        "output_sha256",
+        "output_tail"
+      ],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "status": { "enum": ["green", "red"] },
+        "severity": { "enum": ["critical", "warning"] },
+        "command": { "type": "string" },
+        "command_sha256": { "$ref": "#/$defs/sha256" },
+        "started_at": { "type": "string", "format": "date-time" },
+        "finished_at": { "type": "string", "format": "date-time" },
+        "duration_ms": { "type": "number", "minimum": 0 },
+        "exit_code": { "type": ["integer", "null"] },
+        "output_sha256": { "$ref": "#/$defs/sha256" },
+        "output_tail": { "type": "string", "maxLength": 2000 },
+        "note": { "type": "string", "maxLength": 2000 },
+        "survivors": { "type": "array" },
+        "ts": { "type": "string", "format": "date-time" }
+      }
+    }
+  }
+}

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; }
+    },
+  });
+}