@xemahq/ui-kernel 0.11.1 → 0.12.0

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

package/src/lib/system-bus/deeplink.ts

@@ -1,210 +0,0 @@
-import { DeeplinkTargetKind } from './enums';
-
-/**
- * Typed parse/resolve of the SystemBus `xema://` deeplink scheme.
- *
- * The deeplink scheme addresses *places in the running shell*. It is a
- * distinct, narrower grammar from the kernel's `XemaObjectRef`
- * (`xema://<scope>/<kind>/<slug>`): a deeplink's first segment is a
- * {@link DeeplinkTargetKind} discriminator, not a scope path. The two
- * schemes share the `xema://` scheme prefix but never the same body —
- * `parseDeeplink` rejects anything whose head is not a known target kind,
- * so an `XemaObjectRef` is only valid as a deeplink when wrapped as
- * `xema://object/<XemaObjectRef-without-scheme>`.
- *
- * Grammar:
- *   xema://biome/<biomeId>/<route...>?<ctx>     → BiomeRoute
- *   xema://object/<scope>/<kind>/<slug>[@<ver>] → Object
- *   xema://capability/<capability-ref>?<input>  → Capability
- *   xema://window/<windowId>                    → Window
- *
- * Every parse is fail-fast: an unknown target kind, a missing required
- * segment, or a malformed query is a {@link DeeplinkParseError}, never a
- * silent fallback.
- */
-
-const DEEPLINK_SCHEME = 'xema://';
-
-/** Structured, fail-fast error raised by `parseDeeplink`. */
-export class DeeplinkParseError extends Error {
-  public readonly code = 'DEEPLINK_INVALID';
-  public readonly raw: string;
-  public readonly reason: string;
-
-  public constructor(raw: string, reason: string) {
-    super(`Invalid deeplink "${raw}": ${reason}`);
-    this.name = 'DeeplinkParseError';
-    this.raw = raw;
-    this.reason = reason;
-  }
-}
-
-/** A parsed `xema://biome/...` deeplink. */
-export interface BiomeRouteDeeplink {
-  readonly kind: DeeplinkTargetKind.BiomeRoute;
-  readonly biomeId: string;
-  /** The route path within the biome, with a leading slash. */
-  readonly route: string;
-  /** Parsed `?ctx` query params, empty when absent. */
-  readonly ctx: Readonly<Record<string, string>>;
-}
-
-/** A parsed `xema://object/...` deeplink. The body is the scheme-less
- * `XemaObjectRef` (e.g. `system/capability/kb.page.read@1`). */
-export interface ObjectDeeplink {
-  readonly kind: DeeplinkTargetKind.Object;
-  /** Full `XemaObjectRef` (`xema://` re-prefixed) for handing to the
-   * kernel object resolver. */
-  readonly objectRef: `xema://${string}`;
-}
-
-/** A parsed `xema://capability/...` deeplink. */
-export interface CapabilityDeeplink {
-  readonly kind: DeeplinkTargetKind.Capability;
-  /** The raw capability ref string (validated by the kernel
-   * `parseCapabilityRef` when the host launches it). */
-  readonly capabilityRef: string;
-  /** Parsed `?...` query params used as launch input, empty when absent. */
-  readonly input: Readonly<Record<string, string>>;
-}
-
-/** A parsed `xema://window/...` deeplink. */
-export interface WindowDeeplink {
-  readonly kind: DeeplinkTargetKind.Window;
-  readonly windowId: string;
-}
-
-/** Discriminated union of every deeplink target. */
-export type ParsedDeeplink =
-  | BiomeRouteDeeplink
-  | ObjectDeeplink
-  | CapabilityDeeplink
-  | WindowDeeplink;
-
-function parseQuery(search: string): Record<string, string> {
-  const out: Record<string, string> = {};
-  if (search.length === 0) {
-    return out;
-  }
-  for (const pair of search.split('&')) {
-    if (pair.length === 0) {
-      continue;
-    }
-    const eq = pair.indexOf('=');
-    if (eq === -1) {
-      out[decodeURIComponent(pair)] = '';
-    } else {
-      out[decodeURIComponent(pair.slice(0, eq))] = decodeURIComponent(
-        pair.slice(eq + 1),
-      );
-    }
-  }
-  return out;
-}
-
-/**
- * Parse a `xema://` deeplink string into a typed, discriminated
- * {@link ParsedDeeplink}. Throws {@link DeeplinkParseError} on any
- * malformed input — never returns null, never coerces.
- */
-export function parseDeeplink(raw: string): ParsedDeeplink {
-  if (typeof raw !== 'string' || !raw.startsWith(DEEPLINK_SCHEME)) {
-    throw new DeeplinkParseError(
-      String(raw),
-      `must start with "${DEEPLINK_SCHEME}"`,
-    );
-  }
-  const afterScheme = raw.slice(DEEPLINK_SCHEME.length);
-  if (afterScheme.length === 0) {
-    throw new DeeplinkParseError(raw, 'empty body after scheme');
-  }
-
-  const qIndex = afterScheme.indexOf('?');
-  const path = qIndex === -1 ? afterScheme : afterScheme.slice(0, qIndex);
-  const search = qIndex === -1 ? '' : afterScheme.slice(qIndex + 1);
-  const segments = path.split('/').filter((s) => s.length > 0);
-
-  const head = segments[0];
-  if (head === undefined) {
-    throw new DeeplinkParseError(raw, 'missing target-kind head segment');
-  }
-
-  switch (head) {
-    case DeeplinkTargetKind.BiomeRoute: {
-      const biomeId = segments[1];
-      if (biomeId === undefined) {
-        throw new DeeplinkParseError(raw, 'biome deeplink missing <biomeId>');
-      }
-      const routeSegments = segments.slice(2);
-      const route = `/${routeSegments.join('/')}`;
-      return {
-        kind: DeeplinkTargetKind.BiomeRoute,
-        biomeId,
-        route,
-        ctx: parseQuery(search),
-      };
-    }
-    case DeeplinkTargetKind.Object: {
-      const body = segments.slice(1).join('/');
-      if (body.length === 0) {
-        throw new DeeplinkParseError(
-          raw,
-          'object deeplink missing <XemaObjectRef>',
-        );
-      }
-      return {
-        kind: DeeplinkTargetKind.Object,
-        objectRef: `${DEEPLINK_SCHEME}${body}`,
-      };
-    }
-    case DeeplinkTargetKind.Capability: {
-      const capabilityRef = segments.slice(1).join('/');
-      if (capabilityRef.length === 0) {
-        throw new DeeplinkParseError(
-          raw,
-          'capability deeplink missing <capability-ref>',
-        );
-      }
-      return {
-        kind: DeeplinkTargetKind.Capability,
-        capabilityRef,
-        input: parseQuery(search),
-      };
-    }
-    case DeeplinkTargetKind.Window: {
-      const windowId = segments[1];
-      if (windowId === undefined) {
-        throw new DeeplinkParseError(raw, 'window deeplink missing <windowId>');
-      }
-      return { kind: DeeplinkTargetKind.Window, windowId };
-    }
-    default:
-      throw new DeeplinkParseError(
-        raw,
-        `unknown deeplink target kind "${head}" (expected one of: ${Object.values(
-          DeeplinkTargetKind,
-        ).join(', ')})`,
-      );
-  }
-}
-
-/**
- * The `deeplink` surface of the SystemBus. `parse` is pure
- * (framework-agnostic) and re-exported from the runtime as
- * {@link parseDeeplink}. `resolve` navigates the running shell to the
- * parsed target; the host supplies the concrete navigation. Resolution
- * is orchestration only — for a capability target the actual auth check
- * happens when `capability.invoke` reaches the backend router.
- */
-export interface DeeplinkBus {
-  /** Parse a `xema://` deeplink string. Throws on malformed input. */
-  parse(raw: string): ParsedDeeplink;
-  /**
-   * Navigate the running shell to the deeplink target. The host
-   * implements the actual navigation (biome route push, object detail
-   * open, capability launch, window focus). Rejects if the target cannot
-   * be resolved (e.g. unknown biome / window) — fail-fast, no silent
-   * no-op.
-   */
-  resolve(target: string | ParsedDeeplink): Promise<void>;
-}