wowbagger 0.1.0-alpha.1

package/src/adapter/schema-helpers.js

@@ -0,0 +1,60 @@
+// Small schema-checking primitives shared by describe.js and core-probe.js.
+// Both files validate several exact-shape JSON objects (the describe
+// request, the static manifest, the dynamic describe result, and the core
+// capabilities probe) and need identical notions of "safe integer",
+// "exact member set", and "deep JSON equality" so the checks agree with
+// each other.
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+// `value` has exactly the `required` members, plus zero or more of the
+// `optional` members, and nothing else.
+export function hasExactMembers(value, required, optional = []) {
+  if (!isPlainObject(value)) {
+    return false;
+  }
+  const allowed = new Set([...required, ...optional]);
+  const present = Object.keys(value);
+  return present.every((key) => allowed.has(key)) && required.every((key) => present.includes(key));
+}
+
+export function isPositiveSafeInteger(value) {
+  return Number.isSafeInteger(value) && value > 0;
+}
+
+export function isNonNegativeSafeInteger(value) {
+  return Number.isSafeInteger(value) && value >= 0;
+}
+
+export function isNonEmptyString(value) {
+  return typeof value === 'string' && value.length > 0;
+}
+
+export function isAllBoolean(value) {
+  return Object.values(value).every((member) => typeof member === 'boolean');
+}
+
+// Recursively sorts object members by key and leaves everything else alone.
+// Array element order is deliberately untouched: two of sameJson's three call
+// sites compare arrays where order is significant (`adapter_contract_versions`
+// and `trusted_approval.sources`), so sorting elements would erase a real
+// difference. Object.fromEntries defines rather than assigns, so a member
+// named `__proto__` survives the rebuild instead of becoming a prototype.
+function canonicalize(value) {
+  if (Array.isArray(value)) {
+    return value.map(canonicalize);
+  }
+  if (value !== null && typeof value === 'object') {
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]));
+  }
+  return value;
+}
+
+// Deep JSON equality that treats member order as insignificant, per RFC 8259.
+// JSON.parse preserves the source member order, so two wire values carrying
+// the same map under different key orders would otherwise be falsely refused.
+export function sameJson(left, right) {
+  return JSON.stringify(canonicalize(left)) === JSON.stringify(canonicalize(right));
+}

package/src/claim-capabilities.js

@@ -0,0 +1,54 @@
+export function resolveWorkClaimCapability({ gitCommonDir, namespace = null }) {
+  if (!gitCommonDir) {
+    return {
+      supported: false,
+      api_version: 1,
+      mode: 'advisory',
+      claim_protected_publication: false,
+      fencing_enforced_at: 'none',
+      safe_exclusive_dispatch: false,
+    };
+  }
+  if (!namespace) {
+    return {
+      supported: true,
+      api_version: 1,
+      mode: 'advisory',
+      claim_protected_publication: false,
+      fencing_enforced_at: 'none',
+      safe_exclusive_dispatch: false,
+    };
+  }
+  return {
+    supported: true,
+    api_version: 1,
+    mode: 'merge-coordinated',
+    claim_protected_publication: true,
+    fencing_enforced_at: 'git-history-reconciliation',
+    safe_exclusive_dispatch: false,
+    write_paths: {
+      alternate: 'none',
+      claimed_publication_v1: 'git-journal-fence',
+      legacy_create_v1: 'reject-claimed-id',
+      legacy_transition_v1: 'reject-active-claim',
+    },
+  };
+}
+
+export function resolveClaimBackend({ gitCommonDir, namespace = null }) {
+  if (!gitCommonDir || !namespace) {
+    return {
+      name: 'local-filesystem',
+      coordination_scope: coordinationScope({ gitCommonDir }),
+    };
+  }
+  return {
+    name: 'local-filesystem-git-journal',
+    coordination_scope: 'shared-git-common-dir-serialized-journal',
+    ledger_binding: { mode: 'explicit-allowlist', namespaces: [namespace] },
+  };
+}
+
+export function coordinationScope({ gitCommonDir }) {
+  return gitCommonDir ? 'shared-git-directory-cooperative-writers' : 'same-working-copy-cooperative-writers';
+}

package/src/claim-coordinator.js

