SH2-0: shape parity gate, coverage fail-fast, and toy recognizer.

Add target-neutral shape-machine contracts, transplant the SH2a toy fixture,
and harden Shape AST codegen with emit-time coverage counters, unsupported
fail-fast, multi-alt choice backtracking, and the sep/not/opt/call-LED subset
needed so calc+toy stay fully generable under the new gate (48/48).

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: johnsoncodehk

src/shape-machine.ts

@@ -0,0 +1,76 @@
+/**
+ * Target-neutral data contracts for generated shape recognizers.
+ *
+ * This module deliberately contains no target runtime. TS, Rust, and Go emitters
+ * can share these identities and transaction rules without sharing codegen.
+ */
+
+/** Identity path through RD alternatives, nested inline alternatives, and Pratt events. */
+export type AltPathPart =
+  | { kind: 'rd'; rule: string; alt: number }
+  | { kind: 'inline-alt'; branch: number }
+  | { kind: 'pratt-nud'; event: 'atom' | 'group' | 'prefix' | 'nudSeq' | 'nudCapped'; index: number }
+  | { kind: 'pratt-led'; event: 'binary' | 'postfix' | 'postfixTok' | 'led'; index: number };
+export type AltPath = readonly AltPathPart[];
+
+/** A visible value channel. Optional holes retain position instead of disappearing. */
+export type VisibleSlot<H = unknown> =
+  | { kind: 'slot'; value: H }
+  | { kind: 'list'; values: H[] }
+  | { kind: 'hole'; value: H | null };
+
+export type PrattEvent<H = unknown> =
+  | { kind: 'atom'; value: H }
+  | { kind: 'group'; value: H }
+  | { kind: 'prefix'; operator: string; argument: H }
+  | { kind: 'binary'; left: H; operator: string; right: H }
+  | { kind: 'postfix'; left: H; operator: string }
+  | { kind: 'postfixTok'; left: H; token: H }
+  | { kind: 'led'; left: H; slots: readonly VisibleSlot<H>[] }
+  | { kind: 'nudSeq'; slots: readonly VisibleSlot<H>[] }
+  | { kind: 'nudCapped'; slots: readonly VisibleSlot<H>[] };
+
+/** Length snapshots are valid only for append-only channels. */
+export type AppendOnlyCheckpoint = {
+  pos: number;
+  kidsLength: number;
+  listsLength: number;
+  holesLength: number;
+  altPathLength: number;
+};
+
+/** Prior value for a slot overwritten during a speculative transaction. */
+export type UndoEntry<H = unknown> = {
+  channel: 'slot' | 'state';
+  index: number;
+  previous: H;
+};
+
+export type ShapeTransaction<H = unknown> = {
+  checkpoint: AppendOnlyCheckpoint;
+  undo: UndoEntry<H>[];
+  status: 'open' | 'committed' | 'rolledBack';
+};
+
+/**
+ * Transaction contract:
+ * - append-only arrays roll back by restoring their checkpointed lengths;
+ * - overwrites must be recorded in `undo`, or staged and applied only on commit;
+ * - parser position and every mutable Pratt/control flag join the same transaction;
+ * - function-local `left`/`opText` values need no log when assigned only after success.
+ */
+export const SHAPE_TRANSACTION_CONTRACT = {
+  appendOnly: 'restore-lengths',
+  overwrite: 'undo-log-or-commit-on-success',
+  prattLocals: 'commit-on-success',
+} as const;
+
+/** Local custom context (SH2-0). Full AltPathPart form is deferred. */
+export type AstCustomCtx = {
+  kids: readonly unknown[];
+  altPath: readonly number[];
+  src: string;
+  off: number;
+  end: number;
+};
+export type AstCustom = (ctx: AstCustomCtx) => unknown;

src/shape-schema.ts

@@ -105,3 +105,26 @@ export const ADJUDICATIONS = {
   altHeterogeneous: 'Choice arms partition every RD alternative exactly once.',
   ruleKeying: 'Exact IR rule names override inherited cstName mappings.',
 } as const;
+
+/** Emit-time static coverage of Shape AST step/pratt rendering. */
+export type ShapeStepKind =
+  | 'lit' | 'tok' | 'rule' | 'ruleBp' | 'star' | 'opt' | 'sep'
+  | 'altlit' | 'alt' | 'not' | 'seq' | 'sameLine' | 'suppress';
+export type ShapePrattKind =
+  | 'atom' | 'group' | 'prefix' | 'binary' | 'postfix' | 'postfixTok'
+  | 'led' | 'nudSeq' | 'nudCapped';
+export type ShapeUnsupported = { rule: string; construct: string };
+export type ShapeCoverage = {
+  step: Record<ShapeStepKind, number>;
+  pratt: Record<ShapePrattKind, number>;
+  unsupported: ShapeUnsupported[];
+};
+
+export const SHAPE_STEP_KINDS: readonly ShapeStepKind[] = [
+  'lit', 'tok', 'rule', 'ruleBp', 'star', 'opt', 'sep',
+  'altlit', 'alt', 'not', 'seq', 'sameLine', 'suppress',
+] as const;
+export const SHAPE_PRATT_KINDS: readonly ShapePrattKind[] = [
+  'atom', 'group', 'prefix', 'binary', 'postfix', 'postfixTok',
+  'led', 'nudSeq', 'nudCapped',
+] as const;