wendkeep 0.59.0 → 0.61.0

package/CHANGELOG.md

@@ -4,6 +4,51 @@ All notable changes to **wendkeep** are documented here. Format based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project follows
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.61.0] — 2026-07-28
+
+### Added
+
+- **`wendkeep/vault` passa a expor o kernel de memória operacional.** Schema v2, detecção de
+  modo, handoff, ledger/projeção e validadores CORE/SHARED ficam disponíveis pela superfície
+  pública e são exercitados a partir de um tarball realmente instalado.
+
+### Changed
+
+- **A implementação canônica do kernel agora pertence a `packages/vault/src`.** Os paths
+  históricos em `hooks/` e `src/` permanecem como fachadas de reexport, inclusive por bare
+  specifiers no pacote instalado, preservando identidade de funções, classes, constantes e
+  compatibilidade com consumidores existentes.
+- **A extração é estrutural e não migra dados.** Schema 2, ledger, locks, projeção,
+  SessionStop e o conteúdo de cada Vault mantêm o mesmo contrato persistente.
+
+### Fixed
+
+- **`memory repair` converge checkpoints assert-only históricos pré-0.59 sem editar o ledger.**
+  O repair só migra quando prefixo, revision, cursor, hash, identidade e turns reproduzem
+  exatamente a semântica antiga e o espelho `memory_checkpoint` é compatível; o caminho preserva
+  CORE/ledger, usa CAS do attempt e do espelho, backup e auditoria e continua falhando fechado para
+  tuples, operações ou espelhos divergentes.
+
+## [0.60.0] — 2026-07-27
+
+### Added
+
+- **O runtime ganha seis fronteiras físicas internas:** `cli`, `harness`, `vault`, `mcp`,
+  `integrations` e `pi` passam a existir como workspaces privados `@wendkeep/*`, mantendo
+  `wendkeep` como uma única unidade de instalação e publicação.
+- **O Keep Core inaugura a API programática `wendkeep/vault`.** Binding/resolução do Vault e a
+  fronteira segura de paths podem ser importados pelo novo subpath público, incluído e validado no
+  tarball.
+
+### Changed
+
+- **Binding e segurança física agora pertencem a `packages/vault`.** Os paths históricos em
+  `src/project-vault.mjs` e `hooks/vault-path-safety.mjs` permanecem como fachadas compatíveis, sem
+  alterar CLI, hooks ou dados existentes.
+- **A direção de dependências virou gate estrutural.** O workspace Vault aceita somente built-ins
+  Node e módulos internos, impedindo que Keep Core passe a depender de Harness, perfis, changes,
+  FLOW, sensores ou CLI.
+
 ## [0.59.0] — 2026-07-27
 
 ### Added

package/README.en.md

@@ -15,6 +15,14 @@
 
 **Persistent memory for AI coding agents, built on your Obsidian vault.** Every Claude Code **and Codex** session is captured turn by turn into local Markdown — `init` wires both (Codex asks you to approve its hooks once; `import` backfills past sessions either way) — with token/cost tracking and automatically extracted decisions, bugs, and learnings. That always-on plane is **Keep Core**. On top of it, **Wend Runtime** provides a native, zero-dependency lifecycle (spec → change → TDD → sensor-gated archive), selected through the `OFF`, `FLOW`, `GUIDE`, `GOVERN`, and `ASSURE` Operating Profiles. 100% local, open-core.
 
+The runtime is being separated into six physical boundaries — `cli`, `harness`, `vault`, `mcp`,
+`integrations`, and `pi` — without fragmenting installation. The private `vault` workspace now
+canonically owns safe binding and the Shared Project Memory v2 kernel (schema, mode, handoff,
+ledger, projection, and validation), exposed by the root package through `wendkeep/vault`.
+Historical imports, including installed bare subpaths such as `wendkeep/hooks/...`, keep working
+through compatibility facades and no session data needs migration;
+see the [modular architecture](docs/en/architecture.md).
+
 ```bash
 npm i -D wendkeep && npx wendkeep init      # captures from the next session on
 npx wendkeep import                          # backfill past Claude + Codex sessions
@@ -244,9 +252,11 @@ lost publication, or mismatched checkpoint blocks. See [migration](docs/en/comma
 and [diagnostics](docs/en/commands/maintenance-and-diagnostics.md).
 
 If status blocks, preserve the evidence and run `wendkeep memory repair --vault <vault>` to back up
-the corrupt ledger, retain valid lines, and re-project. Repair never reclassifies attempts. A
-valid pre-0.59 causal checkpoint is CAS-migrated to the physical boundary with backup/audit. A
-demonstrably superseded ambiguity uses `memory reconcile <session> --by-session <successor>
+the corrupt ledger, retain valid lines, and re-project. Repair never reclassifies attempts. Valid
+pre-0.59 causal checkpoints and exactly re-derived assert-only historical prefixes are
+CAS-migrated on both the attempt and `memory_checkpoint` to the correct physical boundary with
+backup/audit; divergent mirrors fail closed. A demonstrably superseded
+ambiguity uses `memory reconcile <session> --by-session <successor>
 --reason <reason>` as a dry run and requires `--apply`; the decision is backed up and audited
 without rewriting ledger, CORE, or notes. Run `status --gate` again afterwards. Conflicts require
 explicit curation with `memory promote <id>` or `memory reject <id>`; doctor only diagnoses.

