Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
56.9 KB
Raw Blame
/**
 * Kernel 2: atomic multi-operation write core.
 *
 * Generalises the validate-project-commit shape of
 * {@link applyPinnedOperations} (pinned.ts) into a core that executes an
 * ordered list of typed write operations all-or-nothing. Every operation
 * is validated and projected against the current disk state in memory
 * FIRST; only if every operation passes does the core commit them, in
 * order. The first invalid operation aborts with a typed
 * {@link WriteBatchError} that names the offending operation index, and
 * no disk write happens - so a later invalid operation never lets an
 * earlier one land.
 *
 * The core takes typed operations only; MCP layers map their request
 * params onto these types (no MCP shapes leak in here). The note write
 * operations reuse the exact create-note safety envelope
 * ({@link resolveNoteTarget}) and the atomic-write pipeline, so a
 * single-operation update or append that fails mid-write leaves its
 * target byte-identical.
 *
 * Atomicity model: this is validate-all-then-commit, matching the pinned
 * batch. Full multi-file rollback of a fault that strikes DURING the
 * commit phase (e.g. ENOSPC after the first of several files is written)
 * is not attempted - the guarantee is that a detectable-invalid operation
 * aborts the batch before ANY write. Each individual file write is atomic
 * (temp file + rename), so no single target is ever left half-written.
 */

import { existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
import { dirname, join, relative } from "node:path";

import type { FrontmatterMap } from "../types.ts";
import { atomicWriteFileSync } from "../fs-atomic.ts";
import {
  CreateNoteError,
  createNote,
  logWatchedNoteOwnerWrite,
  noteOwnerGateVerdict,
  resolveNoteTarget,
} from "./notes/create-note.ts";
import { refuseBlankOverwrite } from "./notes/blank-overwrite-guard.ts";
import {
  NOTE_WRITE_OP,
  recordNoteWrite,
  storeBeforeImage,
  type NoteWriteOp,
} from "./notes/write-record.ts";
import { formatFrontmatter, parseFrontmatterWithNotices } from "../vault.ts";
import { hasPrivacyDenyMarker, PRIVACY_MARKER_KEYS } from "../graph/privacy-markers.ts";
import { normToken } from "../graph/visibility.ts";
import { DEGRADATION_CODE } from "../integrity/degradation.ts";
import { writePathAdvisoryField, type WritePathAdvisoryField } from "./write-path-advisory.ts";
import {
  appendApplyEvidence,
  isApplyEvidenceTargetPresent,
  type AppendApplyEvidenceInput,
  type AppendApplyEvidenceOptions,
} from "./apply-evidence.ts";
import { appendBrainNote, type AppendBrainNoteInput } from "./note.ts";
import { ORIGIN_CHANNEL, ORIGIN_CHANNEL_FIELD, originChannelStamp } from "../origin-channel.ts";
import { CONTENT_CLASS_FIELD } from "./provenance/content-class.ts";
import { preferencePath, validateSlug } from "./paths.ts";
import { refuseDocumentDeny, type WriteSubject } from "./write-disposition.ts";
import { REVIEW_LANE } from "./write-gate.ts";
import { assertVaultIdentityForWrite } from "./vault-identity.ts";
import { writeBatchPrivacy } from "./write-batch-privacy.ts";
import type { OperationPrivacy } from "../store/operation-privacy.ts";
import { withOperationPrivacy } from "../store/operation-scope.ts";
import { BRAIN_APPLY_RESULT } from "./types.ts";
import { ROUTE_STAGE, timeStageSync } from "../route-scope.ts";
import {
  computePayloadHash,
  IdempotencyPayloadMismatchError,
  lookupKey,
  REMEMBER_KEY_STATUS,
  rememberKey,
  type RememberKeyStatus,
} from "./idempotency-ledger.ts";

/** Separator inserted between the existing body and appended text. */
const APPEND_SEPARATOR = "\n\n";

/**
 * Upper bound on operations in a single batch. Each committed operation
 * performs synchronous file I/O (read + atomic temp-file + rename), which
 * blocks the event loop for the duration of the whole batch; an unbounded
 * batch would let one caller stall the server. 100 is comfortably above any
 * legitimate batch while capping the worst-case blocking window.
 */
export const MAX_BATCH_OPERATIONS = 100;

/**
 * The idempotency-ledger key space of write-batch request IDs. Request IDs
 * come from a different client vocabulary than the `idempotency_key` of
 * brain_feedback and apply-evidence, so they live in their own namespace:
 * the same string supplied to both tools never collides.
 */
const WRITE_BATCH_KEY_NAMESPACE = "write_batch";

/**
 * What a request receipt says about the call that returned it:
 * - `applied`: this call committed the batch and recorded the ID.
 * - `duplicate`: the ID was already recorded with the same payload; this
 *   call wrote nothing and every other result field is the retained
 *   receipt of the call that committed.
 * - `concurrent_duplicate`: this call committed the batch, but a concurrent
 *   call recorded the same ID with the same payload between this call's
 *   consult and its record. Both calls' writes landed; the result fields
 *   are this call's own.
 * - `payload_conflict`: this call committed the batch - its writes landed
 *   and the result fields are this call's own - but a concurrent call
 *   recorded the same ID with a DIFFERENT payload between this call's
 *   consult and its record. The ID stays bound to that other payload, so
 *   this call's receipt was not recorded and a retry under the same ID is
 *   refused as a mismatch. Never retry this batch under a new ID: it is
 *   already applied.
 */
export const WRITE_BATCH_RECEIPT_STATUS = Object.freeze({
  applied: "applied",
  duplicate: "duplicate",
  concurrent_duplicate: "concurrent_duplicate",
  payload_conflict: "payload_conflict",
} as const);

export type WriteBatchReceiptStatus =
  (typeof WRITE_BATCH_RECEIPT_STATUS)[keyof typeof WRITE_BATCH_RECEIPT_STATUS];

/**
 * Create a new vault note. Refuses to clobber an existing file. Maps to
 * the {@link createNote} core writer.
 */
export interface CreateNoteOperation {
  readonly kind: "create_note";
  readonly path: string;
  readonly frontmatter?: FrontmatterMap;
  readonly content?: string;
}

/**
 * Update an EXISTING note: merge `frontmatter` keys into the current
 * frontmatter and/or replace the body with `body`. At least one of the
 * two must be present.
 */
export interface UpdateNoteOperation {
  readonly kind: "update_note";
  readonly path: string;
  readonly frontmatter?: FrontmatterMap;
  readonly body?: string;
  /**
   * Permit `body` to be blank, clearing the note's contents. Default
   * false: see {@link refuseBlankOverwrite}, which exists because an
   * accidentally-empty body is byte-identical to a deliberate clear.
   */
  readonly allowEmpty?: boolean;
}

/** Append `content` to the body of an EXISTING note. */
export interface AppendNoteOperation {
  readonly kind: "append_note";
  readonly path: string;
  readonly content: string;
}

/**
 * Record one apply-evidence event against a preference. Maps to the
 * {@link appendApplyEvidence} core writer; the kernel only pre-validates
 * so an invalid op aborts the batch before any commit.
 */
export interface ApplyEvidenceOperation {
  readonly kind: "apply_evidence";
  readonly input: AppendApplyEvidenceInput;
  readonly options?: AppendApplyEvidenceOptions;
}

/**
 * Append one narrative note line to today's Brain log. Maps to the
 * {@link appendBrainNote} core writer. `vault` is supplied by the batch.
 */
export interface AppendLogLineOperation {
  readonly kind: "append_log_line";
  readonly input: Omit<AppendBrainNoteInput, "vault">;
}

/** Typed operation the write-batch core understands. */
export type WriteOperation =
  | CreateNoteOperation
  | UpdateNoteOperation
  | AppendNoteOperation
  | ApplyEvidenceOperation
  | AppendLogLineOperation;

/** Machine-readable reason a write batch was refused. */
export type WriteBatchErrorCode =
  | "invalid_operation"
  | "invalid_path"
  | "excluded"
  | "outside_vault"
  | "exists"
  | "target_missing"
  // nothing-writes-silently, unit B. The target exists and the process
  // could not read it (a permission bit, a directory in its place, a
  // transient I/O fault, a file mid-sync). Until this code existed the
  // parser resolved that to `[{}, ""]` and the projection believed it:
  // an update then wrote the caller's body over an empty frontmatter
  // map and reported `updated: true`, and an append wrote just the
  // appended text over a body it never saw. Read failure is now a
  // refusal that names the path and the reason. On Windows it also
  // covers a note carrying the read-only attribute, which the rewrite's
  // rename could not replace (see `refuseReadOnlyAttribute`).
  | "target_unreadable"
  // nothing-writes-silently, unit B. The target was read and the
  // frontmatter scanner reported a line it could not express as a
  // key/value pair or a list item, so that line is absent from the parsed
  // map. Both update and append re-serialise that map over the file, so
  // proceeding would delete the line and answer `updated: true` - the
  // same loss `target_unreadable` refuses, on the half of the read the
  // parser DID manage. The operator's way through is to fix the
  // frontmatter the scanner names.
  | "target_frontmatter_lossy"
  // nothing-writes-silently, unit B. The update would replace a body
  // that carries text with a blank one. See
  // {@link refuseBlankOverwrite}; `allowEmpty` is the way through.
  | "blank_overwrite_refused"
  // The caller's frontmatter names a key the server owns. `visibility`
  // is the read-boundary token field (private-is-not-a-suggestion), and
  // `origin_channel` is the server-derived transport stamp that creation
  // writes and mutation deliberately never re-stamps. The update merge
  // is `{...existing, ...caller}` - caller wins - so leaving these keys
  // free would let one update demote a private page out of the boundary
  // or forge the creating channel. The operator edits them in the file,
  // where the boundary's authority lives.
  | "reserved_frontmatter_key"
  | "duplicate_target"
  | "too_many_operations"
  | "preference_not_found"
  // provenance-at-the-boundary, unit B. Propagated from the shared
  // create-note envelope by `envelopeError`, which preserves the
  // envelope's code rather than flattening every refusal into
  // `invalid_operation`. The check runs in the projection phase, so an
  // operation outside the operator's declared binding aborts the whole
  // batch before any commit - including the operations that WERE
  // admitted.
  | "write_binding"
  // provenance-at-the-boundary, unit C. Declared because
  // `envelopeError` preserves whatever code the shared create-note
  // envelope raises, so the two unions have to stay in step. Neither is
  // reachable from a batch today: `create_note` operations expose
  // neither the `strict` validator nor template-mode bodies, and they
  // are not going to. A batch is all-or-nothing, and per-operation
  // authoring modes - above all `if_exists: "skip"` - would make one
  // `applied` count mean two different things in one result list. The
  // batch keeps refusing an occupied target outright.
  | "invalid_document"
  | "invalid_template"
  // The vault's `Brain/_brain.yaml` exists and does not validate, so
  // neither the vault scope nor the write binding can be determined.
  // Propagated from the same envelope: no operation in the batch can be
  // projected, and the operator - not the caller - holds the fix.
  | "config_invalid"
  // write-side-trust, Task 13. An operation's frontmatter names an
  // `owner` the owner-write gate refuses (`integrity.owner_scope_writes`:
  // fail, or a permissions-document `owner_write` verdict of deny/ask) -
  // the same claim the create envelope refuses, carried under the same
  // token so the two note-lane refusals read as one rule. The gate runs
  // before the existing note is read, so the refusal answers the claim
  // and never the question of whether the target exists.
  | "owner_write_refused";

/**
 * All-or-nothing failure for {@link applyWriteBatch}. Thrown during the
 * validate/project phase, before any commit, so the vault is guaranteed
 * unchanged. Carries the offending operation `index` (`-1` for
 * batch-level failures) and machine-readable `details` so an MCP layer
 * can surface a structured rejection.
 */
export class WriteBatchError extends Error {
  readonly code: WriteBatchErrorCode;
  readonly index: number;
  readonly details: Readonly<Record<string, unknown>>;

  constructor(
    code: WriteBatchErrorCode,
    index: number,
    message: string,
    details: Readonly<Record<string, unknown>> = {},
  ) {
    super(message);
    this.name = "WriteBatchError";
    this.code = code;
    this.index = index;
    this.details = details;
  }
}

/**
 * The audit half every note-write result carries (who-wrote-what, Task A).
 *
 * `write_id` names the `note-write` event that attributes the write; it is
 * null when the bytes landed and the event could not be appended, and in
 * that case - and only that case - `audit_reason` says why. The two travel
 * together so a caller can never read an unrecorded write as a recorded
 * one.
 */
export interface NoteWriteAudit {
  readonly write_id: string | null;
  readonly audit_reason?: string;
}

/**
 * The advisory half every note-write result MAY carry (p4
 * silent-failure-hardening, Task 3): the absolute home paths the call's
 * authored content embeds. Byte-identical-when-absent - the key is simply
 * not there for a clean write - and never a refusal: the write lands and
 * the receipt says what it embeds. Log-line and evidence ops author no
 * note content and never carry it.
 */
export type NoteWriteAdvisory = WritePathAdvisoryField;

/**
 * Per-operation outcome, discriminated by `kind`.
 *
 * The update and append arms split on their flag so a caller cannot read
 * a write that did not happen as one that did: `updated: true` /
 * `appended: true` always carry the audit half (an id, or null plus the
 * reason there is none), while the `false` arms carry no audit fields at
 * all - a skipped write stored no before-image and recorded no event, so
 * there is no null that could be mistaken for a lost one, the same shape
 * the create skip spells. Both arms carry the advisory: the caller
 * authored that content either way.
 *
 * The create arm splits the same way since the review gate (write-side
 * trust, Task 9): `created: true` published; `created: false` with
 * `staged: true` staged the exact bytes into the review queue under
 * `pending_id` - a staged create never touches the real path, which is
 * why the validate-all-then-commit kernel is untouched by it.
 */
export type WriteBatchOpResult =
  | ({
      readonly kind: "create_note";
      readonly path: string;
      readonly created: true;
    } & NoteWriteAudit &
      NoteWriteAdvisory)
  | ({
      readonly kind: "create_note";
      readonly path: string;
      /** The create was staged for review, not published. */
      readonly created: false;
      readonly staged: true;
      /** Id of the pending queue entry holding the staged bytes. */
      readonly pending_id: string;
    } & NoteWriteAdvisory)
  | ({
      readonly kind: "update_note";
      readonly path: string;
      readonly updated: true;
    } & NoteWriteAudit &
      NoteWriteAdvisory)
  | ({
      readonly kind: "update_note";
      readonly path: string;
      /** The target already held these bytes; nothing was written. */
      readonly updated: false;
    } & NoteWriteAdvisory)
  | ({
      readonly kind: "append_note";
      readonly path: string;
      readonly appended: true;
    } & NoteWriteAudit &
      NoteWriteAdvisory)
  | ({
      readonly kind: "append_note";
      readonly path: string;
      /** The target already held the would-be result; nothing was written. */
      readonly appended: false;
    } & NoteWriteAdvisory)
  | { readonly kind: "apply_evidence"; readonly logged_at: string; readonly log_path: string }
  | { readonly kind: "append_log_line"; readonly logged_at: string; readonly log_path: string };

export interface WriteBatchResult {
  /** Number of operations committed (== operations.length on success). */
  readonly applied: number;
  /** One result per operation, in input order. */
  readonly results: ReadonlyArray<WriteBatchOpResult>;
  /** Terminal success marker: the batch committed, do not re-call. */
  readonly done: true;
  /**
   * Present exactly when the caller supplied a request ID (see
   * {@link ReceiptedWriteBatchResult}); {@link WRITE_BATCH_RECEIPT_STATUS}
   * names what each status means.
   */
  readonly receipt?: WriteBatchReceipt;
}

/** The request-receipt block a caller-supplied request ID adds to a result. */
export interface WriteBatchReceipt {
  readonly requestId: string;
  readonly status: WriteBatchReceiptStatus;
}

/** A batch result for a call that supplied a request ID: the receipt is always there. */
export type ReceiptedWriteBatchResult = WriteBatchResult & { readonly receipt: WriteBatchReceipt };

/** A validated operation paired with the closure that commits it. */
interface PlannedOperation {
  readonly commit: () => WriteBatchOpResult;
}

/** Facts the kernel needs that are not part of any single operation. */
export interface ApplyWriteBatchOptions {
  /**
   * Config file that names the writing agent, for the note-write record
   * (who-wrote-what, Task A). Absent falls back to the shared discovery;
   * a caller that knows which config it runs under passes it so the
   * record names the agent the caller is.
   */
  readonly configPath?: string;
  /**
   * The credential-minted subject of the caller (write-side-trust, Task
   * 7), when the transport resolved one. It WINS over the config
   * resolution in every gate the batch consults: the owner-write gate's
   * resolved identity, the review disposition's subject on a staged
   * create, and the deny-only document consult every mutation runs
   * (write-side trust: a denied agent cannot rewrite or append to a note
   * by updating what an allowed create once published). Absent (stdio,
   * the CLI) keeps the config-derived subject.
   */
  readonly subject?: WriteSubject;
  /**
   * Client-supplied request ID (t_b34439d9). Supplied, the batch consults
   * the idempotency ledger BEFORE any validation or write: the same ID with
   * the same semantic payload returns the retained original receipt marked
   * `duplicate`; the same ID with a different payload throws the ledger's
   * own {@link IdempotencyPayloadMismatchError}; an unseen ID proceeds and
   * records the receipt after the commit - the sequencing
   * {@link import('./signal.ts').writeSignal} already ships. A concurrent
   * record of the same ID found only after the commit becomes a receipt
   * status on the committed result (see {@link WRITE_BATCH_RECEIPT_STATUS}).
   * Absent, behavior is byte-identical. Validation of the ID itself is the
   * ledger's (non-empty, bounded length), so an invalid ID surfaces the
   * ledger's named {@link import('./idempotency-ledger.ts').IdempotencyKeyError}
   * before any write.
   */
  readonly requestId?: string;
  /**
   * May the caller read the existing note at this vault-relative path?
   * An update or append whose target it may not read is refused as
   * `target_missing`, the refusal a path with no note gets, before the
   * note is read or any other check runs on it. Absent, every existing
   * note is a target (the CLI, which reads the vault directly).
   */
  readonly readable?: (rel: string) => boolean;
}

/**
 * Apply an ordered batch of write operations atomically. Validates and
 * projects every operation in memory first; only if all pass does it
 * commit them in order. The first invalid operation throws
 * {@link WriteBatchError} naming its index, before any disk write.
 */
export function applyWriteBatch(
  vault: string,
  operations: ReadonlyArray<WriteOperation>,
  opts: ApplyWriteBatchOptions & { readonly requestId: string },
): ReceiptedWriteBatchResult;
export function applyWriteBatch(
  vault: string,
  operations: ReadonlyArray<WriteOperation>,
  opts?: ApplyWriteBatchOptions,
): WriteBatchResult;
export function applyWriteBatch(
  vault: string,
  operations: ReadonlyArray<WriteOperation>,
  opts: ApplyWriteBatchOptions = {},
): WriteBatchResult {
  // Vault-identity write guard (context-integrity-gates, Unit J).
  assertVaultIdentityForWrite(vault);
  // The batch's shape is checked first: the request-ID consult hashes the
  // operations, and a non-array must surface as the named batch error, not
  // as whatever the hashing throws.
  if (!Array.isArray(operations) || operations.length === 0) {
    throw new WriteBatchError("invalid_operation", -1, "operations must be a non-empty array");
  }
  if (operations.length > MAX_BATCH_OPERATIONS) {
    throw new WriteBatchError(
      "too_many_operations",
      -1,
      `a batch may contain at most ${MAX_BATCH_OPERATIONS} operations, got ${operations.length}`,
      { max: MAX_BATCH_OPERATIONS, count: operations.length },
    );
  }
  // The request-ID consult sits before any per-operation validation: a
  // duplicate must never re-validate (the original already passed) and an
  // invalid ID must surface before anything is written.
  const requestId = opts.requestId;
  const idempotency =
    requestId === undefined ? undefined : consultBatchKey(vault, requestId, operations);
  if (idempotency?.retained !== undefined) return idempotency.retained;

  // A note target may appear at most once per batch: projecting each note
  // op against the pre-batch disk state means a second op on the same file
  // would silently clobber the first at commit time. Refuse it loudly.
  const noteTargets = new Set<string>();
  // One privacy verdict for every store record the batch writes (its log
  // events, note-write events, evidence records, inner receipts and its
  // request receipt),
  // judged from the operations only when the first record is written,
  // after every operation validated (`write-batch-privacy.ts`).
  const privacy = writeBatchPrivacy(vault, operations, requestId, opts.readable);
  // Every store record written from here on, by the batch or by any
  // writer it calls (a note's owner-write decision row included), carries
  // this verdict (`operation-scope.ts`).
  return withOperationPrivacy(privacy, () => {
    const planned: PlannedOperation[] = operations.map((operation, index) =>
      projectOperation(vault, operation, index, noteTargets, opts, privacy),
    );

    const results = planned.map((p) => p.commit());
    const result: WriteBatchResult = { applied: operations.length, results, done: true };
    if (idempotency !== undefined && requestId !== undefined) {
      // Record AFTER the commit so a sequential retry dedupes against a
      // durable receipt. `rememberKey` re-checks under its shard lock; the
      // residual crash window between commit and record is the one the
      // ledger documents for every writer that follows this pattern.
      const stored: Readonly<Record<string, unknown>> = {
        applied: result.applied,
        results: result.results.map((opResult) => storedOpResult(vault, opResult)),
        done: result.done,
      };
      // The receipt's coordinates do not say what the batch touched, so the
      // batch hands the ledger its own verdict for the store copy.
      const remembered = rememberKey(vault, {
        key: requestId,
        namespace: WRITE_BATCH_KEY_NAMESPACE,
        contentHash: idempotency.contentHash,
        ref: stored,
        private: privacy,
      });
      // The unlocked consult above can miss a concurrent call's record; the
      // locked re-check's verdict is acted on, never dropped. Either way this
      // call's writes have landed, so the verdict is a receipt status on the
      // committed result, never an error that would read as "nothing
      // written" and invite a second application under a fresh ID.
      return { ...result, receipt: { requestId, status: RECEIPT_STATUS_FOR[remembered.status] } };
    }
    return result;
  });
}

/** The receipt status of a committed batch, by the locked re-check's verdict. */
const RECEIPT_STATUS_FOR: Readonly<Record<RememberKeyStatus, WriteBatchReceiptStatus>> =
  Object.freeze({
    [REMEMBER_KEY_STATUS.inserted]: WRITE_BATCH_RECEIPT_STATUS.applied,
    [REMEMBER_KEY_STATUS.duplicate_match]: WRITE_BATCH_RECEIPT_STATUS.concurrent_duplicate,
    [REMEMBER_KEY_STATUS.payload_mismatch]: WRITE_BATCH_RECEIPT_STATUS.payload_conflict,
  });

/**
 * One op result as the durable receipt stores it. The ledger is vault
 * content that syncs to every device, so a log path is stored
 * vault-relative - the form apply-evidence keeps for its own receipt -
 * and never as this machine's absolute path. Note results already name
 * vault-relative paths.
 */
function storedOpResult(vault: string, opResult: WriteBatchOpResult): WriteBatchOpResult {
  if (opResult.kind !== "apply_evidence") return opResult;
  return { ...opResult, log_path: relative(vault, opResult.log_path) };
}

/** Inverse of {@link storedOpResult}: the log path rebuilt under the vault serving the retry. */
function retainedOpResult(vault: string, opResult: WriteBatchOpResult): WriteBatchOpResult {
  if (opResult.kind !== "apply_evidence") return opResult;
  return { ...opResult, log_path: join(vault, opResult.log_path) };
}

/**
 * The pre-write consult for a caller-supplied request ID. Returns the hash
 * the batch must record after a successful commit; when the ID is already
 * in the ledger, `retained` carries the outcome instead - the stored
 * receipt marked `duplicate` for a matching payload, or nothing after the
 * mismatch error propagates.
 */
function consultBatchKey(
  vault: string,
  requestId: string,
  operations: ReadonlyArray<WriteOperation>,
): { readonly contentHash: string; readonly retained?: ReceiptedWriteBatchResult } {
  const contentHash = computePayloadHash({ operations: [...operations] });
  const existing = lookupKey(vault, requestId, WRITE_BATCH_KEY_NAMESPACE);
  if (existing === null) return { contentHash };
  if (existing.contentHash !== contentHash) {
    throw new IdempotencyPayloadMismatchError(requestId, existing.contentHash, contentHash);
  }
  const ref = existing.ref as WriteBatchResult | undefined;
  if (
    ref === undefined ||
    typeof ref !== "object" ||
    ref.applied === undefined ||
    !Array.isArray(ref.results) ||
    ref.done !== true
  ) {
    // The ledger cannot answer for a key whose stored receipt is not a
    // batch receipt. Refusing by name beats inventing an empty result that
    // would tell the caller the batch applied when nothing did.
    throw new WriteBatchError(
      "invalid_operation",
      -1,
      `request id '${requestId}' is already recorded without a readable write-batch receipt`,
    );
  }
  return {
    contentHash,
    retained: {
      ...ref,
      results: ref.results.map((opResult) => retainedOpResult(vault, opResult)),
      receipt: { requestId, status: WRITE_BATCH_RECEIPT_STATUS.duplicate },
    },
  };
}

function projectOperation(
  vault: string,
  operation: WriteOperation,
  index: number,
  noteTargets: Set<string>,
  opts: ApplyWriteBatchOptions,
  privacy: OperationPrivacy,
): PlannedOperation {
  const kind = (operation as { readonly kind?: unknown } | null | undefined)?.kind;
  switch (kind) {
    case "create_note":
      return projectCreateNote(
        vault,
        operation as CreateNoteOperation,
        index,
        noteTargets,
        opts,
        privacy,
      );
    case "update_note":
      return projectUpdateNote(
        vault,
        operation as UpdateNoteOperation,
        index,
        noteTargets,
        opts,
        privacy,
      );
    case "append_note":
      return projectAppendNote(
        vault,
        operation as AppendNoteOperation,
        index,
        noteTargets,
        opts,
        privacy,
      );
    case "apply_evidence":
      return projectApplyEvidence(
        vault,
        operation as ApplyEvidenceOperation,
        index,
        opts.readable,
        privacy,
      );
    case "append_log_line":
      return projectAppendLogLine(vault, operation as AppendLogLineOperation, index, privacy);
    default:
      throw new WriteBatchError(
        "invalid_operation",
        index,
        `operation ${index}: unknown kind '${String(kind)}'`,
      );
  }
}

/**
 * Translate a {@link CreateNoteError} from the shared safety envelope
 * into an index-bearing {@link WriteBatchError}, preserving the code.
 */
function envelopeError(err: unknown, index: number): WriteBatchError {
  if (err instanceof CreateNoteError) {
    return new WriteBatchError(err.code, index, `operation ${index}: ${err.message}`);
  }
  return new WriteBatchError(
    "invalid_operation",
    index,
    `operation ${index}: ${err instanceof Error ? err.message : String(err)}`,
  );
}

/**
 * Reserve a note target for this batch, refusing a duplicate. Returns the
 * resolved target so callers project against it.
 */
function reserveNoteTarget(
  vault: string,
  path: string,
  index: number,
  noteTargets: Set<string>,
): { readonly relPath: string; readonly abs: string } {
  let target;
  try {
    target = resolveNoteTarget(vault, path);
  } catch (err) {
    throw envelopeError(err, index);
  }
  if (noteTargets.has(target.abs)) {
    throw new WriteBatchError(
      "duplicate_target",
      index,
      `operation ${index}: note ${target.relPath} is already targeted earlier in this batch`,
      { path: target.relPath },
    );
  }
  noteTargets.add(target.abs);
  return target;
}

function projectCreateNote(
  vault: string,
  op: CreateNoteOperation,
  index: number,
  noteTargets: Set<string>,
  opts: ApplyWriteBatchOptions,
  privacy: OperationPrivacy,
): PlannedOperation {
  const target = reserveNoteTarget(vault, op.path, index, noteTargets);
  // The owner gate at PROJECTION (write-side-trust, Task 13): a
  // foreign-owner create is refused before ANY operation commits, which
  // is the all-or-nothing contract the kernel sells. The create writer
  // consults the same gate again at commit - that arm covers the
  // single-note callers, and this one exists so a batch never leaves
  // earlier operations committed behind a refused claim.
  const ownerGate = noteOwnerGateVerdict(vault, op.frontmatter, opts.configPath, opts.subject);
  if (ownerGate.refused) {
    throw new WriteBatchError(
      "owner_write_refused",
      index,
      `operation ${index}: create_note at ${target.relPath}: ${ownerGate.reason}`,
    );
  }
  // Pre-check existence so a clobber aborts the batch before any commit.
  // The commit still goes through the exclusive create-note writer, whose
  // link(2) exclusivity closes the residual TOCTOU race race-free.
  if (existsSync(target.abs)) {
    throw new WriteBatchError(
      "exists",
      index,
      `operation ${index}: note already exists: ${target.relPath}`,
      { path: target.relPath },
    );
  }
  return {
    commit: () => {
      try {
        const res = createNote(vault, {
          path: op.path,
          ...(op.frontmatter !== undefined ? { frontmatter: op.frontmatter } : {}),
          ...(op.content !== undefined ? { content: op.content } : {}),
          ...(opts.configPath !== undefined ? { configPath: opts.configPath } : {}),
          ...(opts.subject !== undefined ? { subject: opts.subject } : {}),
          storePrivate: privacy,
        });
        if (res.outcome === "staged") {
          // The review gate staged the create (write-side trust, Task 9).
          // No bytes exist at the target, so there is no audit half and
          // no page to lint - the pending id is the receipt.
          return {
            kind: "create_note",
            path: res.path,
            created: false,
            staged: true,
            pending_id: res.pendingId,
            ...writePathAdvisoryField(op.content, res.path),
          };
        }
        if (res.outcome !== "created") {
          // Unreachable by construction: the batch exposes none of the
          // authoring modes, so `ifExists` is never sent and an occupied
          // target is a refusal rather than a skip. Named rather than
          // cast, because a cast would report `created: true` for a call
          // that created nothing.
          throw new WriteBatchError(
            "exists",
            index,
            `operation ${index}: note already exists: ${res.path}`,
            { path: res.path },
          );
        }
        // The create writer records its own event, so the batch carries
        // its receipt through rather than appending a second one. The
        // advisory was computed in the projection from the authored
        // content; it advises, it never refuses.
        return {
          kind: "create_note",
          path: res.path,
          created: true,
          write_id: res.write_id,
          ...(res.audit_reason !== undefined ? { audit_reason: res.audit_reason } : {}),
          ...writePathAdvisoryField(op.content, res.path),
        };
      } catch (err) {
        throw envelopeError(err, index);
      }
    },
  };
}

/**
 * Frontmatter keys a caller-named UPDATE may not set, whatever the value.
 * They are read as boundary state, not note content: `visibility` carries
 * the page's read-scope tokens (the reserved `private` among them), and
 * `origin_channel` and `content_class` are the server-derived stamps the
 * process that writes the page owns - a caller never names them. The one
 * rewrite a mutation does make is {@link mutationChannelStamp}: a writer
 * whose own channel differs may not keep an inherited `cli` stamp, since
 * the delivery side reads that stamp as operator-authorship of whatever
 * text the mutation left. Keys are matched through {@link normToken}, so a
 * capitalised spelling (`Visibility:`) meets the same refusal as the
 * lower-case one.
 */
const RESERVED_UPDATE_FRONTMATTER_KEYS: ReadonlySet<string> = new Set([
  "visibility",
  ORIGIN_CHANNEL_FIELD,
  CONTENT_CLASS_FIELD,
]);

/**
 * The channel correction a note MUTATION commits under, as the frontmatter
 * keys to merge on top of the caller's map (empty when none apply).
 *
 * A note keeps the `origin_channel` its creation wrote - a stamp describes
 * the process that put the record there, and mutation never rewrites it.
 * The one exception is the stamp a mutation inherits but its own process
 * did not earn: a page stamped `cli` reads at delivery as operator-
 * authored plain text, so when the writer is not the CLI lane - an MCP
 * tool call, an import replay, an unclaimed embedded process - leaving
 * that stamp in place would deliver the mutation's own words under a
 * provenance they do not have. In that one case the stamp is rewritten to
 * {@link originChannelStamp}, the current process's own answer; a page
 * with no stamp stays unstamped (backfill is refused by the stamp
 * doctrine), and a CLI-lane mutation keeps the page exactly as it reads.
 */
function mutationChannelStamp(existing: FrontmatterMap): FrontmatterMap {
  const current = originChannelStamp();
  if (current === ORIGIN_CHANNEL.cli) return {};
  if (existing[ORIGIN_CHANNEL_FIELD] !== ORIGIN_CHANNEL.cli) return {};
  return { [ORIGIN_CHANNEL_FIELD]: current };
}

/**
 * The informal privacy marker keys (`access`, `confidentiality`,
 * `sensitivity`). Unlike {@link RESERVED_UPDATE_FRONTMATTER_KEYS} these are
 * boundary state one layer over: the read roots resolve a deny value under
 * any of them to the same reserved remote-deny token
 * (`graph/privacy-markers.ts`). A caller-named update may rewrite a
 * marker's VALUE freely while the note's deny status stands still - an
 * `access: read-only`, or a move from `access: public` to `access: team`,
 * changes nothing the read roots act on - but a merge that would CLEAR the
 * note's deny value (a merged `access: ""`) or FORGE one is refused, in
 * the visibility posture: edit the note directly.
 *
 * Creation needs no refusal - the server stamps are merged last there and
 * a caller-named class is dropped outright, and a marker a caller authors
 * at creation is the caller stating the claim about their own new note -
 * but the update merge inverts the order, so the guard lives at the merge.
 */
const PRIVACY_MARKER_UPDATE_KEYS: ReadonlySet<string> = new Set(PRIVACY_MARKER_KEYS);

/**
 * The first key of `frontmatter` whose normalised spelling is in
 * `reserved`, or `null`. Keys are compared through {@link normToken} - the
 * same NFC + trim + lower-case normalisation the visibility layer gives a
 * token - so a spelling the parser keeps distinct (`Access:`, `VISIBILITY:`)
 * cannot slip a boundary claim past a guard that reads the lower-case form.
 */
function reservedFrontmatterKey(
  frontmatter: FrontmatterMap | undefined,
  reserved: ReadonlySet<string>,
): string | null {
  if (frontmatter === undefined) return null;
  for (const key of Object.keys(frontmatter)) {
    if (reserved.has(normToken(key))) return key;
  }
  return null;
}

function projectUpdateNote(
  vault: string,
  op: UpdateNoteOperation,
  index: number,
  noteTargets: Set<string>,
  opts: ApplyWriteBatchOptions,
  privacy: OperationPrivacy,
): PlannedOperation {
  if (op.frontmatter === undefined && op.body === undefined) {
    throw new WriteBatchError(
      "invalid_operation",
      index,
      `operation ${index}: update_note requires 'frontmatter' or 'body'`,
    );
  }
  const target = reserveNoteTarget(vault, op.path, index, noteTargets);
  // The document-deny consult rides the same seam ahead of the
  // existing-note read (write-side trust): the review boundary is ENTRY,
  // so an admitted note is never re-staged, but a caller the document
  // denies cannot rewrite it either - mutation is not a door around the
  // rule that refused the create. An ask and an allow change nothing
  // here: no row, no stage, the update proceeds exactly as before.
  refuseDocumentDeny(vault, REVIEW_LANE.notes, opts.subject, {
    target: target.relPath,
    // The no-subject fallback answers for the principal THIS config
    // declares - the same one the owner gate below resolves against.
    ...(opts.configPath !== undefined ? { configPath: opts.configPath } : {}),
  });
  // The owner gate rides the update seam AHEAD of the existing-note read
  // (write-side-trust, Task 13): a caller-named `owner:` the gate refuses
  // is refused with the same error whether the target exists or not, so
  // probing foreign owners learns nothing about which paths are real.
  // Under the gate's `off` mode the predicate refuses nothing and the
  // update writes exactly as it did before this wave - which is why
  // `owner` is gated here rather than joining the unconditionally
  // reserved keys above. The warn row, when the verdict says to watch,
  // is logged at the COMMIT below and only when the rewrite lands:
  // projection must stay row-free so a later operation's refusal never
  // leaves a row for a write that never happened, and a byte-identical
  // skip is such a write too.
  const ownerGate = noteOwnerGateVerdict(vault, op.frontmatter, opts.configPath, opts.subject);
  if (ownerGate.refused) {
    throw new WriteBatchError(
      "owner_write_refused",
      index,
      `operation ${index}: update_note at ${target.relPath}: ${ownerGate.reason}`,
    );
  }
  const state = readExistingNote(target.abs, target.relPath, index, opts.readable);
  // The one seam the blank-overwrite guard is wired at - it covers both
  // callers, `brain_update_note` and `brain_write_batch`'s update op,
  // because both project through here.
  if (
    op.body !== undefined &&
    refuseBlankOverwrite({
      existingBody: state.body,
      nextBody: op.body,
      allowEmpty: op.allowEmpty === true,
    })
  ) {
    throw new WriteBatchError(
      "blank_overwrite_refused",
      index,
      `operation ${index}: refusing to replace the body of ${target.relPath} with an empty ` +
        "one; pass allow_empty to clear the note deliberately",
      { path: target.relPath },
    );
  }
  // The reserved-key guard rides the same seam: the merge below lets the
  // caller's map win over the file's, so a boundary key arriving here
  // would silently rewrite it. The unconditional keys refuse on presence
  // alone; a marker key refuses only when the merge would change the
  // note's deny status (a marker the note's deny status does not move -
  // `access: read-only`, or `access: public` becoming `access: team` -
  // writes exactly as any other content key does).
  const reservedKey = reservedFrontmatterKey(op.frontmatter, RESERVED_UPDATE_FRONTMATTER_KEYS);
  if (reservedKey !== null) {
    throw new WriteBatchError(
      "reserved_frontmatter_key",
      index,
      `operation ${index}: frontmatter key "${reservedKey}" is reserved and cannot be set ` +
        `through an update of ${target.relPath}; edit the note directly`,
      { path: target.relPath, key: reservedKey },
    );
  }
  const markerKey = reservedFrontmatterKey(op.frontmatter, PRIVACY_MARKER_UPDATE_KEYS);
  if (markerKey !== null) {
    const merged: FrontmatterMap = { ...state.frontmatter, ...op.frontmatter };
    if (hasPrivacyDenyMarker(merged) !== hasPrivacyDenyMarker(state.frontmatter)) {
      throw new WriteBatchError(
        "reserved_frontmatter_key",
        index,
        `operation ${index}: frontmatter key "${markerKey}" would change whether ` +
          `${target.relPath} denies a remote read (a deny value under access / ` +
          "confidentiality / sensitivity is boundary state); edit the note directly",
        { path: target.relPath, key: markerKey },
      );
    }
  }
  // The caller's map wins over the file's; the mutation's own channel
  // correction wins over both (see {@link mutationChannelStamp}).
  const frontmatter =
    op.frontmatter !== undefined
      ? { ...state.frontmatter, ...op.frontmatter, ...mutationChannelStamp(state.frontmatter) }
      : { ...state.frontmatter, ...mutationChannelStamp(state.frontmatter) };
  const body = op.body !== undefined ? op.body : state.body;
  const contents = formatFrontmatter(frontmatter, body);
  return {
    commit: () => {
      const audit = commitNoteRewrite(
        vault,
        target,
        state.raw,
        contents,
        NOTE_WRITE_OP.update,
        opts,
        privacy,
      );
      // The warn row the projection's verdict asked for, logged only when
      // the write actually commits - never during projection, where a
      // later operation could still abort the batch, and never for a
      // byte-identical skip, which is a write that did not happen and so
      // owes no ledger row.
      if (audit.wrote && ownerGate.watch) {
        logWatchedNoteOwnerWrite(
          vault,
          target.relPath,
          ownerGate.named,
          ownerGate.resolvedIdentity,
          opts.subject?.via ?? "config",
        );
      }
      // The flag is the write's own verdict, not a hardcoded success: a
      // byte-identical re-apply skipped the write and says so, carrying
      // no audit half because nothing was recorded.
      if (audit.wrote) {
        const { write_id, audit_reason } = audit;
        return {
          kind: "update_note",
          path: target.relPath,
          updated: true,
          write_id,
          ...(audit_reason !== undefined ? { audit_reason } : {}),
          // The caller's authored body, not the note's whole content: a
          // path already on disk was not this call's authorship.
          ...writePathAdvisoryField(op.body, target.relPath),
        };
      }
      return {
        kind: "update_note",
        path: target.relPath,
        updated: false,
        ...writePathAdvisoryField(op.body, target.relPath),
      };
    },
  };
}

function projectAppendNote(
  vault: string,
  op: AppendNoteOperation,
  index: number,
  noteTargets: Set<string>,
  opts: ApplyWriteBatchOptions,
  privacy: OperationPrivacy,
): PlannedOperation {
  if (typeof op.content !== "string" || op.content.trim().length === 0) {
    throw new WriteBatchError(
      "invalid_operation",
      index,
      `operation ${index}: append_note requires non-empty 'content'`,
    );
  }
  const target = reserveNoteTarget(vault, op.path, index, noteTargets);
  // The same deny-only consult the update runs (write-side trust): an
  // append mutates an admitted note, so the document's deny refuses it,
  // while an ask and an allow leave the append exactly as it was.
  refuseDocumentDeny(vault, REVIEW_LANE.notes, opts.subject, {
    target: target.relPath,
    // The no-subject fallback answers for the principal THIS config
    // declares, like the update's consult above.
    ...(opts.configPath !== undefined ? { configPath: opts.configPath } : {}),
  });
  const state = readExistingNote(target.abs, target.relPath, index, opts.readable);
  const appended = op.content.trim();
  const body = state.body.length > 0 ? `${state.body}${APPEND_SEPARATOR}${appended}` : appended;
  // The appended text is this process's authorship, so the same channel
  // correction the update arm applies holds here ({@link mutationChannelStamp}).
  const contents = formatFrontmatter(
    { ...state.frontmatter, ...mutationChannelStamp(state.frontmatter) },
    body,
  );
  return {
    commit: () => {
      const audit = commitNoteRewrite(
        vault,
        target,
        state.raw,
        contents,
        NOTE_WRITE_OP.append,
        opts,
        privacy,
      );
      // Honest for the same reason the update's flag is: a rewrite whose
      // bytes already sit on disk (a hand-edited note that already
      // contains the would-be result) wrote nothing and says so, with no
      // audit half because nothing was recorded.
      if (audit.wrote) {
        const { write_id, audit_reason } = audit;
        return {
          kind: "append_note",
          path: target.relPath,
          appended: true,
          write_id,
          ...(audit_reason !== undefined ? { audit_reason } : {}),
          // The appended text is the call's authorship; the body it
          // joined is not.
          ...writePathAdvisoryField(op.content, target.relPath),
        };
      }
      return {
        kind: "append_note",
        path: target.relPath,
        appended: false,
        ...writePathAdvisoryField(op.content, target.relPath),
      };
    },
  };
}

/**
 * What one note rewrite actually did: either it wrote, and carries the
 * audit half (`write_id`, plus `audit_reason` exactly when that id is
 * null), or it skipped a byte-identical target and carries nothing. The
 * split - rather than a boolean beside optional fields - is what keeps a
 * skipped write from ever spelling a null write_id that a caller could
 * mistake for a lost record.
 */
type CommittedNoteRewrite = ({ readonly wrote: true } & NoteWriteAudit) | { readonly wrote: false };

/**
 * Commit one note rewrite and attribute it: for a rewrite that changes
 * the bytes, keep the bytes it replaces, write, and record the event.
 *
 * The write runs with `skipIfUnchanged`, so a byte-identical re-apply
 * leaves the target untouched - no temp file, no rename, no mtime bump
 * for the recency and validity consumers to misread - and the returned
 * verdict is the one source of truth for what happened. A skipped write
 * stores no before-image (the prior bytes are still the bytes on disk;
 * an image would claim a replace that never occurred) and records no
 * note-write event (no audit line exists for a write that did not
 * happen).
 *
 * The order is the design's: image, then write, then record. Whether an
 * image is owed is decided up front (`before !== contents`), so the image
 * lands BEFORE the rename and a crash or a failed store never leaves the
 * prior bytes replaced without their copy - a retry would otherwise see
 * the new bytes, skip as unchanged and never reach the ledger. The store
 * is content-addressed and idempotent, so an image stored for a write
 * that `skipIfUnchanged` then skips (the target changed underneath to
 * the new bytes) is harmless.
 */
function commitNoteRewrite(
  vault: string,
  target: { readonly relPath: string; readonly abs: string },
  before: string,
  contents: string,
  op: NoteWriteOp,
  opts: ApplyWriteBatchOptions,
  privacy: OperationPrivacy,
): CommittedNoteRewrite {
  if (before === contents) return { wrote: false };
  storeBeforeImage(vault, before);
  mkdirSync(dirname(target.abs), { recursive: true });
  const wrote = atomicWriteFileSync(target.abs, contents, { skipIfUnchanged: true });
  if (!wrote) return { wrote: false };
  const audit = timeStageSync(ROUTE_STAGE.writeReceipt, () =>
    recordNoteWrite(vault, {
      op,
      target: target.relPath,
      before: { bytes: before },
      after: { bytes: contents },
      ...(opts.configPath !== undefined ? { configPath: opts.configPath } : {}),
      storePrivate: privacy,
    }),
  );
  return { wrote: true, ...audit };
}

/** Accepted apply-evidence result values, for phase-1 validation. */
const APPLY_RESULTS: ReadonlySet<string> = new Set([
  BRAIN_APPLY_RESULT.applied,
  BRAIN_APPLY_RESULT.violated,
  BRAIN_APPLY_RESULT.outdated,
]);

/**
 * Project an apply_evidence operation. Pre-validates the required fields,
 * the result enum, and the target preference's existence so an invalid
 * op aborts the batch before any commit. The commit delegates to the
 * {@link appendApplyEvidence} core writer, which re-validates and renders
 * the log event - the kernel does not reimplement it.
 */
function projectApplyEvidence(
  vault: string,
  op: ApplyEvidenceOperation,
  index: number,
  readable: ((rel: string) => boolean) | undefined,
  privacy: OperationPrivacy,
): PlannedOperation {
  const input = op.input;
  if (input === null || typeof input !== "object") {
    throw new WriteBatchError(
      "invalid_operation",
      index,
      `operation ${index}: missing evidence input`,
    );
  }
  const prefId = typeof input.pref_id === "string" ? input.pref_id.trim() : "";
  if (prefId === "") {
    throw new WriteBatchError(
      "invalid_operation",
      index,
      `operation ${index}: apply_evidence requires pref_id`,
    );
  }
  if (typeof input.artifact !== "string" || input.artifact.trim() === "") {
    throw new WriteBatchError(
      "invalid_operation",
      index,
      `operation ${index}: apply_evidence requires artifact`,
    );
  }
  if (typeof input.agent !== "string" || input.agent.trim() === "") {
    throw new WriteBatchError(
      "invalid_operation",
      index,
      `operation ${index}: apply_evidence requires agent`,
    );
  }
  if (!APPLY_RESULTS.has(input.result)) {
    throw new WriteBatchError(
      "invalid_operation",
      index,
      `operation ${index}: apply_evidence result must be applied, violated, or outdated`,
    );
  }
  // Existence pre-check mirrors appendApplyEvidence's own resolution so a
  // missing preference aborts the whole batch before any write happens. A
  // preference the caller may not read is answered as a missing one.
  const slug = prefId.startsWith("pref-") ? prefId.slice("pref-".length) : prefId;
  try {
    validateSlug(slug);
  } catch (err) {
    throw new WriteBatchError(
      "invalid_operation",
      index,
      `operation ${index}: ${err instanceof Error ? err.message : String(err)}`,
    );
  }
  if (!isApplyEvidenceTargetPresent(vault, preferencePath(vault, slug), readable)) {
    throw new WriteBatchError(
      "preference_not_found",
      index,
      `operation ${index}: preference not found: pref-${slug}`,
      { pref_id: `pref-${slug}` },
    );
  }
  return {
    commit: () => {
      const res = appendApplyEvidence(vault, input, {
        ...op.options,
        ...(readable !== undefined ? { readable } : {}),
        storePrivate: privacy,
      });
      return { kind: "apply_evidence", logged_at: res.logged_at, log_path: res.log_path };
    },
  };
}

/**
 * Project an append_log_line operation. Pre-validates that the text is a
 * non-empty string; the commit delegates to the {@link appendBrainNote}
 * core writer.
 */
function projectAppendLogLine(
  vault: string,
  op: AppendLogLineOperation,
  index: number,
  privacy: OperationPrivacy,
): PlannedOperation {
  const input = op.input;
  if (
    input === null ||
    typeof input !== "object" ||
    typeof input.text !== "string" ||
    input.text.trim() === ""
  ) {
    throw new WriteBatchError(
      "invalid_operation",
      index,
      `operation ${index}: append_log_line requires non-empty text`,
    );
  }
  return {
    commit: () => {
      const res = appendBrainNote({ vault, ...input, storePrivate: privacy });
      return { kind: "append_log_line", logged_at: res.logged_at, log_path: res.log_path };
    },
  };
}

interface ExistingNote {
  readonly frontmatter: FrontmatterMap;
  readonly body: string;
  /**
   * The target's bytes exactly as they sit on disk (who-wrote-what,
   * Task A).
   *
   * Not `formatFrontmatter(frontmatter, body)`: the before-image and the
   * `hash_before` have to describe what a revert would put BACK, and a
   * re-serialisation of the parsed halves is what this build would have
   * written, not what the previous writer did. Key order, spacing and a
   * hand-edited block all survive here and would not survive there.
   */
  readonly raw: string;
}

/** Attribution for the frontmatter notices this reader inspects. */
const READ_EXISTING_NOTE_SITE = "brain.write-batch.read-existing-note";

/**
 * Windows arm of the permission refusal. Windows has no POSIX mode bits:
 * `chmod` and Explorer's "Read-only" box both set the one read-only
 * attribute, which Node reports as a mode without any write bit. Such a
 * note stays readable, so the unreadable-file notice never fires, but
 * the commit's atomic rename onto it then fails with a raw `EPERM` after
 * the before-image is already stored. Checking here keeps the POSIX
 * contract on both hosts: a note the process cannot rewrite for a
 * permission reason is refused as `target_unreadable` - the code the
 * POSIX `EACCES` read already produces, and an operator fault either way
 * - in the projection, before any commit. POSIX needs no arm: a 0444
 * file in a writable directory is legitimately replaced by the rename.
 */
function refuseReadOnlyAttribute(abs: string, relPath: string, index: number): void {
  if (process.platform !== "win32") return;
  let mode: number;
  try {
    mode = statSync(abs).mode;
  } catch {
    // The parse that follows names a stat/read failure itself.
    return;
  }
  if ((mode & 0o222) !== 0) return;
  const reason = "the file has the Windows read-only attribute";
  throw new WriteBatchError(
    "target_unreadable",
    index,
    `operation ${index}: note ${relPath} cannot be rewritten (${reason}); ` +
      "clear the attribute to let this write replace it",
    { path: relPath, reason },
  );
}

/**
 * Read and parse an existing note, or throw a typed error naming which
 * of the two ways it was unavailable. update and append only touch
 * notes that already exist.
 *
 * An UNREADABLE file raises rather than resolving to an empty note. The
 * two-tuple `parseFrontmatter` reports a read failure as `[{}, ""]` -
 * correct for the fail-soft walkers it was written for, and fatal here,
 * because this result is the base of a read-modify-write: an update
 * would write the caller's body under an empty frontmatter map and an
 * append would write its text over a body nobody read, both reporting
 * success. The projection runs before any commit, so raising leaves the
 * file byte-identical.
 *
 * A DROPPED frontmatter line raises for the same reason. The parse
 * succeeded, and the scanner reported by name a line it could not
 * express; the callers below re-serialise the parsed map with
 * `formatFrontmatter`, so that line would be deleted from disk by a
 * write the caller never asked to touch it - a frontmatter-only update
 * that answers `updated: true` while removing a field it never mentioned.
 * Both notices come off the same parse, and both mean the same thing:
 * part of the content this write would replace is unknown to it.
 */
function readExistingNote(
  abs: string,
  relPath: string,
  index: number,
  readable: ((rel: string) => boolean) | undefined,
): ExistingNote {
  // A note the caller may not read is answered as a missing one, asked
  // first so no later check (read-only attribute, parse, reserved key)
  // can tell the two apart.
  if (readable?.(relPath) === false || !existsSync(abs)) {
    throw new WriteBatchError(
      "target_missing",
      index,
      `operation ${index}: note does not exist: ${relPath}`,
      { path: relPath },
    );
  }
  refuseReadOnlyAttribute(abs, relPath, index);
  const [frontmatter, body, notices] = parseFrontmatterWithNotices(abs, {
    site: READ_EXISTING_NOTE_SITE,
  });
  const unreadable = notices.find((n) => n.code === DEGRADATION_CODE.frontmatterUnreadable);
  if (unreadable !== undefined) {
    throw new WriteBatchError(
      "target_unreadable",
      index,
      `operation ${index}: note ${relPath} exists but could not be read ` +
        `(${unreadable.detail}), so the content this write would replace is unknown`,
      { path: relPath, reason: unreadable.detail },
    );
  }
  const dropped = notices.filter((n) => n.code === DEGRADATION_CODE.frontmatterLineDropped);
  if (dropped.length > 0) {
    const reason = dropped.map((n) => n.detail).join("; ");
    throw new WriteBatchError(
      "target_frontmatter_lossy",
      index,
      `operation ${index}: note ${relPath} has frontmatter this build cannot round-trip ` +
        `(${reason}), and rewriting it would delete those lines`,
      { path: relPath, reason },
    );
  }
  // Read after the parse rather than before it: the two notices above
  // are the named ways this file can be unavailable, and a raw read that
  // ran first would have to invent a third.
  return { frontmatter: { ...frontmatter }, body, raw: readFileSync(abs, "utf8") };
}