entangled-worlds-orbiters-shared 2.17.0 → 3.1.0

package/README.md

@@ -81,10 +81,8 @@ import * as EntangledWorlds from 'entangled-worlds-orbiters-shared';
 - Real binaries (close pair from component masses, a distant companion for wide pairs) and an optional debris disc; `mainSequenceTemperature` / `Radius` / `Luminosity` helpers
 - Perf + look harness: `npm run bench:star` (see `bench/star/results/REPORT.md`)
 
-### Capabilities (`entangled-worlds-orbiters-shared/capabilities`)
-- `createCapabilityRegistry` - Validated, named registry of studio actions (query / mutation / generative)
-- `validate`, `assertValid` - JSON-Schema-subset validator used for capability inputs
-- Error taxonomy - `ValidationError`, `UnavailableError`, `PrecheckError`, …
+### Capabilities → moved
+The capability registry (`createCapabilityRegistry`, `validate` / `assertValid`, the error taxonomy) moved to its own package, **`plantasia.space-orchidea/capabilities`** (removed here in 3.0.0).
 
 ### Studio session (`entangled-worlds-orbiters-shared/studio`)
 - `createHistory` - Snapshot undo/redo with injected snapshot/restore

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "entangled-worlds-orbiters-shared",
-  "version": "2.17.0",
+  "version": "3.1.0",
   "description": "Shared library for entangled worlds orbiters - contains core world rendering, moons system, and UI components",
   "type": "module",
   "main": "src/index.js",
@@ -38,10 +38,6 @@
       "types": "./dist/clock/curves.d.ts",
       "import": "./dist/clock/curves.js"
     },
