@cleocode/contracts 2026.6.11 → 2026.6.13

package/dist/llm/sealed-credential.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Sealed credential handle — the E10 on-demand-decrypt contract (T11752).
+ *
+ * ## Why a sealed handle exists
+ *
+ * Until E10, a resolved credential carried the secret **inline** as a bare
+ * `apiKey: string` field on `CredentialResultWire` / `ResolvedLLM`. That
+ * plaintext token traveled up the entire resolution call stack — through
+ * `resolveLLMForRole` → `resolveLLMForSystem` → consumers — where it could be
+ * accidentally logged, serialized into a LAFS envelope, or copied into a
+ * diagnostic. Every layer that merely *routed* the credential to the wire still
+ * had structural read access to the plaintext.
+ *
+ * A {@link SealedCredential} inverts that. The resolver returns an **opaque
+ * handle** that names the credential (`provider` + `account`) and exposes a
+ * single asynchronous {@link SealedCredential.fetch} method. The plaintext token
+ * is materialized ONLY when `fetch()` is invoked — and by E10 design that call
+ * happens at exactly two trust boundaries:
+ *
+ *  1. the wire — `transportForProvider` / `session-factory.ts` immediately
+ *     before building the provider transport / auth headers, or
+ *  2. daemon worker-injection — the daemon brokering a short-lived credential
+ *     into a spawned agent.
+ *
+ * Between the resolver and those boundaries, NO layer holds a plaintext secret;
+ * it holds a handle whose `fetch()` is the sole decryption chokepoint.
+ *
+ * ## Types-only (Gate 10 contracts purity)
+ *
+ * This module is **types-only**. {@link SealedCredential.fetch} is a
+ * *function-typed field* on an interface — a declaration of shape, NOT a bodied
+ * runtime function — so it satisfies the contracts-purity gate
+ * (`lint-no-runtime-in-contracts`). The concrete implementation of `fetch()`
+ * (the actual `crypto/credentials.ts` decrypt + the vault/daemon round-trip)
+ * lives in `@cleocode/core` — never in contracts.
+ *
+ * @module llm/sealed-credential
+ * @task T11752
+ * @epic T11746
+ * @see ADR-072 §Type lock-in
+ */
+import type { ProviderId } from './provider-id.js';
+/**
+ * The plaintext secret materialized by {@link SealedCredential.fetch}.
+ *
+ * ## Branded so it cannot be silently created or widened
+ *
+ * `DecryptedToken` is a *branded* string: an opaque nominal type produced ONLY
+ * by the core decrypt chokepoint inside {@link SealedCredential.fetch}. The
+ * `readonly __decryptedToken` brand is a phantom marker — it is NEVER assigned a
+ * runtime value (there is no runtime field; this is purely a compile-time
+ * nominal tag), so a plain `string` cannot be passed where a `DecryptedToken`
+ * is expected, and a `DecryptedToken` is not assignable to an arbitrary
+ * `string` sink without an explicit, auditable read of `.value`.
+ *
+ * ## NEVER serialized
+ *
+ * A `DecryptedToken` MUST NEVER be:
+ *   - returned up the resolver call stack (it exists only transiently inside
+ *     the `fetch()` consumer at the wire / daemon worker-injection boundary),
+ *   - placed on any envelope, `NormalizedResponse.providerData`, log line,
+ *     diagnostic, or `cleo llm whoami` output,
+ *   - persisted, cached across calls, or held beyond the single transport
+ *     construction / auth-header build that consumed it.
+ *
+ * The CI chokepoint lint (`lint-llm-chokepoint`) plus the E10 redaction tests
+ * (T11754) enforce that no bare secret string crosses the resolver boundary.
+ *
+ * Because the brand is phantom (compile-time only) and there is no enumerable
+ * runtime field, `JSON.stringify(token)` over the value field yields only the
+ * underlying string — which is precisely why callers MUST treat the value as
+ * write-once-to-the-wire and never route it into a serializer.
+ *
+ * @task T11752
+ */
+export type DecryptedToken = {
+    /**
+     * Phantom brand marker — compile-time only, never materialized at runtime.
+     * Prevents a plain `string` from being assigned where a {@link DecryptedToken}
+     * is required (nominal typing). Reading this field is meaningless at runtime;
+     * it exists solely to make the type opaque.
+     *
+     * @internal
+     */
+    readonly __decryptedToken: 'DecryptedToken';
+    /**
+     * The materialized plaintext secret (API key or OAuth bearer token).
+     *
+     * SECURITY: read this ONLY at the wire (`transportForProvider`) or daemon
+     * worker-injection, build the auth header, and discard. NEVER log, serialize,
+     * or return it up the stack. Marked `readonly` so a consumer cannot mutate it
+     * in place.
+     */
+    readonly value: string;
+};
+/**
+ * An opaque, sealed reference to a credential whose plaintext is fetched on
+ * demand at the wire — never carried inline up the resolver stack.
+ *
+ * The resolver returns this *instead of* a bare `apiKey: string` (E10 ·
+ * T11753). Consumers route the handle to the transport boundary unchanged;
+ * only the boundary calls {@link fetch} to materialize the
+ * {@link DecryptedToken}, build the provider auth headers, and discard the
+ * plaintext.
+ *
+ * @example
+ * ```ts
+ * // At the wire boundary (session-factory.ts) — the ONLY place fetch() runs.
+ * // Prefer `authHeadersFromSealed` (core), which invokes fetch() internally so
+ * // the plaintext is never bound to a caller-visible variable:
+ * const headers = await authHeadersFromSealed(sealed, authType);
+ * // …or, for diagnostics, name the credential WITHOUT materializing it:
+ * log.info({ provider: sealed.provider, preview: sealed.tokenPreview });
+ * // The full token is NEVER returned, logged, or serialized.
+ * ```
+ *
+ * @task T11752
+ */
+export interface SealedCredential {
+    /** Provider this credential targets (e.g. `'anthropic'`, `'openai'`). */
+    readonly provider: ProviderId;
+    /**
+     * Account / store-label identifier this handle resolves against (e.g.
+     * `'default'`, `'work'`). Names *which* credential the handle points at
+     * without revealing its secret — safe to log and serialize.
+     */
+    readonly account: string;
+    /**
+     * Non-secret, redacted preview of the underlying credential (e.g. `'…6789'`
+     * or `'oat-…6789'` for OAuth). The SOLE token-derived value safe to place on
+     * a log line, LAFS envelope, or `cleo llm whoami` diagnostic.
+     *
+     * SECURITY: this is computed ONCE at seal time from at most the last 4 token
+     * characters via the core redaction chokepoint (`tokenPreviewOf`) — it can
+     * never be reversed into the plaintext. Diagnostics that need to *name* a
+     * credential without materializing it MUST read this field, never call
+     * {@link fetch}. The E10 redaction test (T11754 · AC3) asserts that the
+     * preview, not the full token, is the only credential-derived string that
+     * crosses any logging/diagnostic boundary.
+     *
+     * @task T11754
+     */
+    readonly tokenPreview: string;
+    /**
+     * Materialize the plaintext secret on demand.
+     *
+     * SECURITY INVARIANT: the returned {@link DecryptedToken} is the ONLY point
+     * at which the secret exists in plaintext. Implementations (in
+     * `@cleocode/core`) run the `crypto/credentials.ts` decrypt INSIDE this
+     * method and MUST be invoked ONLY at the wire (`transportForProvider` /
+     * `session-factory.ts`) or daemon worker-injection — never to surface a key
+     * up the resolution stack. The result MUST NOT be cached, persisted, logged,
+     * or serialized by any caller.
+     *
+     * This is a *function-typed field on an interface* (a type, not a bodied
+     * function), so the declaration is contracts-purity-safe (Gate 10): the body
+     * lives in core.
+     *
+     * @returns The materialized plaintext token, valid only for immediate
+     *   wire/daemon use.
+     */
+    readonly fetch: () => Promise<DecryptedToken>;
+}
+//# sourceMappingURL=sealed-credential.d.ts.map

