@crouton-kit/capture 1.3.8 → 1.3.9

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

package/src/contracts/snapshot.ts

@@ -0,0 +1,92 @@
+/** Immutable source snapshot contracts. V2 is the only acquisition schema; V1 is read-only legacy evidence. */
+import { OK, ValidationResult, combine, fail, isObject } from './primitives.js';
+
+export type SchemaVersion = 1 | 2;
+export const SNAPSHOT_FACET_NAMES = ['viewport', 'geometry', 'styles', 'hit-testing', 'text', 'forms', 'media', 'animation', 'accessibility', 'queries', 'focus', 'scroll', 'layers', 'states', 'pixels', 'screenshot', 'dom-html'] as const;
+export type SnapshotFacetName = (typeof SNAPSHOT_FACET_NAMES)[number];
+/** @deprecated Legacy source facets are read-only; new snapshots use SNAPSHOT_FACET_NAMES. */
+export const FACET_NAMES = SNAPSHOT_FACET_NAMES;
+export type FacetName = SnapshotFacetName;
+
+export type CollectorCoverage = {
+  readonly retained_count: number;
+  readonly availability: 'available' | { readonly state: 'unavailable'; readonly reason: string };
+  readonly truncation: { readonly state: 'none' } | { readonly state: 'exact'; readonly dropped_count: number } | { readonly state: 'lower_bound'; readonly dropped_count_lower_bound: number } | { readonly state: 'unknown' };
+  readonly source_total: { readonly state: 'exact'; readonly count: number } | { readonly state: 'lower_bound'; readonly count_lower_bound: number } | { readonly state: 'unavailable'; readonly reason: string };
+};
+export type SnapshotFacet = { readonly status: 'available' | 'unavailable' | 'not-requested'; readonly primary_population: { readonly name: string; readonly coverage: CollectorCoverage }; readonly subpopulations: Readonly<Record<string, CollectorCoverage>>; readonly unavailable_reason: string | null };
+export interface CdpEndpoint { readonly host: '127.0.0.1'; readonly port: number; }
+export interface SnapshotTargetAttestation { readonly mode: 'fresh-url' | 'session' | 'explicit-target'; readonly session_id: string | null; readonly session_source: 'active' | 'explicit' | null; readonly target_id: string; readonly endpoint: CdpEndpoint; readonly observed_url: string; }
+export interface SourceManifestArtifact { readonly key: string; readonly path: string; readonly bytes: number; readonly sha256: string; readonly media_type: string; readonly retained_arrays: readonly { readonly key: string; readonly json_pointer: string; readonly retained_count: number }[]; }
+export interface SourceArtifactManifest { readonly schemaVersion: 2; readonly artifacts: readonly SourceManifestArtifact[]; }
+export interface SnapshotMetaV2 {
+  readonly schemaVersion: 2;
+  readonly snapshotId: string;
+  readonly request: Record<string, unknown>;
+  readonly settled: boolean;
+  readonly timing: Record<string, unknown>;
+  readonly coordinateAuthority: Record<string, unknown>;
+  readonly contentInputs: Record<string, unknown>;
+  readonly target: SnapshotTargetAttestation;
+  readonly facets: { readonly [K in SnapshotFacetName]: SnapshotFacet };
+  readonly source_artifact_manifest: SourceArtifactManifest;
+  readonly sourcePixelCoverage: unknown;
+}
+export interface SnapshotMetaV1 { readonly schemaVersion?: 1; readonly snapshotId: string; readonly request?: Record<string, unknown>; readonly facets: readonly { readonly name: string; readonly path: string }[]; }
+export type SnapshotMeta = SnapshotMetaV1 | SnapshotMetaV2;
+export function isV2Meta(meta: SnapshotMeta): meta is SnapshotMetaV2 { return (meta as { schemaVersion?: number }).schemaVersion === 2; }
+export function effectiveSchemaVersion(obj: unknown): SchemaVersion | 'unknown' { if (!isObject(obj)) return 'unknown'; return obj.schemaVersion === undefined || obj.schemaVersion === 1 ? 1 : obj.schemaVersion === 2 ? 2 : 'unknown'; }
+
+const safe = (n: unknown): n is number => Number.isSafeInteger(n) && n >= 0;
+const reason = (x: unknown): x is string => typeof x === 'string' && x.length > 0 && x.length <= 512;
+const keys = (x: object): string[] => Object.keys(x);
+const SUBPOPULATIONS: Record<SnapshotFacetName, readonly string[]> = { viewport: [], geometry: [], styles: [], 'hit-testing': [], text: [], forms: [], media: [], animation: [], accessibility: [], queries: ['media-queries', 'container-queries'], focus: ['forward', 'reverse'], scroll: ['snap-descendants', 'sticky-fixed-descendants', 'sampled-visible-children'], layers: [], states: [], pixels: [], screenshot: [], 'dom-html': [] };
+function normalizedPath(value: unknown): value is string { return typeof value === 'string' && value.length > 0 && value.length <= 512 && !value.includes('\\') && !value.startsWith('/') && !value.split('/').some(p => !p || p === '.' || p === '..'); }
+function coverage(value: unknown): ValidationResult {
+  if (!isObject(value)) return fail('coverage must be an object');
+  const v = value as Partial<CollectorCoverage>;
+  const errors: ValidationResult[] = [];
+  if (!safe(v.retained_count)) errors.push(fail('retained_count must be a nonnegative safe integer'));
+  const unavailable = isObject(v.availability) && v.availability.state === 'unavailable' && reason(v.availability.reason);
+  if (v.availability !== 'available' && !unavailable) errors.push(fail('coverage availability is invalid'));
+  if (!isObject(v.truncation) || !['none', 'exact', 'lower_bound', 'unknown'].includes(String(v.truncation.state))) errors.push(fail('coverage truncation is invalid'));
+  else if (v.truncation.state === 'exact' && !safe(v.truncation.dropped_count)) errors.push(fail('exact truncation needs dropped_count'));
+  else if (v.truncation.state === 'lower_bound' && !safe(v.truncation.dropped_count_lower_bound)) errors.push(fail('lower_bound truncation needs dropped_count_lower_bound'));
+  if (!isObject(v.source_total) || !['exact', 'lower_bound', 'unavailable'].includes(String(v.source_total.state))) errors.push(fail('coverage source_total is invalid'));
+  else if (v.source_total.state === 'exact' && !safe(v.source_total.count)) errors.push(fail('exact source_total needs count'));
+  else if (v.source_total.state === 'lower_bound' && !safe(v.source_total.count_lower_bound)) errors.push(fail('lower_bound source_total needs count_lower_bound'));
+  else if (v.source_total.state === 'unavailable' && !reason(v.source_total.reason)) errors.push(fail('unavailable source_total needs reason'));
+  if (unavailable && (v.retained_count !== 0 || v.truncation?.state !== 'unknown' || v.source_total?.state !== 'unavailable')) errors.push(fail('unavailable coverage cannot represent zero evidence'));
+  if (v.source_total?.state === 'exact' && v.truncation?.state === 'exact' && v.source_total.count !== (v.retained_count ?? 0) + v.truncation.dropped_count) errors.push(fail('exact coverage totals disagree'));
+  return combine(...errors);
+}
+export function validateCollectorCoverage(value: unknown): ValidationResult { return coverage(value); }
+function facet(name: SnapshotFacetName, value: unknown): ValidationResult {
+  if (!isObject(value)) return fail(`facet ${name} must be an object`);
+  const v = value as Partial<SnapshotFacet>; const errors = [coverage(v.primary_population?.coverage)];
+  if (!v.primary_population || !reason(v.primary_population.name)) errors.push(fail(`facet ${name} primary population is invalid`));
+  const expected = SUBPOPULATIONS[name];
+  if (!isObject(v.subpopulations) || keys(v.subpopulations).join('\0') !== expected.join('\0')) errors.push(fail(`facet ${name} subpopulations are invalid`));
+  else for (const item of expected) errors.push(coverage(v.subpopulations[item]));
+  if (!['available', 'unavailable', 'not-requested'].includes(String(v.status))) errors.push(fail(`facet ${name} status is invalid`));
+  if (v.status === 'unavailable' && !reason(v.unavailable_reason)) errors.push(fail(`facet ${name} unavailable without reason`));
+  if (v.status !== 'unavailable' && v.unavailable_reason !== null) errors.push(fail(`facet ${name} has inconsistent unavailable reason`));
+  if (v.status === 'not-requested' && name !== 'states' && name !== 'pixels') errors.push(fail(`facet ${name} cannot be not-requested`));
+  return combine(...errors);
+}
+function validateSourceManifest(value: unknown): ValidationResult {
+  if (!isObject(value) || value.schemaVersion !== 2 || !Array.isArray(value.artifacts)) return fail('source_artifact_manifest is invalid');
+  const artifactKeys = new Set<string>(); const paths = new Set<string>(); const arrayKeys = new Set<string>(); const errors: ValidationResult[] = [];
+  for (const a of value.artifacts) { if (!isObject(a) || !reason(a.key) || !normalizedPath(a.path) || !safe(a.bytes) || typeof a.media_type !== 'string' || !/^[a-f0-9]{64}$/.test(String(a.sha256)) || !Array.isArray(a.retained_arrays)) { errors.push(fail('source artifact is invalid')); continue; } if (artifactKeys.has(a.key) || paths.has(a.path)) errors.push(fail('duplicate source artifact key or path')); artifactKeys.add(a.key); paths.add(a.path); for (const r of a.retained_arrays) { if (!isObject(r) || !reason(r.key) || typeof r.json_pointer !== 'string' || (!r.json_pointer.startsWith('/') && r.json_pointer !== '') || !safe(r.retained_count) || arrayKeys.has(r.key)) errors.push(fail('source retained array is invalid')); else arrayKeys.add(r.key); } }
+  return combine(...errors);
+}
+export function validateSnapshotMetaV2(meta: SnapshotMetaV2): ValidationResult {
+  const errors: ValidationResult[] = [];
+  if (!isObject(meta) || meta.schemaVersion !== 2 || typeof meta.snapshotId !== 'string' || !meta.snapshotId) errors.push(fail('invalid v2 identity'));
+  if (!isObject(meta.request) || !isObject(meta.timing) || !isObject(meta.coordinateAuthority) || !isObject(meta.contentInputs)) errors.push(fail('v2 request/timing/authority fields must be objects'));
+  if (!isObject(meta.facets) || keys(meta.facets).join('\0') !== SNAPSHOT_FACET_NAMES.join('\0')) errors.push(fail('v2 facets must use fixed ordered keys')); else for (const n of SNAPSHOT_FACET_NAMES) errors.push(facet(n, meta.facets[n]));
+  const t = meta.target; if (!isObject(t) || !['fresh-url', 'session', 'explicit-target'].includes(String(t.mode)) || typeof t.target_id !== 'string' || !t.target_id || !isObject(t.endpoint) || t.endpoint.host !== '127.0.0.1' || !Number.isSafeInteger(t.endpoint.port) || t.endpoint.port < 1 || t.endpoint.port > 65535 || typeof t.observed_url !== 'string') errors.push(fail('invalid target attestation')); else if (t.mode === 'session' ? !(typeof t.session_id === 'string' && /^ses_[0-9a-z]{26}$/.test(t.session_id) && (t.session_source === 'active' || t.session_source === 'explicit')) : t.session_id !== null || t.session_source !== null) errors.push(fail('target attestation session fields disagree with mode'));
+  errors.push(validateSourceManifest(meta.source_artifact_manifest));
+  return combine(...errors);
+}
+export function validateSnapshotMeta(meta: unknown): ValidationResult { const version = effectiveSchemaVersion(meta); if (version === 'unknown' || !isObject(meta)) return fail('unsupported snapshot schemaVersion'); if (version === 2) return validateSnapshotMetaV2(meta as SnapshotMetaV2); return typeof meta.snapshotId === 'string' && Array.isArray(meta.facets) ? OK : fail('legacy meta is invalid'); }

