entangled-worlds-orbiters-shared 2.17.0 → 3.1.0

package/dist/capabilities/schema.d.ts

@@ -1,52 +0,0 @@
-/**
- * Tiny JSON-Schema-subset validator (shared machinery, TypeScript).
- *
- * The ONE validator both registries use (supersedes the duplicated
- * `studio/capabilities/schema.js` + `core/edit/capabilities/schema.ts`). Deliberately NOT a
- * dependency (no zod/ajv) — the app is bundle-weight sensitive and the house style is
- * lightweight guard clauses. Each capability carries an `inputSchema` literal in this subset;
- * the SAME literal is what the future agent layer hands the model as a tool definition, so
- * there is no second schema language to keep in sync.
- *
- * Supported keywords (a pragmatic subset of JSON Schema draft-07):
- *   type        'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null'
- *               (or an array of those — value matches if it satisfies any)
- *   properties  per-key subschemas (objects)
- *   required    array of keys that must be present and not undefined (objects)
- *   items       subschema applied to every array element
- *   enum        value must be one of the listed values
- *   const       value must deep-equal the given value
- *   nullable    when true, null always passes regardless of type
- *   minimum / maximum                 numbers
- *   minLength / maxLength             strings
- *   minItems / maxItems               arrays
- *   pattern     string regex source (tested with RegExp)
- *
- * A schema with no `type` accepts any value (still honouring enum/const/properties if set).
- * Unknown keywords are ignored — forward-compatible, never throws on shape it doesn't know.
- */
-import { type SchemaIssue } from './errors.js';
-export type JsonType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';
-export interface JsonSchema {
-    type?: JsonType | JsonType[];
-    properties?: Record<string, JsonSchema>;
-    required?: string[];
-    items?: JsonSchema;
-    enum?: unknown[];
-    const?: unknown;
-    nullable?: boolean;
-    minimum?: number;
-    maximum?: number;
-    minLength?: number;
-    maxLength?: number;
-    minItems?: number;
-    maxItems?: number;
-    pattern?: string;
-}
-/** Returns { ok, issues }. Never throws. */
-export declare function validate(schema: JsonSchema, value: unknown): {
-    ok: boolean;
-    issues: SchemaIssue[];
-};
-/** Throws ValidationError when invalid; returns the value otherwise. Used by the registry. */
-export declare function assertValid<T>(schema: JsonSchema, value: T, capability?: string | null): T;

package/dist/capabilities/schema.js

