rcf-lite 0.30.0 → 0.31.0

package/src/core/store/writer.js

@@ -52,6 +52,111 @@ function canonicalKind(kind) {
   return KIND_ALIASES[kind] ?? kind;
 }
 
+/**
+ * Fields the R1 create-replay compare ignores: every field the writer or
+ * a post-create side effect stamps on its own, never from the caller's
+ * input. A verbatim replay of a create must compare equal even after
+ * those stamps landed; every other field is deep-compared. Add a field
+ * here whenever a writer path or a post-create hook starts stamping one.
+ * Ruling R1 extension (PR 292 follow-up; list made exhaustive on the
+ * PR 293 landing review, d-2026-10-05-015 finding 2).
+ */
+export const REPLAY_IGNORE_FIELDS = Object.freeze([
+  // Writer clock: assembleBody / createCn stamp it on every create and
+  // strip any caller-supplied value (B1 fix).
+  'createdAt',
+  // Writer clock: stamped on every create and bumped by every update,
+  // including the classifier's own write-back below.
+  'updatedAt',
+  // REQ shape classifier (src/req-detection/persist.js
+  // classifyAndPersistReq): src/cli/create.js runs it after every
+  // `create req` and persists the block through updateDocument, so the
+  // first create leaves a field the replay body never carries.
+  'shapeClassification',
+]);
+const REPLAY_IGNORE_SET = new Set(REPLAY_IGNORE_FIELDS);
+
+/**
+ * Deep-equality over JSON-shaped values. Pure. Mirrors
+ * `src/define/ledgers.js` `deepEqual` so the R1 extension to `rcf
+ * define create` compares content the same way the add path does.
+ */
+function deepEqual(a, b) {
+  if (Object.is(a, b)) return true;
+  if (a === null || b === null) return false;
+  if (typeof a !== typeof b) return false;
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b) || a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i += 1) if (!deepEqual(a[i], b[i])) return false;
+    return true;
+  }
+  if (typeof a === 'object') {
+    if (typeof b !== 'object' || Array.isArray(b)) return false;
+    const ak = Object.keys(a);
+    const bk = Object.keys(b);
+    if (ak.length !== bk.length) return false;
+    for (const k of ak) if (!deepEqual(a[k], b[k])) return false;
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Compare an on-disk doc body to a would-be create body and return
+ * the sorted list of differing field keys. Ignores every field in
+ * REPLAY_IGNORE_FIELDS (writer- and classifier-owned stamps), so a
+ * verbatim replay does not show up as "updatedAt differs" or
+ * "shapeClassification differs". A key present on only one side counts as
+ * differing. R1 extension 2026-10-05 (PR 292 follow-up).
+ *
+ * @param {Record<string, unknown>} existing
+ * @param {Record<string, unknown>} candidate
+ * @returns {string[]}
+ */
+function diffDocFields(existing, candidate) {
+  /** @type {Set<string>} */
+  const differing = new Set();
+  const keys = new Set([...Object.keys(existing ?? {}), ...Object.keys(candidate ?? {})]);
+  for (const key of keys) {
+    if (REPLAY_IGNORE_SET.has(key)) continue;
+    if (!deepEqual(existing?.[key], candidate?.[key])) differing.add(key);
+  }
+  return [...differing];
+}
+
+/**
+ * Ruling R1 extension (PR 292 follow-up, amended on the PR 293 landing
+ * review): resolve a same-id create replay against the entry already on
+ * the tree. Returns null when the id is free; otherwise the
+ * `{ status: 'unchanged' }` result (identical content, nothing is
+ * written) or a `kind: 'conflict'` refusal naming the differing field
+ * keys (exit 3; never a silent overwrite). Shared by the document path
+ * (createDocument), the inline AC / TC paths and the CN path so every
+ * `rcf define create <kind> --id` follows one rule.
+ *
+ * @param {object} args
+ * @param {string} args.kind - the CLI kind, for the message
+ * @param {string} args.id
+ * @param {object | null | undefined} args.existing - the entry on the tree
+ * @param {object} args.candidate - the would-be entry
+ * @param {string} args.filePath - repo-relative file the entry lives in
+ * @param {object} [args.extra] - extra fields carried on the unchanged result
+ * @returns {object | null}
+ */
+function resolveReplay({ kind, id, existing, candidate, filePath, extra = {} }) {
+  if (!existing) return null;
+  const differing = diffDocFields(existing, candidate);
+  if (differing.length === 0) {
+    return { id, filePath, ...extra, body: existing, status: 'unchanged' };
+  }
+  return rcfError({
+    kind: 'conflict',
+    message: `create ${kind}: id ${id} already exists with different content; differing fields: ${differing.sort().join(', ')}. Use the update verb to patch.`,
+    documentId: id,
+    filePath,
+  });
+}
+
 // ---------------------------------------------------------------------------
 // B5: post-write validation gate
 // ---------------------------------------------------------------------------
@@ -496,17 +601,28 @@ export async function createDocument({ projectRoot, tree, kind, body, options =
     });
   }
 
