@crouton-kit/capture 1.3.8 → 1.3.10

package/src/contracts/a11y.ts

@@ -0,0 +1,33 @@
+/** Frozen retained accessibility tree contract (U1), with pure validators only. */
+import { Availability, OK, ValidationResult, combine, fail, isObject } from './primitives.js';
+
+export interface AxRectCoverage { readonly eligible: number; readonly attempted: number; readonly succeeded: number; readonly failed: number; readonly skipped: number; }
+/** Every retained AX node is source ordered, including ignored/unnamed nodes, and preserves evidence verbatim. */
+export interface AxTreeNode { readonly axId: string; readonly sourceOrdinal: number; readonly role?: string; readonly name?: string; readonly description?: string; readonly value?: unknown; readonly ignored: boolean; readonly cdpNodeId?: number; readonly backendNodeId?: number; readonly parentAxId?: string; readonly childAxIds: readonly string[]; readonly rect: Availability<unknown>; readonly raw: Record<string, unknown>; }
+/** Exhaustive retained store: first <=5000 source-array nodes, no semantic filtering. */
+export interface AxTreeManifest { readonly schemaVersion: 1; readonly treeId: string; readonly source: 'live' | 'snapshot'; readonly snapshotId?: string; readonly nodes: readonly AxTreeNode[]; readonly sourceTotal?: number; readonly retained: number; readonly dropped?: number; readonly droppedUnknown?: boolean; readonly rectCoverage: AxRectCoverage; readonly iframeExclusion: Availability<null>; }
+/** Sidecar meta at `<owner>/a11y/trees/<tree-id>/meta.json`; tree lifetime equals file lifetime. */
+export interface AxTreeReference { readonly schemaVersion: 1; readonly treeId: string; readonly treePath: string; readonly metaPath: string; readonly owner: string; readonly retained: number; readonly coverage: Pick<AxTreeManifest, 'sourceTotal' | 'dropped' | 'droppedUnknown' | 'rectCoverage'>; }
+export function validateAxTreeManifest(value: unknown): ValidationResult {
+  if (!isObject(value)) return fail('a11y tree must be an object');
+  const errs: ValidationResult[] = [];
+  if (value.schemaVersion !== 1) errs.push(fail('a11y tree schemaVersion must be 1'));
+  if (typeof value.treeId !== 'string' || !value.treeId) errs.push(fail('a11y tree missing treeId'));
+  if (value.source !== 'live' && value.source !== 'snapshot') errs.push(fail('a11y tree source must be live or snapshot'));
+  if (!isObject(value.rectCoverage)) errs.push(fail('a11y tree missing rectCoverage'));
+  if (!isObject(value.iframeExclusion)) errs.push(fail('a11y tree missing iframeExclusion'));
+  if (!Array.isArray(value.nodes)) errs.push(fail('a11y tree requires nodes array'));
+  else {
+    if (value.nodes.length > 5000) errs.push(fail('a11y tree retains more than 5000 nodes'));
+    const ids = new Set<string>();
+    for (const node of value.nodes) {
+      if (!isObject(node) || typeof node.axId !== 'string') { errs.push(fail('a11y tree has malformed node')); continue; }
+      if (ids.has(node.axId)) errs.push(fail(`a11y tree duplicate retained AX ID: ${node.axId}`));
+      ids.add(node.axId);
+    }
+  }
+  if (typeof value.retained !== 'number') errs.push(fail('a11y tree missing retained count'));
+  else if (Array.isArray(value.nodes) && value.retained !== value.nodes.length) errs.push(fail('a11y tree retained count must equal node count'));
+  if (typeof value.sourceTotal === 'number' && typeof value.dropped === 'number' && typeof value.retained === 'number' && value.sourceTotal !== value.retained + value.dropped) errs.push(fail('a11y tree sourceTotal must equal retained + dropped'));
+  return combine(...errs);
+}

package/src/contracts/cursor.ts

