wendkeep 0.80.2 → 0.85.0

package/src/sync-adapters.mjs

@@ -0,0 +1,188 @@
+import {
+  existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync,
+} from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+import {
+  applySyncEvent, canonicalSyncJson, createSyncState, resolveSyncConflict, validateSyncEvent,
+} from './sync-protocol.mjs';
+
+function adapterError(code, message) {
+  return Object.assign(new Error(message), { code });
+}
+
+function atomicJson(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', flag: 'wx' });
+    renameSync(temporary, path);
+  } finally {
+    if (existsSync(temporary)) rmSync(temporary, { force: true });
+  }
+}
+
+function parseLedger(path) {
+  if (!existsSync(path)) return [];
+  return readFileSync(path, 'utf8').split(/\r?\n/).filter(Boolean).map((line, index) => {
+    try { return JSON.parse(line); }
+    catch { throw adapterError('WENDKEEP_SYNC_BACKEND_CORRUPT', `backend event line ${index + 1} is corrupt`); }
+  });
+}
+
+function readState(path, projectId) {
+  if (!existsSync(path)) return createSyncState(projectId);
+  try {
+    const state = JSON.parse(readFileSync(path, 'utf8'));
+    if (state?.schema_version !== 1 || state?.project_id !== projectId) throw new Error('state identity mismatch');
+    return state;
+  } catch (error) {
+    throw adapterError('WENDKEEP_SYNC_BACKEND_CORRUPT', `backend state is corrupt: ${error.message}`);
+  }
+}
+
+function sleep(milliseconds) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+
+function withLock(path, operation, { timeoutMs = 5000, staleMs = 30000 } = {}) {
+  const started = Date.now();
+  mkdirSync(dirname(path), { recursive: true });
+  while (true) {
+    try { mkdirSync(path); break; }
+    catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      try {
+        if (Date.now() - statSync(path).mtimeMs > staleMs) {
+          rmSync(path, { recursive: true, force: true });
+          continue;
+        }
+      } catch (inspectError) {
+        if (inspectError?.code !== 'ENOENT') throw inspectError;
+        continue;
+      }
+      if (Date.now() - started >= timeoutMs) throw adapterError('WENDKEEP_SYNC_BACKEND_BUSY', 'backend lock is busy');
+      sleep(20);
+    }
+  }
+  try { return operation(); }
+  finally { rmSync(path, { recursive: true, force: true }); }
+}
+
+export function createFilesystemSyncAdapter(rootPath, { available = true } = {}) {
+  const root = resolve(rootPath);
+  const statePath = join(root, 'STATE.json');
+  const eventsPath = join(root, 'EVENTS.jsonl');
+  const lockPath = join(root, '.sync.lock');
+  const assertAvailable = () => {
+    if (!available) throw adapterError('WENDKEEP_SYNC_BACKEND_UNAVAILABLE', 'filesystem backend is unavailable');
+  };
+  return {
+    kind: 'filesystem',
+    id: `filesystem:${root}`,
+    async push(event) {
+      assertAvailable();
+      validateSyncEvent(event);
+      return withLock(lockPath, () => {
+        const events = parseLedger(eventsPath);
+        const state = readState(statePath, event.project_id);
+        const result = applySyncEvent(state, event);
+        if (!events.some((item) => item.event_id === event.event_id)) {
+          mkdirSync(root, { recursive: true });
+          const previous = existsSync(eventsPath) ? readFileSync(eventsPath, 'utf8') : '';
+          writeFileSync(eventsPath, `${previous}${canonicalSyncJson(event)}\n`, 'utf8');
+        }
+        atomicJson(statePath, state);
+        return result;
+      });
+    },
+    async pull({ cursor = 0, projectId = '' } = {}) {
+      assertAvailable();
+      const offset = Number(cursor);
+      if (!Number.isSafeInteger(offset) || offset < 0) throw adapterError('WENDKEEP_SYNC_CURSOR_INVALID', 'cursor is invalid');
+      const events = parseLedger(eventsPath);
+      const inferredProject = projectId || events[0]?.project_id || '';
+      const state = inferredProject ? readState(statePath, inferredProject) : null;
+      return {
+        schema_version: 1,
+        cursor: events.length,
+        events: events.slice(offset),
+        state,
+      };
+    },
+    async resolve(options = {}) {
+      assertAvailable();
+      return withLock(lockPath, () => {
+        const state = readState(statePath, options.projectId);
+        const result = resolveSyncConflict(state, options);
+        const previous = existsSync(eventsPath) ? readFileSync(eventsPath, 'utf8') : '';
+        writeFileSync(eventsPath, `${previous}${canonicalSyncJson(result.event)}\n`, 'utf8');
+        atomicJson(statePath, state);
+        return result;
+      });
+    },
+  };
+}
+
+function httpUrl(base, suffix) {
+  let parsed;
+  try { parsed = new URL(base); } catch { throw adapterError('WENDKEEP_SYNC_HTTP_URL_INVALID', 'HTTP backend URL is invalid'); }
+  if (!['http:', 'https:'].includes(parsed.protocol)) throw adapterError('WENDKEEP_SYNC_HTTP_URL_INVALID', 'HTTP backend must use HTTP(S)');
+  return `${parsed.href.replace(/\/$/, '')}/${suffix}`;
+}
+
+export function createHttpSyncAdapter({ url, fetchImpl = globalThis.fetch, headers = {} } = {}) {
+  if (typeof fetchImpl !== 'function') throw adapterError('WENDKEEP_SYNC_HTTP_UNAVAILABLE', 'fetch is unavailable');
+  const request = async (target, init) => {
+    let response;
+    try { response = await fetchImpl(target, init); }
+    catch { throw adapterError('WENDKEEP_SYNC_BACKEND_UNAVAILABLE', 'HTTP backend is unavailable'); }
+    if (!response?.ok) throw adapterError('WENDKEEP_SYNC_HTTP_FAILED', `HTTP backend returned ${response?.status || 'error'}`);
+    return response.json();
+  };
+  return {
+    kind: 'http',
+    id: `http:${syncHost(url)}`,
+    async push(event) {
+      validateSyncEvent(event);
+      return request(httpUrl(url, 'events'), {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...headers },
+        body: canonicalSyncJson(event),
+      });
+    },
+    async pull({ cursor = 0, projectId } = {}) {
+      const query = new URLSearchParams({ project_id: String(projectId || ''), cursor: String(cursor) });
+      return request(`${httpUrl(url, 'events')}?${query}`, { method: 'GET', headers: { ...headers } });
+    },
+    async resolve(options = {}) {
+      return request(httpUrl(url, 'conflicts/resolve'), {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...headers },
+        body: canonicalSyncJson(options),
+      });
+    },
+  };
+}
+
+function syncHost(value) {
+  try { return new URL(value).host; } catch { return 'invalid'; }
+}
+
+export async function pushSyncEvents({ adapter, events = [], onAcknowledged = async () => {} } = {}) {
+  if (!adapter?.push) throw adapterError('WENDKEEP_SYNC_ADAPTER_INVALID', 'sync adapter cannot push');
+  const results = [];
+  for (const event of events) {
+    const result = await adapter.push(event);
+    results.push(result);
+    if (['applied', 'duplicate', 'conflict', 'pending'].includes(result.status)) {
+      await onAcknowledged(event, result);
+    }
+  }
+  return results;
+}
+
+export async function pullSyncEvents({ adapter, cursor = 0, projectId = '' } = {}) {
+  if (!adapter?.pull) throw adapterError('WENDKEEP_SYNC_ADAPTER_INVALID', 'sync adapter cannot pull');
+  return adapter.pull({ cursor, projectId });
+}

