writeHandoffOnce method

SeatHandoff writeHandoffOnce({
  1. required String fileName,
  2. required String contents,
})

Writes contents as this disc's ONE live handoff, at disc-local fileName, and returns the note it parsed back.

Write-once, by refusal. The disc is resolved through handoffs FIRST, so the constraint keys on front matter kind: handoff (the_grid#agent-disc-file-shape-and-home) and never on a file-name pattern: a note that declares the kind is a handoff whatever it is called, and a lesson called handoff-notes.md is not one. When the disc already carries one or more, this throws a SeatHandoffWriteException naming every one of them and the kHandoffWriteRemedy — BEFORE parsing the candidate and before touching the filesystem. That refusal is the whole point: consuming a handoff was already an enforced verb while writing one was prose, which is how one note came to be rewritten thirty times across nine hours.

The candidate must be one disc-local .md basename that is not the index, and parseSeatHandoff must recognize the COMPLETE contents as a handoff — so a kind: journal note, a half-written note and an empty one are all refused without a file being created. No fifth note kind is admitted here: the ruling is explicit that the checkpoint IS a handoff, cycled fast.

The target is created with exclusive: true, so an existing file at that exact name loses the race loudly rather than being truncated — the one window handoffs cannot close, because a note with no kind: handoff in it is invisible to that scan.

It owns the NOTE and nothing else. It never writes kSeatMemoryFileName: the index append stays one explicit step in the vended ritual, because the index is CHECKED here and never rewritten (power_station#seat-disc-index-integrity-is-checked-not-written). It deletes nothing, renames nothing, and decides nothing about what the note should say.

Implementation

SeatHandoff writeHandoffOnce({
  required String fileName,
  required String contents,
}) {
  Never refuse(
    String detail, {
    Iterable<String> existing = const <String>[],
  }) {
    throw SeatHandoffWriteException(
      directory: directory,
      fileName: fileName,
      detail: detail,
      existingHandoffs: existing,
    );
  }

  final live = handoffs();
  if (live.isNotEmpty) {
    refuse(
      'the disc already carries ${live.length} live '
      'handoff${live.length == 1 ? '' : 's'}, and a handoff is WORKING '
      'memory written ONCE at a boundary, never amended — '
      '$kHandoffWriteRemedy.',
      existing: [for (final entry in live) entry.handoff.relativePath],
    );
  }

  if (fileName.trim().isEmpty || p.basename(fileName) != fileName) {
    refuse(
      'a handoff name is ONE disc-local file name — no directory part, no '
      'traversal.',
    );
  }
  if (p.extension(fileName) != '.md') {
    refuse('a disc note is Markdown, so the name ends in ".md".');
  }
  if (fileName == kSeatMemoryFileName) {
    refuse(
      '$kSeatMemoryFileName is the disc INDEX, not a note — it is never '
      'written as a handoff.',
    );
  }

  final target = p.join(directory, fileName);
  final parsed = parseSeatHandoff(
    path: target,
    relativePath: p.relative(target, from: gridHome),
    contents: contents,
  );
  if (parsed == null) {
    refuse(
      'the candidate is not a handoff: its front matter must declare '
      '"kind: $kHandoffKind" between two "---" fences, and no other note '
      'kind is written here.',
    );
  }

  // Nothing above this line WRITES, so EVERY refusal leaves the disc exactly
  // as it was — not even a directory created for a note that never landed.
  ensure();
  final file = File(target);
  try {
    file.createSync(exclusive: true);
  } on FileSystemException catch (error) {
    refuse(
      'the target already exists on the disc, so writing would overwrite '
      'it — $kHandoffWriteRemedy (${error.osError?.message ?? error.message}).',
    );
  }
  final handle = file.openSync(mode: FileMode.writeOnly);
  try {
    handle.writeStringSync(contents);
    handle.flushSync();
  } finally {
    handle.closeSync();
  }
  return parsed;
}