entangled-worlds-orbiters-shared 2.16.0 → 3.0.0

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

package/src/capabilities/schema.ts

@@ -1,164 +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, 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
-}
-
-const TYPE_CHECKS: Record<JsonType, (v: unknown) => boolean> = {
-  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: unknown, b: unknown): boolean {
-  if (a === b) return true
-  if (typeof a !== typeof b || a === null || b === null || typeof a !== 'object') return false
-  const ka = Object.keys(a as object)
-  const kb = Object.keys(b as object)
-  if (ka.length !== kb.length) return false
-  return ka.every((k) => deepEqual((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k]))
-}
-
-function checkType(schema: JsonSchema, value: unknown): boolean {
-  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: unknown): string {
-  if (value === null) return 'null'
-  if (Array.isArray(value)) return 'array'
-  return typeof value
-}
-
-function validateNode(schema: JsonSchema | undefined, value: unknown, path: string, issues: SchemaIssue[]): void {
-  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 as Record<string, unknown>
-    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: JsonSchema, value: unknown): { ok: boolean; issues: SchemaIssue[] } {
-  const issues: SchemaIssue[] = []
-  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<T>(schema: JsonSchema, value: T, capability: string | null = null): T {
-  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
-}