@@ -0,0 +1,85 @@
+
+import { claimJournalPath, replayClaimJournal } from './claim-journal.js';
+import { resolveWorkClaimCapability } from './claim-capabilities.js';
+import { readBack } from './claim-operations.js';
+import { reconcileClaimJournal } from './claim-publication.js';
+import { claimStorePath, resolveVerifiedGitCommonDir, withClaimLock } from './claim-store.js';
+import { readNamespace } from './namespace.js';
+
+export async function withLegacyMutationFence(ledgerDirectory, itemId, command, write) {
+  const gitCommonDir = await resolveVerifiedGitCommonDir(ledgerDirectory);
+  const namespace = gitCommonDir ? await readNamespace(ledgerDirectory) : null;
+  const capability = resolveWorkClaimCapability({ gitCommonDir, namespace });
+  if (!capability.claim_protected_publication) return write();
+
+  const storePath = claimStorePath(gitCommonDir, namespace);
+  const journalPath = claimJournalPath(gitCommonDir, namespace);
+  try {
+    return await withClaimLock(storePath, async () => {
+      const replayed = await replayClaimJournal(journalPath, namespace);
+      const reconciled = await reconcileClaimJournal({
+        ledgerDirectory,
+        gitCommonDir,
+        namespace,
+        replayed,
+        physicalNow: new Date().toISOString(),
+      });
+      if (reconciled.unsafe) {
+        return claimStoreUnavailable(command, 'publication-reconciliation-required', {
+          findings: reconciled.findings,
+        });
+      }
+      const observedAt = reconciled.observedAt;
+      const record = reconciled.state.claims.find((entry) => entry.item_id === itemId)
+        ?? { item_id: itemId, last_epoch: '0', active: null };
+      const mustRefuse = command === 'create-v1'
+        ? record.last_epoch !== '0'
+        : record.active !== null && observedAt < record.active.expires_at;
+      if (!mustRefuse) return write();
+      return legacyRefusal(command, namespace, itemId, observedAt, record);
+    });
+  } catch (error) {
+    return claimStoreUnavailable(command, error?.code === 'CLAIM_LOCK_HELD'
+      ? 'claim-store-locked'
+      : 'claim-store-unreadable');
+  }
+}
+
+function legacyRefusal(command, namespace, itemId, observedAt, record) {
+  const create = command === 'create-v1';
+  return {
+    exit: 4,
+    stdout: {
+      ok: false,
+      namespace: 'ledger-mutation',
+      command,
+      contract_version: 1,
+      state: 'unchanged',
+      error: {
+        code: create ? 'claimed-item-write-refused' : 'active-claim-write-refused',
+        message: create
+          ? 'Legacy create cannot write an item identity with claim history.'
+          : 'Legacy transition cannot write an item with an active claim.',
+        details: readBack(namespace, itemId, observedAt, record),
+      },
+    },
+  };
+}
+
+function claimStoreUnavailable(command, reason, details = {}) {
+  return {
+    exit: 6,
+    stdout: {
+      ok: false,
+      namespace: 'ledger-mutation',
+      command,
+      contract_version: 1,
+      state: 'unchanged',
+      error: {
+        code: 'claim-store-unavailable',
+        message: 'The durable claim store is unavailable.',
+        details: { reason, ...details },
+      },
+    },
+  };
+}

package/src/claim-journal.js