package/dist/llm/sealed-credential.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sealed-credential.d.ts","sourceRoot":"","sources":["../../src/llm/sealed-credential.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;;;;;;OAOG;IACH,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IAC5C;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,cAAc,CAAC,CAAC;CAC/C"}

package/dist/llm/sealed-credential.js

@@ -0,0 +1,43 @@
+/**
+ * Sealed credential handle — the E10 on-demand-decrypt contract (T11752).
+ *
+ * ## Why a sealed handle exists
+ *
+ * Until E10, a resolved credential carried the secret **inline** as a bare
+ * `apiKey: string` field on `CredentialResultWire` / `ResolvedLLM`. That
+ * plaintext token traveled up the entire resolution call stack — through
+ * `resolveLLMForRole` → `resolveLLMForSystem` → consumers — where it could be
+ * accidentally logged, serialized into a LAFS envelope, or copied into a
+ * diagnostic. Every layer that merely *routed* the credential to the wire still
+ * had structural read access to the plaintext.
+ *
+ * A {@link SealedCredential} inverts that. The resolver returns an **opaque
+ * handle** that names the credential (`provider` + `account`) and exposes a
+ * single asynchronous {@link SealedCredential.fetch} method. The plaintext token
+ * is materialized ONLY when `fetch()` is invoked — and by E10 design that call
+ * happens at exactly two trust boundaries:
+ *
+ *  1. the wire — `transportForProvider` / `session-factory.ts` immediately
+ *     before building the provider transport / auth headers, or
+ *  2. daemon worker-injection — the daemon brokering a short-lived credential
+ *     into a spawned agent.
+ *
+ * Between the resolver and those boundaries, NO layer holds a plaintext secret;
+ * it holds a handle whose `fetch()` is the sole decryption chokepoint.
+ *
+ * ## Types-only (Gate 10 contracts purity)
+ *
+ * This module is **types-only**. {@link SealedCredential.fetch} is a
+ * *function-typed field* on an interface — a declaration of shape, NOT a bodied
+ * runtime function — so it satisfies the contracts-purity gate
+ * (`lint-no-runtime-in-contracts`). The concrete implementation of `fetch()`
+ * (the actual `crypto/credentials.ts` decrypt + the vault/daemon round-trip)
+ * lives in `@cleocode/core` — never in contracts.
+ *
+ * @module llm/sealed-credential
+ * @task T11752
+ * @epic T11746
+ * @see ADR-072 §Type lock-in
+ */
+export {};
+//# sourceMappingURL=sealed-credential.js.map