@@ -0,0 +1,35 @@
+/** Frozen immutable index/cursor contract (U1), pure types/validators only. */
+import { MAX_CURSOR_BYTES, OK, ValidationResult, combine, fail, isAscii, isObject, isSha256Hex } from './primitives.js';
+
+/** Exactly the five public leaves permitted to materialize immutable cursor indexes. */
+export type CursorLeaf = 'browser detect' | 'browser list' | 'library list' | 'library search' | 'library show';
+export interface ImmutableIndex<Row = unknown> { readonly schemaVersion: 1; readonly leaf: CursorLeaf; readonly path: string; readonly digest: string; readonly createdAt: string; readonly expiresAt: string; readonly filter: Record<string, unknown>; readonly pageSize: number; readonly order: string; readonly coverage: unknown; readonly rows: readonly Row[]; }
+/** Authenticated opaque cursor claims. The serialized token itself is <=2048 ASCII bytes. */
+export interface CursorClaims { readonly schemaVersion: 1; readonly indexDigest: string; readonly leaf: CursorLeaf; readonly filter: Record<string, unknown>; readonly nextExclusiveOrdinal: number; readonly pageSize: number; readonly expiresAt: string; readonly mac: string; }
+export function validateImmutableIndex(value: unknown): ValidationResult {
+  if (!isObject(value)) return fail('immutable index must be an object');
+  const errs: ValidationResult[] = [];
+  if (value.schemaVersion !== 1) errs.push(fail('index schemaVersion must be 1'));
+  if (typeof value.digest !== 'string' || !isSha256Hex(value.digest)) errs.push(fail('index digest must be lowercase SHA-256 hex'));
+  if (!Array.isArray(value.rows)) errs.push(fail('index requires rows array'));
+  if (!(typeof value.pageSize === 'number' && value.pageSize >= 1 && value.pageSize <= 20)) errs.push(fail('index pageSize must be 1..20'));
+  return combine(...errs);
+}
+export function validateCursorToken(token: string): ValidationResult {
+  if (!isAscii(token)) return fail('cursor must be ASCII');
+  if (Buffer.byteLength(token, 'ascii') > MAX_CURSOR_BYTES) return fail(`cursor exceeds ${MAX_CURSOR_BYTES} ASCII bytes`);
+  return OK;
+}
+export function validateCursorClaims(value: unknown): ValidationResult {
+  if (!isObject(value)) return fail('cursor claims must be an object');
+  const errs: ValidationResult[] = [];
+  if (value.schemaVersion !== 1) errs.push(fail('cursor schemaVersion must be 1'));
+  if (typeof value.indexDigest !== 'string' || !isSha256Hex(value.indexDigest)) errs.push(fail('cursor missing valid indexDigest'));
+  if (!['browser detect', 'browser list', 'library list', 'library search', 'library show'].includes(value.leaf as string)) errs.push(fail('cursor has invalid leaf'));
+  if (!isObject(value.filter)) errs.push(fail('cursor missing filter object'));
+  if (typeof value.expiresAt !== 'string' || Number.isNaN(Date.parse(value.expiresAt))) errs.push(fail('cursor missing valid expiresAt'));
+  if (!(typeof value.nextExclusiveOrdinal === 'number' && Number.isSafeInteger(value.nextExclusiveOrdinal) && value.nextExclusiveOrdinal >= 0)) errs.push(fail('cursor nextExclusiveOrdinal must be nonnegative safe integer'));
+  if (!(typeof value.pageSize === 'number' && value.pageSize >= 1 && value.pageSize <= 20)) errs.push(fail('cursor pageSize must be 1..20'));
+  if (typeof value.mac !== 'string' || !value.mac) errs.push(fail('cursor missing MAC'));
+  return combine(...errs);
+}

package/src/contracts/index.ts

@@ -0,0 +1,15 @@
+/**
+ * U1 frozen Capture hard-cut contract surface. Import from this module for
+ * descriptor/result/schema types; it has no browser, CLI, output, or process
+ * side effects and remains intentionally unreachable from `src/capture.ts`
+ * until the atomic U15 public cutover.
+ */
+export * from './primitives.js';
+export * from './results.js';
+export * from './routes.js';
+export * from './snapshot.js';
+export * from './neutral.js';
+export * from './a11y.js';
+export * from './cursor.js';
+export * from './motion.js';
+export * from './release.js';

package/src/contracts/motion.ts