@@ -1,139 +0,0 @@
-/**
- * Tiny JSON-Schema-subset validator (shared machinery, TypeScript).
- *
- * The ONE validator both registries use (supersedes the duplicated
- * `studio/capabilities/schema.js` + `core/edit/capabilities/schema.ts`). Deliberately NOT a
- * dependency (no zod/ajv) — the app is bundle-weight sensitive and the house style is
- * lightweight guard clauses. Each capability carries an `inputSchema` literal in this subset;
- * the SAME literal is what the future agent layer hands the model as a tool definition, so
- * there is no second schema language to keep in sync.
- *
- * Supported keywords (a pragmatic subset of JSON Schema draft-07):
- *   type        'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null'
- *               (or an array of those — value matches if it satisfies any)
- *   properties  per-key subschemas (objects)
- *   required    array of keys that must be present and not undefined (objects)
- *   items       subschema applied to every array element
- *   enum        value must be one of the listed values
- *   const       value must deep-equal the given value
- *   nullable    when true, null always passes regardless of type
- *   minimum / maximum                 numbers
- *   minLength / maxLength             strings
- *   minItems / maxItems               arrays
- *   pattern     string regex source (tested with RegExp)
- *
- * A schema with no `type` accepts any value (still honouring enum/const/properties if set).
- * Unknown keywords are ignored — forward-compatible, never throws on shape it doesn't know.
- */
-import { ValidationError } from './errors.js';
-const TYPE_CHECKS = {
-    object: (v) => v !== null && typeof v === 'object' && !Array.isArray(v),
-    array: (v) => Array.isArray(v),
-    string: (v) => typeof v === 'string',
-    number: (v) => typeof v === 'number' && Number.isFinite(v),
-    integer: (v) => typeof v === 'number' && Number.isInteger(v),
-    boolean: (v) => typeof v === 'boolean',
-    null: (v) => v === null,
-};
-function deepEqual(a, b) {
-    if (a === b)
-        return true;
-    if (typeof a !== typeof b || a === null || b === null || typeof a !== 'object')
-        return false;
-    const ka = Object.keys(a);
-    const kb = Object.keys(b);
-    if (ka.length !== kb.length)
-        return false;
-    return ka.every((k) => deepEqual(a[k], b[k]));
-}
-function checkType(schema, value) {
-    if (schema.type == null)
-        return true;
-    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
-    return types.some((t) => (TYPE_CHECKS[t] ? TYPE_CHECKS[t](value) : true));
-}
-function describeType(value) {
-    if (value === null)
-        return 'null';
-    if (Array.isArray(value))
-        return 'array';
-    return typeof value;
-}
-function validateNode(schema, value, path, issues) {
-    if (!schema || typeof schema !== 'object')
-        return;
-    const at = path || '(root)';
-    if (schema.nullable && value === null)
-        return;
-    if (!checkType(schema, value)) {
-        const want = Array.isArray(schema.type) ? schema.type.join('|') : schema.type;
-        issues.push({ path: at, message: `expected type ${want}, got ${describeType(value)}` });
-        return; // type is the gate; downstream checks would be noise
-    }
-    if ('const' in schema && !deepEqual(value, schema.const)) {
-        issues.push({ path: at, message: `must equal ${JSON.stringify(schema.const)}` });
-    }
-    if (Array.isArray(schema.enum) && !schema.enum.some((e) => deepEqual(e, value))) {
-        issues.push({ path: at, message: `must be one of ${JSON.stringify(schema.enum)}` });
-    }
-    if (typeof value === 'number') {
-        if (typeof schema.minimum === 'number' && value < schema.minimum) {
-            issues.push({ path: at, message: `must be >= ${schema.minimum}` });
-        }
-        if (typeof schema.maximum === 'number' && value > schema.maximum) {
-            issues.push({ path: at, message: `must be <= ${schema.maximum}` });
-        }
-    }
-    if (typeof value === 'string') {
-        if (typeof schema.minLength === 'number' && value.length < schema.minLength) {
-            issues.push({ path: at, message: `must be at least ${schema.minLength} chars` });
-        }
-        if (typeof schema.maxLength === 'number' && value.length > schema.maxLength) {
-            issues.push({ path: at, message: `must be at most ${schema.maxLength} chars` });
-        }
-        if (typeof schema.pattern === 'string' && !new RegExp(schema.pattern).test(value)) {
-            issues.push({ path: at, message: `must match /${schema.pattern}/` });
-        }
-    }
-    if (Array.isArray(value)) {
-        if (typeof schema.minItems === 'number' && value.length < schema.minItems) {
-            issues.push({ path: at, message: `must have at least ${schema.minItems} items` });
-        }
-        if (typeof schema.maxItems === 'number' && value.length > schema.maxItems) {
-            issues.push({ path: at, message: `must have at most ${schema.maxItems} items` });
-        }
-        if (schema.items) {
-            value.forEach((el, i) => validateNode(schema.items, el, `${path}[${i}]`, issues));
-        }
-    }
-    if (TYPE_CHECKS.object(value)) {
-        const obj = value;
-        if (Array.isArray(schema.required)) {
-            for (const key of schema.required) {
-                if (obj[key] === undefined)
-                    issues.push({ path: path ? `${path}.${key}` : key, message: 'is required' });
-            }
-        }
-        if (schema.properties) {
-            for (const [key, sub] of Object.entries(schema.properties)) {
-                if (obj[key] !== undefined)
-                    validateNode(sub, obj[key], path ? `${path}.${key}` : key, issues);
-            }
-        }
-    }
-}
-/** Returns { ok, issues }. Never throws. */
-export function validate(schema, value) {
-    const issues = [];
-    validateNode(schema ?? {}, value, '', issues);
-    return { ok: issues.length === 0, issues };
-}
-/** Throws ValidationError when invalid; returns the value otherwise. Used by the registry. */
-export function assertValid(schema, value, capability = null) {
-    const { ok, issues } = validate(schema, value);
-    if (!ok) {
-        const summary = issues.map((i) => `${i.path}: ${i.message}`).join('; ');
-        throw new ValidationError(`Invalid input${capability ? ` for "${capability}"` : ''}: ${summary}`, { capability, issues });
-    }
-    return value;
-}

