@xemahq/ui-kernel 0.11.0 → 0.11.2

package/src/lib/contribution-registry/contribution-registry.spec.ts

@@ -1,141 +0,0 @@
-/**
- * Guards the shared closed+open contribution registry core — the ONE
- * implementation behind the ChatWidget, biome output-renderer, reply-variant
- * and Vista-surface planes. Every property the hand-written copies had must
- * survive the extraction.
- *
- * Runs under the host-web vitest mirror (this package carries no vitest dep).
- */
-import { describe, expect, it, vi } from 'vitest';
-
-import {
-  ContributionFallbackReason,
-  DuplicateContributionPolicy,
-  createContributionRegistry,
-  createRenderableContributionRegistry,
-} from './index';
-
-function makeRegistry(): ReturnType<typeof createContributionRegistry<string>> {
-  return createContributionRegistry<string>({
-    name: 'test',
-    reservedKinds: ['plan', 'diff'],
-  });
-}
-
-describe('createContributionRegistry', () => {
-  it('resolves first-party before open, and lists both', () => {
-    const registry = makeRegistry();
-    registry.registerFirstParty('plan', 'builtin-plan');
-    registry.register('acme:gantt', 'acme-gantt');
-    expect(registry.get('plan')).toBe('builtin-plan');
-    expect(registry.get('acme:gantt')).toBe('acme-gantt');
-    expect(registry.has('nope')).toBe(false);
-    expect(registry.list()).toEqual(['acme:gantt', 'plan']);
-    expect(registry.listOpen()).toEqual(['acme:gantt']);
-    expect([...registry.entries().keys()].sort()).toEqual(['acme:gantt', 'plan']);
-  });
-
-  it('refuses to let the open set claim a reserved first-party kind', () => {
-    const registry = makeRegistry();
-    expect(registry.isReserved('diff')).toBe(true);
-    expect(() => registry.register('diff', 'hijack')).toThrow(/reserved/);
-    // The namespaced form is fine.
-    expect(() => registry.register('acme:diff', 'ok')).not.toThrow();
-  });
-
-  it('is idempotent for the identical entry and throws for a different one', () => {
-    const registry = makeRegistry();
-    registry.register('acme:gantt', 'entry');
-    expect(() => registry.register('acme:gantt', 'entry')).not.toThrow();
-    expect(() => registry.register('acme:gantt', 'other')).toThrow(
-      /already registered/,
-    );
-    registry.registerFirstParty('plan', 'builtin');
-    expect(() => registry.registerFirstParty('plan', 'builtin')).not.toThrow();
-    expect(() => registry.registerFirstParty('plan', 'other')).toThrow(
-      /already registered/,
-    );
-  });
-
-  it('resets only the OPEN set', () => {
-    const registry = makeRegistry();
-    registry.registerFirstParty('plan', 'builtin');
-    registry.register('acme:gantt', 'entry');
-    registry.__resetOpenForTests();
-    expect(registry.list()).toEqual(['plan']);
-  });
-
-  it('reports — never swallows — a duplicate under FirstWins', () => {
-    const onDuplicate = vi.fn();
-    const registry = createContributionRegistry<string>({
-      name: 'overlay',
-      duplicatePolicy: DuplicateContributionPolicy.FirstWins,
-      onDuplicate,
-    });
-    registry.register('k', 'first');
-    registry.register('k', 'second');
-    expect(registry.get('k')).toBe('first');
-    expect(onDuplicate).toHaveBeenCalledWith('k', 'first', 'second');
-  });
-
-  it('refuses FirstWins without a reporter', () => {
-    expect(() =>
-      createContributionRegistry<string>({
-        name: 'overlay',
-        duplicatePolicy: DuplicateContributionPolicy.FirstWins,
-      }),
-    ).toThrow(/onDuplicate/);
-  });
-});
-
-describe('createRenderableContributionRegistry', () => {
-  const registry = createRenderableContributionRegistry<string>({
-    name: 'renderable',
-    reservedKinds: ['plan'],
-  });
-  registry.registerFirstParty<{ label: string }>('plan', {
-    version: 2,
-    validate: (payload) =>
-      typeof payload === 'object' &&
-      payload !== null &&
-      typeof (payload as { label?: unknown }).label === 'string'
-        ? (payload as { label: string })
-        : null,
-    render: (payload) => `plan:${payload.label}`,
-  });
-
-  it('renders a matching envelope', () => {
-    const resolution = registry.resolve({
-      kind: 'plan',
-      version: 1,
-      payload: { label: 'ship it' },
-    });
-    expect(resolution).toEqual({
-      matched: true,
-      kind: 'plan',
-      version: 2,
-      rendered: 'plan:ship it',
-    });
-  });
-
-  it('never throws — it returns a typed reason instead', () => {
-    expect(
-      registry.resolve({ kind: 'nope', version: 1, payload: {} }),
-    ).toMatchObject({
-      matched: false,
-      reason: ContributionFallbackReason.UnknownKind,
-    });
-    expect(
-      registry.resolve({ kind: 'plan', version: 99, payload: {} }),
-    ).toMatchObject({
-      matched: false,
-      reason: ContributionFallbackReason.UnsupportedVersion,
-    });
-    expect(
-      registry.resolve({ kind: 'plan', version: 1, payload: { label: 7 } }),
-    ).toMatchObject({
-      matched: false,
-      reason: ContributionFallbackReason.InvalidPayload,
-    });
-  });
-});