@@ -0,0 +1,19 @@
+/** Frozen motion observations schema-2 contract (U1), pure types/validators only. */
+import { Availability, OK, ValidationResult, combine, fail, isObject } from './primitives.js';
+
+export const MOTION_OBSERVATION_FAMILIES = ['source-record', 'trace-event', 'frame-interval', 'frame-pixel-delta', 'element-rect-delta', 'observer-rect-delta'] as const;
+export type MotionObservationFamily = (typeof MOTION_OBSERVATION_FAMILIES)[number];
+/** Source ordinals are contiguous across the entire recording before final write. */
+export interface MotionObservation { readonly id: string; readonly family: MotionObservationFamily; readonly sourceOrdinal: number; readonly kindRank: number; readonly childRank: number; readonly values: Record<string, unknown>; readonly availability: Availability<null>; readonly provenance: { readonly recordingId: string; readonly artifactPath: string; readonly jsonPointer: string }; }
+export interface MotionObservationsManifest { readonly schemaVersion: 2; readonly recordingId: string; readonly sourceSchemaVersion: 2; readonly observations: readonly MotionObservation[]; readonly completeWithinRetainedCoverage: true; readonly ordering: '(sourceOrdinal,kind-rank,child-rank)'; }
+export function validateMotionObservationsManifest(value: unknown): ValidationResult {
+  if (!isObject(value)) return fail('motion observations must be an object');
+  const errs: ValidationResult[] = [];
+  if (value.schemaVersion !== 2 || value.sourceSchemaVersion !== 2) errs.push(fail('motion observations requires recording/source schemaVersion 2'));
+  if (typeof value.recordingId !== 'string' || !value.recordingId) errs.push(fail('motion observations missing recordingId'));
+  if (value.ordering !== '(sourceOrdinal,kind-rank,child-rank)') errs.push(fail('motion observations has wrong ordering declaration'));
+  if (value.completeWithinRetainedCoverage !== true) errs.push(fail('motion observations must attest retained coverage completeness'));
+  if (!Array.isArray(value.observations)) errs.push(fail('motion observations requires array'));
+  else for (const observation of value.observations) if (!isObject(observation) || typeof observation.id !== 'string' || !MOTION_OBSERVATION_FAMILIES.includes(observation.family as MotionObservationFamily) || !Number.isSafeInteger(observation.sourceOrdinal)) errs.push(fail('motion observations contains malformed observation'));
+  return combine(...errs);
+}

package/src/contracts/neutral.ts