@@ -0,0 +1,236 @@
+import { constants } from 'node:fs';
+import { mkdir, open, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { validateClaimRequest } from './claim-request.js';
+
+import { advanceClockFloor, claimAcquire, claimRead, claimRelease, claimRenew } from './claim-operations.js';
+import { emptyClaimState } from './claim-store.js';
+
+const MAX_JOURNAL_ENTRIES = 65536;
+const MAX_JOURNAL_BYTES = 8388608;
+const MAX_RECONCILE_LOG_BYTES = MAX_JOURNAL_BYTES + 1024;
+const JOURNAL_ENTRY_TYPES = new Set([
+  'claim',
+  'clock',
+  'publish-final',
+  'publish-finalization',
+  'publish-intent',
+]);
+
+export function claimJournalPath(commonDir, namespace) {
+  return path.join(commonDir, 'wowbagger', namespace, 'journal.ndjson');
+}
+
+export function claimReconcileLogPath(repoRoot, namespace) {
+  return path.join(repoRoot, 'wowbagger', `reconcile-${namespace}.md`);
+}
+
+export async function appendClaimEntry(journalPath, entry) {
+  const entries = await readJournalEntries(journalPath);
+  if (entries.length >= MAX_JOURNAL_ENTRIES) throw journalCapacityExceeded();
+  const persisted = { seq: entries.length + 1, ...entry };
+  const line = `${JSON.stringify(persisted)}\n`;
+  const existingBytes = await fileSize(journalPath);
+  if (existingBytes + Buffer.byteLength(line) > MAX_JOURNAL_BYTES) throw journalCapacityExceeded();
+  await ensureDurableJournal(journalPath);
+  const handle = await open(journalPath, 'a');
+  try {
+    await handle.writeFile(line, 'utf8');
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  return persisted;
+}
+
+export async function replayClaimJournal(journalPath, namespace) {
+  const entries = await readJournalEntries(journalPath, namespace);
+  let state = emptyClaimState(namespace);
+  const operations = { acquire: claimAcquire, read: claimRead, release: claimRelease, renew: claimRenew };
+  for (const entry of entries) {
+    if (entry.type === 'clock') {
+      advanceClockFloor(state, entry.floor);
+    } else if (entry.type === 'claim' && Object.hasOwn(operations, entry.command)) {
+      state = operations[entry.command](state, entry.request, entry.physical_now).state;
+    }
+  }
+  return { state, entries };
+}
+
+export async function writeReconcileLog(logPath, namespace, entries) {
+  const mergeableEntries = entries.filter((entry) => entry.type !== 'publish-finalization');
+  const content = [
+    `# Wowbagger reconciliation log \`${namespace}\``,
+    '',
+    'Derived from the authoritative common-directory journal. Preserve sequence order when merging.',
+    '',
+    '```jsonl',
+    ...mergeableEntries.map((entry) => JSON.stringify(entry)),
+    '```',
+    '',
+  ].join('\n');
+  if (Buffer.byteLength(content) > MAX_RECONCILE_LOG_BYTES) throw journalCapacityExceeded();
+  await mkdir(path.dirname(logPath), { recursive: true });
+  const handle = await open(logPath,
+    constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW);
+  try {
+    await handle.writeFile(content, 'utf8');
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+async function readJournalEntries(journalPath, namespace = null) {
+  let source;
+  try {
+    const info = await stat(journalPath);
+    if (info.size > MAX_JOURNAL_BYTES) throw journalCapacityExceeded();
+    source = await readFile(journalPath, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') return [];
+    throw error;
+  }
+  const lines = source.split('\n').filter(Boolean);
+  if (lines.length > MAX_JOURNAL_ENTRIES) throw journalCapacityExceeded();
+  const entries = lines.map((line) => JSON.parse(line));
+  for (let index = 0; index < entries.length; index += 1) {
+    if (!Number.isSafeInteger(entries[index]?.seq) || entries[index].seq !== index + 1) {
+      throw journalInvalid('non-contiguous-sequence');
+    }
+    if (!JOURNAL_ENTRY_TYPES.has(entries[index].type)) {
+      throw journalInvalid('unknown-entry-type');
+    }
+    if (!validJournalEntry(entries[index], namespace)) {
+      throw journalInvalid('invalid-entry');
+    }
+  }
+  return entries;
+}
+
+async function ensureDurableJournal(journalPath) {
+  const journalDirectory = path.dirname(journalPath);
+  await mkdir(journalDirectory, { recursive: true });
+  const directories = [
+    path.dirname(path.dirname(journalDirectory)),
+    path.dirname(journalDirectory),
+    journalDirectory,
+  ];
+  for (const directory of new Set(directories)) {
+    await syncDirectory(directory);
+  }
+
+  let handle;
+  try {
+    handle = await open(journalPath, 'ax');
+  } catch (error) {
+    if (error?.code === 'EEXIST') return;
+    throw error;
+  }
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  await syncDirectory(journalDirectory);
+}
+
+async function syncDirectory(directory) {
+  const handle = await open(directory, 'r');
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+async function fileSize(file) {
+  try {
+    return (await stat(file)).size;
+  } catch (error) {
+    if (error?.code === 'ENOENT') return 0;
+    throw error;
+  }
+}
+
+function journalCapacityExceeded() {
+  const error = new Error('claim journal capacity exceeded');
+  error.code = 'CLAIM_JOURNAL_CAPACITY';
+  error.reason = 'journal-capacity-exceeded';
+  return error;
+}
+
+function journalInvalid(reason) {
+  const error = new Error('claim journal is invalid');
+  error.code = 'CLAIM_JOURNAL_INVALID';
+  error.reason = reason;
+  return error;
+}
+
+function validJournalEntry(entry, namespace) {
+  if (entry.type === 'clock') {
+    return typeof entry.now === 'string' && typeof entry.floor === 'string';
+  }
+  if (entry.type === 'claim') {
+    return ['acquire', 'read', 'release', 'renew'].includes(entry.command)
+      && typeof entry.physical_now === 'string'
+      && validateClaimRequest(entry.command, entry.request).length === 0
+      && (namespace === null || entry.request.ledger_namespace === namespace);
+  }
+  if (entry.type === 'publish-intent') {
+    return typeof entry.operation_id === 'string'
+      && typeof entry.operation_digest === 'string'
+      && typeof entry.item_id === 'string'
+      && typeof entry.expected_revision === 'string'
+      && typeof entry.candidate_sha256 === 'string'
+      && isRecord(entry.fence)
+      && (namespace === null || entry.fence.ledger_namespace === namespace)
+      && entry.fence.item_id === entry.item_id;
+  }
+  if (entry.type === 'publish-final') {
+    return typeof entry.operation_id === 'string'
+      && typeof entry.operation_digest === 'string'
+      && typeof entry.ledger_namespace === 'string'
+      && (namespace === null || entry.ledger_namespace === namespace)
+      && typeof entry.item_id === 'string'
+      && validPublicationOutcome(entry);
+  }
+  return typeof entry.operation_id === 'string'
+    && typeof entry.item_id === 'string'
+    && typeof entry.committed_revision === 'string'
+    && typeof entry.git_commit === 'string';
+}
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function validPublicationOutcome(entry) {
+  const outcome = entry.outcome;
+  if (!isRecord(outcome) || !Number.isInteger(outcome.exit) || !isRecord(outcome.stdout)) return false;
+  const stdout = outcome.stdout;
+  if (
+    stdout.namespace !== 'ledger-publication'
+      || stdout.command !== 'publish-claimed'
+      || stdout.contract_version !== 1
+      || stdout.operation_id !== entry.operation_id
+      || !['committed', 'unchanged', 'unknown'].includes(stdout.state)
+  ) return false;
+  if (stdout.ok === true) {
+    return outcome.exit === 0
+      && stdout.state === 'committed'
+      && isRecord(stdout.result)
+      && stdout.result.ledger_namespace === entry.ledger_namespace
+      && stdout.result.item_id === entry.item_id
+      && typeof stdout.result.committed_revision === 'string'
+      && isRecord(stdout.result.claim_fence)
+      && stdout.result.claim_fence.ledger_namespace === entry.ledger_namespace
+      && stdout.result.claim_fence.item_id === entry.item_id;
+  }
+  if (stdout.ok !== false || !isRecord(stdout.error)) return false;
+  const details = stdout.error.details;
+  return !isRecord(details)
+    || ((!Object.hasOwn(details, 'operation_id') || details.operation_id === entry.operation_id)
+      && (!Object.hasOwn(details, 'ledger_namespace') || details.ledger_namespace === entry.ledger_namespace)
+      && (!Object.hasOwn(details, 'item_id') || details.item_id === entry.item_id));
+}

package/src/claim-operations.js

@@ -0,0 +1,138 @@
+// src/claim-operations.js
+import { isDeepStrictEqual } from 'node:util';
+
+const MAX_EPOCH = 18446744073709551615n;
+
+export function advanceClockFloor(state, physicalNow) {
+  const floor = state.clock_floor;
+  const effective = floor === null || physicalNow > floor ? physicalNow : floor;
+  state.clock_floor = effective;
+  return effective;
+}
+
+export function findOrCreateClaim(state, itemId) {
+  let record = state.claims.find((entry) => entry.item_id === itemId);
+  if (!record) {
+    record = { item_id: itemId, last_epoch: '0', active: null };
+    state.claims.push(record);
+  }
+  return record;
+}
+
+export function readBack(namespace, itemId, observedAt, record) {
+  return {
+    ledger_namespace: namespace,
+    item_id: itemId,
+    observed_at: observedAt,
+    last_epoch: record.last_epoch,
+    active: record.active === null ? null : { ...record.active },
+  };
+}
+
+function success(command, request, observedAt, record, extra) {
+  return {
+    exit: 0,
+    stdout: {
+      ok: true,
+      namespace: 'work-claim',
+      command,
+      contract_version: 1,
+      state: 'committed',
+      result: { ...extra, read_back: readBack(request.ledger_namespace, request.item_id, observedAt, record) },
+    },
+  };
+}
+
+export function claimError(command, code, message, request, observedAt, record, exit = 4) {
+  return {
+    exit,
+    stdout: {
+      ok: false,
+      namespace: 'work-claim',
+      command,
+      contract_version: 1,
+      state: 'unchanged',
+      error: {
+        code,
+        message,
+        details: readBack(request.ledger_namespace, request.item_id, observedAt, record),
+      },
+    },
+  };
+}
+
+export function claimRead(state, request, physicalNow) {
+  const next = structuredClone(state);
+  const observedAt = advanceClockFloor(next, physicalNow);
+  const record = findOrCreateClaim(next, request.item_id);
+  return { state: next, envelope: success('read', request, observedAt, record, {}) };
+}
+
+export function addMilliseconds(instant, milliseconds) {
+  return new Date(Date.parse(instant) + milliseconds).toISOString();
+}
+
+export function claimAcquire(state, request, physicalNow) {
+  const next = structuredClone(state);
+  const observedAt = advanceClockFloor(next, physicalNow);
+  const record = findOrCreateClaim(next, request.item_id);
+  const observed = { last_epoch: record.last_epoch, active: record.active };
+  if (!isDeepStrictEqual(observed, { last_epoch: request.expected.last_epoch, active: request.expected.active })) {
+    return { state: next, envelope: claimError('acquire', 'claim-conflict',
+      'The observed claim state no longer matches this request.', request, observedAt, record) };
+  }
+  if (record.active !== null && observedAt < record.active.expires_at) {
+    return { state: next, envelope: claimError('acquire', 'claim-held',
+      'The item has an unexpired active claim.', request, observedAt, record) };
+  }
+  if (BigInt(record.last_epoch) >= MAX_EPOCH) {
+    return { state: next, envelope: claimError('acquire', 'epoch-exhausted',
+      'The epoch high-water mark is exhausted.', request, observedAt, record, 6) };
+  }
+  const epoch = (BigInt(record.last_epoch) + 1n).toString();
+  record.last_epoch = epoch;
+  record.active = {
+    owner_id: request.owner_id,
+    epoch,
+    issued_at: observedAt,
+    expires_at: addMilliseconds(observedAt, request.lease_duration_ms),
+  };
+  return { state: next, envelope: success('acquire', request, observedAt, record, { claim: { ...record.active } }) };
+}
+
+function tupleMatches(active, request) {
+  return active !== null
+    && active.owner_id === request.owner_id
+    && active.epoch === request.epoch
+    && active.expires_at === request.expected_expires_at;
+}
+
+function renewOrRelease(command, state, request, physicalNow, apply) {
+  const next = structuredClone(state);
+  const observedAt = advanceClockFloor(next, physicalNow);
+  const record = findOrCreateClaim(next, request.item_id);
+  if (!tupleMatches(record.active, request)) {
+    return { state: next, envelope: claimError(command, 'claim-conflict',
+      'The active claim tuple no longer matches this request.', request, observedAt, record) };
+  }
+  if (observedAt >= record.active.expires_at) {
+    return { state: next, envelope: claimError(command, 'claim-expired',
+      'The matching claim has expired.', request, observedAt, record) };
+  }
+  return apply(next, record, observedAt);
+}
+
+export function claimRenew(state, request, physicalNow) {
+  return renewOrRelease('renew', state, request, physicalNow, (next, record, observedAt) => {
+    record.active = { ...record.active, expires_at: addMilliseconds(observedAt, request.lease_duration_ms) };
+    return { state: next, envelope: success('renew', request, observedAt, record, { claim: { ...record.active } }) };
+  });
+}
+
+export function claimRelease(state, request, physicalNow) {
+  return renewOrRelease('release', state, request, physicalNow, (next, record, observedAt) => {
+    const released = { ...record.active };
+    record.active = null;
+    return { state: next, envelope: success('release', request, observedAt, record, { released_claim: released }) };
+  });
+}