package/src/lib/contribution-registry/contribution-registry.ts

@@ -1,204 +0,0 @@
-/**
- * `createContributionRegistry` — the ONE two-layer closed+open registry core
- * the Xema frontend uses everywhere a biome may contribute into a set the
- * platform also ships a closed first-party version of.
- *
- * Before this module the exact same bookkeeping was hand-written four times
- * (in-chat widgets, biome output renderers, open reply variants, and — next —
- * Vista surfaces), each with slightly different guards. This is that core,
- * extracted once (reuse register U1).
- *
- * ── The two layers ──────────────────────────────────────────────────────────
- *   • a CLOSED first-party set, registered at module load and keyed by a
- *     platform enum value;
- *   • an OPEN biome set, registered at runtime (a biome registers from its
- *     `FrontendBiome.init()` hook) and keyed by a namespaced `<biomeId>:<kind>`
- *     slug.
- *
- * ── The invariants (all fail-loud, none silent) ─────────────────────────────
- *   • RESERVED KINDS. Every first-party kind is reserved: `register()` throws
- *     if a biome tries to claim one. The open set can never shadow the closed
- *     one.
- *   • DUPLICATE GUARD. Registering the EXACT same entry object twice is a
- *     no-op (this is what tolerates React Fast Refresh / a double-invoked
- *     `init()`); registering a DIFFERENT entry for a kind that is already
- *     taken is an error — two biomes cannot silently shadow each other.
- *   • The one exception is {@link DuplicateContributionPolicy.FirstWins}, for
- *     registries rebuilt on a hot path where a throw would crash a render
- *     (the biome output-renderer overlay). It is NOT a silent fallback: an
- *     `onDuplicate` reporter is REQUIRED, and the registry factory throws at
- *     construction if it is missing.
- *
- * Resolution itself lives in the caller (or in `renderable-registry.ts` for the
- * versioned + payload-validated flavour) and NEVER throws.
- */
-
-/** What to do when a DIFFERENT entry is registered for an already-taken kind. */
-export enum DuplicateContributionPolicy {
-  /**
-   * Throw. The default, and correct for every registry whose registrations
-   * happen once at module load or once per biome `init()`.
-   */
-  Throw = 'throw',
-  /**
-   * Keep the first registration and report the loser through `onDuplicate`.
-   * For registries REBUILT on a hot path (e.g. per render) where throwing
-   * would take down the UI. Requires `onDuplicate` — there is no silent mode.
-   */
-  FirstWins = 'first-wins',
-}
-
-/** Options for {@link createContributionRegistry}. */
-export interface ContributionRegistryOptions<TEntry> {
-  /** Registry name, used verbatim in every thrown message. */
-  readonly name: string;
-  /**
-   * The CLOSED first-party kinds. Reserved: `register()` refuses them so a
-   * biome can never shadow a platform kind. Typically `Object.values(SomeEnum)`.
-   */
-  readonly reservedKinds?: Iterable<string>;
-  /** Duplicate handling. Defaults to {@link DuplicateContributionPolicy.Throw}. */
-  readonly duplicatePolicy?: DuplicateContributionPolicy;
-  /**
-   * Reporter for a rejected duplicate under
-   * {@link DuplicateContributionPolicy.FirstWins}. REQUIRED under that policy.
-   */
-  readonly onDuplicate?: (
-    kind: string,
-    existing: TEntry,
-    rejected: TEntry,
-  ) => void;
-}
-
-/** The two-layer registry surface. */
-export interface ContributionRegistry<TEntry> {
-  /** Registry name (diagnostics). */
-  readonly name: string;
-  /**
-   * Register a FIRST-PARTY entry for a closed platform kind. Called once per
-   * kind at module load.
-   */
-  registerFirstParty(kind: string, entry: TEntry): void;
-  /**
-   * OPEN seam: register a biome entry under its namespaced `<biomeId>:<kind>`
-   * slug. Throws when the slug is a reserved first-party kind.
-   */
-  register(kind: string, entry: TEntry): void;
-  /** True when SOME entry (first-party or biome) is registered for the kind. */
-  has(kind: string): boolean;
-  /** The entry for a kind — first-party wins — or `undefined`. */
-  get(kind: string): TEntry | undefined;
-  /** True when the kind belongs to the closed first-party set. */
-  isReserved(kind: string): boolean;
-  /** Every registered kind (sorted) — diagnostics + tests. */
-  list(): readonly string[];
-  /** Only the OPEN (biome-contributed) kinds (sorted). */
-  listOpen(): readonly string[];
-  /** Flattened `kind -> entry` view, first-party wins. Diagnostics + overlays. */
-  entries(): ReadonlyMap<string, TEntry>;
-  /** Test-only: clear the OPEN set (the first-party set stays). */
-  __resetOpenForTests(): void;
-}
-
-export function createContributionRegistry<TEntry>(
-  options: ContributionRegistryOptions<TEntry>,
-): ContributionRegistry<TEntry> {
-  const {
-    name,
-    reservedKinds,
-    duplicatePolicy = DuplicateContributionPolicy.Throw,
-    onDuplicate,
-  } = options;
-
-  if (
-    duplicatePolicy === DuplicateContributionPolicy.FirstWins &&
-    onDuplicate === undefined
-  ) {
-    throw new Error(
-      `${name} registry: DuplicateContributionPolicy.FirstWins requires an ` +
-        `'onDuplicate' reporter — a dropped contribution must never be silent.`,
-    );
-  }
-
-  const reserved = new Set<string>(reservedKinds ?? []);
-  const firstParty = new Map<string, TEntry>();
-  const open = new Map<string, TEntry>();
-
-  /**
-   * Idempotent for the IDENTICAL entry (Fast Refresh / double-invoked
-   * `init()`); an error for a DIFFERENT one. Returns whether the entry landed.
-   */
-  function put(target: Map<string, TEntry>, kind: string, entry: TEntry): void {
-    const existing = target.get(kind);
-    if (existing === undefined) {
-      target.set(kind, entry);
-      return;
-    }
-    if (existing === entry) {
-      return;
-    }
-    if (duplicatePolicy === DuplicateContributionPolicy.FirstWins) {
-      // `onDuplicate` is guaranteed present under this policy (checked above).
-      (onDuplicate as (k: string, e: TEntry, r: TEntry) => void)(
-        kind,
-        existing,
-        entry,
-      );
-      return;
-    }
-    throw new Error(
-      `${name} registry: a DIFFERENT entry is already registered for kind ` +
-        `'${kind}'. Two contributors cannot claim the same slug.`,
-    );
-  }
-
-  return {
-    name,
-
-    registerFirstParty(kind: string, entry: TEntry): void {
-      put(firstParty, kind, entry);
-    },
-
-    register(kind: string, entry: TEntry): void {
-      if (reserved.has(kind)) {
-        throw new Error(
-          `${name} registry: '${kind}' is a reserved first-party kind and ` +
-            `cannot be overridden by a biome. Use a namespaced ` +
-            `'<biomeId>:${kind}' slug.`,
-        );
-      }
-      put(open, kind, entry);
-    },
-
-    has(kind: string): boolean {
-      return firstParty.has(kind) || open.has(kind);
-    },
-
-    get(kind: string): TEntry | undefined {
-      return firstParty.get(kind) ?? open.get(kind);
-    },
-
-    isReserved(kind: string): boolean {
-      return reserved.has(kind);
-    },
-
-    list(): readonly string[] {
-      return [...firstParty.keys(), ...open.keys()].sort();
-    },
-
-    listOpen(): readonly string[] {
-      return [...open.keys()].sort();
-    },
-
-    entries(): ReadonlyMap<string, TEntry> {
-      // First-party last so it wins on a key present in both (which `register`
-      // already forbids for reserved kinds, but `entries()` must not depend on
-      // that to be correct).
-      return new Map<string, TEntry>([...open, ...firstParty]);
-    },
-
-    __resetOpenForTests(): void {
-      open.clear();
-    },
-  };
-}