package/src/sync-outbox.mjs

@@ -0,0 +1,155 @@
+import { existsSync, lstatSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  assertVaultPathSafe,
+  mkdirVaultPath,
+  VAULT_LOCK_BUSY,
+  withVaultPathLock,
+  writeVaultFileAtomic,
+} from '../packages/vault/src/vault-path-safety.mjs';
+import { canonicalSyncJson, createSyncState, validateSyncEvent } from './sync-protocol.mjs';
+
+const RUNTIME = ['.brain', 'runtime', 'sync'];
+const OUTBOX = 'OUTBOX.jsonl';
+const ACKS = 'ACKS.jsonl';
+const LOCAL_STATE = 'LOCAL_STATE.json';
+const CURSOR = 'CURSOR.json';
+
+function outboxError(code, message) {
+  return Object.assign(new Error(message), { code });
+}
+
+export function syncRuntimePaths(vaultBase) {
+  const directory = join(vaultBase, ...RUNTIME);
+  return {
+    directory, outbox: join(directory, OUTBOX), acks: join(directory, ACKS),
+    state: join(directory, LOCAL_STATE), cursor: join(directory, CURSOR),
+  };
+}
+
+function parseLines(bytes, label) {
+  const rows = [];
+  for (const [index, line] of String(bytes || '').split(/\r?\n/).entries()) {
+    if (!line.trim()) continue;
+    try { rows.push(JSON.parse(line)); }
+    catch { throw outboxError('WENDKEEP_SYNC_OUTBOX_CORRUPT', `${label} line ${index + 1} is invalid JSON`); }
+  }
+  return rows;
+}
+
+function safeRead(vaultBase, path, label) {
+  if (!existsSync(path)) return '';
+  let checked;
+  try { checked = assertVaultPathSafe(vaultBase, path, { expectedType: 'file', label }); }
+  catch (error) { throw outboxError('WENDKEEP_SYNC_OUTBOX_UNSAFE', error.message); }
+  return checked.exists ? readFileSync(checked.target, 'utf8') : '';
+}
+
+function appendUnique(vaultBase, path, record, idField) {
+  const { directory } = syncRuntimePaths(vaultBase);
+  mkdirVaultPath(vaultBase, directory, { label: 'sync runtime directory' });
+  const outcome = withVaultPathLock(vaultBase, path, () => {
+    const previous = safeRead(vaultBase, path, 'sync append-only ledger');
+    const rows = parseLines(previous, 'sync ledger');
+    if (rows.some((item) => item?.[idField] === record[idField])) return { created: false, record };
+    writeVaultFileAtomic(vaultBase, path, `${previous}${canonicalSyncJson(record)}\n`, 'utf8', {
+      label: 'sync append-only ledger',
+    });
+    return { created: true, record };
+  }, { code: 'WENDKEEP_SYNC_OUTBOX_BUSY' });
+  if (outcome === VAULT_LOCK_BUSY) throw outboxError('WENDKEEP_SYNC_OUTBOX_BUSY', 'sync ledger is busy');
+  return outcome;
+}
+
+export function enqueueSyncEvent(vaultBase, event) {
+  validateSyncEvent(event);
+  return appendUnique(vaultBase, syncRuntimePaths(vaultBase).outbox, event, 'event_id');
+}
+
+export function ackSyncEvent(vaultBase, eventId, {
+  observedAt = new Date().toISOString(), backend = '',
+} = {}) {
+  const id = String(eventId || '').trim();
+  if (!/^[a-f0-9]{64}$/.test(id)) throw outboxError('WENDKEEP_SYNC_ACK_INVALID', 'event id is invalid');
+  const record = {
+    schema_version: 1,
+    event_id: id,
+    acknowledged_at: new Date(observedAt).toISOString(),
+    backend: String(backend || '').slice(0, 120),
+  };
+  return appendUnique(vaultBase, syncRuntimePaths(vaultBase).acks, record, 'event_id');
+}
+
+export function readSyncOutbox(vaultBase) {
+  const paths = syncRuntimePaths(vaultBase);
+  const events = parseLines(safeRead(vaultBase, paths.outbox, 'sync outbox'), 'OUTBOX.jsonl');
+  for (const event of events) validateSyncEvent(event);
+  const acks = parseLines(safeRead(vaultBase, paths.acks, 'sync acknowledgements'), 'ACKS.jsonl');
+  const acknowledged = new Set(acks.map((item) => item.event_id));
+  return { events, acks, pending: events.filter((event) => !acknowledged.has(event.event_id)) };
+}
+
+export function readPendingSyncEvents(vaultBase) {
+  return readSyncOutbox(vaultBase).pending;
+}
+
+export function inspectSyncOutbox(vaultBase) {
+  const paths = syncRuntimePaths(vaultBase);
+  if (!existsSync(paths.directory)) return { status: 'disabled', events: 0, pending: 0, acknowledged: 0 };
+  try {
+    if (lstatSync(paths.directory).isSymbolicLink()) throw outboxError('WENDKEEP_SYNC_OUTBOX_UNSAFE', 'sync runtime is a symlink');
+    const state = readSyncOutbox(vaultBase);
+    return {
+      status: state.pending.length ? 'pending' : 'healthy',
+      events: state.events.length,
+      pending: state.pending.length,
+      acknowledged: state.acks.length,
+    };
+  } catch (error) {
+    return { status: 'corrupt', events: 0, pending: 0, acknowledged: 0, code: error.code || 'WENDKEEP_SYNC_OUTBOX_CORRUPT' };
+  }
+}
+
+export function readLocalSyncState(vaultBase, projectId) {
+  const path = syncRuntimePaths(vaultBase).state;
+  if (!existsSync(path)) return createSyncState(projectId);
+  try {
+    const state = JSON.parse(safeRead(vaultBase, path, 'local sync state'));
+    if (state?.schema_version !== 1 || state?.project_id !== projectId) throw new Error('identity mismatch');
+    return state;
+  } catch (error) {
+    throw outboxError('WENDKEEP_SYNC_STATE_CORRUPT', `local sync state is corrupt: ${error.message}`);
+  }
+}
+
+function writeRuntimeJson(vaultBase, path, value, label) {
+  const { directory } = syncRuntimePaths(vaultBase);
+  mkdirVaultPath(vaultBase, directory, { label: 'sync runtime directory' });
+  const outcome = withVaultPathLock(vaultBase, path, () => {
+    writeVaultFileAtomic(vaultBase, path, `${JSON.stringify(value, null, 2)}\n`, 'utf8', { label });
+    return value;
+  }, { code: 'WENDKEEP_SYNC_OUTBOX_BUSY' });
+  if (outcome === VAULT_LOCK_BUSY) throw outboxError('WENDKEEP_SYNC_OUTBOX_BUSY', 'sync runtime is busy');
+  return outcome;
+}
+
+export function writeLocalSyncState(vaultBase, state) {
+  return writeRuntimeJson(vaultBase, syncRuntimePaths(vaultBase).state, state, 'local sync state');
+}
+
+export function readSyncCursor(vaultBase) {
+  const path = syncRuntimePaths(vaultBase).cursor;
+  if (!existsSync(path)) return 0;
+  try {
+    const value = JSON.parse(safeRead(vaultBase, path, 'sync cursor'));
+    return Number.isSafeInteger(value?.cursor) && value.cursor >= 0 ? value.cursor : 0;
+  } catch { throw outboxError('WENDKEEP_SYNC_CURSOR_CORRUPT', 'local sync cursor is corrupt'); }
+}
+
+export function writeSyncCursor(vaultBase, cursor) {
+  if (!Number.isSafeInteger(cursor) || cursor < 0) throw outboxError('WENDKEEP_SYNC_CURSOR_INVALID', 'cursor is invalid');
+  return writeRuntimeJson(vaultBase, syncRuntimePaths(vaultBase).cursor, {
+    schema_version: 1, cursor,
+  }, 'sync cursor');
+}

