@crouton-kit/capture 1.3.7 → 1.3.9

package/src/contracts/primitives.ts

@@ -0,0 +1,205 @@
+/**
+ * Frozen shared contract primitives for the Capture measurement/help hard cut
+ * (build unit U1). This module owns the small, purely-computational validators
+ * and shape vocabulary that every other `src/contracts/*` module builds on:
+ * argv grammar, ID grammars, integer/decimal grammars, byte bounds, coordinate
+ * spaces, and availability shapes.
+ *
+ * CONTRACT: this file is type/interface + pure functions ONLY. It imports no
+ * browser, CLI, filesystem-effect, or caller-facing print/exit API. It never
+ * emits to stdout/stderr and never exits the process. Downstream units freeze
+ * against these types; changing a shape here is a contract change.
+ *
+ * EVIDENCE POLICY: nothing here deletes, substitutes, hashes, or redacts a code
+ * point. Sanitation, where it exists downstream, is lossless/reversible and
+ * protects the result protocol, never secrecy (see `taste/no-redaction`).
+ */
+
+/** Structured, side-effect-free validation outcome. Validators never throw for invalid data. */
+export interface ValidationResult {
+  readonly valid: boolean;
+  /** Human-readable, machine-stable reasons. Empty iff `valid`. */
+  readonly errors: readonly string[];
+}
+
+/** A passing result. */
+export const OK: ValidationResult = { valid: true, errors: [] };
+
+/** Build a failing result from one or more reasons. */
+export function fail(...errors: string[]): ValidationResult {
+  return { valid: false, errors };
+}
+
+/** Merge child results; valid iff every child is valid, accumulating all reasons in order. */
+export function combine(...results: readonly ValidationResult[]): ValidationResult {
+  const errors: string[] = [];
+  for (const r of results) errors.push(...r.errors);
+  return errors.length === 0 ? OK : { valid: false, errors };
+}
+
+/** Prefix every reason of a result with `context: `. Useful for nested field paths. */
+export function contextualize(context: string, result: ValidationResult): ValidationResult {
+  if (result.valid) return OK;
+  return { valid: false, errors: result.errors.map((e) => `${context}: ${e}`) };
+}
+
+// ---------------------------------------------------------------------------
+// Byte bounds (all measured as UTF-8 unless a contract narrows to ASCII).
+// ---------------------------------------------------------------------------
+
+/** Maximum bytes of a single argv value (unless a tighter per-flag bound applies). */
+export const MAX_ARGV_BYTES = 4096;
+/** Maximum bytes of any single bounded-leaf success payload, independently in prose and JSON. */
+export const MAX_BOUNDED_BYTES = 16_384;
+/** Maximum ASCII bytes of an opaque pagination cursor token. */
+export const MAX_CURSOR_BYTES = 2048;
+/** Maximum bytes of one progress line on a declared-progress leaf. */
+export const MAX_PROGRESS_LINE_BYTES = 256;
+/** Maximum total progress bytes across a whole sweep run. */
+export const MAX_PROGRESS_TOTAL_BYTES = 25_600;
+/** Default and maximum page size for every immutable-cursor leaf. */
+export const DEFAULT_PAGE_SIZE = 20;
+export const MAX_PAGE_SIZE = 20;
+
+/** UTF-8 byte length of a string without allocating a Buffer view of the caller's data. */
+export function utf8ByteLength(value: string): number {
+  return Buffer.byteLength(value, 'utf8');
+}
+
+/** True iff every code unit is ASCII (0x00–0x7F). */
+export function isAscii(value: string): boolean {
+  for (let i = 0; i < value.length; i++) {
+    if (value.charCodeAt(i) > 0x7f) return false;
+  }
+  return true;
+}
+
+/** True iff the string contains no NUL. */
+export function isNulFree(value: string): boolean {
+  return value.indexOf('\u0000') === -1;
+}
+
+/** Validate a raw argv value: NUL-free UTF-8 within the declared byte bound. */
+export function validateArgvValue(value: string, maxBytes: number = MAX_ARGV_BYTES): ValidationResult {
+  if (!isNulFree(value)) return fail('argv value contains NUL');
+  const bytes = utf8ByteLength(value);
+  if (bytes > maxBytes) return fail(`argv value is ${bytes} bytes, exceeds ${maxBytes}`);
+  return OK;
+}
+
+// ---------------------------------------------------------------------------
+// ID and number grammars (case-sensitive; no coercion; safe integers only).
+// ---------------------------------------------------------------------------
+
+/** Public container IDs: session, HAR, snapshot, tree, recording. */
+export const CONTAINER_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+/** Evidence IDs: fact IDs, occurrence IDs, subject IDs, AX IDs. */
+export const EVIDENCE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,127}$/;
+/** `uint` grammar: 0 or a no-leading-zero positive. */
+export const UINT_RE = /^(?:0|[1-9][0-9]*)$/;
+/** `positive-int` grammar: a no-leading-zero positive. */
+export const POSITIVE_INT_RE = /^[1-9][0-9]*$/;
+/** `signed-int` grammar: 0 or a signed no-leading-zero integer (no `-0`). */
+export const SIGNED_INT_RE = /^(?:0|-?[1-9][0-9]*)$/;
+/** Non-exponent decimal grammar (no `+`, `-0`, leading zero, NaN, or infinity). Sweep endpoints override this. */
+export const DECIMAL_RE = /^(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$/;
+
+export function isContainerId(value: string): boolean {
+  return CONTAINER_ID_RE.test(value);
+}
+export function isEvidenceId(value: string): boolean {
+  return EVIDENCE_ID_RE.test(value);
+}
+
+/** Parse a `uint` token to a safe integer; null on grammar or safe-integer failure. */
+export function parseUint(token: string): number | null {
+  if (!UINT_RE.test(token)) return null;
+  const n = Number(token);
+  return Number.isSafeInteger(n) ? n : null;
+}
+
+/** Parse a `positive-int` token to a safe integer; null on failure. */
+export function parsePositiveInt(token: string): number | null {
+  if (!POSITIVE_INT_RE.test(token)) return null;
+  const n = Number(token);
+  return Number.isSafeInteger(n) && n >= 1 ? n : null;
+}
+
+/** Parse a `signed-int` token to a safe integer; null on failure. */
+export function parseSignedInt(token: string): number | null {
+  if (!SIGNED_INT_RE.test(token)) return null;
+  const n = Number(token);
+  return Number.isSafeInteger(n) ? n : null;
+}
+
+/** True iff `value` is an absolute WHATWG http:/https: URL. */
+export function isAbsoluteHttpUrl(value: string): boolean {
+  let u: URL;
+  try {
+    u = new URL(value);
+  } catch {
+    return false;
+  }
+  return u.protocol === 'http:' || u.protocol === 'https:';
+}
+
+/** Lowercase 64-hex SHA-256 digest grammar. */
+export const SHA256_HEX_RE = /^[0-9a-f]{64}$/;
+export function isSha256Hex(value: string): boolean {
+  return SHA256_HEX_RE.test(value);
+}
+
+// ---------------------------------------------------------------------------
+// Coordinate spaces and availability.
+// ---------------------------------------------------------------------------
+
+/**
+ * The three declared coordinate spaces. Layers have NO Capture geometric
+ * rectangle or coordinate space and therefore never carry one of these.
+ */
+export type CoordinateSpace =
+  | 'top-visual-viewport/css-px'
+  | 'top-page/css-px'
+  | 'screenshot/device-px';
+
+export const COORDINATE_SPACES: readonly CoordinateSpace[] = [
+  'top-visual-viewport/css-px',
+  'top-page/css-px',
+  'screenshot/device-px',
+];
+
+export function isCoordinateSpace(value: string): value is CoordinateSpace {
+  return (COORDINATE_SPACES as readonly string[]).includes(value);
+}
+
+/** A retained rectangle always names its coordinate space and unit. */
+export interface GeometricRect {
+  readonly space: CoordinateSpace;
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/**
+ * An availability wrapper. A dependent fact is either present with a value or
+ * absent with a fixed machine-stable reason and optional detail. Zero is NEVER
+ * used to stand in for unavailable evidence.
+ */
+export type Availability<T> =
+  | { readonly available: true; readonly value: T }
+  | { readonly available: false; readonly reason: string; readonly details?: string };
+
+export function isAvailable<T>(a: Availability<T>): a is { available: true; value: T } {
+  return a.available === true;
+}
+
+/** True iff `x` is a finite number (never NaN/±Infinity). Availability, not zero, marks missing facts. */
+export function isFiniteNumber(x: unknown): x is number {
+  return typeof x === 'number' && Number.isFinite(x);
+}
+
+/** True iff `x` is a plain (non-null, non-array) object. */
+export function isObject(x: unknown): x is Record<string, unknown> {
+  return typeof x === 'object' && x !== null && !Array.isArray(x);
+}

package/src/contracts/release.ts

@@ -0,0 +1,17 @@
+/** Frozen hard-cut release metadata contract (U1), pure types/validators only. */
+import { OK, ValidationResult, combine, fail, isObject, isSha256Hex } from './primitives.js';
+/** Canonical JSON stored in the annotated release tag message. */
+export interface ReleaseTagMetadata { readonly schemaVersion: 1; readonly package: '@crouton-kit/capture'; readonly version: string; readonly baseSha: string; readonly releaseSha: string; readonly gateSha: string; readonly tarball: { readonly filename: string; readonly bytes: number; readonly sha256: string; readonly integrity: string }; readonly runtime: { readonly node: string; readonly npm: string; readonly pnpm: string }; }
+/** Persisted release controller state; conflicts are nonmutating. */
+export type ReleaseDisposition = 'candidate' | 'release_already_published' | 'release_publish_retryable' | 'registry_integrity_conflict' | 'release_state_conflict';
+export function validateReleaseTagMetadata(value: unknown): ValidationResult {
+  if (!isObject(value)) return fail('release tag metadata must be an object');
+  const errs: ValidationResult[] = [];
+  if (value.schemaVersion !== 1) errs.push(fail('release tag schemaVersion must be 1'));
+  if (value.package !== '@crouton-kit/capture') errs.push(fail('release tag package must be @crouton-kit/capture'));
+  if (typeof value.version !== 'string' || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(value.version)) errs.push(fail('invalid version'));
+  for (const key of ['baseSha', 'releaseSha', 'gateSha']) if (typeof value[key] !== 'string' || !/^[0-9a-f]{40,64}$/.test(value[key] as string)) errs.push(fail(`invalid ${key}`));
+  if (!isObject(value.tarball) || typeof value.tarball.filename !== 'string' || !(typeof value.tarball.bytes === 'number' && value.tarball.bytes >= 0) || typeof value.tarball.integrity !== 'string' || typeof value.tarball.sha256 !== 'string' || !isSha256Hex(value.tarball.sha256)) errs.push(fail('invalid tarball metadata'));
+  if (!isObject(value.runtime) || !['node', 'npm', 'pnpm'].every((key) => typeof value.runtime[key] === 'string' && value.runtime[key])) errs.push(fail('invalid runtime metadata'));
+  return combine(...errs);
+}

package/src/contracts/results.ts

@@ -0,0 +1,208 @@
+/**
+ * Frozen result-lane contracts (U1). Two lanes only:
+ *
+ *  - `bounded:<domain>`  — one typed projection through the bounded output
+ *    kernel: at most {@link MAX_BOUNDED_BYTES} UTF-8 bytes independently in
+ *    prose and JSON, with fixed identity/summary/scope/coverage/count/artifact
+ *    metadata that is NEVER dropped, and optional records removed only at
+ *    record boundaries (never byte-sliced) until both encodings fit.
+ *  - `exact-raw:<payload>` — handler-produced bytes/text for one named payload,
+ *    unbounded and preserved exactly (including final-newline presence); empty
+ *    stderr on success. Global `--json` is rejected before effects.
+ *
+ * This module is type/interface + pure validators only. It imports no print or
+ * exit API. The "no direct stdout" rule is a contract on the handlers that
+ * produce these values, encoded in the descriptor layer (see `routes.ts`).
+ */
+
+import {
+  MAX_BOUNDED_BYTES,
+  OK,
+  ValidationResult,
+  combine,
+  contextualize,
+  fail,
+  isObject,
+  utf8ByteLength,
+} from './primitives.js';
+
+export { MAX_BOUNDED_BYTES };
+
+/** Discriminator for the two public result lanes plus the effect-only branch/launcher rows. */
+export type ResultLaneKind = 'bounded' | 'exact-raw' | 'branch' | 'launcher-metadata';
+
+/** A `bounded:<domain>` lane naming exactly one bounded projection domain. */
+export interface BoundedLane {
+  readonly kind: 'bounded';
+  readonly domain: string;
+  /** The JSON/prose schema name the bounded kernel serializes. */
+  readonly schema: string;
+}
+
+/** An exact raw lane naming its handler-owned unbounded payload. */
+export interface ExactRawLane {
+  readonly kind: 'exact-raw';
+  /** The payload type, e.g. `recorded HAR bytes`. */
+  readonly payload: string;
+}
+
+/** A branch row: help + child assembly, no result. */
+export interface BranchLane {
+  readonly kind: 'branch';
+}
+
+/** The launcher `--version` metadata row. */
+export interface LauncherMetadataLane {
+  readonly kind: 'launcher-metadata';
+}
+
+export type ResultLane = BoundedLane | ExactRawLane | BranchLane | LauncherMetadataLane;
+
+// ---------------------------------------------------------------------------
+// Byte/list bounds descriptor a bounded leaf declares.
+// ---------------------------------------------------------------------------
+
+/**
+ * Every bounded leaf declares its collection and byte bounds up front so the
+ * registry can reject a growing collection that lacks an omission contract.
+ */
+export interface BoundedBounds {
+  /** Independent max UTF-8 bytes of prose and JSON. Always {@link MAX_BOUNDED_BYTES}. */
+  readonly maxBytes: number;
+  /** Max displayed records for the primary collection (e.g. 20). */
+  readonly maxRecords: number;
+  /**
+   * Whether the primary collection can grow with the underlying source. A
+   * growing collection MUST declare `paginated` so a cursor covers every row.
+   */
+  readonly growing: boolean;
+  /** True iff this leaf adopts the immutable-cursor pagination service. */
+  readonly paginated: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Bounded projection payload shape (the kernel's typed input, pre-encoding).
+// ---------------------------------------------------------------------------
+
+/** Fixed metadata every bounded projection carries and never drops when bounding. */
+export interface BoundedFixedMeta {
+  readonly domain: string;
+  readonly schema: string;
+  /** Identity of the subject the projection describes (snapshot id, session id, tree id, …). */
+  readonly identity: Record<string, string>;
+  /** Scope and source coverage (populations/caps/availability), preserved verbatim. */
+  readonly coverage: unknown;
+  /** total/displayed/omitted/limit for the primary collection. */
+  readonly counts: BoundedCollectionCounts;
+  /** Absolute artifact paths a caller can re-read for the exhaustive evidence. */
+  readonly artifacts: readonly string[];
+}
+
+/** total/displayed/omitted/limit accounting for one bounded collection. */
+export interface BoundedCollectionCounts {
+  readonly total: number;
+  readonly displayed: number;
+  readonly omitted: number;
+  readonly limit: number;
+  /** Machine-stable reasons the omitted records were dropped (e.g. `byte-bound`, `record-limit`). */
+  readonly omissionCauses: readonly string[];
+}
+
+/**
+ * A capped string reports byte accounting and an exact RFC-6901 pointer into
+ * the exhaustive artifact rather than silently truncating.
+ */
+export interface CappedStringMeta {
+  readonly sourceBytes: number;
+  readonly displayedBytes: number;
+  readonly omittedBytes: number;
+  /** Absolute artifact path + RFC-6901 JSON Pointer to the full value. */
+  readonly artifactPath: string;
+  readonly jsonPointer: string;
+}
+
+/**
+ * A structured public error (bounded, factual). Written to stderr by the result
+ * owner, never by a handler. Exit 2 = invalid route/grammar/selection/cursor
+ * input; exit 3 = source/runtime/publication failure.
+ */
+export interface BoundedError {
+  readonly message: string;
+  readonly exit: 2 | 3;
+  readonly details?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Validators.
+// ---------------------------------------------------------------------------
+
+export function validateResultLane(lane: ResultLane): ValidationResult {
+  switch (lane.kind) {
+    case 'bounded':
+      if (!lane.domain) return fail('bounded lane missing domain');
+      if (!lane.schema) return fail('bounded lane missing schema');
+      return OK;
+    case 'exact-raw':
+      if (!lane.payload) return fail('exact-raw lane missing payload type');
+      return OK;
+    case 'branch':
+    case 'launcher-metadata':
+      return OK;
+    default:
+      return fail(`unknown result lane kind: ${(lane as { kind: string }).kind}`);
+  }
+}
+
+export function validateBoundedBounds(bounds: BoundedBounds): ValidationResult {
+  const errs: ValidationResult[] = [];
+  if (bounds.maxBytes !== MAX_BOUNDED_BYTES) {
+    errs.push(fail(`bounded maxBytes must be ${MAX_BOUNDED_BYTES}, got ${bounds.maxBytes}`));
+  }
+  if (!(bounds.maxRecords >= 0)) errs.push(fail('bounded maxRecords must be >= 0'));
+  if (bounds.growing && !bounds.paginated) {
+    errs.push(fail('a growing bounded collection must declare pagination (cursor coverage)'));
+  }
+  return combine(...errs);
+}
+
+/** True iff both encodings fit the independent byte bound. */
+export function fitsBoundedBounds(prose: string, json: string): ValidationResult {
+  const errs: ValidationResult[] = [];
+  const p = utf8ByteLength(prose);
+  const j = utf8ByteLength(json);
+  if (p > MAX_BOUNDED_BYTES) errs.push(fail(`prose is ${p} bytes, exceeds ${MAX_BOUNDED_BYTES}`));
+  if (j > MAX_BOUNDED_BYTES) errs.push(fail(`json is ${j} bytes, exceeds ${MAX_BOUNDED_BYTES}`));
+  return combine(...errs);
+}
+
+/** Validate collection counts are internally consistent: displayed+omitted==total, displayed<=limit. */
+export function validateCollectionCounts(counts: BoundedCollectionCounts): ValidationResult {
+  const errs: ValidationResult[] = [];
+  if (counts.displayed + counts.omitted !== counts.total) {
+    errs.push(fail(`displayed(${counts.displayed}) + omitted(${counts.omitted}) != total(${counts.total})`));
+  }
+  if (counts.displayed > counts.limit) {
+    errs.push(fail(`displayed(${counts.displayed}) exceeds limit(${counts.limit})`));
+  }
+  if (counts.omitted > 0 && counts.omissionCauses.length === 0) {
+    errs.push(fail('omitted records present but no omissionCauses declared'));
+  }
+  return combine(...errs);
+}
+
+/** Validate the fixed metadata block that must precede any bounded records. */
+export function validateBoundedFixedMeta(meta: unknown): ValidationResult {
+  if (!isObject(meta)) return fail('bounded fixed meta must be an object');
+  const errs: ValidationResult[] = [];
+  if (typeof meta.domain !== 'string' || !meta.domain) errs.push(fail('missing domain'));
+  if (typeof meta.schema !== 'string' || !meta.schema) errs.push(fail('missing schema'));
+  if (!isObject(meta.identity)) errs.push(fail('missing identity object'));
+  if (!('coverage' in meta)) errs.push(fail('missing coverage'));
+  if (!Array.isArray(meta.artifacts)) errs.push(fail('artifacts must be an array of absolute paths'));
+  if (isObject(meta.counts)) {
+    errs.push(contextualize('counts', validateCollectionCounts(meta.counts as BoundedCollectionCounts)));
+  } else {
+    errs.push(fail('missing counts'));
+  }
+  return combine(...errs);
+}

package/src/contracts/routes.ts

@@ -0,0 +1,140 @@
+/**
+ * Frozen public route/leaf descriptor contract. A descriptor is the sole truth
+ * for one canonical public path. It names inputs, effects, output lane, bounds,
+ * stderr, exits, and an opaque handler slot; it never imports a handler.
+ */
+import { OK, ValidationResult, combine, contextualize, fail } from './primitives.js';
+import { BoundedBounds, ResultLane, validateBoundedBounds, validateResultLane } from './results.js';
+
+export interface RouteEffects {
+  readonly browser: boolean;
+  readonly session: boolean;
+  readonly artifact: boolean;
+  readonly environment: boolean;
+}
+export const NO_EFFECTS: RouteEffects = { browser: false, session: false, artifact: false, environment: false };
+
+export interface PositionalSpec { readonly name: string; readonly grammar: string; readonly required: boolean; readonly variadic?: boolean; }
+export interface FlagSpec {
+  readonly name: string;
+  readonly grammar: string | 'boolean';
+  /** Required singleton unless repeatable is explicitly declared. */
+  readonly required?: boolean;
+  /** Repetition is accepted; required means at least one occurrence. */
+  readonly repeatable?: boolean;
+  readonly values?: readonly string[];
+  readonly default?: string | number | boolean;
+  readonly units?: string;
+}
+export type StderrPolicy = 'empty-on-success' | 'declared-progress';
+export type LeafExit = 0 | 2 | 3 | 10 | 11 | 130 | 143;
+
+export interface BranchDescriptor { readonly kind: 'branch'; readonly path: string; readonly summary: string; }
+export interface LeafDescriptor {
+  readonly kind: 'leaf'; readonly path: string; readonly summary: string;
+  readonly positionals: readonly PositionalSpec[]; readonly flags: readonly FlagSpec[];
+  readonly mutualExclusions: readonly (readonly string[])[]; readonly effects: RouteEffects;
+  readonly result: ResultLane; readonly bounds?: BoundedBounds; readonly stderr: StderrPolicy;
+  readonly exits: readonly LeafExit[]; readonly handler: string;
+}
+export type RouteDescriptor = BranchDescriptor | LeafDescriptor;
+
+/** All public non-root branches in the seven-noun Capture topology. */
+export const EXPECTED_BRANCH_PATHS: readonly string[] = [
+  'session', 'page', 'measure', 'measure map', 'measure variation', 'motion',
+  'traffic', 'traffic har', 'browser', 'library',
+];
+
+/** Every public runnable path, exactly once. There are no aliases. */
+export const EXPECTED_LEAF_PATHS: readonly string[] = [
+  'session start', 'session stop', 'session list', 'session view', 'session log',
+  'page a11y', 'page screenshot', 'page click', 'page type', 'page navigate', 'page exec',
+  'measure snap', 'measure check', 'measure geometry', 'measure map focus', 'measure map scroll', 'measure map layers', 'measure explain', 'measure variation diff', 'measure variation census', 'measure variation sweep',
+  'motion rec', 'motion mask', 'motion timeline', 'motion jank', 'motion response',
+  'traffic record', 'traffic har create', 'traffic har read', 'traffic har delete',
+  'browser detect', 'browser list', 'browser open', 'browser reset', 'browser network', 'browser cdp',
+  'library list', 'library search', 'library show', 'library read',
+];
+
+export const PAGINATED_LEAF_PATHS: readonly string[] = [
+  'browser detect', 'browser list', 'library list', 'library search', 'library show',
+];
+
+/** Exact raw leaves are handler-owned bytes/text, never global JSON envelopes. */
+export const EXACT_RAW_LEAF_PAYLOADS: Readonly<Record<string, string>> = {
+  'session log': 'recorded session log bytes',
+  'page a11y': 'full accessibility-tree text',
+  'page exec': 'handler evaluation bytes/text',
+  'traffic har read': 'stored HAR bytes',
+  'browser cdp': 'raw protocol response bytes',
+  'library read': 'bundled function source bytes',
+};
+
+/** Legacy spellings are deliberately unreachable after the U15 cutover. */
+export const FORBIDDEN_PUBLIC_PATHS: readonly string[] = [
+  '-v', 'version', 'log', 'detect', 'list', 'open', 'reset-tab', 'screenshot',
+  'click', 'type', 'a11y', 'record', 'navigate', 'network', 'har', 'lib', 'cdp',
+  'exec', 'motion observations', '__bridge-serve',
+];
+
+function flagNames(leaf: LeafDescriptor): Set<string> { return new Set(leaf.flags.map((flag) => flag.name)); }
+
+export function validateLeafDescriptor(leaf: LeafDescriptor): ValidationResult {
+  const errors: ValidationResult[] = [];
+  if (!leaf.path) errors.push(fail('leaf has empty path'));
+  const fixed = leaf.positionals.filter((positional) => !positional.variadic);
+  const required = fixed.filter((positional) => positional.required);
+  const optional = fixed.filter((positional) => !positional.required);
+  if (required.length > 1 || optional.length > 1 || fixed.length > 2 || (fixed.length === 2 && (!fixed[0].required || fixed[1].required))) {
+    errors.push(fail(`leaf ${leaf.path} permits only one required positional followed by one optional trailing positional`));
+  }
+  const names = flagNames(leaf);
+  if (names.size !== leaf.flags.length) errors.push(fail(`leaf ${leaf.path} declares duplicate flag names`));
+  for (const flag of leaf.flags) {
+    if (!flag.name.startsWith('--')) errors.push(fail(`leaf ${leaf.path} flag ${flag.name} is not a long option`));
+    if (flag.grammar === 'boolean' && (flag.values || flag.default !== undefined || flag.units)) errors.push(fail(`boolean flag ${flag.name} must not declare value metadata`));
+    if (flag.repeatable && flag.default !== undefined) errors.push(fail(`repeatable flag ${flag.name} must not declare a default`));
+  }
+  for (const group of leaf.mutualExclusions) for (const name of group) if (!names.has(name)) errors.push(fail(`leaf ${leaf.path} mutual-exclusion references undeclared flag ${name}`));
+  errors.push(contextualize(`leaf ${leaf.path} result`, validateResultLane(leaf.result)));
+  if (leaf.result.kind === 'bounded') {
+    if (!leaf.bounds) errors.push(fail(`bounded leaf ${leaf.path} missing byte/list bounds`));
+    else errors.push(contextualize(`leaf ${leaf.path} bounds`, validateBoundedBounds(leaf.bounds)));
+  } else if (leaf.result.kind === 'exact-raw') {
+    if (leaf.bounds) errors.push(fail(`exact raw leaf ${leaf.path} must not declare bounded bounds`));
+    if (leaf.stderr !== 'empty-on-success') errors.push(fail(`exact raw leaf ${leaf.path} must have empty-on-success stderr`));
+  } else errors.push(fail(`leaf ${leaf.path} must use bounded or exact-raw result lane`));
+  if (!leaf.handler) errors.push(fail(`leaf ${leaf.path} missing handler slot`));
+  if (!leaf.exits.length) errors.push(fail(`leaf ${leaf.path} declares no exits`));
+  return combine(...errors);
+}
+
+export function validateBranchDescriptor(branch: BranchDescriptor): ValidationResult {
+  if (!branch.path) return fail('branch has empty path');
+  if ((branch as unknown as { handler?: unknown }).handler !== undefined) return fail(`branch ${branch.path} must not declare a handler`);
+  return OK;
+}
+
+/** Validate an assembled public registry against the canonical seven-noun census. */
+export function validateRegistry(descriptors: readonly RouteDescriptor[]): ValidationResult {
+  const errors: ValidationResult[] = [];
+  const seen = new Set<string>(); const leaves = new Set<string>(); const branches = new Set<string>();
+  for (const descriptor of descriptors) {
+    if (seen.has(descriptor.path)) errors.push(fail(`duplicate route path: ${descriptor.path}`));
+    seen.add(descriptor.path);
+    if (FORBIDDEN_PUBLIC_PATHS.includes(descriptor.path)) errors.push(fail(`forbidden public path present: ${descriptor.path}`));
+    if (descriptor.kind === 'leaf') {
+      leaves.add(descriptor.path); errors.push(validateLeafDescriptor(descriptor));
+      const expectedPayload = EXACT_RAW_LEAF_PAYLOADS[descriptor.path];
+      if (expectedPayload && (descriptor.result.kind !== 'exact-raw' || descriptor.result.payload !== expectedPayload)) errors.push(fail(`leaf ${descriptor.path} must be exact-raw:${expectedPayload}`));
+      if (!expectedPayload && descriptor.result.kind === 'exact-raw') errors.push(fail(`leaf ${descriptor.path} is not declared exact-raw by the public output contract`));
+      const paginated = descriptor.result.kind === 'bounded' && descriptor.bounds?.paginated === true;
+      if (PAGINATED_LEAF_PATHS.includes(descriptor.path) !== paginated) errors.push(fail(`leaf ${descriptor.path} pagination declaration disagrees with census`));
+    } else { branches.add(descriptor.path); errors.push(validateBranchDescriptor(descriptor)); }
+  }
+  for (const path of EXPECTED_LEAF_PATHS) if (!leaves.has(path)) errors.push(fail(`missing expected leaf path: ${path}`));
+  for (const path of EXPECTED_BRANCH_PATHS) if (!branches.has(path)) errors.push(fail(`missing expected branch path: ${path}`));
+  for (const path of leaves) if (!EXPECTED_LEAF_PATHS.includes(path)) errors.push(fail(`unexpected leaf path (not in census): ${path}`));
+  for (const path of branches) if (!EXPECTED_BRANCH_PATHS.includes(path)) errors.push(fail(`unexpected branch path (not in census): ${path}`));
+  return combine(...errors);
+}