package/src/capabilities/errors.ts

@@ -1,115 +0,0 @@
-/**
- * Capability layer error taxonomy (shared machinery).
- *
- * This is the ONE generic capability machinery, app-agnostic and layer-neutral
- * (`src/capabilities/` imports nothing app-level — see `.agents/decisions/`). Both the studio
- * registry (`src/studio/capabilities/`, the credit-metered superset caller) and the edit-mode
- * registry (`src/core/edit/capabilities/`, the lean preview caller) build on it. It supersedes
- * the previously duplicated `studio/capabilities/errors.js` + `core/edit/capabilities/errors.ts`.
- *
- * One base class so callers — today the UI, tomorrow the agent loop — branch on `err.code`
- * instead of string-matching messages. Every error carries the offending capability name when
- * known, so failures are traceable without a stack dive.
- */
-
-export type CapabilityErrorCode =
-  | 'CAPABILITY_ERROR'
-  | 'VALIDATION'
-  | 'UNAVAILABLE'
-  | 'PRECHECK_FAILED'
-  | 'NOT_IMPLEMENTED'
-  | 'INSUFFICIENT_CREDITS'
-  | 'UNKNOWN_CAPABILITY'
-
-export interface SchemaIssue {
-  path: string
-  message: string
-}
-
-export class CapabilityError extends Error {
-  code: CapabilityErrorCode
-  capability: string | null
-  cause?: unknown
-  constructor(
-    message: string,
-    { code = 'CAPABILITY_ERROR', capability = null, cause = null }:
-      { code?: CapabilityErrorCode; capability?: string | null; cause?: unknown } = {},
-  ) {
-    super(message)
-    this.name = 'CapabilityError'
-    this.code = code
-    this.capability = capability
-    if (cause) this.cause = cause
-  }
-}
-
-/** Input args failed the capability's inputSchema. Thrown before any write. */
-export class ValidationError extends CapabilityError {
-  issues: SchemaIssue[]
-  constructor(message: string, { capability = null, issues = [] }: { capability?: string | null; issues?: SchemaIssue[] } = {}) {
-    super(message, { code: 'VALIDATION', capability })
-    this.name = 'ValidationError'
-    this.issues = issues
-  }
-}
-
-/** Capability is declared but not invokable yet (status: 'planned' / available()===false). */
-export class UnavailableError extends CapabilityError {
-  reason: string | null
-  constructor(message: string, { capability = null, reason = null }: { capability?: string | null; reason?: string | null } = {}) {
-    super(message, { code: 'UNAVAILABLE', capability })
-    this.name = 'UnavailableError'
-    this.reason = reason
-  }
-}
-
-/**
- * Capability's precheck rejected the args against live state (no-op target, missing element,
- * guard condition). Thrown before pushHistory / any write.
- */
-export class PrecheckError extends CapabilityError {
-  reason: string | null
-  constructor(message: string, { capability = null, reason = null }: { capability?: string | null; reason?: string | null } = {}) {
-    super(message, { code: 'PRECHECK_FAILED', capability })
-    this.name = 'PrecheckError'
-    this.reason = reason
-  }
-}
-
-/**
- * Wired capability whose execute() is not implemented (generative stubs). Distinct from
- * UnavailableError: "active but unfinished", reachable only if status was flipped to 'active'
- * before the implementation landed.
- */
-export class NotImplementedError extends CapabilityError {
-  constructor(capability: string, message: string | null = null) {
-    super(message || `Capability "${capability}" is not implemented yet`, { code: 'NOT_IMPLEMENTED', capability })
-    this.name = 'NotImplementedError'
-  }
-}
-
-/**
- * Reserved for the future generative path: the backend credit check failed (402-style).
- * Declared now so the agent loop can catch it without a follow-up refactor.
- */
-export class InsufficientCreditsError extends CapabilityError {
-  required: number | null
-  available: number | null
-  constructor(
-    message: string,
-    { capability = null, required = null, available = null }:
-      { capability?: string | null; required?: number | null; available?: number | null } = {},
-  ) {
-    super(message, { code: 'INSUFFICIENT_CREDITS', capability })
-    this.name = 'InsufficientCreditsError'
-    this.required = required
-    this.available = available
-  }
-}
-
-export class UnknownCapabilityError extends CapabilityError {
-  constructor(name: string) {
-    super(`Unknown capability "${name}"`, { code: 'UNKNOWN_CAPABILITY', capability: name })
-    this.name = 'UnknownCapabilityError'
-  }
-}