package/src/cursor/index.ts

@@ -0,0 +1,13 @@
+/** Narrow, unreachable cursor-pagination service seam for future bounded read handlers. */
+export {
+  CursorService,
+  CursorServiceError,
+  MemoryCursorIndexStore,
+  type ContinueCursorPageInput,
+  type CreateCursorPageInput,
+  type CursorIndexStore,
+  type CursorPage,
+  type CursorQueryIdentity,
+  type CursorServiceErrorCode,
+  type CursorServiceOptions,
+} from './service.js';

package/src/cursor/service.ts

@@ -0,0 +1,310 @@
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+
+import {
+  DEFAULT_PAGE_SIZE,
+  MAX_PAGE_SIZE,
+  type CursorClaims,
+  type CursorLeaf,
+  type ImmutableIndex,
+  validateCursorClaims,
+  validateCursorToken,
+  validateImmutableIndex,
+} from '../contracts/index.js';
+
+/** A durable owner for immutable indexes. This service never chooses a session or artifact location. */
+export interface CursorIndexStore<Row> {
+  put(index: ImmutableIndex<Row>): void | Promise<void>;
+  get(digest: string): ImmutableIndex<Row> | undefined | Promise<ImmutableIndex<Row> | undefined>;
+}
+
+/** Caller-owned identity for one cursorable read. `scope` must be explicit and nonempty. */
+export interface CursorQueryIdentity {
+  readonly scope: Record<string, unknown>;
+  readonly query: Record<string, unknown>;
+}
+
+export interface CreateCursorPageInput<Row> extends CursorQueryIdentity {
+  readonly leaf: CursorLeaf;
+  readonly path: string;
+  /** The declared source order. Rows are retained in exactly this order; the service never re-sorts them. */
+  readonly order: string;
+  readonly coverage: unknown;
+  readonly rows: readonly Row[];
+  readonly expiresAt: string;
+  readonly limit?: number;
+}
+
+export interface ContinueCursorPageInput extends CursorQueryIdentity {
+  readonly cursor: string;
+  /** A continuation's limit is fixed by its signed first-page limit. */
+  readonly limit?: number;
+}
+
+/** Bounded public page; the retained index and its undisplayed rows remain store-private. */
+export interface CursorPage<Row> {
+  readonly indexDigest: string;
+  readonly expiresAt: string;
+  readonly rows: readonly Row[];
+  readonly limit: number;
+  readonly total: number;
+  readonly nextCursor: string | null;
+}
+
+export type CursorServiceErrorCode =
+  | 'cursor_invalid'
+  | 'cursor_expired'
+  | 'cursor_scope_mismatch'
+  | 'cursor_query_mismatch'
+  | 'cursor_limit_invalid'
+  | 'cursor_index_unavailable'
+  | 'cursor_index_invalid';
+
+/** A typed public error; handlers map it to their stable error envelope. */
+export class CursorServiceError extends Error {
+  constructor(readonly code: CursorServiceErrorCode, message: string) {
+    super(message);
+    this.name = 'CursorServiceError';
+  }
+}
+
+export interface CursorServiceOptions<Row> {
+  readonly store: CursorIndexStore<Row>;
+  /** HMAC key. It is caller configuration, never read from an ambient environment. */
+  readonly secret: string | Uint8Array;
+  /** Injectable only for deterministic tests; production callers pass no clock. */
+  readonly now?: () => Date;
+}
+
+interface CursorPayload {
+  readonly schemaVersion: 1;
+  readonly indexDigest: string;
+  readonly leaf: CursorLeaf;
+  readonly filter: Record<string, unknown>;
+  readonly nextExclusiveOrdinal: number;
+  readonly pageSize: number;
+  readonly expiresAt: string;
+}
+
+const TOKEN_PREFIX = 'c1';
+
+/**
+ * An isolated immutable-index paginator. It has no active-session, cwd, environment,
+ * filesystem, or browser lookup: callers supply the durable index store and identity.
+ */
+export class CursorService<Row> {
+  private readonly now: () => Date;
+
+  constructor(private readonly options: CursorServiceOptions<Row>) {
+    if ((typeof options.secret === 'string' && options.secret.length === 0) || (options.secret instanceof Uint8Array && options.secret.byteLength === 0)) {
+      throw new Error('cursor service secret must not be empty');
+    }
+    this.now = options.now ?? (() => new Date());
+  }
+
+  async createPage(input: CreateCursorPageInput<Row>): Promise<CursorPage<Row>> {
+    const limit = validateLimit(input.limit ?? DEFAULT_PAGE_SIZE);
+    canonicalIdentity(input);
+    const expiresAt = parseFutureExpiry(input.expiresAt, this.now());
+    if (!input.path || !input.order) throw new CursorServiceError('cursor_index_invalid', 'cursor index requires nonempty path and order');
+
+    // Canonical JSON both makes the digest deterministic and snapshots caller-owned rows.
+    const rows = cloneJson(input.rows) as readonly Row[];
+    const filter = cloneJson({ scope: input.scope, query: input.query }) as Record<string, unknown>;
+    const draft = {
+      schemaVersion: 1 as const,
+      leaf: input.leaf,
+      path: input.path,
+      createdAt: this.now().toISOString(),
+      expiresAt: expiresAt.toISOString(),
+      filter,
+      pageSize: limit,
+      order: input.order,
+      coverage: cloneJson(input.coverage),
+      rows,
+    };
+    const index: ImmutableIndex<Row> = { ...draft, digest: digestIndex(draft) };
+    assertIndex(index);
+    // Identity was validated before the durable write and is represented in the signed/indexed filter.
+    await this.options.store.put(index);
+    return this.page(index, 0);
+  }
+
+  async continuePage(input: ContinueCursorPageInput): Promise<CursorPage<Row>> {
+    // All untrusted token/identity/limit checks precede the store lookup.
+    const claims = this.decode(input.cursor);
+    const now = this.now();
+    if (Date.parse(claims.expiresAt) <= now.getTime()) {
+      throw new CursorServiceError('cursor_expired', 'cursor has expired');
+    }
+    const expected = canonicalIdentity(input);
+    const actual = canonicalJson(claims.filter);
+    if (canonicalJson((claims.filter as Record<string, unknown>).scope) !== canonicalJson(input.scope)) {
+      throw new CursorServiceError('cursor_scope_mismatch', 'cursor scope does not match this read');
+    }
+    if (actual !== expected) {
+      throw new CursorServiceError('cursor_query_mismatch', 'cursor query does not match this read');
+    }
+    if (input.limit !== undefined && input.limit !== claims.pageSize) {
+      throw new CursorServiceError('cursor_limit_invalid', 'continuation limit must equal the signed cursor limit');
+    }
+
+    const index = await this.options.store.get(claims.indexDigest);
+    if (!index) throw new CursorServiceError('cursor_index_unavailable', 'cursor index is unavailable');
+    this.assertClaimsMatchIndex(claims, index);
+    return this.page(index, claims.nextExclusiveOrdinal);
+  }
+
+  private page(index: ImmutableIndex<Row>, start: number): CursorPage<Row> {
+    if (start > index.rows.length) {
+      throw new CursorServiceError('cursor_index_invalid', 'cursor ordinal exceeds retained index rows');
+    }
+    const end = Math.min(start + index.pageSize, index.rows.length);
+    const rows = index.rows.slice(start, end);
+    const nextCursor = end < index.rows.length ? this.encode({
+      schemaVersion: 1,
+      indexDigest: index.digest,
+      leaf: index.leaf,
+      filter: index.filter,
+      // This is the exclusive array offset: rows [0, offset) have already been returned.
+      nextExclusiveOrdinal: end,
+      pageSize: index.pageSize,
+      expiresAt: index.expiresAt,
+    }) : null;
+    return { indexDigest: index.digest, expiresAt: index.expiresAt, rows, limit: index.pageSize, total: index.rows.length, nextCursor };
+  }
+
+  private encode(payload: CursorPayload): string {
+    const encoded = Buffer.from(canonicalJson(payload), 'utf8').toString('base64url');
+    const mac = this.mac(`${TOKEN_PREFIX}.${encoded}`);
+    const token = `${TOKEN_PREFIX}.${encoded}.${mac}`;
+    const result = validateCursorToken(token);
+    if (!result.valid) throw new CursorServiceError('cursor_index_invalid', result.errors.join('; '));
+    return token;
+  }
+
+  private decode(token: string): CursorClaims {
+    const syntax = validateCursorToken(token);
+    if (!syntax.valid) throw new CursorServiceError('cursor_invalid', syntax.errors.join('; '));
+    const parts = token.split('.');
+    if (parts.length !== 3 || parts[0] !== TOKEN_PREFIX || !/^[A-Za-z0-9_-]+$/.test(parts[1]) || !/^[A-Za-z0-9_-]+$/.test(parts[2])) {
+      throw new CursorServiceError('cursor_invalid', 'cursor has invalid encoding');
+    }
+    const expectedMac = this.mac(`${parts[0]}.${parts[1]}`);
+    if (!constantTimeEqual(parts[2], expectedMac)) throw new CursorServiceError('cursor_invalid', 'cursor MAC is invalid');
+    let payload: unknown;
+    try {
+      const bytes = Buffer.from(parts[1], 'base64url');
+      if (bytes.toString('base64url') !== parts[1]) throw new Error('noncanonical base64url');
+      payload = JSON.parse(bytes.toString('utf8'));
+    } catch {
+      throw new CursorServiceError('cursor_invalid', 'cursor payload is invalid');
+    }
+    const claims = { ...(payload as Record<string, unknown>), mac: parts[2] } as CursorClaims;
+    const valid = validateCursorClaims(claims);
+    if (!valid.valid) throw new CursorServiceError('cursor_invalid', valid.errors.join('; '));
+    try {
+      canonicalIdentityFilter(claims.filter);
+    } catch {
+      throw new CursorServiceError('cursor_invalid', 'cursor filter must contain an explicit scope and query');
+    }
+    return claims;
+  }
+
+  private assertClaimsMatchIndex(claims: CursorClaims, index: ImmutableIndex<Row>): void {
+    try {
+      assertIndex(index);
+      const { digest: _digest, ...draft } = index;
+      if (digestIndex(draft) !== index.digest) throw new Error('index digest does not match contents');
+      if (index.digest !== claims.indexDigest || index.leaf !== claims.leaf || index.pageSize !== claims.pageSize || index.expiresAt !== claims.expiresAt || canonicalJson(index.filter) !== canonicalJson(claims.filter)) {
+        throw new Error('index does not match cursor claims');
+      }
+    } catch (error) {
+      throw new CursorServiceError('cursor_index_invalid', error instanceof Error ? error.message : 'cursor index is invalid');
+    }
+  }
+
+  private mac(value: string): string {
+    return createHmac('sha256', this.options.secret).update(value, 'utf8').digest('base64url');
+  }
+}
+
+/** Minimal reusable in-memory store for tests and callers that own their own process lifetime. */
+export class MemoryCursorIndexStore<Row> implements CursorIndexStore<Row> {
+  private readonly indexes = new Map<string, ImmutableIndex<Row>>();
+  put(index: ImmutableIndex<Row>): void { this.indexes.set(index.digest, index); }
+  get(digest: string): ImmutableIndex<Row> | undefined { return this.indexes.get(digest); }
+}
+
+function validateLimit(limit: number): number {
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_PAGE_SIZE) {
+    throw new CursorServiceError('cursor_limit_invalid', `cursor limit must be an integer from 1 to ${MAX_PAGE_SIZE}`);
+  }
+  return limit;
+}
+
+function parseFutureExpiry(value: string, now: Date): Date {
+  const timestamp = Date.parse(value);
+  if (!Number.isFinite(timestamp) || timestamp <= now.getTime()) {
+    throw new CursorServiceError('cursor_index_invalid', 'cursor index expiry must be a valid future timestamp');
+  }
+  return new Date(timestamp);
+}
+
+function canonicalIdentity(identity: CursorQueryIdentity): string {
+  try {
+    return canonicalIdentityFilter({ scope: identity.scope, query: identity.query });
+  } catch (error) {
+    if (error instanceof CursorServiceError) throw error;
+    throw new CursorServiceError('cursor_scope_mismatch', 'cursor scope and query must be JSON objects');
+  }
+}
+
+function canonicalIdentityFilter(filter: Record<string, unknown>): string {
+  if (Object.keys(filter).length !== 2 || !Object.prototype.hasOwnProperty.call(filter, 'scope') || !Object.prototype.hasOwnProperty.call(filter, 'query') || !isPlainRecord(filter.scope) || !isPlainRecord(filter.query) || Object.keys(filter.scope).length === 0) {
+    throw new Error('invalid cursor identity filter');
+  }
+  return canonicalJson(filter);
+}
+
+function assertIndex(index: ImmutableIndex<unknown>): void {
+  const valid = validateImmutableIndex(index);
+  if (!valid.valid) throw new Error(valid.errors.join('; '));
+  canonicalIdentityFilter(index.filter);
+  canonicalJson(index.rows);
+  if (!index.path || !index.order || !Number.isFinite(Date.parse(index.createdAt)) || !Number.isFinite(Date.parse(index.expiresAt))) {
+    throw new Error('cursor index has invalid immutable metadata');
+  }
+}
+
+function digestIndex(index: Omit<ImmutableIndex<unknown>, 'digest'>): string {
+  return createHash('sha256').update(canonicalJson(index), 'utf8').digest('hex');
+}
+
+function cloneJson(value: unknown): unknown {
+  return JSON.parse(canonicalJson(value));
+}
+
+/** Deterministic JSON for query identity and immutable-index digests. */
+function canonicalJson(value: unknown): string {
+  if (value === null || typeof value === 'boolean' || typeof value === 'string') return JSON.stringify(value);
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) throw new Error('cursor values must be finite JSON numbers');
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (isPlainRecord(value)) {
+    const record = value as Record<string, unknown>;
+    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(',')}}`;
+  }
+  throw new Error('cursor values must be JSON values');
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && Object.getPrototypeOf(value) === Object.prototype;
+}
+
+function constantTimeEqual(actual: string, expected: string): boolean {
+  const a = Buffer.from(actual, 'utf8');
+  const b = Buffer.from(expected, 'utf8');
+  return a.byteLength === b.byteLength && timingSafeEqual(a, b);
+}

package/src/errors.ts

@@ -0,0 +1,71 @@
+import { fact, type RenderableResult } from './output/render.js';
+
+export type CaptureFailureKind = 'invocation' | 'precondition' | 'world' | 'artifact' | 'cleanup' | 'internal';
+
+export interface CaptureFailureDescriptor {
+  readonly code: string;
+  readonly message: string;
+  readonly kind: CaptureFailureKind;
+  readonly cause?: unknown;
+}
+
+/** A failure that crosses Capture's command boundary without rendering itself. */
+export class CaptureError extends Error {
+  readonly descriptor: CaptureFailureDescriptor;
+
+  constructor(descriptor: CaptureFailureDescriptor) {
+    super(descriptor.message, descriptor.cause === undefined ? undefined : { cause: descriptor.cause });
+    this.name = 'CaptureError';
+    this.descriptor = descriptor;
+  }
+}
+
+export function captureError(kind: CaptureFailureKind, code: string, message: string, cause?: unknown): CaptureError {
+  return new CaptureError({ kind, code, message, cause });
+}
+
+export function invalidInput(message: string, code = 'invalid_input'): CaptureError {
+  return captureError('invocation', code, message);
+}
+
+export function worldFailure(message: string, cause?: unknown): CaptureError {
+  return captureError('world', 'world_failure', message, cause);
+}
+
+/** Convert an arbitrary thrown value into Capture's single typed vocabulary. */
+export function normalizeFailure(error: unknown): CaptureError {
+  if (error instanceof CaptureError) return error;
+  if (error instanceof AggregateError) return normalizeAggregateFailure(error);
+  const message = error instanceof Error ? error.message : String(error);
+  return captureError('internal', 'internal_error', message || 'Capture encountered an unknown internal failure.', error);
+}
+
+/**
+ * A dual-failure envelope (primary + cleanup, e.g. a screenshot capture that
+ * failed AND whose device-metrics restore failed) renders with the primary
+ * sub-failure's kind/code and EVERY sub-failure's message, so both failures
+ * stay distinguishable in the one rendered error an agent sees — the thrown
+ * objects themselves never cross the process boundary. Producers put the
+ * primary failure first (`new AggregateError([primary, cleanup], …)`).
+ */
+function normalizeAggregateFailure(error: AggregateError): CaptureError {
+  const subs = error.errors.map((sub) => normalizeFailure(sub));
+  const primary = subs[0];
+  const message = [error.message, ...subs.map((sub, i) => `[${i + 1}] ${sub.descriptor.message}`)]
+    .filter((part) => part.length > 0)
+    .join(' ');
+  if (primary === undefined) {
+    return captureError('internal', 'internal_error', message || 'Capture encountered an empty aggregate failure.', error);
+  }
+  return captureError(primary.descriptor.kind, primary.descriptor.code, message, error);
+}
+
+/** The one renderer-compatible error envelope, emitted only by capture.ts. */
+export function failureResult(error: unknown): RenderableResult {
+  const { descriptor } = normalizeFailure(error);
+  return {
+    tag: 'error',
+    attrs: { code: descriptor.code, kind: descriptor.kind },
+    summary: fact`${descriptor.message}`,
+  };
+}