package/dist/llm/sealed-credential.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sealed-credential.js","sourceRoot":"","sources":["../../src/llm/sealed-credential.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG"}

package/dist/llm/system-of-use.d.ts

@@ -0,0 +1,383 @@
+/**
+ * `SystemOfUse` taxonomy — the structured identity of every CLEO subsystem that
+ * may request an LLM through the E9 chokepoint (`resolveLLMForSystem`).
+ *
+ * ## Why a discriminated descriptor (the hermes `_AUX_TASKS` analog)
+ *
+ * The first cut of the E9 chokepoint (T11749) accepted a flat string-literal
+ * label ({@link SystemOfUseLabel} — `'sentient' | 'memory' | …`). That covered
+ * the seven role-mapped background subsystems but had no room for the OTHER
+ * axes CLEO routes LLMs along:
+ *
+ *   - **orchestration tiers** (`frontier`/`standard`/`fast`/`local`) — the
+ *     capability lane a delegated turn runs in, independent of any role;
+ *   - **tools / skills** — atomic tool primitives and `ct-*` skills that each
+ *     may pin a model (the hermes `_AUX_TASKS` registry: one entry per named
+ *     auxiliary task, each with its own provider/model binding);
+ *   - **cantbook nodes** — per-node model selection inside a `.cantbook` flow;
+ *   - **spawn units** — orchestrator-spawned worker agents that resolve their
+ *     own LLM.
+ *
+ * `SystemOfUse` is the discriminated `{ kind, id }` descriptor that unifies all
+ * of these axes under ONE identity type. {@link BUILTIN_SYSTEMS_OF_USE} is the
+ * static registry of the well-known systems (orchestration tiers + the seven
+ * {@link RoleName}s + the auxiliary systems); `tool:` / `skill:` / `cantbook:` /
+ * `spawn-unit:` keys are OPEN — any runtime id is a valid `SystemOfUse` of the
+ * corresponding kind without a registry edit (see {@link OPEN_SYSTEM_KEY_PREFIXES}).
+ *
+ * ## Relationship to the resolver input
+ *
+ * This descriptor is the *taxonomy / identity* layer. The E9 resolver
+ * (`resolveLLMForSystem`) still accepts the ergonomic flat {@link SystemOfUseLabel}
+ * for the seven role-mapped background subsystems (its locked contract); this
+ * file is the SSoT that label set is derived against ({@link AUX_SYSTEM_IDS}),
+ * and the home of the richer descriptor that profile-axis routing (tiers,
+ * tools, skills, cantbook nodes, spawn units) keys off.
+ *
+ * Contracts-purity: this module is **types + `as const` DATA + type guards**
+ * only — no runtime logic (Gate 10 · T11418). The runtime encode/decode for the
+ * open-axis string keys (`parseSystemKey` / `formatSystemKey`) is intentionally
+ * NOT defined here; it lives in `@cleocode/core` so this package stays type-only
+ * (this module exposes only the {@link OPEN_SYSTEM_KEY_PREFIXES} DATA those
+ * helpers read).
+ *
+ * @module llm/system-of-use
+ * @task T11747
+ * @epic T11745
+ */
+import type { LlmProviderTransport, RoleName } from '../config.js';
+import type { ProviderTier } from './provider-profile.js';
+/**
+ * The axis a {@link SystemOfUse} belongs to — the discriminant of the
+ * descriptor union.
+ *
+ * | Kind            | Meaning                                                        | Registry        |
+ * |-----------------|----------------------------------------------------------------|-----------------|
+ * | `role`          | One of the seven background {@link RoleName}s.                  | closed (7)      |
+ * | `orchestration` | A capability tier lane (frontier/standard/fast/local).         | closed (4)      |
+ * | `aux`           | A named auxiliary subsystem (hermes `_AUX_TASKS` analog).      | closed (~10)    |
+ * | `tool`          | An atomic tool primitive that pins a model.                    | open (`tool:`)  |
+ * | `skill`         | A `ct-*` skill that pins a model.                              | open (`skill:`) |
+ * | `cantbook-node` | A node inside a `.cantbook` flow.                              | open (`cantbook:`) |
+ * | `spawn-unit`    | An orchestrator-spawned worker agent.                          | open (`spawn-unit:`) |
+ *
+ * @task T11747
+ */
+export type SystemOfUseKind = 'role' | 'orchestration' | 'aux' | 'tool' | 'skill' | 'cantbook-node' | 'spawn-unit';
+/**
+ * A subsystem whose identity is one of the seven background {@link RoleName}s.
+ *
+ * `id` is constrained to {@link RoleName} so the role axis can never drift from
+ * the config SSoT.
+ *
+ * @task T11747
+ */
+export interface RoleSystem {
+    readonly kind: 'role';
+    /** The canonical role name (config SSoT — {@link RoleName}). */
+    readonly id: RoleName;
+}
+/**
+ * A subsystem identified by an orchestration capability tier.
+ *
+ * `id` is a {@link ProviderTier} — the lane a delegated/orchestrated turn runs
+ * in (frontier flagship reasoning ↔ local on-device), independent of role.
+ *
+ * @task T11747
+ */
+export interface OrchestrationSystem {
+    readonly kind: 'orchestration';
+    /** Capability tier lane (see {@link ProviderTier}). */
+    readonly id: ProviderTier;
+}
+/**
+ * A named auxiliary subsystem — the direct analog of a hermes `_AUX_TASKS`
+ * entry. Each id (`sentient`, `memory`, `compression`, …) is a stable,
+ * code-referenced subsystem that may carry its own model binding.
+ *
+ * @task T11747
+ */
+export interface AuxSystem {
+    readonly kind: 'aux';
+    /** Stable auxiliary subsystem id (a member of {@link AUX_SYSTEM_IDS}). */
+    readonly id: AuxSystemId;
+}
+/**
+ * A tool primitive that resolves its own LLM. OPEN id — any atomic tool name is
+ * valid (encoded `tool:<name>`), so new tools need no registry edit.
+ *
+ * @task T11747
+ */
+export interface ToolSystem {
+    readonly kind: 'tool';
+    /** Atomic tool name (free-form runtime id). */
+    readonly id: string;
+}
+/**
+ * A `ct-*` skill that resolves its own LLM. OPEN id — encoded `skill:<name>`.
+ *
+ * @task T11747
+ */
+export interface SkillSystem {
+    readonly kind: 'skill';
+    /** Skill name (free-form runtime id). */
+    readonly id: string;
+}
+/**
+ * A node inside a `.cantbook` flow that resolves its own LLM. OPEN id — encoded
+ * `cantbook:<nodeId>`.
+ *
+ * @task T11747
+ */
+export interface CantbookNodeSystem {
+    readonly kind: 'cantbook-node';
+    /** Cantbook node id (free-form runtime id). */
+    readonly id: string;
+}
+/**
+ * An orchestrator-spawned worker agent that resolves its own LLM. OPEN id —
+ * encoded `spawn-unit:<taskId>` (typically the `T####` it executes).
+ *
+ * @task T11747
+ */
+export interface SpawnUnitSystem {
+    readonly kind: 'spawn-unit';
+    /** Spawn-unit id, typically the executing task id (free-form runtime id). */
+    readonly id: string;
+}
+/**
+ * The discriminated `{ kind, id }` identity of any CLEO subsystem that requests
+ * an LLM through the E9 chokepoint.
+ *
+ * Discriminate on {@link SystemOfUseKind} (`system.kind`) to narrow `id` to the
+ * axis-specific type. Closed-axis kinds (`role`/`orchestration`/`aux`) carry a
+ * typed id; open-axis kinds (`tool`/`skill`/`cantbook-node`/`spawn-unit`) carry
+ * a free-form runtime string.
+ *
+ * @example
+ * ```ts
+ * const sys: SystemOfUse = { kind: 'tool', id: 'web-search' };
+ * if (sys.kind === 'role') {
+ *   // sys.id is narrowed to RoleName here
+ * }
+ * ```
+ *
+ * @task T11747
+ * @epic T11745
+ */
+export type SystemOfUse = RoleSystem | OrchestrationSystem | AuxSystem | ToolSystem | SkillSystem | CantbookNodeSystem | SpawnUnitSystem;
+/**
+ * Value-level SSoT for the seven {@link RoleName}s.
+ *
+ * The `RoleName` *type* lives in `config.ts`; this `as const` tuple is the
+ * single iterable VALUE mirror used to build the registry (and any other
+ * `for (const role of ROLE_SYSTEM_IDS)` loop) so the role axis is enumerated
+ * from ONE place. A compile-time `satisfies readonly RoleName[]` keeps it
+ * locked to the type — adding a role to `RoleName` without extending this tuple
+ * is a type error.
+ *
+ * @task T11747
+ */
+export declare const ROLE_SYSTEM_IDS: readonly ["extraction", "consolidation", "derivation", "hygiene", "judgement", "plugin", "compression"];
+/**
+ * Value-level SSoT for the user-facing, *enumerable* background {@link RoleName}s
+ * — the set `cleo llm whoami` reports and `cleo llm profile` accepts.
+ *
+ * This is the proper subset of {@link ROLE_SYSTEM_IDS} that excludes the two
+ * internal sandbox/utility roles (`plugin`, `compression`): they are resolved
+ * by code paths (plugin-scoped single-turn calls, context compression) rather
+ * than configured per-call by users, so they are intentionally NOT enumerated
+ * by the `whoami` / `profile` CLI surface.
+ *
+ * Sourcing the `cli-ops.ts` role list from THIS one tuple (instead of a
+ * duplicated inline array) is the AC3 "ALL_ROLES from one SSoT" requirement
+ * (T11750): the type-checker's `satisfies readonly RoleName[]` keeps every id
+ * locked to {@link RoleName}, so the enumerable set can never silently drift
+ * from the config vocabulary.
+ *
+ * @task T11750
+ * @epic T11745
+ */
+export declare const WHOAMI_ROLE_IDS: readonly ["extraction", "consolidation", "derivation", "hygiene", "judgement"];
+/**
+ * The id of a `whoami`-enumerable role — the element type of
+ * {@link WHOAMI_ROLE_IDS}.
+ *
+ * @task T11750
+ */
+export type WhoamiRoleId = (typeof WHOAMI_ROLE_IDS)[number];
+/**
+ * Value-level SSoT for the four orchestration capability tiers. Mirrors the
+ * {@link ProviderTier} type, most→least capable.
+ *
+ * @task T11747
+ */
+export declare const ORCHESTRATION_TIER_IDS: readonly ["frontier", "standard", "fast", "local"];
+/**
+ * Value-level SSoT for the auxiliary subsystem ids (the hermes `_AUX_TASKS`
+ * key set). These are the stable, code-referenced background subsystems CLEO
+ * resolves an LLM for outside the role/tier/tool axes.
+ *
+ * The seven role-mapped resolver labels in {@link SystemOfUseLabel} are derived
+ * from this set plus `default` — keeping the flat resolver vocabulary and the
+ * structured taxonomy in lock-step.
+ *
+ * @task T11747
+ */
+export declare const AUX_SYSTEM_IDS: readonly ["sentient", "memory", "task-executor", "deriver", "hygiene", "plugin", "compression", "decision-validator", "title-generation", "embedding"];
+/**
+ * The id of a registered auxiliary subsystem — the element type of
+ * {@link AUX_SYSTEM_IDS}.
+ *
+ * @task T11747
+ */
+export type AuxSystemId = (typeof AUX_SYSTEM_IDS)[number];
+/**
+ * The four OPEN {@link SystemOfUseKind}s and the string-key prefix each is
+ * encoded with for transport across string-only boundaries (config keys, CLI
+ * args, audit logs). E.g. `{ kind: 'tool', id: 'web-search' }` ↔ `'tool:web-search'`.
+ *
+ * Declared as DATA so encode/decode never branches on a hardcoded prefix —
+ * `@cleocode/core` reads this map (Gate 10 keeps the runtime split out).
+ *
+ * @task T11747
+ */
+export declare const OPEN_SYSTEM_KEY_PREFIXES: {
+    readonly tool: "tool:";
+    readonly skill: "skill:";
+    readonly 'cantbook-node': "cantbook:";
+    readonly 'spawn-unit': "spawn-unit:";
+};
+/**
+ * The subset of {@link SystemOfUseKind} whose ids are OPEN (any runtime string),
+ * encoded via {@link OPEN_SYSTEM_KEY_PREFIXES}.
+ *
+ * @task T11747
+ */
+export type OpenSystemKind = 'tool' | 'skill' | 'cantbook-node' | 'spawn-unit';
+/**
+ * Static registry of every well-known (closed-axis) {@link SystemOfUse}: the
+ * four orchestration tiers, the seven {@link RoleName}s, and the ~10 auxiliary
+ * subsystems — the hermes `_AUX_TASKS` analog as a single typed table.
+ *
+ * Open-axis systems (`tool:`/`skill:`/`cantbook:`/`spawn-unit:`) are NOT listed
+ * here — they are valid without a registry edit (see {@link OPEN_SYSTEM_KEY_PREFIXES}).
+ *
+ * Built by spreading the three closed-axis value SSoTs so the registry can
+ * never drift from {@link ROLE_SYSTEM_IDS} / {@link ORCHESTRATION_TIER_IDS} /
+ * {@link AUX_SYSTEM_IDS}.
+ *
+ * @task T11747
+ * @epic T11745
+ */
+export declare const BUILTIN_SYSTEMS_OF_USE: readonly (RoleSystem | OrchestrationSystem | AuxSystem)[];
+/**
+ * Type guard: is `value` a {@link SystemOfUse} descriptor (a `{ kind, id }`
+ * object whose `kind` is a known {@link SystemOfUseKind})?
+ *
+ * Structural-only — does NOT assert that closed-axis ids are registered (use
+ * {@link isBuiltinSystemOfUse} for that); an open-axis or as-yet-unregistered
+ * id still passes.
+ *
+ * @param value - The candidate value.
+ * @returns `true` when `value` is shaped like a {@link SystemOfUse}.
+ * @task T11747
+ */
+export declare function isSystemOfUse(value: unknown): value is SystemOfUse;
+/**
+ * Type guard: is `value` a closed-axis {@link SystemOfUse} present in
+ * {@link BUILTIN_SYSTEMS_OF_USE} (an exact `kind`+`id` match)?
+ *
+ * @param value - The candidate value.
+ * @returns `true` when `value` is a registered builtin system-of-use.
+ * @task T11747
+ */
+export declare function isBuiltinSystemOfUse(value: unknown): value is SystemOfUse;
+/**
+ * Type guard: is `kind` an OPEN-axis {@link OpenSystemKind} (one whose ids are
+ * encoded with an {@link OPEN_SYSTEM_KEY_PREFIXES} prefix)?
+ *
+ * @param kind - The kind discriminant to test.
+ * @returns `true` for `tool` / `skill` / `cantbook-node` / `spawn-unit`.
+ * @task T11747
+ */
+export declare function isOpenSystemKind(kind: SystemOfUseKind): kind is OpenSystemKind;
+/**
+ * The default provider/model binding a runtime-registered {@link SystemOfUse}
+ * advertises (T11751 · AC1).
+ *
+ * `registerSystemOfUse(key, displayName, defaults)` lets a plugin / extension /
+ * downstream package declare a NEW system-of-use without a registry edit and
+ * give it a default binding. That default is consulted strictly BELOW user
+ * config (`llm.systems[key]` / `llm.default` / `llm.defaultProfile`) so the user
+ * always wins — it only supplies a binding when the user has configured nothing
+ * for that key.
+ *
+ * Either `profile` (a key of `LlmConfig.profiles`) OR an inline `provider` +
+ * `model` tuple supplies the binding; `profile` wins when both are present. An
+ * entry that supplies neither a resolvable `profile` nor a complete
+ * `provider`+`model` tuple is structurally incomplete and is skipped at
+ * resolution time (the chain falls through to implicit-fallback) — never an
+ * error.
+ *
+ * @task T11751
+ * @epic T11745
+ */
+export interface SystemOfUseDefaults {
+    /**
+     * Optional reference to a named profile in `LlmConfig.profiles`. When set and
+     * resolvable, the named profile's provider/model/credentialLabel win over this
+     * entry's inline tuple.
+     */
+    readonly profile?: string;
+    /** Inline LLM provider transport (used when `profile` is absent/unresolvable). */
+    readonly provider?: LlmProviderTransport;
+    /** Inline full model identifier (used when `profile` is absent/unresolvable). */
+    readonly model?: string;
+    /**
+     * Optional credential label pinning this default to a specific credential pool
+     * entry. When omitted, standard priority-based credential resolution applies.
+     */
+    readonly credentialLabel?: string;
+}
+/**
+ * A runtime-registered system-of-use — the merged record surfaced by the
+ * profile-picker enumeration (T11751 · AC2).
+ *
+ * @task T11751
+ * @epic T11745
+ */
+export interface RegisteredSystemOfUse {
+    /** Encoded system-of-use key (e.g. `'sentient'`, `'tool:web-search'`). */
+    readonly key: string;
+    /** Human-readable display name for the picker surface. */
+    readonly displayName: string;
+    /** Default binding consulted strictly below user config (user wins). */
+    readonly defaults: SystemOfUseDefaults;
+}
+/**
+ * One enumerated entry in the merged profile-picker surface (T11751 · AC2).
+ *
+ * Combines the structured {@link SystemOfUse} identity with its display name and
+ * provenance so the TUI/Studio picker can render every well-known builtin AND
+ * every runtime-registered system in one list.
+ *
+ * @task T11751
+ * @epic T11745
+ */
+export interface SystemOfUsePickerEntry {
+    /** Encoded system-of-use key (the picker value). */
+    readonly key: string;
+    /** Human-readable display name. */
+    readonly displayName: string;
+    /** Discriminant axis of this system (see {@link SystemOfUseKind}). */
+    readonly kind: SystemOfUseKind;
+    /** Where this entry came from: a static builtin or a runtime registration. */
+    readonly source: 'builtin' | 'registered';
+    /**
+     * The default binding when `source === 'registered'`. Absent for builtins
+     * (their binding is resolved purely from user config + the role/aux mapping).
+     */
+    readonly defaults?: SystemOfUseDefaults;
+}
+//# sourceMappingURL=system-of-use.d.ts.map

package/dist/llm/system-of-use.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-of-use.d.ts","sourceRoot":"","sources":["../../src/llm/system-of-use.ts"],"names":[],"mappings":"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"}