entangled-worlds-orbiters-shared 2.16.0 → 3.0.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/dist/faust/recipes.js

@@ -70,20 +70,24 @@ export function readHeadShape(value, sources) {
         if (typeof file !== 'string' || !Object.hasOwn(sources, file))
             throw new Error(`module ${index}: no such source`);
         const last = index === value.length - 1;
-        if (last) {
-            if (notes?.kind !== 'instrument' || !whole(notes.polyphony, MAX_NOTE_LANES))
-                throw new Error(`module ${index}: a head ends with an instrument of 1 to ${MAX_NOTE_LANES} voices`);
-            const constants = notes.constants ?? {};
+        // Program constants, an instrument's or a note module's: a few safe names, each a small whole number.
+        const constantsOf = (given) => {
+            const constants = given ?? {};
             if (typeof constants !== 'object' || Array.isArray(constants))
                 throw new Error(`module ${index}: constants`);
             const entries = Object.entries(constants);
             if (entries.length > 8 || entries.some(([name, n]) => !/^[A-Z][A-Z0-9_]{0,23}$/.test(name) || !whole(n, MAX_CONSTANT)))
                 throw new Error(`module ${index}: constants`);
-            return { dspFileName: file, notes: { kind: 'instrument', polyphony: notes.polyphony, ...(entries.length ? { constants: Object.fromEntries(entries) } : {}) } };
+            return entries.length ? { constants: Object.fromEntries(entries) } : {};
+        };
+        if (last) {
+            if (notes?.kind !== 'instrument' || !whole(notes.polyphony, MAX_NOTE_LANES))
+                throw new Error(`module ${index}: a head ends with an instrument of 1 to ${MAX_NOTE_LANES} voices`);
+            return { dspFileName: file, notes: { kind: 'instrument', polyphony: notes.polyphony, ...constantsOf(notes.constants) } };
         }
         if ((notes?.kind !== 'generator' && notes?.kind !== 'midi') || !whole(notes.lanesPerLane, MAX_NOTE_LANES))
             throw new Error(`module ${index}: a note module with 1 to ${MAX_NOTE_LANES} lanes per lane`);
-        return { dspFileName: file, notes: { kind: notes.kind, lanesPerLane: notes.lanesPerLane } };
+        return { dspFileName: file, notes: { kind: notes.kind, lanesPerLane: notes.lanesPerLane, ...constantsOf(notes.constants) } };
     });
 }
 const isHead = (head) => {

package/dist/faust/voiceProgram.d.ts

@@ -41,6 +41,7 @@
  * lanes so far and multiplies them by its `lanesPerLane`, inside its note-domain bypass; the
  * instrument plays every lane that reaches it. `SLOT` is the module's place, its part of the seed;
  * a module that adds lanes (a structural `lanesOut`) also gets `LANES_OUT`, its lanes out per lane in,
+ * and a note module with program constants (an optional section compiled in or out) gets them too,
  * since `notes(n)` is told only n.
  *
  * Between the note modules a lane carries a fourth signal, the beat its note started on (what Random
@@ -62,6 +63,7 @@ export type SlotNotes = {
 } | {
     kind: 'generator' | 'midi';
     lanesPerLane: number;
+    constants?: Readonly<Record<string, number>>;
 };
 /** One slot of a composed voice: the module's `.dsp`, by file name. */
 export interface VoiceSlot {

package/dist/faust/voiceProgram.js

@@ -41,6 +41,7 @@
  * lanes so far and multiplies them by its `lanesPerLane`, inside its note-domain bypass; the
  * instrument plays every lane that reaches it. `SLOT` is the module's place, its part of the seed;
  * a module that adds lanes (a structural `lanesOut`) also gets `LANES_OUT`, its lanes out per lane in,
+ * and a note module with program constants (an optional section compiled in or out) gets them too,
  * since `notes(n)` is told only n.
  *
  * Between the note modules a lane carries a fourth signal, the beat its note started on (what Random
@@ -117,7 +118,7 @@ function noteModules(slots, head) {
         }
         const k = wholeAtLeastOne(notes.lanesPerLane, `slot ${index}: lanesPerLane`);
         // A module that adds lanes is told how many it puts out per lane in (an echo's repeats + 1).
-        const env = k === 1 ? `SLOT = ${index};` : `SLOT = ${index}; LANES_OUT = ${k};`;
+        const env = (k === 1 ? `SLOT = ${index};` : `SLOT = ${index}; LANES_OUT = ${k};`) + constantsEnv(notes.constants, index);
         const fx = `library("${slot.dspFileName}")[${env}].notes(${lanes})`;
         parts.push(`hgroup("${slotGroupId(index)}", nt.bypass(${lanes}, ${k}, ${fx}))`);
         lanes *= k;
@@ -134,13 +135,16 @@ function noteModules(slots, head) {
 function instrumentPart(slots, head, lanes) {
     // The instrument's place salts its random draws too (an LFO's Random), as every note module's does;
     // its program constants (unison's `U`) shape it, as its polyphony does.
-    const constants = Object.entries(slots[head].notes.constants ?? {})
-        .map(([name, value]) => {
+    const constants = constantsEnv(slots[head].notes.constants, head);
+    return `hgroup("${slotGroupId(head)}", library("${slots[head].dspFileName}")[SLOT = ${head};${constants}].play(${lanes}))`;
+}
+/** A slot's program constants as library environment entries (` U = 2;`), each a safe name and a whole number. */
+function constantsEnv(constants, index) {
+    return Object.entries(constants ?? {}).map(([name, value]) => {
         if (!/^[A-Z][A-Z0-9_]*$/.test(name))
-            throw new Error(`[voiceProgram] slot ${head}: unsafe constant ${name}`);
-        return ` ${name} = ${wholeAtLeastOne(value, `slot ${head}: ${name}`)};`;
+            throw new Error(`[voiceProgram] slot ${index}: unsafe constant ${name}`);
+        return ` ${name} = ${wholeAtLeastOne(value, `slot ${index}: ${name}`)};`;
     }).join('');
-    return `hgroup("${slotGroupId(head)}", library("${slots[head].dspFileName}")[SLOT = ${head};${constants}].play(${lanes}))`;
 }
 /** The entry, the note modules and the instrument, up to `head` (the instrument): lanes all the way. */
 function noteChain(slots, head) {
@@ -167,8 +171,8 @@ export function voiceCacheKey(slots) {
     // A note module's lane count is structural too: it shapes the program.
     const shape = (slots ?? []).map((slot) => {
         const notes = slot?.notes;
-        const constants = notes?.kind === 'instrument' ? constantsKey(notes.constants) : '';
-        const lanes = !notes ? '' : notes.kind === 'instrument' ? `#p${notes.polyphony}${constants}` : `#${notes.kind}${notes.lanesPerLane}`;
+        const constants = notes ? constantsKey(notes.constants) : '';
+        const lanes = !notes ? '' : notes.kind === 'instrument' ? `#p${notes.polyphony}${constants}` : `#${notes.kind}${notes.lanesPerLane}${constants}`;
         return String(slot?.dspFileName ?? '') + lanes;
     }).join('>');
     return `v${fnv(shape)}`;
@@ -238,7 +242,10 @@ export function buildHeadPrograms(slots) {
     // FAUST roots a program's controls in a group named after it only when it has several groups at the
     // top: named here, both programs' addresses start as the one program's do, whatever each holds.
     const root = (chain) => `vgroup("${HEAD_PROGRAM_NAME}", ${chain})`;
-    const shape = slots.slice(0, head).map((slot) => `${slot.dspFileName}#${slot.notes.kind}${slot.notes.lanesPerLane}`).join('>');
+    const shape = slots.slice(0, head).map((slot) => {
+        const n = slot.notes;
+        return `${slot.dspFileName}#${n.kind}${n.lanesPerLane}${constantsKey(n.constants)}`;
+    }).join('>');
     return {
         notes: {
             key: `n${fileKey(`${shape}>#p${notes.polyphony}`)}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "entangled-worlds-orbiters-shared",
-  "version": "2.16.0",
+  "version": "3.0.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/faust/recipes.ts

@@ -90,16 +90,20 @@ export function readHeadShape(value: unknown, sources: Readonly<Record<string, s
     const notes = (slot as VoiceSlot | null)?.notes as SlotNotes | undefined;
     if (typeof file !== 'string' || !Object.hasOwn(sources, file)) throw new Error(`module ${index}: no such source`);
     const last = index === value.length - 1;
-    if (last) {
-      if (notes?.kind !== 'instrument' || !whole(notes.polyphony, MAX_NOTE_LANES)) throw new Error(`module ${index}: a head ends with an instrument of 1 to ${MAX_NOTE_LANES} voices`);
-      const constants = notes.constants ?? {};
+    // Program constants, an instrument's or a note module's: a few safe names, each a small whole number.
+    const constantsOf = (given: unknown): { constants?: Record<string, number> } => {
+      const constants = given ?? {};
       if (typeof constants !== 'object' || Array.isArray(constants)) throw new Error(`module ${index}: constants`);
       const entries = Object.entries(constants);
       if (entries.length > 8 || entries.some(([name, n]) => !/^[A-Z][A-Z0-9_]{0,23}$/.test(name) || !whole(n, MAX_CONSTANT))) throw new Error(`module ${index}: constants`);
-      return { dspFileName: file, notes: { kind: 'instrument', polyphony: notes.polyphony, ...(entries.length ? { constants: Object.fromEntries(entries) } : {}) } };
+      return entries.length ? { constants: Object.fromEntries(entries) } : {};
+    };
+    if (last) {
+      if (notes?.kind !== 'instrument' || !whole(notes.polyphony, MAX_NOTE_LANES)) throw new Error(`module ${index}: a head ends with an instrument of 1 to ${MAX_NOTE_LANES} voices`);
+      return { dspFileName: file, notes: { kind: 'instrument', polyphony: notes.polyphony, ...constantsOf(notes.constants) } };
     }
     if ((notes?.kind !== 'generator' && notes?.kind !== 'midi') || !whole(notes.lanesPerLane, MAX_NOTE_LANES)) throw new Error(`module ${index}: a note module with 1 to ${MAX_NOTE_LANES} lanes per lane`);
-    return { dspFileName: file, notes: { kind: notes.kind, lanesPerLane: notes.lanesPerLane } };
+    return { dspFileName: file, notes: { kind: notes.kind, lanesPerLane: notes.lanesPerLane, ...constantsOf(notes.constants) } };
   });
 }
 

package/src/faust/voiceProgram.ts

@@ -41,6 +41,7 @@
  * lanes so far and multiplies them by its `lanesPerLane`, inside its note-domain bypass; the
  * instrument plays every lane that reaches it. `SLOT` is the module's place, its part of the seed;
  * a module that adds lanes (a structural `lanesOut`) also gets `LANES_OUT`, its lanes out per lane in,
+ * and a note module with program constants (an optional section compiled in or out) gets them too,
  * since `notes(n)` is told only n.
  *
  * Between the note modules a lane carries a fourth signal, the beat its note started on (what Random
@@ -55,7 +56,7 @@ export const MAX_NOTE_LANES = 16;
  * What a slot does with notes: a notes instrument's polyphony (and its program constants, when it has
  * any), or a generator's or MIDI effect's lanes out per lane in.
  */
-export type SlotNotes = { kind: 'instrument'; polyphony: number; constants?: Readonly<Record<string, number>>; copies?: number } | { kind: 'generator' | 'midi'; lanesPerLane: number };
+export type SlotNotes = { kind: 'instrument'; polyphony: number; constants?: Readonly<Record<string, number>>; copies?: number } | { kind: 'generator' | 'midi'; lanesPerLane: number; constants?: Readonly<Record<string, number>> };
 
 /** Faust identifiers: the group name goes into generated source, so keep it tame. */
 const SAFE_SEGMENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -143,7 +144,7 @@ function noteModules(slots: readonly VoiceSlot[], head: number): { parts: string
     }
     const k = wholeAtLeastOne(notes.lanesPerLane, `slot ${index}: lanesPerLane`);
     // A module that adds lanes is told how many it puts out per lane in (an echo's repeats + 1).
-    const env = k === 1 ? `SLOT = ${index};` : `SLOT = ${index}; LANES_OUT = ${k};`;
+    const env = (k === 1 ? `SLOT = ${index};` : `SLOT = ${index}; LANES_OUT = ${k};`) + constantsEnv(notes.constants, index);
     const fx = `library("${slot.dspFileName}")[${env}].notes(${lanes})`;
     parts.push(`hgroup("${slotGroupId(index)}", nt.bypass(${lanes}, ${k}, ${fx}))`);
     lanes *= k;
@@ -160,14 +161,18 @@ function noteModules(slots: readonly VoiceSlot[], head: number): { parts: string
 function instrumentPart(slots: readonly VoiceSlot[], head: number, lanes: number): string {
   // The instrument's place salts its random draws too (an LFO's Random), as every note module's does;
   // its program constants (unison's `U`) shape it, as its polyphony does.
-  const constants = Object.entries((slots[head].notes as { constants?: Readonly<Record<string, number>> }).constants ?? {})
-    .map(([name, value]) => {
-      if (!/^[A-Z][A-Z0-9_]*$/.test(name)) throw new Error(`[voiceProgram] slot ${head}: unsafe constant ${name}`);
-      return ` ${name} = ${wholeAtLeastOne(value, `slot ${head}: ${name}`)};`;
-    }).join('');
+  const constants = constantsEnv((slots[head].notes as { constants?: Readonly<Record<string, number>> }).constants, head);
   return `hgroup("${slotGroupId(head)}", library("${slots[head].dspFileName}")[SLOT = ${head};${constants}].play(${lanes}))`;
 }
 
+/** A slot's program constants as library environment entries (` U = 2;`), each a safe name and a whole number. */
+function constantsEnv(constants: Readonly<Record<string, number>> | undefined, index: number): string {
+  return Object.entries(constants ?? {}).map(([name, value]) => {
+    if (!/^[A-Z][A-Z0-9_]*$/.test(name)) throw new Error(`[voiceProgram] slot ${index}: unsafe constant ${name}`);
+    return ` ${name} = ${wholeAtLeastOne(value, `slot ${index}: ${name}`)};`;
+  }).join('');
+}
+
 /** The entry, the note modules and the instrument, up to `head` (the instrument): lanes all the way. */
 function noteChain(slots: readonly VoiceSlot[], head: number): string[] {
   const { parts, lanes } = noteModules(slots, head);
@@ -194,8 +199,8 @@ export function voiceCacheKey(slots: readonly VoiceSlot[] | null | undefined): s
   // A note module's lane count is structural too: it shapes the program.
   const shape = (slots ?? []).map((slot) => {
     const notes = slot?.notes;
-    const constants = notes?.kind === 'instrument' ? constantsKey(notes.constants) : '';
-    const lanes = !notes ? '' : notes.kind === 'instrument' ? `#p${notes.polyphony}${constants}` : `#${notes.kind}${notes.lanesPerLane}`;
+    const constants = notes ? constantsKey(notes.constants) : '';
+    const lanes = !notes ? '' : notes.kind === 'instrument' ? `#p${notes.polyphony}${constants}` : `#${notes.kind}${notes.lanesPerLane}${constants}`;
     return String(slot?.dspFileName ?? '') + lanes;
   }).join('>');
   return `v${fnv(shape)}`;
@@ -287,7 +292,10 @@ export function buildHeadPrograms(slots: readonly VoiceSlot[]): HeadPrograms {
   // FAUST roots a program's controls in a group named after it only when it has several groups at the
   // top: named here, both programs' addresses start as the one program's do, whatever each holds.
   const root = (chain: string) => `vgroup("${HEAD_PROGRAM_NAME}", ${chain})`;
-  const shape = slots.slice(0, head).map((slot) => `${slot.dspFileName}#${slot.notes!.kind}${(slot.notes as { lanesPerLane: number }).lanesPerLane}`).join('>');
+  const shape = slots.slice(0, head).map((slot) => {
+    const n = slot.notes as Extract<SlotNotes, { kind: 'generator' | 'midi' }>;
+    return `${slot.dspFileName}#${n.kind}${n.lanesPerLane}${constantsKey(n.constants)}`;
+  }).join('>');
   return {
     notes: {
       key: `n${fileKey(`${shape}>#p${notes.polyphony}`)}`,

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 {};