package/README.md

@@ -15,6 +15,14 @@
 
 **Persistent memory for AI coding agents, built on your Obsidian vault.** Every Claude Code **and Codex** session is captured turn by turn into local Markdown — `init` wires both (Codex asks you to approve its hooks once; `import` backfills past sessions either way) — with token/cost tracking and automatically extracted decisions, bugs, and learnings. That always-on plane is **Keep Core**. On top of it, **Wend Runtime** provides a native, zero-dependency lifecycle (spec → change → TDD → sensor-gated archive), selected through the `OFF`, `FLOW`, `GUIDE`, `GOVERN`, and `ASSURE` Operating Profiles. 100% local, open-core.
 
+The runtime is being separated into six physical boundaries — `cli`, `harness`, `vault`, `mcp`,
+`integrations`, and `pi` — without fragmenting installation. The private `vault` workspace now
+canonically owns safe binding and the Shared Project Memory v2 kernel (schema, mode, handoff,
+ledger, projection, and validation), exposed by the root package through `wendkeep/vault`.
+Historical imports, including installed bare subpaths such as `wendkeep/hooks/...`, keep working
+through compatibility facades and no session data needs migration;
+see the [modular architecture](docs/en/architecture.md).
+
 ```bash
 npm i -D wendkeep && npx wendkeep init      # captures from the next session on
 npx wendkeep import                          # backfill past Claude + Codex sessions
@@ -244,9 +252,11 @@ lost publication, or mismatched checkpoint blocks. See [migration](docs/en/comma
 and [diagnostics](docs/en/commands/maintenance-and-diagnostics.md).
 
 If status blocks, preserve the evidence and run `wendkeep memory repair --vault <vault>` to back up
-the corrupt ledger, retain valid lines, and re-project. Repair never reclassifies attempts. A
-valid pre-0.59 causal checkpoint is CAS-migrated to the physical boundary with backup/audit. A
-demonstrably superseded ambiguity uses `memory reconcile <session> --by-session <successor>
+the corrupt ledger, retain valid lines, and re-project. Repair never reclassifies attempts. Valid
+pre-0.59 causal checkpoints and exactly re-derived assert-only historical prefixes are
+CAS-migrated on both the attempt and `memory_checkpoint` to the correct physical boundary with
+backup/audit; divergent mirrors fail closed. A demonstrably superseded
+ambiguity uses `memory reconcile <session> --by-session <successor>
 --reason <reason>` as a dry run and requires `--apply`; the decision is backed up and audited
 without rewriting ledger, CORE, or notes. Run `status --gate` again afterwards. Conflicts require
 explicit curation with `memory promote <id>` or `memory reject <id>`; doctor only diagnoses.

package/docs/en/commands/memory.md

@@ -47,8 +47,12 @@ npx wendkeep validate-memory --vault <v2-vault>
   mismatched checkpoint blocks; `degraded` with an intact outbox is a warning.
 - `memory repair` is structural only: it uses PID/token-owned locks, writes a `.bak`, retains
   valid events, and reprojects state. When it recognizes a valid pre-0.59 checkpoint whose cursor
-  is causal, it CAS-migrates it to the physical boundary with backup/audit; it never reclassifies
-  registry attempts or accepts a tuple that cannot be fully re-derived.
+  is causal, it CAS-migrates it to the physical boundary. It also recognizes an assert-only
+  historical prefix only when revision, cursor, hash, identity, turns, and the
+  `memory_checkpoint` mirror exactly reproduce the old semantics; the target is the current replay
+  of that prefix, without absorbing later events. Both paths CAS-check the attempt and mirror and
+  record backup/audit. Repair never reclassifies registry attempts or accepts a tuple, operation,
+  or mirror that cannot be fully re-derived.
 - `memory reconcile` is a dry run by default. `--apply` requires two named sessions plus a reason,
   CAS-checks the exact attempt, backs up the registry, and limits mutation to the ambiguous attempt
   and its successor. Replay is CORE-aware, checkpoints use the physical ledger cursor, and the

