feat(vrs): transactional intent-as-code record allocation and renumbering

Problem

VRS decision and delta ordinals are currently allocated by editing filenames directly. Two branches can independently choose the same next ordinal, merge cleanly, and leave one identifier naming two accepted records.

A checker can detect the collision after merge, but repair is still a manual multi-file transaction:

• choose which record retains the existing ordinal;
• compute fresh monotonic ordinals from the current tree;
• move record files;
• rewrite path-qualified citations and visible labels together;
• prove that no stale path, ambiguous bare citation, or partial rename remains.

The important concurrency property is that "next free" cannot be reserved on a branch. It must be resolved against the tree at application time; otherwise two branches merely reserve the same future collision.

Direction: intent as code

Explore a reusable effect-utils facility that treats VRS identity changes as declarative reconciliation intents rather than sequences of filesystem edits.

Example conceptual operations:

allocate VRS record(kind=decision, subsystem=..., slug=...)
renumber VRS record(path=..., allocation=monotonic)
reconcile VRS identity intents

The exact surface may be a CLI, a checked-in intent resource, a Genie primitive, or a library plus adapters. The important contract is transactional behavior, not the spelling.

Required semantics

1. Resolve at write time. Scan the current subsystem and allocate max(used) + 1; never refill historical gaps.
2. Optimistic concurrency. Bind a plan to an owner-set/tree digest. If the tree changes before apply, reject or recompute rather than applying a stale allocation.
3. Atomic plan. Record move, markdown target rewrites, and visible ordinal-label rewrites succeed together or not at all.
4. Semantic restraint. Rewrite identity-bearing paths and labels only; never rewrite decision prose or status automatically.
5. Idempotence. Reapplying a completed intent is a no-op with the same result.
6. Auditable dry run. Emit a stable human-readable and machine-readable plan showing allocations, moves, citation rewrites, and preconditions.
7. Fail closed. Refuse ambiguous ownership, unresolved references, unsupported citation syntax, or a partial working tree overlap.
8. Repository-independent core. Keep allocation/rewrite logic reusable; repositories declare their record containers and citation conventions.

Verification

The implementation should be verified by breaking it:

• two concurrent intents based on the same starting ordinal replay onto one merged tree and receive distinct ordinals;
• a stale plan is rejected after another record lands;
• a planted duplicate is detected;
• a planted inbound citation is rewritten with matching label and target;
• an unsupported or ambiguous citation aborts without partial filesystem changes;
• a second apply is a no-op.

Acceptance criteria

• A single command/reconciler can allocate or renumber a VRS record without manual ordinal selection.
• Two independently authored intents converge to unique monotonic identities when applied to the same updated tree.
• File moves and all recognized references are committed as one validated transaction.
• Failure leaves the tracked tree byte-identical to its pre-apply state.
• Dry-run output is deterministic and suitable for CI/review.
• The checker and reconciler share one ownership/citation model so detection and repair cannot drift.
• Documentation includes the concurrency model and explains why gaps are never reused.

Open design question

Should intent resources be committed and reconciled (closest to infrastructure-as-code), or should the CLI compile an ephemeral user request into a reviewed deterministic patch? Evaluate both against merge behavior, auditability, and cleanup of completed intents.

Start by locating the existing VRS checker and the effect-utils entry points that could host a reusable reconciliation facility. Compare committed intent resources with an ephemeral CLI request against the stated merge and audit requirements. Done means the chosen design meets the concurrency, atomicity, idempotence, dry-run, fail-closed, and verification criteria, with documentation covering the concurrency model and non-reuse of gaps.