-    "./capabilities": {
-      "types": "./dist/capabilities/index.d.ts",
-      "import": "./dist/capabilities/index.js"
-    },
     "./faust": {
       "types": "./dist/faust/index.d.ts",
       "import": "./dist/faust/index.js"
@@ -129,14 +125,13 @@
     "prepare": "npm run build:ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test:clock": "node --test --import tsx src/clock/*.test.ts",
-    "test:capabilities": "node --test --import tsx src/capabilities/*.test.js",
     "test:notes": "node --test --import tsx src/notes/*.test.ts",
     "test:faust": "node --test --import tsx src/faust/*.test.ts",
     "test:studio": "node --test --import tsx src/studio/*.test.js",
     "test:uploads": "node --test --import tsx src/uploads/*.test.js",
     "test:audio": "node --test --import tsx src/audio/*.test.ts",
     "test:render": "node --test src/render/*.test.js",
-    "test": "npm run test:clock && npm run test:capabilities && npm run test:notes && npm run test:faust && npm run test:studio && npm run test:uploads && npm run test:audio && npm run test:render && npm run test:moons && npm run test:star",
+    "test": "npm run test:clock && npm run test:notes && npm run test:faust && npm run test:studio && npm run test:uploads && npm run test:audio && npm run test:render && npm run test:moons && npm run test:star",
     "test:moons": "node --test src/moons/*.test.js",
     "test:star": "node --test --import tsx src/star/*.test.ts",
     "bench:star:build": "esbuild bench/star/main.ts --bundle --format=esm --target=es2022 --outfile=bench/star/build/main.js --log-level=warning",

package/src/render/viewportCompositor.js

@@ -158,6 +158,10 @@ export function createViewportCompositor({
   let grid = null;
   let raf = null;
   let disposed = false;
+  // A load meter's watch on the realm's frames (`setFrameProbe`): null when nobody is watching.
+  let frameProbe = null;
+  let frameProbeAt = 0;
+  let probePixel = null;
   let lastCanvasW = 0;
   let lastCanvasH = 0;
   let viewportH = 0; // per-cell cull band (CSS px), refreshed with the rects
@@ -514,7 +518,60 @@ export function createViewportCompositor({
     // at half the realm's rate. Skipping the whole frame instead leaves every cell showing the last
     // frame that was drawn — together, which is the only way a shared canvas can be consistent.
     if (performanceOn && !frameBudget.shouldRender(nowMs)) return;
-    renderOnce();
+    if (!frameProbe) {
+      renderOnce();
+      return;
+    }
+    const probe = frameProbe;
+    probe.onFrame?.(nowMs);
+    const timed = nowMs - frameProbeAt >= probe.everyMs;
+    if (!timed) {
+      renderOnce();
+      return;
+    }
+    frameProbeAt = nowMs;
+    // Every cell's draw counted together: one composited frame is several renders.
+    const info = renderer.info;
+    const autoReset = info.autoReset;
+    info.autoReset = false;
+    info.reset();
+    try {
+      const started = performance.now();
+      renderOnce();
+      // A lost context draws nothing and answers nothing: no reading, not a good one.
+      if (waitForDraw()) {
+        const drawn = performance.now();
+        // Asked again with nothing left to draw: what the asking itself costs, taken off the reading.
+        waitForDraw();
+        probe.onDraw(Math.max(0, drawn - started - (performance.now() - drawn)), info.render.calls, info.render.triangles);
+      }
+    } finally {
+      // Put back as it was, even when a voice throws mid-frame.
+      info.autoReset = autoReset;
+    }
+  }
+
+  /** Block until the graphics chip has drawn what was sent: reading a pixel back is the one wait every
+   *  browser honours. False when there is no context to ask. */
+  function waitForDraw() {
+    const gl = renderer.getContext?.();
+    if (!gl || gl.isContextLost()) return false;
+    probePixel ??= new Uint8Array(4);
+    gl.readPixels(0, 0, 1, 1, gl.RGBA, gl.UNSIGNED_BYTE, probePixel);
+    return true;
+  }
+
+  /**
+   * Watch the realm's frames, for a load meter: `onFrame(nowMs)` for every frame drawn, and one frame
+   * every `everyMs` timed to the end of its drawing (`onDraw(workMs, calls, triangles)`, every cell
+   * together). Only the timed frame waits for the graphics chip; every other frame is untouched.
+   * `null` stops it.
+   *
+   * @param {{ everyMs: number, onFrame?: (nowMs: number) => void, onDraw: (workMs: number, calls: number, triangles: number) => void } | null} probe
+   */
+  function setFrameProbe(probe) {
+    frameProbe = probe ?? null;
+    frameProbeAt = 0;
   }
 
   /**
@@ -572,6 +629,7 @@ export function createViewportCompositor({
     removeVoice,
     renderOnce,
     setPerformanceMode,
+    setFrameProbe,
     dispose,
   };
   // Dev handle: lets tooling force a composited frame when rAF is throttled (e.g. a hidden/background

package/dist/capabilities/errors.d.ts

@@ -1,79 +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 declare class CapabilityError extends Error {
-    code: CapabilityErrorCode;
-    capability: string | null;
-    cause?: unknown;
-    constructor(message: string, { code, capability, cause }?: {
-        code?: CapabilityErrorCode;
-        capability?: string | null;
-        cause?: unknown;
-    });
-}
-/** Input args failed the capability's inputSchema. Thrown before any write. */
-export declare class ValidationError extends CapabilityError {
-    issues: SchemaIssue[];
-    constructor(message: string, { capability, issues }?: {
-        capability?: string | null;
-        issues?: SchemaIssue[];
-    });
-}
-/** Capability is declared but not invokable yet (status: 'planned' / available()===false). */
-export declare class UnavailableError extends CapabilityError {
-    reason: string | null;
-    constructor(message: string, { capability, reason }?: {
-        capability?: string | null;
-        reason?: string | null;
-    });
-}
-/**
- * Capability's precheck rejected the args against live state (no-op target, missing element,
- * guard condition). Thrown before pushHistory / any write.
- */
-export declare class PrecheckError extends CapabilityError {
-    reason: string | null;
-    constructor(message: string, { capability, reason }?: {
-        capability?: string | null;
-        reason?: string | null;
-    });
-}
-/**
- * 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 declare class NotImplementedError extends CapabilityError {
-    constructor(capability: string, message?: string | null);
-}
-/**
- * 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 declare class InsufficientCreditsError extends CapabilityError {
-    required: number | null;
-    available: number | null;
-    constructor(message: string, { capability, required, available }?: {
-        capability?: string | null;
-        required?: number | null;
-        available?: number | null;
-    });
-}
-export declare class UnknownCapabilityError extends CapabilityError {
-    constructor(name: string);
-}

package/dist/capabilities/errors.js

@@ -1,87 +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 class CapabilityError extends Error {
-    code;
-    capability;
-    cause;
-    constructor(message, { code = 'CAPABILITY_ERROR', capability = null, cause = null } = {}) {
-        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;
-    constructor(message, { capability = null, issues = [] } = {}) {
-        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;
-    constructor(message, { capability = null, reason = 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;
-    constructor(message, { capability = null, reason = 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, message = 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;
-    available;
-    constructor(message, { capability = null, required = null, available = null } = {}) {
-        super(message, { code: 'INSUFFICIENT_CREDITS', capability });
-        this.name = 'InsufficientCreditsError';
-        this.required = required;
-        this.available = available;
-    }
-}
-export class UnknownCapabilityError extends CapabilityError {
-    constructor(name) {
-        super(`Unknown capability "${name}"`, { code: 'UNKNOWN_CAPABILITY', capability: name });
-        this.name = 'UnknownCapabilityError';
-    }
-}

package/dist/capabilities/index.d.ts

@@ -1,9 +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/dist/capabilities/index.js

@@ -1,9 +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, } from './registry.js';
-export { validate, assertValid } from './schema.js';
-export * from './errors.js';

package/dist/capabilities/registry.d.ts

@@ -1,106 +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 { 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;
-}
-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 declare function createCapabilityRegistry<Ctx = Record<string, unknown>>({ ctx }?: {
-    ctx?: Ctx;
-}): CapabilityRegistry<Ctx>;
-export {};

package/dist/capabilities/registry.js

@@ -1,215 +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 } from './schema.js';
-const VALID_KINDS = new Set(['mutation', 'query', 'generative']);
-// Fill descriptor defaults once at registration so invoke() stays branch-light.
-function normalize(descriptor) {
-    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 = 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),
-        precheck: (typeof descriptor.precheck === 'function' ? descriptor.precheck : () => ({ ok: true })),
-        execute: descriptor.execute,
-    };
-}
-export function createCapabilityRegistry({ ctx = {} } = {}) {
-    const caps = new Map();
-    function register(descriptor) {
-        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) => caps.has(name);
-    const get = (name) => 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) {
-        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) {
-        const cap = get(name);
-        return cap ? info(cap) : null;
-    }
-    function list({ includePlanned = false, kind = null } = {}) {
-        const out = [];
-        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) {
-        const cap = get(name);
-        if (!cap || cap.status !== 'active')
-            return false;
-        try {
-            return cap.available(ctx) !== false;
-        }
-        catch {
-            return false;
-        }
-    }
-    function cost(name, args = {}) {
-        const cap = get(name);
-        if (!cap)
-            return 0;
-        try {
-            return Number(cap.cost(args, ctx)) || 0;
-        }
-        catch {
-            return 0;
-        }
-    }
-    // Steps 1–3 (resolve → availability → validate): pure, no side effects. Shared by both paths.
-    function prepareInvocation(name, args, meta) {
-        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;
-        try {
-            availResult = cap.available(ctx);
-        }
-        catch (err) {
-            throw new UnavailableError(`Capability "${name}" availability check threw`, { capability: name, reason: err?.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, err) {
-        if (err instanceof ValidationError || err instanceof PrecheckError)
-            return err;
-        return new PrecheckError(`Precheck for "${name}" threw: ${err?.message || err}`, { capability: name, reason: err?.message || String(err) });
-    }
-    function resolvePrecheck(name, pre) {
-        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, pre) {
-        const pushHistory = ctx?.pushHistory;
-        if (cap.reversible && pre.willMutate !== false && typeof pushHistory === 'function') {
-            pushHistory();
-        }
-    }
-    const fullMeta = (opts) => ({ source: opts?.source ?? 'ui', mode: opts?.mode ?? 'commit' });
-    // Async pipeline — supports async precheck/execute (the generative/agent path).
-    async function invoke(name, args = {}, opts) {
-        const meta = fullMeta(opts);
-        const cap = prepareInvocation(name, args, meta);
-        let pre;
-        try {
-            pre = resolvePrecheck(name, await cap.precheck(args, ctx, meta));
-        }
-        catch (err) {
-            throw wrapPrecheckError(name, err);
-        }
-        commitHistory(cap, pre);
-        return cap.execute(args, 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, args = {}, opts) {
-        const meta = fullMeta(opts);
-        const cap = prepareInvocation(name, args, meta);
-        let preResult;
-        try {
-            preResult = cap.precheck(args, ctx, meta);
-        }
-        catch (err) {
-            throw wrapPrecheckError(name, err);
-        }
-        if (preResult && typeof preResult.then === 'function') {
-            throw new Error(`Capability "${name}" has an async precheck — use invoke()`);
-        }
-        const pre = resolvePrecheck(name, preResult);
-        commitHistory(cap, pre);
-        const result = cap.execute(args, ctx, meta);
-        if (result && typeof result.then === 'function') {
-            throw new Error(`Capability "${name}" execute() is async — use invoke() (e.g. generative)`);
-        }
-        return result;
-    }
-    const api = {
-        register,
-        registerAll(descriptors) {
-            descriptors.forEach(register);
-            return api;
-        },
-        has,
-        get,
-        describe,
-        list,
-        isAvailable,
-        cost,
-        invoke,
-        invokeSync,
-    };
-    return api;
-}