@@ -0,0 +1,56 @@
+/** Frozen neutral measurement derived-read contracts (U1), pure types/validators only. */
+import { Availability, OK, ValidationResult, combine, fail, isObject } from './primitives.js';
+
+/** The eleven canonical family order is semantic and deterministic. */
+export const NEUTRAL_FAMILIES = [
+  'viewport-box-position', 'element-scroll-extent', 'native-interactive-box-size',
+  'computed-color-pair-contrast', 'sampled-hit-reception', 'text-inline-extent',
+  'form-control-state', 'media-state', 'animation-state',
+  'opaque-background-sibling-box-intersection',
+  'css-overflow-visible-descendant-peer-box-intersection',
+] as const;
+export type NeutralFamily = (typeof NEUTRAL_FAMILIES)[number];
+
+export interface NumericSummary { readonly count: number; readonly unavailableCount: number; readonly min: number | null; readonly p25: number | null; readonly p50: number | null; readonly p75: number | null; readonly max: number | null; }
+export interface FactProvenance { readonly snapshotId: string; readonly sources: readonly string[]; readonly artifactPath: string; readonly jsonPointer: string; }
+export interface NeutralFact { readonly id: string; readonly family: NeutralFamily; readonly schemaVersion: 1; readonly subjects: readonly string[]; readonly values: Record<string, unknown>; readonly units: Record<string, string>; readonly availability: Availability<null>; readonly provenance: FactProvenance; }
+export interface FamilyCoverage { readonly populationDefinition: string; readonly schemaVersion: 1; readonly sources: readonly string[]; readonly availability: Availability<null>; readonly populationCount: number; readonly measuredCount: number; readonly unavailableCount: number; readonly sourceTotal?: number; readonly kept: number; readonly dropped?: number; readonly droppedUnknown?: boolean; readonly caps: readonly string[]; readonly exclusions: readonly string[]; readonly unavailableReasons: Readonly<Record<string, number>>; }
+export interface NeutralFamilyStore { readonly family: NeutralFamily; readonly coverage: FamilyCoverage; readonly numericSummaries: Readonly<Record<string, NumericSummary>>; readonly categoricalMaps: Readonly<Record<string, Readonly<Record<string, number>>>>; readonly relationCandidateAccounting?: Record<string, number>; readonly facts: readonly NeutralFact[]; }
+/** Exhaustive retained measurement evidence, never a bounded display projection. */
+export interface FactsManifest { readonly schemaVersion: 1; readonly snapshotIds: readonly string[]; readonly familyOrder: readonly NeutralFamily[]; readonly families: readonly NeutralFamilyStore[]; readonly completeWithinRetainedCoverage: true; }
+
+/** One merged snapshot-local subject; collisions never merge subjects. */
+export interface SelectorSubject { readonly subjectId: string; readonly snapshotId: string; readonly geometryOrdinal?: number; readonly axSourceOrdinal?: number; readonly textSourceOrdinal?: number; readonly backendNodeId?: number; readonly css?: readonly string[]; readonly axIds?: readonly string[]; readonly axNames?: readonly string[]; readonly text?: readonly string[]; }
+export interface SelectorsManifest { readonly schemaVersion: 1; readonly snapshotIds: readonly string[]; readonly order: 'geometry-ordinal-then-ax-document-order-then-text-capture-order'; readonly subjects: readonly SelectorSubject[]; }
+
+/** Source occurrence attested by a derived read. SHA-256 is over source `meta.json` bytes. */
+export interface ReadSourceOccurrence { readonly snapshotId: string; readonly canonicalPath: string; readonly metaSchemaVersion: 1 | 2; readonly metaSha256: string; }
+export interface DerivedReadManifest { readonly schemaVersion: 1; readonly readId: string; readonly owner: string; readonly operation: string; readonly sources: readonly ReadSourceOccurrence[]; readonly factsPath: string; readonly selectorsPath: string; readonly familyCounts: Readonly<Record<string, number>>; readonly factOrderVersion: 1; readonly selectorOrderVersion: 1; readonly completeWithinRetainedCoverage: true; readonly cropsPath?: string; }
+
+export function validateFactsManifest(value: unknown): ValidationResult {
+  if (!isObject(value)) return fail('facts manifest must be an object');
+  const errs: ValidationResult[] = [];
+  if (value.schemaVersion !== 1) errs.push(fail('facts schemaVersion must be 1'));
+  if (!Array.isArray(value.snapshotIds) || !value.snapshotIds.every((x) => typeof x === 'string')) errs.push(fail('facts requires snapshotIds string array'));
+  if (!Array.isArray(value.familyOrder) || !Array.isArray(value.families)) errs.push(fail('facts requires familyOrder and families arrays'));
+  else for (const family of value.families) {
+    if (!isObject(family) || typeof family.family !== 'string' || !isObject(family.coverage) || !Array.isArray(family.facts)) errs.push(fail('facts contains malformed family store'));
+  }
+  if (value.completeWithinRetainedCoverage !== true) errs.push(fail('facts must attest completeWithinRetainedCoverage=true'));
+  return combine(...errs);
+}
+export function validateSelectorsManifest(value: unknown): ValidationResult {
+  if (!isObject(value)) return fail('selectors manifest must be an object');
+  if (value.schemaVersion !== 1) return fail('selectors schemaVersion must be 1');
+  if (!Array.isArray(value.snapshotIds) || !Array.isArray(value.subjects) || typeof value.order !== 'string') return fail('selectors requires snapshotIds, order, and subjects');
+  return OK;
+}
+export function validateDerivedReadManifest(value: unknown): ValidationResult {
+  if (!isObject(value)) return fail('derived read manifest must be an object');
+  const errs: ValidationResult[] = [];
+  if (value.schemaVersion !== 1) errs.push(fail('derived read manifest schemaVersion must be 1'));
+  for (const f of ['readId', 'owner', 'operation', 'factsPath', 'selectorsPath']) if (typeof value[f] !== 'string' || !value[f]) errs.push(fail(`missing ${f}`));
+  if (!Array.isArray(value.sources)) errs.push(fail('derived read manifest requires sources array'));
+  if (value.completeWithinRetainedCoverage !== true) errs.push(fail('derived read must attest completeWithinRetainedCoverage=true'));
+  return combine(...errs);
+}

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);
+}