package/docs/pt-BR/commands/memory.md

@@ -47,8 +47,12 @@ npx wendkeep validate-memory --vault <cofre-v2>
   publicação perdida ou checkpoint divergente bloqueiam; `degraded` com outbox íntegra é warning.
 - `memory repair` é exclusivamente estrutural: trabalha sob locks com owner PID/token, salva
   `.bak`, retém eventos válidos e reprojeta. Quando reconhece um checkpoint pré-0.59 válido com
-  cursor causal, migra-o por CAS para a fronteira física e registra backup/auditoria; nunca
-  reclassifica attempts do registry nem aceita tuple que não seja rederivada integralmente.
+  cursor causal, migra-o por CAS para a fronteira física. Também reconhece um prefixo histórico
+  assert-only somente quando revision, cursor, hash, identidade, turns e o espelho
+  `memory_checkpoint` reproduzem exatamente a semântica antiga; o alvo é o replay atual daquele
+  prefixo, sem absorver eventos posteriores. Ambos os casos fazem CAS do attempt e do espelho e
+  registram backup/auditoria. O repair nunca reclassifica attempts do registry nem aceita tuple,
+  operação ou espelho que não seja rederivado integralmente.
 - `memory reconcile` é dry-run por padrão. `--apply` exige duas sessões nomeadas e motivo, faz CAS
   do attempt exato, salva backup do registry e limita a mutação ao attempt ambíguo e à sucessora.
   O replay é CORE-aware, usa cursor físico do ledger no checkpoint e não reescreve ledger, CORE ou

package/hooks/memory-handoff.mjs