-  // Allocate id (or take the override).
+  // Allocate id (or take the override). Ruling R1 2026-10-05 extended
+  // under w-2026-10-05-dave-013 (PR 292 follow-up): a replayed turn
+  // that carries `--id <existing>` with identical content is a no-op
+  // that returns `{ status: 'unchanged', body: existing }`; different
+  // content refuses with `kind: 'conflict'` naming the differing
+  // field keys. An unloadable (schema-invalid) doc still refuses
+  // unconditionally -- we cannot compare content against a doc we
+  // failed to load.
   let id = options.id;
+  /** @type {object | null} */
+  let existingDocForReplay = null;
   if (id) {
-    // B5: an unloadable (schema-invalid) doc still occupies its id.
-    if (tree.byId.has(id) || tree.invalidDocs?.has(id)) {
+    if (tree.invalidDocs?.has(id)) {
       return rcfError({
         kind: 'usage',
-        message: `create ${kind}: id ${id} is already taken`,
+        message: `create ${kind}: id ${id} is already taken (file on disk failed to load; repair before replaying)`,
         documentId: id,
       });
     }
+    if (tree.byId.has(id)) {
+      existingDocForReplay = tree.byId.get(id);
+    }
   } else {
     try {
       id = nextIdForKind(tree, canonical, { parentId });
@@ -528,7 +644,7 @@ export async function createDocument({ projectRoot, tree, kind, body, options =
       }
       providedOrder = maxOrder + 1;
     } else if (Number.isInteger(providedOrder)) {
-      const collision = siblings.find((sib) => sib.buildOrder === providedOrder);
+      const collision = siblings.find((sib) => sib.buildOrder === providedOrder && sib.fbsId !== id);
       if (collision) {
         return rcfError({
           kind: 'usage',
@@ -553,6 +669,16 @@ export async function createDocument({ projectRoot, tree, kind, body, options =
   });
   if (validation) return { ...validation, documentId: id };
 
+  // Ruling R1 extension 2026-10-05 (PR 292 follow-up): if the id
+  // already exists on the loaded tree, compare the would-be body to
+  // the existing doc (ignoring writer-owned timestamps) and either
+  // return `{ status: 'unchanged' }` or refuse with
+  // `kind: 'conflict'` naming the differing field keys.
+  const replay = resolveReplay({
+    kind, id, existing: existingDocForReplay, candidate: finalBody, filePath: relPath,
+  });
+  if (replay) return replay;
+
   // Cross-link ACs must resolve to existing ACs for fbs / ts.
   if (canonical === 'fbs' || canonical === 'testSuite') {
     const allAcIds = collectAllAcIds(tree);
@@ -644,10 +770,22 @@ async function createCn({ projectRoot, tree, options, body, walkErrors = [] }) {
     return rcfError({ kind: 'usage', message: 'create cn: --path is required' });
   }
 
+  // Ruling R1 extension (PR 293 landing review): a same-id replay is
+  // compared against the existing CN once the body is assembled below.
+  // An unloadable (schema-invalid) CN, or an id held by another kind,
+  // still refuses: there is no CN body to compare against.
   let id = options.id;
+  /** @type {object | null} */
+  let existingCnForReplay = null;
   if (id) {
-    if (tree.byId.has(id) || tree.invalidDocs?.has(id)) {
-      return rcfError({ kind: 'usage', message: `create cn: id ${id} is already taken`, documentId: id });
+    if (tree.invalidDocs?.has(id)) {
+      return rcfError({ kind: 'usage', message: `create cn: id ${id} is already taken (file on disk failed to load; repair before replaying)`, documentId: id });
+    }
+    if (tree.byId.has(id)) {
+      if (tree.kindById.get(id) !== 'codeNode') {
+        return rcfError({ kind: 'usage', message: `create cn: id ${id} is already taken`, documentId: id });
+      }
+      existingCnForReplay = tree.byId.get(id);
     }
   } else {
     id = nextIdForKind(tree, 'codeNode');
@@ -706,6 +844,11 @@ async function createCn({ projectRoot, tree, options, body, walkErrors = [] }) {
   const validation = validateDocument({ doc: finalBody, kind: 'codeNode', filePath: relPath });
   if (validation) return { ...validation, documentId: id };
 
+  const replay = resolveReplay({
+    kind: 'cn', id, existing: existingCnForReplay, candidate: finalBody, filePath: relPath,
+  });
+  if (replay) return replay;
+
   const absPath = pathForKindFile(projectRoot, 'codeNode', id);
   if (await fileExistsOnDisk(absPath)) {
     return rcfError({
@@ -919,12 +1062,14 @@ async function createInlineAc({ projectRoot, tree, options, body, walkErrors = [
   const seedIndex = detectSeededPhantomAcIndex(currentAcs, parentUsId);
   const replacingPhantom = seedIndex !== -1 && !options.id;
 
+  // Ruling R1 extension (PR 293 landing review): an explicit --id that
+  // already names an AC on the parent US is a replay, resolved against
+  // that AC once the would-be entry is built below.
   let acId = options.id;
+  /** @type {object | null} */
+  let existingAcForReplay = null;
   if (acId) {
-    const existing = currentAcs.some((ac) => ac.id === acId);
-    if (existing) {
-      return rcfError({ kind: 'usage', message: `create ac: id ${acId} already exists on ${parentUsId}`, documentId: acId });
-    }
+    existingAcForReplay = currentAcs.find((ac) => ac.id === acId) ?? null;
   } else if (replacingPhantom) {
     // Reuse the seed's id (AC-<us>-1) so the operator's first AC is -1.
     acId = currentAcs[seedIndex].id;
@@ -947,6 +1092,15 @@ async function createInlineAc({ projectRoot, tree, options, body, walkErrors = [
     // consumer, so we only serialise when the CLI passed a value.
     ...(body?.determinism !== undefined ? { determinism: body.determinism } : {}),
   };
+  const acReplay = resolveReplay({
+    kind: 'ac',
+    id: acId,
+    existing: existingAcForReplay,
+    candidate: acEntry,
+    filePath: `rcf/user-stories/${parentUsId.toLowerCase()}.json`,
+    extra: { parentId: parentUsId },
+  });
+  if (acReplay) return acReplay;
   const nextAcs = replacingPhantom
     ? currentAcs.map((ac, i) => (i === seedIndex ? acEntry : ac))
     : [...currentAcs, acEntry];
@@ -1073,9 +1227,14 @@ async function createInlineTc({ projectRoot, tree, options, body, walkErrors = [
     return rcfError({ kind: 'usage', message: `create tc: parent ${parentTsId} has an unrecognised id shape` });
   }
   const tcId = options.id ?? `TC-${tsSuffix}-${slug}`;
-  // Slug collision fails explicitly (§D10 OQ-P4-R-1).
   const existing = (ts.testCases ?? []).find((tc) => tc.id === tcId);
-  if (existing) {
+  // Ruling R1 extension (PR 293 landing review): idempotency is
+  // id-carried. An explicit --id that already names a TC on the parent
+  // TS is a replay, resolved against that TC once the would-be entry is
+  // built below. A derived-slug collision (no --id) still refuses
+  // explicitly (§D10 OQ-P4-R-1).
+  const replayingTc = Boolean(options.id) && Boolean(existing);
+  if (existing && !replayingTc) {
     return rcfError({
       kind: 'usage',
       message: `create tc: slug collision on ${tcId}, supply --slug explicitly`,
@@ -1089,6 +1248,15 @@ async function createInlineTc({ projectRoot, tree, options, body, walkErrors = [
     status: body?.status ?? 'pending',
     testPointer,
   };
+  const tcReplay = resolveReplay({
+    kind: 'tc',
+    id: tcId,
+    existing: replayingTc ? existing : null,
+    candidate: tcEntry,
+    filePath: `rcf/test-suites/${parentTsId.toLowerCase()}.json`,
+    extra: { parentId: parentTsId },
+  });
+  if (tcReplay) return tcReplay;
   const nextTs = {
     ...ts,
     testCases: [...(ts.testCases ?? []), tcEntry],

package/src/define/ledgers.js

@@ -102,7 +102,7 @@ export class LedgerError extends Error {
    * @param {string} message
    * @param {object} [opts]
    * @param {string} [opts.filePath]
-   * @param {'parseFailure' | 'schemaFailure' | 'ioFailure' | 'usage'} [opts.code]
+   * @param {'parseFailure' | 'schemaFailure' | 'ioFailure' | 'usage' | 'conflict'} [opts.code]
    * @param {string} [opts.field]
    */
   constructor(message, opts = {}) {
@@ -390,26 +390,105 @@ export function nextIdFor(name, body) {
  * updated body. Pure over its inputs (does not write to disk); the
  * CLI calls `saveLedger` with the result.
  *
+ * Ruling R1 2026-10-05 (w-2026-10-05-dave-001): `add` is idempotent by
+ * id. When `args.id` is set (the harness carries it on a replayed
+ * turn):
+ *   - no entry with that id exists: honour the override and add the
+ *     entry at that id (any gaps in the id sequence are legal; the
+ *     per-ledger validator enforces uniqueness, not contiguity);
+ *   - entry with that id exists and the content matches: return
+ *     `{ status: 'unchanged', body, entry }`, no new write;
+ *   - entry with that id exists and the content differs: throw a
+ *     `LedgerError` (code 'conflict') naming the id and the differing
+ *     field keys so the CLI exits 3. Update is a separate verb.
+ * When `args.id` is omitted the next id is minted as before (the
+ * pre-R1 behaviour; a replayed turn without a carried id still works
+ * but duplicates the entry at a new id, which is why the harness is
+ * responsible for threading --id back).
+ *
  * @param {object} args
  * @param {LedgerName} args.name
  * @param {Record<string, unknown[]>} args.body
  * @param {Record<string, unknown>} args.entry - fields other than id / addedAt / status
+ * @param {number} [args.id] - optional id override (R1)
  * @param {string} [args.now] - ISO timestamp; defaults to Date.now()
- * @returns {{ body: Record<string, unknown[]>, entry: Record<string, unknown> }}
+ * @returns {{ body: Record<string, unknown[]>, entry: Record<string, unknown>, status?: 'added' | 'unchanged' }}
  */
-export function addEntry({ name, body, entry, now }) {
+export function addEntry({ name, body, entry, id, now }) {
   const cfg = LEDGER_CONFIG[name];
   if (!cfg) throw new LedgerError(`Unknown ledger '${name}'.`, { code: 'usage' });
-  const id = nextIdFor(name, body);
+  const list = /** @type {any[]} */ (body[cfg.arrayKey] ?? []);
+  let resolvedId;
+  if (id !== undefined) {
+    if (!Number.isInteger(id) || id < 1) {
+      throw new LedgerError(`${name} add --id must be a positive integer, got ${id}.`, {
+        filePath: ledgerRelPath(name), field: 'id', code: 'usage',
+      });
+    }
+    const existing = list.find((e) => Number(e?.id) === Number(id));
+    if (existing) {
+      // R1 idempotency check: compare caller-supplied fields against the
+      // existing entry. `addedAt` and `status` default on first add, so
+      // they are compared only when the caller explicitly supplied them.
+      const differing = [];
+      for (const [key, value] of Object.entries(entry)) {
+        if (value === undefined) continue;
+        if (key === 'id') continue;
+        if (key === 'addedAt' || key === 'status') {
+          // Default values auto-populated on first add; skip unless the
+          // caller passed them explicitly AND they differ.
+          if (existing[key] !== value) differing.push(key);
+          continue;
+        }
+        if (!deepEqual(existing[key], value)) differing.push(key);
+      }
+      if (differing.length === 0) {
+        return { body, entry: existing, status: 'unchanged' };
+      }
+      throw new LedgerError(
+        `${name} ledger entry ${id} already exists with different content; differing fields: ${differing.sort().join(', ')}. Use the update verb to patch.`,
+        { filePath: ledgerRelPath(name), field: `id ${id}`, code: 'conflict' },
+      );
+    }
+    resolvedId = id;
+  } else {
+    resolvedId = nextIdFor(name, body);
+  }
   const full = {
-    id,
+    id: resolvedId,
     ...entry,
     addedAt: entry.addedAt ?? now ?? new Date().toISOString(),
     status: entry.status ?? 'open',
   };
-  const nextBody = { ...body, [cfg.arrayKey]: [...(body[cfg.arrayKey] ?? []), full] };
+  const nextBody = { ...body, [cfg.arrayKey]: [...list, full] };
   validateLedger(name, nextBody, ledgerRelPath(name));
-  return { body: nextBody, entry: full };
+  return { body: nextBody, entry: full, status: 'added' };
+}
+
+/**
+ * Deep-equality over JSON-shaped values. Used by R1's idempotency
+ * check to compare a caller-supplied field against the existing entry.
+ * Arrays and plain objects are compared structurally; primitives via
+ * Object.is. Pure.
+ */
+function deepEqual(a, b) {
+  if (Object.is(a, b)) return true;
+  if (a === null || b === null) return false;
+  if (typeof a !== typeof b) return false;
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b) || a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i += 1) if (!deepEqual(a[i], b[i])) return false;
+    return true;
+  }
+  if (typeof a === 'object') {
+    if (typeof b !== 'object' || Array.isArray(b)) return false;
+    const ak = Object.keys(a);
+    const bk = Object.keys(b);
+    if (ak.length !== bk.length) return false;
+    for (const k of ak) if (!deepEqual(a[k], b[k])) return false;
+    return true;
+  }
+  return false;
 }
 
 /**

package/src/mcp/tools.js

@@ -639,7 +639,7 @@ const DEFINITIONS = [
       properties: {
         kind: { type: 'string', enum: KIND_ENUM, description: 'Document kind' },
         parent: { type: 'string', description: 'Parent document id; required for every kind except cn (which has no parent)' },
-        id: { type: 'string', description: 'Override the auto-assigned id (refuses on collision)' },
+        id: { type: 'string', description: 'Override the auto-assigned id. Idempotent by id: an existing id with identical content is a no-op; different content refuses as a conflict naming the differing fields (use rcf_update to patch)' },
         title: { type: 'string', description: 'Required for req / us / tac / adr / fbs / ts' },
         description: { type: 'string', description: 'Required for ac / tc' },
         purpose: { type: 'string', description: 'Required for ts' },