package/src/capabilities/index.ts

@@ -1,22 +0,0 @@
-/**
- * Shared capability machinery — app-agnostic, layer-neutral registry + validator +
- * error taxonomy. Both `src/studio/capabilities/` and `src/core/edit/capabilities/` build their
- * own registry instances and descriptors on top of this. Imports nothing app-level (see
- * `.agents/decisions/`). This is the generic core of the AI-ready capability seam.
- */
-
-export {
-  createCapabilityRegistry,
-  type CapabilityRegistry,
-  type CapabilityDescriptor,
-  type CapabilityInfo,
-  type CapabilityKind,
-  type CapabilityStatus,
-  type Reactivity,
-  type InvokeMeta,
-  type InvokeMode,
-  type PrecheckResult,
-  type RegistryCtx,
-} from './registry.js'
-export { validate, assertValid, type JsonSchema, type JsonType } from './schema.js'
-export * from './errors.js'

package/src/capabilities/registry.ts

@@ -1,307 +0,0 @@
-/**
- * Capability registry — the single, named, validated chokepoint for edits (shared machinery).
- *
- * The ONE registry both callers build on (supersedes the duplicated
- * `studio/capabilities/registry.js` + `core/edit/capabilities/registry.ts`). It is the SUPERSET:
- * the studio uses the full pipeline (precheck → reversible history → credit cost → generative),
- * the edit-mode caller uses the lean subset (validation + named dispatch + the preview/commit
- * `mode`) and simply leaves the extra features unset. App-agnostic: `src/capabilities/` imports
- * nothing app-level (see `.agents/decisions/`); all state/functions arrive via the injected ctx.
- *
- * Today the UI calls invoke()/invokeSync() with source:'ui'; tomorrow the agent loop calls the
- * SAME registry with source:'agent'. Every mutation flows through one pipeline so history,
- * validation, and availability are enforced in exactly one place.
- *
- * invoke() pipeline:
- *   1. resolve        unknown name -> UnknownCapabilityError
- *   2. assertAvailable status:'planned' / available(ctx)===false -> UnavailableError (no writes)
- *   3. validate       args vs inputSchema -> ValidationError (no writes)
- *   4. precheck       PURE, no writes. Returns { ok, reason, willMutate }. !ok -> PrecheckError
- *   5. commit         only now: if reversible && willMutate !== false -> ctx.pushHistory()
- *   6. execute        the actual write
- *
- * `mode` is the edit-mode preview/commit distinction (ignored by studio capabilities):
- *   'preview' → live side effect only, no host broadcast   'commit' → side effect + emit.
- */
-
-import {
-  PrecheckError,
-  UnavailableError,
-  UnknownCapabilityError,
-  ValidationError,
-} from './errors.js'
-import { assertValid, type JsonSchema } from './schema.js'
-
-export type CapabilityKind = 'mutation' | 'query' | 'generative'
-export type Reactivity = 'live' | 'structural'
-export type CapabilityStatus = 'active' | 'planned'
-export type InvokeMode = 'preview' | 'commit'
-
-export interface InvokeMeta {
-  source: string
-  mode: InvokeMode
-}
-
-export interface PrecheckResult {
-  ok: boolean
-  reason?: string | null
-  /** false suppresses the no-op history snapshot at the commit boundary. */
-  willMutate?: boolean
-}
-
-/**
- * The optional history hook the registry calls at the commit boundary for reversible mutations.
- * A caller's ctx may include it (the studio does) or not (edit-mode has no history). It is NOT a
- * generic constraint — the ctx type is free-form per caller — the registry just reads pushHistory
- * off it when present.
- */
-export interface RegistryCtx {
-  pushHistory?: () => void
-}
-
-export interface CapabilityDescriptor<Ctx = Record<string, unknown>, Args = Record<string, unknown>> {
-  name: string
-  kind: CapabilityKind
-  description?: string
-  inputSchema?: JsonSchema
-  status?: CapabilityStatus
-  reversible?: boolean
-  /** Cost class of applying the edit: 'live' (cheap in-place) vs 'structural' (rebuild). */
-  reactivity?: Reactivity
-  available?: (ctx: Ctx) => boolean
-  cost?: (args: Args, ctx: Ctx) => number
-  precheck?: (args: Args, ctx: Ctx, meta: InvokeMeta) => PrecheckResult | Promise<PrecheckResult>
-  execute: (args: Args, ctx: Ctx, meta: InvokeMeta) => unknown
-}
-
-/** Public, function-free view of a capability — what the agent tool-catalog builder consumes. */
-export interface CapabilityInfo {
-  name: string
-  kind: CapabilityKind
-  status: CapabilityStatus
-  description: string
-  inputSchema: JsonSchema
-  reversible: boolean
-  reactivity: Reactivity | null
-}
-
-interface NormalizedCapability<Ctx> {
-  name: string
-  kind: CapabilityKind
-  status: CapabilityStatus
-  description: string
-  inputSchema: JsonSchema
-  reversible: boolean
-  reactivity: Reactivity | null
-  available: (ctx: Ctx) => boolean
-  cost: (args: never, ctx: Ctx) => number
-  precheck: (args: never, ctx: Ctx, meta: InvokeMeta) => PrecheckResult | Promise<PrecheckResult>
-  execute: (args: never, ctx: Ctx, meta: InvokeMeta) => unknown
-}
-
-const VALID_KINDS = new Set<CapabilityKind>(['mutation', 'query', 'generative'])
-
-// Fill descriptor defaults once at registration so invoke() stays branch-light.
-function normalize<Ctx>(descriptor: CapabilityDescriptor<Ctx>): NormalizedCapability<Ctx> {
-  if (!descriptor || typeof descriptor !== 'object') throw new Error('[capabilities] descriptor must be an object')
-  const { name, kind } = descriptor
-  if (typeof name !== 'string' || !name) throw new Error('[capabilities] descriptor.name is required')
-  if (!VALID_KINDS.has(kind)) {
-    throw new Error(`[capabilities] "${name}" has invalid kind "${kind}" (expected mutation|query|generative)`)
-  }
-  const status: CapabilityStatus = descriptor.status ?? 'active'
-  if (status !== 'active' && status !== 'planned') {
-    throw new Error(`[capabilities] "${name}" has invalid status "${status}" (expected active|planned)`)
-  }
-  if (typeof descriptor.execute !== 'function') throw new Error(`[capabilities] "${name}" must define an execute() function`)
-  return {
-    name,
-    kind,
-    status,
-    description: descriptor.description ?? '',
-    inputSchema: descriptor.inputSchema ?? { type: 'object' },
-    reversible: descriptor.reversible === true,
-    reactivity: descriptor.reactivity ?? null,
-    available: typeof descriptor.available === 'function' ? descriptor.available : () => status === 'active',
-    cost: (typeof descriptor.cost === 'function' ? descriptor.cost : () => 0) as NormalizedCapability<Ctx>['cost'],
-    precheck: (typeof descriptor.precheck === 'function' ? descriptor.precheck : () => ({ ok: true })) as NormalizedCapability<Ctx>['precheck'],
-    execute: descriptor.execute as NormalizedCapability<Ctx>['execute'],
-  }
-}
-
-export interface CapabilityRegistry<Ctx = Record<string, unknown>> {
-  register: (descriptor: CapabilityDescriptor<Ctx>) => NormalizedCapability<Ctx>
-  registerAll: (descriptors: CapabilityDescriptor<Ctx>[]) => CapabilityRegistry<Ctx>
-  has: (name: string) => boolean
-  get: (name: string) => NormalizedCapability<Ctx> | null
-  /** Public catalog view of one capability by name (null if unknown). */
-  describe: (name: string) => CapabilityInfo | null
-  list: (opts?: { includePlanned?: boolean; kind?: CapabilityKind | null }) => CapabilityInfo[]
-  isAvailable: (name: string) => boolean
-  cost: (name: string, args?: Record<string, unknown>) => number
-  invoke: (name: string, args?: Record<string, unknown>, opts?: Partial<InvokeMeta>) => Promise<unknown>
-  invokeSync: (name: string, args?: Record<string, unknown>, opts?: Partial<InvokeMeta>) => unknown
-}
-
-export function createCapabilityRegistry<Ctx = Record<string, unknown>>(
-  { ctx = {} as Ctx }: { ctx?: Ctx } = {},
-): CapabilityRegistry<Ctx> {
-  const caps = new Map<string, NormalizedCapability<Ctx>>()
-
-  function register(descriptor: CapabilityDescriptor<Ctx>): NormalizedCapability<Ctx> {
-    const cap = normalize(descriptor)
-    if (caps.has(cap.name)) throw new Error(`[capabilities] "${cap.name}" is already registered`)
-    caps.set(cap.name, cap)
-    return cap
-  }
-
-  const has = (name: string) => caps.has(name)
-  const get = (name: string) => caps.get(name) || null
-
-  // Function-free catalog view of a capability — never leaks execute/precheck to catalog-only
-  // callers (the future tool-schema builder).
-  function info(cap: NormalizedCapability<Ctx>): CapabilityInfo {
-    return {
-      name: cap.name,
-      kind: cap.kind,
-      status: cap.status,
-      description: cap.description,
-      inputSchema: cap.inputSchema,
-      reversible: cap.reversible,
-      reactivity: cap.reactivity,
-    }
-  }
-
-  function describe(name: string): CapabilityInfo | null {
-    const cap = get(name)
-    return cap ? info(cap) : null
-  }
-
-  function list({ includePlanned = false, kind = null }: { includePlanned?: boolean; kind?: CapabilityKind | null } = {}): CapabilityInfo[] {
-    const out: CapabilityInfo[] = []
-    for (const cap of caps.values()) {
-      if (!includePlanned && cap.status !== 'active') continue
-      if (kind && cap.kind !== kind) continue
-      out.push(info(cap))
-    }
-    return out
-  }
-
-  function isAvailable(name: string): boolean {
-    const cap = get(name)
-    if (!cap || cap.status !== 'active') return false
-    try {
-      return cap.available(ctx) !== false
-    } catch {
-      return false
-    }
-  }
-
-  function cost(name: string, args: Record<string, unknown> = {}): number {
-    const cap = get(name)
-    if (!cap) return 0
-    try {
-      return Number(cap.cost(args as never, ctx)) || 0
-    } catch {
-      return 0
-    }
-  }
-
-  // Steps 1–3 (resolve → availability → validate): pure, no side effects. Shared by both paths.
-  function prepareInvocation(name: string, args: Record<string, unknown>, meta: InvokeMeta): NormalizedCapability<Ctx> {
-    const cap = get(name)
-    if (!cap) throw new UnknownCapabilityError(name)
-    if (cap.status !== 'active') {
-      throw new UnavailableError(`Capability "${name}" is declared but not available yet`, { capability: name, reason: `status:${cap.status}` })
-    }
-    let availResult: boolean
-    try {
-      availResult = cap.available(ctx)
-    } catch (err) {
-      throw new UnavailableError(`Capability "${name}" availability check threw`, { capability: name, reason: (err as Error)?.message || String(err) })
-    }
-    if (availResult === false) {
-      throw new UnavailableError(`Capability "${name}" is not currently available`, { capability: name, reason: 'available(ctx) returned false' })
-    }
-    assertValid(cap.inputSchema, args, name)
-    void meta
-    return cap
-  }
-
-  function wrapPrecheckError(name: string, err: unknown): Error {
-    if (err instanceof ValidationError || err instanceof PrecheckError) return err
-    return new PrecheckError(`Precheck for "${name}" threw: ${(err as Error)?.message || err}`, { capability: name, reason: (err as Error)?.message || String(err) })
-  }
-
-  function resolvePrecheck(name: string, pre: PrecheckResult | undefined): PrecheckResult {
-    const r = pre || { ok: true }
-    if (r.ok === false) {
-      throw new PrecheckError(`Precheck for "${name}" rejected: ${r.reason || 'no reason given'}`, { capability: name, reason: r.reason ?? null })
-    }
-    return r
-  }
-
-  // commit boundary — snapshot only a change that will actually mutate.
-  function commitHistory(cap: NormalizedCapability<Ctx>, pre: PrecheckResult): void {
-    const pushHistory = (ctx as unknown as RegistryCtx)?.pushHistory
-    if (cap.reversible && pre.willMutate !== false && typeof pushHistory === 'function') {
-      pushHistory()
-    }
-  }
-
-  const fullMeta = (opts?: Partial<InvokeMeta>): InvokeMeta => ({ source: opts?.source ?? 'ui', mode: opts?.mode ?? 'commit' })
-
-  // Async pipeline — supports async precheck/execute (the generative/agent path).
-  async function invoke(name: string, args: Record<string, unknown> = {}, opts?: Partial<InvokeMeta>): Promise<unknown> {
-    const meta = fullMeta(opts)
-    const cap = prepareInvocation(name, args, meta)
-    let pre: PrecheckResult
-    try {
-      pre = resolvePrecheck(name, await cap.precheck(args as never, ctx, meta))
-    } catch (err) {
-      throw wrapPrecheckError(name, err)
-    }
-    commitHistory(cap, pre)
-    return cap.execute(args as never, ctx, meta)
-  }
-
-  // Synchronous pipeline for UI mutation/query callers — preserves handler ordering (the write
-  // lands before the caller's following side effects). Rejects async precheck/execute.
-  function invokeSync(name: string, args: Record<string, unknown> = {}, opts?: Partial<InvokeMeta>): unknown {
-    const meta = fullMeta(opts)
-    const cap = prepareInvocation(name, args, meta)
-    let preResult: PrecheckResult | Promise<PrecheckResult>
-    try {
-      preResult = cap.precheck(args as never, ctx, meta)
-    } catch (err) {
-      throw wrapPrecheckError(name, err)
-    }
-    if (preResult && typeof (preResult as Promise<PrecheckResult>).then === 'function') {
-      throw new Error(`Capability "${name}" has an async precheck — use invoke()`)
-    }
-    const pre = resolvePrecheck(name, preResult as PrecheckResult)
-    commitHistory(cap, pre)
-    const result = cap.execute(args as never, ctx, meta)
-    if (result && typeof (result as Promise<unknown>).then === 'function') {
-      throw new Error(`Capability "${name}" execute() is async — use invoke() (e.g. generative)`)
-    }
-    return result
-  }
-
-  const api: CapabilityRegistry<Ctx> = {
-    register,
-    registerAll(descriptors) {
-      descriptors.forEach(register)
-      return api
-    },
-    has,
-    get,
-    describe,
-    list,
-    isAvailable,
-    cost,
-    invoke,
-    invokeSync,
-  }
-  return api
-}