@@ -1,199 +1 @@
-import { createHash } from 'node:crypto';
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { basename, join, relative } from 'node:path';
-
-import { sanitizeMemoryText } from './memory-schema.mjs';
-
-function canonicalValue(value) {
-  if (Array.isArray(value)) return value.map(canonicalValue);
-  if (!value || typeof value !== 'object') return value;
-  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalValue(value[key])]));
-}
-
-function eventId(context, memoryKey, value) {
-  const digest = createHash('sha256')
-    .update(JSON.stringify([
-      context.projectId,
-      context.identity?.canonicalConversationId,
-      context.activation?.id,
-      context.turn?.id,
-      memoryKey,
-      canonicalValue(value),
-    ]))
-    .digest('hex')
-    .slice(0, 24);
-  return `mem-${digest}`;
-}
-
-function makeEvent(context, { memoryKey, value, authority, evidence }) {
-  const cleanValue = typeof value === 'string' ? sanitizeMemoryText(value) : canonicalValue(value);
-  return {
-    v: 1,
-    event_id: eventId(context, memoryKey, cleanValue),
-    project_id: String(context.projectId || ''),
-    memory_key: memoryKey,
-    operation: 'assert',
-    value: cleanValue,
-    authority,
-    canonical_session_id: String(context.identity?.canonicalConversationId || ''),
-    activation_id: String(context.activation?.id || ''),
-    activation_epoch: Number(context.activation?.epoch || 0),
-    turn_sequence: Number(context.turn?.sequence || 0),
-    source_turn_id: String(context.turn?.id || ''),
-    observed_at: context.observedAt,
-    evidence: (evidence || []).filter(Boolean).map((item) => sanitizeMemoryText(item)),
-  };
-}
-
-function readJson(path) {
-  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; }
-}
-
-function filesBelow(dir, accept, found = []) {
-  let entries = [];
-  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return found; }
-  for (const entry of entries) {
-    const path = join(dir, entry.name);
-    if (entry.isDirectory()) filesBelow(path, accept, found);
-    else if (accept(entry.name)) found.push(path);
-  }
-  return found;
-}
-
-function vaultRel(vaultBase, path) {
-  return relative(vaultBase, path).replaceAll('\\', '/');
-}
-
-function nextActionFrom(summary) {
-  const match = String(summary || '').match(/(?:a\s+)?pr[oó]xima\s+(?:change\s+)?(?:ser[aá]|[ée]|:)\s+(?:a\s+)?([^.!?\n]+)/i);
-  if (!match) return null;
-  const text = sanitizeMemoryText(match[1].trim());
-  const id = text.normalize('NFD').replace(/[\u0300-\u036f]/g, '').toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 64);
-  return id && text ? { id, summary: text } : null;
-}
-
-export function collectLifecycleEvidence(vaultBase, { changeSlug = '', summary = '', noteRel = '' } = {}) {
-  const evidence = {};
-  const slug = String(changeSlug || '').trim();
-  if (slug) {
-    const changeRoots = ['08-Mudanças', '08-Changes'];
-    let archivedDir = '';
-    for (const root of changeRoots) {
-      const archive = join(vaultBase, root, '_arquivo');
-      let names = [];
-      try { names = readdirSync(archive, { withFileTypes: true }); } catch { /* absent locale */ }
-      const match = names.find((entry) => entry.isDirectory() && (entry.name === slug || entry.name.endsWith(`-${slug}`)));
-      if (match) { archivedDir = join(archive, match.name); break; }
-    }
-
-    const adrPattern = new RegExp(`^ADR-(\\d{4})-${slug.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\.md$`, 'i');
-    const adrPath = filesBelow(vaultBase, (name) => adrPattern.test(name))[0];
-    if (archivedDir && adrPath) {
-      const adr = (basename(adrPath).match(/^ADR-\d{4}/i) || [''])[0].toUpperCase();
-      evidence.change = { slug, status: 'archived', adr, path: vaultRel(vaultBase, adrPath) };
-      const verdictPath = join(archivedDir, 'verdict.json');
-      const verdict = readJson(verdictPath);
-      if (verdict && typeof verdict.ok === 'boolean' && Array.isArray(verdict.coverage)) {
-        evidence.verdict = {
-          ok: verdict.ok,
-          covered: verdict.coverage.filter((item) => item?.covered === true).length,
-          total: verdict.coverage.length,
-          path: vaultRel(vaultBase, verdictPath),
-        };
-      }
-      const sensorPath = join(archivedDir, 'evidencia.json');
-      const sensors = readJson(sensorPath);
-      if (Array.isArray(sensors) && sensors.length && sensors.every((item) => item?.status === 'green')) {
-        evidence.sensors = [...new Set(sensors.map((item) => String(item.id || '')).filter(Boolean))].sort();
-      }
-    }
-  }
-
-  const nextAction = nextActionFrom(summary);
-  if (nextAction) evidence.nextAction = nextAction;
-  const commit = String(summary || '').match(/\b[0-9a-f]{40}\b/i)?.[0];
-  if (commit) {
-    evidence.git = {
-      commit: commit.toLowerCase(),
-      pushed: !/(?:nenhum|sem)\s+push/i.test(String(summary || '')),
-      verified: false,
-      path: noteRel,
-    };
-  }
-  return evidence;
-}
-
-export function buildSessionMemoryEvents({
-  projectId,
-  identity,
-  activation,
-  turn,
-  noteRel,
-  observedAt,
-  summary,
-  evidence = {},
-}) {
-  const context = { projectId, identity, activation, turn, observedAt };
-  const events = [makeEvent(context, {
-    memoryKey: 'handoff.latest',
-    value: sanitizeMemoryText(summary),
-    authority: 'reported',
-    evidence: [noteRel],
-  })];
-
-  if (evidence.change?.slug && evidence.change?.status && evidence.change?.adr) {
-    events.push(makeEvent(context, {
-      memoryKey: `change.${evidence.change.slug}.status`,
-      value: { status: evidence.change.status, adr: evidence.change.adr },
-      authority: 'verified',
-      evidence: [evidence.change.path || evidence.change.adr],
-    }));
-  }
-
-  if (evidence.verdict?.path && typeof evidence.verdict.ok === 'boolean') {
-    events.push(makeEvent(context, {
-      memoryKey: 'quality.latest-verdict',
-      value: {
-        ok: evidence.verdict.ok,
-        covered: Number(evidence.verdict.covered || 0),
-        total: Number(evidence.verdict.total || 0),
-      },
-      authority: 'verified',
-      evidence: [evidence.verdict.path],
-    }));
-  }
-
-  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,
-    }));
-  }
-
-  if (evidence.git?.commit) {
-    events.push(makeEvent(context, {
-      memoryKey: 'git.local-head',
-      value: {
-        commit: evidence.git.commit,
-        pushed: Boolean(evidence.git.pushed),
-        push_status: evidence.git.pushed ? 'pushed' : 'nenhum push',
-      },
-      authority: evidence.git.verified === false ? 'reported' : 'verified',
-      evidence: [evidence.git.path || evidence.git.commit],
-    }));
-  }
-
-  if (evidence.nextAction?.id && evidence.nextAction?.summary) {
-    events.push(makeEvent(context, {
-      memoryKey: `next.${evidence.nextAction.id}`,
-      value: sanitizeMemoryText(evidence.nextAction.summary),
-      authority: 'verified',
-      evidence: [noteRel],
-    }));
-  }
-
-  return events;
-}
+export * from '../packages/vault/src/memory-handoff.mjs';