package/src/sync-protocol-cli.mjs

@@ -0,0 +1,277 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+
+import { resolveProjectVault } from './project-vault.mjs';
+import { importPortableState } from './portable.mjs';
+import {
+  createFilesystemSyncAdapter, createHttpSyncAdapter, pullSyncEvents, pushSyncEvents,
+} from './sync-adapters.mjs';
+import {
+  applySyncEvent, canonicalRecordKey, createSyncEvent, syncSha256,
+} from './sync-protocol.mjs';
+import {
+  ackSyncEvent, enqueueSyncEvent, inspectSyncOutbox, readLocalSyncState,
+  readPendingSyncEvents, readSyncCursor, writeLocalSyncState, writeSyncCursor,
+} from './sync-outbox.mjs';
+
+const SUBCOMMANDS = new Set(['status', 'push', 'pull', 'conflicts', 'resolve']);
+
+function cliError(code, message) {
+  return Object.assign(new Error(message), { code });
+}
+
+function option(argv, name) {
+  const index = argv.indexOf(name);
+  if (index >= 0) return argv[index + 1] || '';
+  return argv.find((item) => item.startsWith(`${name}=`))?.slice(name.length + 1) || '';
+}
+
+function requiredOption(argv, name) {
+  const value = option(argv, name);
+  if (!value || value.startsWith('--')) throw cliError('WENDKEEP_SYNC_ARGUMENT_REQUIRED', `${name} is required`);
+  return value;
+}
+
+function readPortable(path) {
+  if (!existsSync(path)) throw cliError('WENDKEEP_SYNC_PORTABLE_MISSING', `portable state not found: ${path}`);
+  try {
+    const state = JSON.parse(readFileSync(path, 'utf8'));
+    if (state?.schema_version !== 1 || state?.kind !== 'wendkeep-portable-state'
+      || !Array.isArray(state.artifacts) || !Array.isArray(state.active_work)
+      || !state.project_id || !state.repository_id || !state.authored_sha256) throw new Error('schema mismatch');
+    return state;
+  } catch (error) {
+    throw cliError('WENDKEEP_SYNC_PORTABLE_INVALID', `portable state is invalid: ${error.message}`);
+  }
+}
+
+function branchForArtifact(state, path) {
+  const match = String(path).match(/^08-(?:Mudanças|Changes)\/([^/]+)\//);
+  if (!match) return '';
+  return state.active_work.find((item) => item.change_slug === match[1])?.branch || '';
+}
+
+function desiredRecords(state) {
+  const records = [{
+    namespace: 'portable-manifest', key: 'state', scope: 'project', branch: '',
+    payload: {
+      kind: 'manifest', project_id: state.project_id, repository_id: state.repository_id,
+      authored_sha256: state.authored_sha256,
+    },
+  }];
+  for (const artifact of state.artifacts) {
+    const branch = branchForArtifact(state, artifact.path);
+    records.push({
+      namespace: 'authored', key: artifact.path, scope: branch ? 'branch' : 'project', branch,
+      payload: { kind: 'artifact', value: artifact },
+    });
+  }
+  for (const activeWork of state.active_work) records.push({
+    namespace: 'active-work', key: activeWork.active_work_id, scope: 'branch', branch: activeWork.branch,
+    payload: { kind: 'active-work', value: activeWork },
+  });
+  return records;
+}
+
+export function portableStateToSyncEvents(state, localState, {
+  actorId, deviceId, observedAt = new Date().toISOString(),
+} = {}) {
+  const events = [];
+  for (const desired of desiredRecords(state)) {
+    const recordKey = canonicalRecordKey({
+      projectId: state.project_id,
+      repositoryId: state.repository_id,
+      namespace: desired.namespace,
+      key: desired.key,
+      branch: desired.branch,
+      scope: desired.scope,
+    });
+    const current = localState.records[recordKey];
+    if (current?.content_hash === syncSha256(desired.payload) && !current.tombstone) continue;
+    const baseRevision = Number(current?.revision || 0);
+    events.push(createSyncEvent({
+      projectId: state.project_id,
+      recordKey,
+      revision: baseRevision + 1,
+      baseRevision,
+      payload: desired.payload,
+      causalParentIds: current?.event_id ? [current.event_id] : [],
+      actorId,
+      deviceId,
+      observedAt,
+      operation: 'put',
+    }));
+  }
+  return events;
+}
+
+export function syncStateToPortableState(state) {
+  const open = Object.values(state.conflicts || {}).filter((item) => item.status === 'open');
+  if (open.length) throw cliError('WENDKEEP_SYNC_CONFLICT_OPEN', `${open.length} conflict(s) require explicit resolution`);
+  let manifest = null;
+  const artifacts = [];
+  const active_work = [];
+  for (const record of Object.values(state.records || {})) {
+    if (record.tombstone || record.conflicted) continue;
+    if (record.payload?.kind === 'manifest') manifest = record.payload;
+    else if (record.payload?.kind === 'artifact') artifacts.push(record.payload.value);
+    else if (record.payload?.kind === 'active-work') active_work.push(record.payload.value);
+  }
+  if (!manifest) throw cliError('WENDKEEP_SYNC_MANIFEST_MISSING', 'remote state has no portable manifest');
+  artifacts.sort((left, right) => left.path.localeCompare(right.path));
+  active_work.sort((left, right) => left.active_work_id.localeCompare(right.active_work_id));
+  return {
+    schema_version: 1,
+    kind: 'wendkeep-portable-state',
+    project_id: manifest.project_id,
+    repository_id: manifest.repository_id,
+    authored_sha256: manifest.authored_sha256,
+    artifacts,
+    active_work,
+  };
+}
+
+function adapterFrom(argv, projectRoot) {
+  const remote = option(argv, '--remote');
+  const url = option(argv, '--url');
+  if (remote && url) throw cliError('WENDKEEP_SYNC_BACKEND_AMBIGUOUS', 'choose --remote or --url');
+  if (remote) {
+    const path = isAbsolute(remote) ? resolve(remote) : resolve(projectRoot, remote);
+    return createFilesystemSyncAdapter(path);
+  }
+  if (url) {
+    const tokenEnv = option(argv, '--token-env');
+    const token = tokenEnv ? process.env[tokenEnv] : '';
+    return createHttpSyncAdapter({
+      url,
+      ...(token ? { headers: { authorization: `Bearer ${token}` } } : {}),
+    });
+  }
+  throw cliError('WENDKEEP_SYNC_BACKEND_REQUIRED', '--remote <path> or --url <https-url> is required');
+}
+
+function runtime(argv) {
+  const projectRoot = resolve(option(argv, '--project') || process.cwd());
+  const vaultBase = resolveProjectVault({
+    startDir: projectRoot,
+    explicitVault: option(argv, '--vault'),
+    validateIdentity: !option(argv, '--vault'),
+  }).base;
+  let projectId;
+  try { projectId = JSON.parse(readFileSync(join(vaultBase, '.brain', 'PROJECT.json'), 'utf8')).projectId; }
+  catch { throw cliError('WENDKEEP_SYNC_IDENTITY_UNAVAILABLE', 'PROJECT.json is unavailable'); }
+  return { projectRoot, vaultBase, projectId };
+}
+
+function openConflicts(state) {
+  return Object.values(state.conflicts || {}).filter((item) => item.status === 'open');
+}
+
+export const SYNC_PROTOCOL_HELP = `wendkeep sync <status|push|pull|conflicts|resolve> [options]
+
+  --remote <path>       filesystem backend (reference/local testing)
+  --url <https-url>     HTTP backend
+  --token-env <name>    read HTTP bearer token from an environment variable
+  --actor <id>          audited actor for push/resolve
+  --device <id>         audited device for push/resolve
+  --input <path>        portable state (default: .wendkeep/portable/state.json)
+  --select <event-id>   conflict candidate selected by resolve
+  --record <key>        canonical conflict record key
+  --reason <text>       audited resolution reason
+  --no-import           pull protocol state without importing authored files
+  --json                structured result
+`;
+
+export function isSyncProtocolCommand(argv = []) {
+  return SUBCOMMANDS.has(argv[0]);
+}
+
+export async function runSyncProtocol(argv = []) {
+  const sub = argv[0];
+  const json = argv.includes('--json');
+  try {
+    if (!SUBCOMMANDS.has(sub)) throw cliError('WENDKEEP_SYNC_SUBCOMMAND_INVALID', 'unknown sync protocol subcommand');
+    const { projectRoot, vaultBase, projectId } = runtime(argv);
+    let localState = readLocalSyncState(vaultBase, projectId);
+    let result;
+    if (sub === 'status') {
+      const outbox = inspectSyncOutbox(vaultBase);
+      result = { ok: true, enabled: outbox.status !== 'disabled', outbox, conflicts: openConflicts(localState).length };
+    } else if (sub === 'conflicts') {
+      result = { ok: true, conflicts: openConflicts(localState) };
+    } else if (sub === 'push') {
+      if (openConflicts(localState).length) {
+        throw cliError('WENDKEEP_SYNC_CONFLICT_OPEN', 'resolve local conflicts before pushing new revisions');
+      }
+      const adapter = adapterFrom(argv, projectRoot);
+      const input = resolve(option(argv, '--input') || join(projectRoot, '.wendkeep', 'portable', 'state.json'));
+      const portable = readPortable(input);
+      if (portable.project_id !== projectId) throw cliError('WENDKEEP_SYNC_PROJECT_MISMATCH', 'portable state belongs to another project');
+      const fresh = portableStateToSyncEvents(portable, localState, {
+        actorId: requiredOption(argv, '--actor'), deviceId: requiredOption(argv, '--device'),
+      });
+      for (const item of fresh) enqueueSyncEvent(vaultBase, item);
+      const pending = readPendingSyncEvents(vaultBase);
+      const pushed = await pushSyncEvents({
+        adapter, events: pending,
+        onAcknowledged: async (item) => { ackSyncEvent(vaultBase, item.event_id, { backend: adapter.id }); },
+      });
+      const cursor = readSyncCursor(vaultBase);
+      const pulled = await pullSyncEvents({ adapter, cursor, projectId });
+      if (pulled.state?.project_id && pulled.state.project_id !== projectId) {
+        throw cliError('WENDKEEP_SYNC_PROJECT_MISMATCH', 'remote state belongs to another project');
+      }
+      if (pulled.state) localState = pulled.state;
+      else for (const item of pulled.events || pending) applySyncEvent(localState, item);
+      writeLocalSyncState(vaultBase, localState);
+      writeSyncCursor(vaultBase, Number(pulled.cursor || cursor));
+      result = {
+        ok: true, generated: fresh.length, pushed: pushed.length, results: pushed,
+        conflicts: openConflicts(localState).length,
+      };
+    } else if (sub === 'pull') {
+      const adapter = adapterFrom(argv, projectRoot);
+      const cursor = readSyncCursor(vaultBase);
+      const pulled = await pullSyncEvents({ adapter, cursor, projectId });
+      if (pulled.state?.project_id && pulled.state.project_id !== projectId) {
+        throw cliError('WENDKEEP_SYNC_PROJECT_MISMATCH', 'remote state belongs to another project');
+      }
+      if (pulled.state) localState = pulled.state;
+      else for (const item of pulled.events || []) applySyncEvent(localState, item);
+      writeLocalSyncState(vaultBase, localState);
+      writeSyncCursor(vaultBase, Number(pulled.cursor || cursor));
+      let imported = null;
+      if (!argv.includes('--no-import') && Object.keys(localState.records || {}).length) {
+        imported = importPortableState({
+          vaultBase, projectRoot, state: syncStateToPortableState(localState),
+        });
+      }
+      result = { ok: true, received: (pulled.events || []).length, cursor: pulled.cursor, imported, conflicts: openConflicts(localState).length };
+    } else {
+      const adapter = adapterFrom(argv, projectRoot);
+      const resolution = await adapter.resolve({
+        projectId,
+        recordKey: requiredOption(argv, '--record'),
+        selectedEventId: requiredOption(argv, '--select'),
+        actorId: requiredOption(argv, '--actor'),
+        deviceId: requiredOption(argv, '--device'),
+        reason: requiredOption(argv, '--reason'),
+      });
+      const pulled = await pullSyncEvents({ adapter, cursor: 0, projectId });
+      if (pulled.state) writeLocalSyncState(vaultBase, pulled.state);
+      writeSyncCursor(vaultBase, Number(pulled.cursor || 0));
+      result = { ok: true, resolution: resolution.decision || resolution };
+    }
+    if (json) process.stdout.write(`${JSON.stringify(result)}\n`);
+    else if (sub === 'status') process.stdout.write(`sync protocol: ${result.enabled ? 'enabled' : 'disabled'} · pending ${result.outbox.pending} · conflicts ${result.conflicts}\n`);
+    else if (sub === 'conflicts') process.stdout.write(`sync conflicts: ${result.conflicts.length}\n`);
+    else if (sub === 'push') process.stdout.write(`sync push: ${result.pushed} event(s) acknowledged\n`);
+    else if (sub === 'pull') process.stdout.write(`sync pull: ${result.received} event(s), ${result.conflicts} conflict(s)\n`);
+    else process.stdout.write('sync conflict resolved\n');
+    return 0;
+  } catch (error) {
+    const payload = { ok: false, code: error?.code || 'WENDKEEP_SYNC_FAILED', error: String(error?.message || error) };
+    process.stderr.write(json ? `${JSON.stringify(payload)}\n` : `wendkeep sync: ${payload.code}: ${payload.error}\n`);
+    return payload.code === 'WENDKEEP_SYNC_BACKEND_UNAVAILABLE' ? 1 : 2;
+  }
+}