package/src/lib/contribution-registry/index.ts

@@ -1,9 +0,0 @@
-/**
- * The shared two-layer (closed first-party + open biome) contribution registry
- * core, and its versioned/validated renderable flavour.
- *
- * One implementation, four consumers: in-chat ChatWidgets, biome output
- * renderers, open reply variants, and Vista surfaces.
- */
-export * from './contribution-registry';
-export * from './renderable-registry';

package/src/lib/contribution-registry/renderable-registry.ts

@@ -1,142 +0,0 @@
-/**
- * The RENDERABLE flavour of {@link createContributionRegistry}: a two-layer
- * closed+open registry whose entries are versioned renderers with a narrowing
- * payload validator, plus the fail-safe resolution every such plane needs.
- *
- * This is the shape the in-chat ChatWidget plane and the Vista render plane
- * both want: an envelope `{ kind, version, payload }` arrives from an agent,
- * and the frontend must turn it into something drawable WITHOUT ever throwing
- * and WITHOUT ever silently drawing a coerced half-widget. Resolution returns a
- * typed reason instead, which the caller renders as a safe fallback card.
- */
-import {
-  createContributionRegistry,
-  type ContributionRegistry,
-  type ContributionRegistryOptions,
-} from './contribution-registry';
-
-/**
- * Why an envelope fell back to the safe card. Populated on the resolution so
- * the Studio debugger (and dev logs) can see WHY — mirrors the Model Resolution
- * Matrix's `ResolvedModelDecision`. Closed set.
- */
-export enum ContributionFallbackReason {
-  UnknownKind = 'unknown-kind',
-  InvalidPayload = 'invalid-payload',
-  UnsupportedVersion = 'unsupported-version',
-}
-
-/** The minimum an agent-emitted envelope must carry to be resolvable. */
-export interface ContributionEnvelope {
-  readonly kind: string;
-  readonly version: number;
-  readonly payload: unknown;
-}
-
-/**
- * A versioned renderer. `validate` narrows the wire payload to the renderer's
- * own type (returning `null` routes to the fallback with `InvalidPayload`) and
- * MUST NOT throw; `render` draws from the narrowed payload.
- */
-export interface RenderableContributionEntry<TRendered, TPayload = unknown> {
-  /** Highest schema version this renderer supports. */
-  readonly version: number;
-  /** Narrowing validator. Returns the typed payload, or `null`. MUST NOT throw. */
-  validate(payload: unknown): TPayload | null;
-  /** Draw from the narrowed payload. */
-  render(payload: TPayload): TRendered;
-}
-
-/** The outcome of resolving an envelope — inspectable for the Studio debugger. */
-export type RenderableResolution<TRendered> =
-  | {
-      readonly matched: true;
-      readonly kind: string;
-      readonly version: number;
-      readonly rendered: TRendered;
-    }
-  | {
-      readonly matched: false;
-      readonly kind: string;
-      readonly reason: ContributionFallbackReason;
-    };
-
-/** A {@link ContributionRegistry} of versioned renderers, plus `resolve`. */
-export interface RenderableContributionRegistry<TRendered>
-  extends Omit<
-    ContributionRegistry<RenderableContributionEntry<TRendered>>,
-    'registerFirstParty' | 'register'
-  > {
-  registerFirstParty<TPayload>(
-    kind: string,
-    entry: RenderableContributionEntry<TRendered, TPayload>,
-  ): void;
-  register<TPayload>(
-    kind: string,
-    entry: RenderableContributionEntry<TRendered, TPayload>,
-  ): void;
-  /**
-   * Resolve an envelope. Pure + deterministic so it can run in render, and it
-   * NEVER throws — an unknown kind, a payload the entry rejects, or a `version`
-   * newer than the entry supports ALL yield `matched: false` with a typed
-   * reason the caller renders as the safe fallback card.
-   */
-  resolve(envelope: ContributionEnvelope): RenderableResolution<TRendered>;
-}
-
-export function createRenderableContributionRegistry<TRendered>(
-  options: ContributionRegistryOptions<RenderableContributionEntry<TRendered>>,
-): RenderableContributionRegistry<TRendered> {
-  const registry =
-    createContributionRegistry<RenderableContributionEntry<TRendered>>(options);
-
-  return {
-    ...registry,
-
-    registerFirstParty<TPayload>(
-      kind: string,
-      entry: RenderableContributionEntry<TRendered, TPayload>,
-    ): void {
-      registry.registerFirstParty(kind, entry);
-    },
-
-    register<TPayload>(
-      kind: string,
-      entry: RenderableContributionEntry<TRendered, TPayload>,
-    ): void {
-      registry.register(kind, entry);
-    },
-
-    resolve(envelope: ContributionEnvelope): RenderableResolution<TRendered> {
-      const entry = registry.get(envelope.kind);
-      if (entry === undefined) {
-        return {
-          matched: false,
-          kind: envelope.kind,
-          reason: ContributionFallbackReason.UnknownKind,
-        };
-      }
-      if (envelope.version > entry.version) {
-        return {
-          matched: false,
-          kind: envelope.kind,
-          reason: ContributionFallbackReason.UnsupportedVersion,
-        };
-      }
-      const narrowed = entry.validate(envelope.payload);
-      if (narrowed === null) {
-        return {
-          matched: false,
-          kind: envelope.kind,
-          reason: ContributionFallbackReason.InvalidPayload,
-        };
-      }
-      return {
-        matched: true,
-        kind: envelope.kind,
-        version: entry.version,
-        rendered: entry.render(narrowed),
-      };
-    },
-  };
-}