package/hooks/memory-mode.mjs

@@ -1,89 +1 @@
-import { readFileSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
-
-import { classifySharedMemory } from './memory-schema.mjs';
-import { assertVaultPathSafe } from './vault-path-safety.mjs';
-
-export const LEGACY_MEMORY_WARNING = 'Vault legado: CORE+DIGEST permanece ativo; execute `wendkeep memory migrate --apply` quando a curadoria estiver pronta.';
-
-function aliasBoundaryError(error) {
-  return error?.code === 'VAULT_PATH_UNSAFE'
-    && /link simbólico|junction|reparse|hardlink|nlink|redirecion|escapa logicamente/i
-      .test(String(error?.message || error));
-}
-
-function readText(vaultBase, path, label) {
-  try {
-    let checked = assertVaultPathSafe(vaultBase, path, { expectedType: 'file', label });
-    if (!checked.exists) return { exists: false, content: '', error: null };
-    checked = assertVaultPathSafe(vaultBase, checked.target, {
-      allowMissing: false, expectedType: 'file', label,
-    });
-    return { exists: true, content: readFileSync(checked.target, 'utf8'), error: null };
-  }
-  catch (error) {
-    if (aliasBoundaryError(error)) throw error;
-    return { exists: true, content: '', error };
-  }
-}
-
-function hasOutboxEvidence(vaultBase, path) {
-  try {
-    let checked = assertVaultPathSafe(vaultBase, path, {
-      expectedType: 'directory', label: 'outbox de memória',
-    });
-    if (!checked.exists) return false;
-    checked = assertVaultPathSafe(vaultBase, checked.target, {
-      allowMissing: false, expectedType: 'directory', label: 'outbox de memória',
-    });
-    const entries = readdirSync(checked.target, { withFileTypes: true });
-    for (const entry of entries) {
-      assertVaultPathSafe(vaultBase, join(checked.target, entry.name), {
-        allowMissing: false, label: `entrada ${entry.name} da outbox de memória`,
-      });
-    }
-    return entries.some((entry) => entry.isFile());
-  }
-  catch (error) {
-    if (aliasBoundaryError(error)) throw error;
-    return true;
-  }
-}
-
-function preflightOptionalMemoryFile(vaultBase, path, label) {
-  try { assertVaultPathSafe(vaultBase, path, { expectedType: 'file', label }); }
-  catch (error) {
-    if (aliasBoundaryError(error)) throw error;
-    // Ordinary unreadable/wrong-type layers preserve the existing degraded-mode contract.
-  }
-}
-
-/** A single, read-only mode decision shared by injection, health and SessionStop. */
-export function detectMemoryMode(vaultBase) {
-  const brain = join(vaultBase, '.brain');
-  assertVaultPathSafe(vaultBase, brain, {
-    expectedType: 'directory', label: 'raiz .brain da memória',
-  });
-  // Preflight the layers consumed immediately after mode detection by injection and Stop.
-  for (const name of ['CORE.md', 'PROJECT.json', 'DIGEST.md']) {
-    preflightOptionalMemoryFile(vaultBase, join(brain, name), `camada de memória ${name}`);
-  }
-  const shared = readText(vaultBase, join(brain, 'SHARED_MEMORY.md'), 'camada SHARED_MEMORY.md');
-  if (shared.error) return { mode: 'v2', reason: 'shared-unreadable' };
-  const classified = classifySharedMemory(shared.content);
-  if (classified.mode === 'v2') return classified;
-
-  const ledger = readText(vaultBase, join(brain, 'MEMORY_EVENTS.jsonl'), 'ledger MEMORY_EVENTS.jsonl');
-  if (ledger.error) return { mode: 'v2', reason: 'ledger-unreadable' };
-  const candidates = readText(
-    vaultBase, join(brain, 'MEMORY_CANDIDATES.jsonl'), 'sidecar MEMORY_CANDIDATES.jsonl',
-  );
-  if (candidates.error) return { mode: 'v2', reason: 'candidates-unreadable' };
-  const ledgerHasEvents = ledger.content.trim().length > 0;
-  const candidatesHaveEntries = candidates.content.trim().length > 0;
-  const outboxHasEvents = hasOutboxEvidence(vaultBase, join(brain, 'memory-outbox'));
-  if (ledgerHasEvents || candidatesHaveEntries || outboxHasEvents) {
-    return { mode: 'v2', reason: 'operational-evidence' };
-  }
-  return classified;
-}
+export * from '../packages/vault/src/memory-mode.mjs';