package/src/lib/system-bus/capability-invoke.ts

@@ -1,92 +0,0 @@
-import type { CapabilityRef } from '@xemahq/kernel-contracts/capability';
-import type { SpaceRef } from '@xemahq/kernel-contracts/space';
-
-/**
- * Orchestration metadata the SystemBus carries on every
- * `capability.invoke` so the backend capability-router can build its
- * `ExecutionContext` envelope and record who invoked what, from where,
- * in which space, against which environment.
- *
- * **This is pure orchestration data. The SystemBus NEVER inspects it to
- * decide allow/deny.** The backend capability-router is the single
- * authority on auth / tenancy / policy / audit. The SystemBus's only job
- * is to faithfully relay this metadata to the router and pass the result
- * back; it adds no authorization of its own.
- *
- * The fields map 1:1 onto the gateway's per-invocation envelope:
- * - `sourceBiomeId`    → `ExecutionContext.biome.id`
- * - `targetCapabilityRef` → `ExecutionContext.capability.ref`
- * - `spaceRef`         → `ExecutionContext.space`
- * - `environmentId`    → `ExecutionContext.environment.id`
- * - `actorId`          → `ExecutionContext.subject` (the host resolves the
- *                        full SubjectRef from the actor's session).
- */
-export interface CapabilityInvokeMeta {
-  /** Biome that originated the invocation (for provenance + audit). */
-  readonly sourceBiomeId: string;
-  /** The capability being invoked. Mirrors the `ref` argument; carried
-   * explicitly so the metadata is self-describing in audit records. */
-  readonly targetCapabilityRef: CapabilityRef;
-  /** The space (5/7-tier scope) the invocation runs in. */
-  readonly spaceRef: SpaceRef;
-  /** Canonical `environment:<slug>` ref of the active execution environment. */
-  readonly environmentId: string;
-  /** The acting subject's id (user / agent / app). The host expands this
-   * into the full `SubjectRef` server-side; the SystemBus only carries
-   * the id, never a credential. */
-  readonly actorId: string;
-}
-
-/**
- * Result of a `capability.invoke`. Mirrors the capability-router's
- * `InvokeMetaToolResponseDto` wire shape (`output? / auditId /
- * obligations`) without importing the generated client — the kernel
- * contract stays framework- and transport-agnostic.
- *
- * `output` is `undefined` on denial / approval-required outcomes; the
- * caller MUST treat its absence explicitly (fetch the structured denial
- * via `auditId`) rather than assume success. `auditId` is ALWAYS
- * populated, including on denial — this is the audit anchor.
- */
-export interface CapabilityInvokeResult<TOutput = unknown> {
-  /** Capability output payload. Omitted on denial / approval-required. */
-  readonly output?: TOutput;
-  /** Audit entry id. Always populated, including on denial. */
-  readonly auditId: string;
-  /**
-   * Closed-set policy obligations the caller must honour locally
-   * (e.g. `redact-secrets`, `max-cost-usd`). Sourced verbatim from the
-   * router response. The string union is left open at the contract layer
-   * because the obligation enum is owned by `@xemahq/kernel-contracts/policy`;
-   * the host maps these to the typed enum when it honours them.
-   */
-  readonly obligations: readonly string[];
-}
-
-/**
- * The `capability.invoke` surface of the SystemBus.
- *
- * `invoke()` routes the call to the host's capability-router client. The
- * backend enforces auth / tenancy / policy / audit; the SystemBus adds
- * NONE of those — it is pure orchestration. A non-2xx transport failure
- * rejects the returned promise (fail-fast); a *policy denial* resolves
- * with `output === undefined` + a populated `auditId` (the router's
- * structured outcome), so denial is observable, never silently swallowed.
- */
-export interface CapabilityBus {
-  /**
-   * Invoke a capability through the backend router.
-   *
-   * @param ref   The capability to invoke (`<domain>:<resource>.<verb>@<major>`).
-   * @param input The capability input payload (validated server-side
-   *              against the descriptor's `inputSchema`).
-   * @param meta  Orchestration metadata for the `ExecutionContext`.
-   *              The host fills `targetCapabilityRef` from `ref` if the
-   *              caller omits it; all other fields are required.
-   */
-  invoke<TInput = unknown, TOutput = unknown>(
-    ref: CapabilityRef,
-    input: TInput,
-    meta: CapabilityInvokeMeta,
-  ): Promise<CapabilityInvokeResult<TOutput>>;
-}