@cleocode/core 2026.6.12 → 2026.6.13

package/dist/llm/sealed-credential.js

@@ -0,0 +1,133 @@
+/**
+ * Sealed credential handle — runtime implementation (E10 · T11753).
+ *
+ * The {@link SealedCredential} **type** lives in `@cleocode/contracts`
+ * (`llm/sealed-credential.ts`, types-only for Gate 10 purity). Its `fetch()` is
+ * a function-TYPED interface field; the concrete body — the on-demand
+ * materialization of the plaintext token — lives HERE in `@cleocode/core`.
+ *
+ * ## Why this module exists
+ *
+ * Before E10, {@link import('./role-resolver.js').resolveLLMForRole} returned
+ * the resolved credential's plaintext `apiKey` **inline** on its envelope. That
+ * bare secret string travelled up the entire resolution call stack
+ * (`resolveLLMForRole` → `resolveLLMForSystem` → consumers) where any layer that
+ * merely *routed* it to the wire could accidentally log it, serialize it into a
+ * LAFS envelope, or copy it into a diagnostic.
+ *
+ * {@link makeSealedCredential} inverts that. The resolver builds an opaque
+ * {@link SealedCredential} handle whose `fetch()` closure captures a
+ * `resolveToken` thunk. The plaintext is materialized **only** when a wire
+ * boundary (`transportForProvider` / `session-factory.ts`) or daemon
+ * worker-injection invokes `fetch()`. Between the resolver and those boundaries,
+ * NO layer holds a plaintext secret — it holds a handle.
+ *
+ * ## The brand chokepoint
+ *
+ * {@link brandDecryptedToken} is the SOLE place a {@link DecryptedToken} is
+ * minted from a raw string. Because `DecryptedToken` is a phantom-branded type
+ * (contracts), a plain `string` cannot be widened into one anywhere else — so an
+ * audit of "who mints a token" reduces to "who calls `brandDecryptedToken`",
+ * and that is exclusively this module (invoked inside `fetch()`).
+ *
+ * @module llm/sealed-credential
+ * @task T11753
+ * @epic T11746
+ * @see ADR-072 §Type lock-in
+ */
+/**
+ * Build the non-secret, redacted preview of a credential string.
+ *
+ * SECURITY: this is the SOLE token→preview redaction chokepoint for the sealed
+ * handle. It reveals at most the last 4 characters of the token plus an
+ * auth-scheme marker (`oat-…` for OAuth, `…` otherwise) — never enough to
+ * reconstruct the secret. It is computed ONCE at seal time and stored on the
+ * handle's {@link SealedCredential.tokenPreview}; the full plaintext is NOT
+ * retained for it.
+ *
+ * The preview is the ONLY credential-derived string that may cross a
+ * logging/diagnostic/envelope boundary (E10 · T11754 · AC3); everything else
+ * goes through {@link SealedCredential.fetch} at the wire and is discarded.
+ *
+ * @param token - The plaintext secret (read transiently; not retained).
+ * @param authType - Auth scheme, used only to pick the cosmetic prefix.
+ * @returns A redacted preview safe to log and serialize.
+ * @task T11754
+ */
+export function tokenPreview(token, authType) {
+    const prefix = authType === 'oauth' ? 'oat-…' : '…';
+    if (!token)
+        return prefix;
+    if (token.length <= 4)
+        return `${prefix}${token}`;
+    return `${prefix}${token.slice(-4)}`;
+}
+/**
+ * Mint a {@link DecryptedToken} from a raw plaintext secret.
+ *
+ * SECURITY: this is the ONE chokepoint that produces a branded
+ * {@link DecryptedToken}. It MUST be called only from inside a
+ * {@link SealedCredential.fetch} closure (see {@link makeSealedCredential}) —
+ * i.e. at the wire / daemon worker-injection boundary — never to surface a
+ * plaintext up the resolver stack.
+ *
+ * The brand is phantom (compile-time only); at runtime this returns a frozen
+ * object `{ value }`. The `__decryptedToken` marker is never materialized at
+ * runtime — the cast below is the deliberate, single, audited point where a
+ * `string` becomes a `DecryptedToken`.
+ *
+ * @param value - The materialized plaintext secret (API key / OAuth bearer).
+ * @returns The branded token, valid only for immediate wire/daemon use.
+ * @internal
+ */
+function brandDecryptedToken(value) {
+    // The single, audited string→DecryptedToken mint. `Object.freeze` prevents a
+    // consumer from mutating `value` in place after fetch().
+    return Object.freeze({ value });
+}
+/**
+ * Build a {@link SealedCredential} handle from a provider/account and an
+ * on-demand token resolver.
+ *
+ * The returned handle carries ONLY the non-secret `provider` + `account`
+ * inline. Its `fetch()` closure captures {@link MakeSealedCredentialParams.resolveToken}
+ * and brands the result — the plaintext exists transiently inside `fetch()` and
+ * is NEVER attached to the handle object, so the handle can be logged or
+ * serialized without leaking the secret.
+ *
+ * @example
+ * ```ts
+ * // In the resolver — capture the already-resolved token in the closure but do
+ * // NOT place it on the returned envelope:
+ * const sealed = makeSealedCredential({
+ *   provider: 'anthropic',
+ *   account: usedLabel ?? 'default',
+ *   tokenPreview: tokenPreview(token, authType), // non-secret; safe to log
+ *   resolveToken: () => token, // captured, not surfaced
+ * });
+ * // At the wire — the ONLY place fetch() runs (via authHeadersFromSealed):
+ * const headers = await authHeadersFromSealed(sealed, authType);
+ * // the plaintext never escapes authHeadersFromSealed; only headers come out.
+ * ```
+ *
+ * @param params - Provider, account label, and the on-demand token resolver.
+ * @returns An opaque sealed-credential handle.
+ * @task T11753
+ */
+export function makeSealedCredential(params) {
+    const { provider, account, tokenPreview: preview, resolveToken } = params;
+    return {
+        provider,
+        account,
+        tokenPreview: preview,
+        fetch: async () => {
+            // The SOLE decrypt/materialize point. `resolveToken` re-obtains (or, in
+            // T11754, decrypts) the plaintext on demand; we brand it and hand it to
+            // the wire. The plaintext never escapes this closure except as the
+            // branded return value the caller is contractually bound to discard.
+            const plaintext = await resolveToken();
+            return brandDecryptedToken(plaintext);
+        },
+    };
+}
+//# 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAIH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,QAA6B;IACvE,MAAM,MAAM,GAAG,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;IACpD,IAAI,CAAC,KAAK;QAAE,OAAO,MAAM,CAAC;IAC1B,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC;QAAE,OAAO,GAAG,MAAM,GAAG,KAAK,EAAE,CAAC;IAClD,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACvC,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAS,mBAAmB,CAAC,KAAa;IACxC,6EAA6E;IAC7E,yDAAyD;IACzD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAmB,CAAC;AACpD,CAAC;AAuCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAkC;IACrE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,MAAM,CAAC;IAC1E,OAAO;QACL,QAAQ;QACR,OAAO;QACP,YAAY,EAAE,OAAO;QACrB,KAAK,EAAE,KAAK,IAA6B,EAAE;YACzC,wEAAwE;YACxE,wEAAwE;YACxE,mEAAmE;YACnE,qEAAqE;YACrE,MAAM,SAAS,GAAG,MAAM,YAAY,EAAE,CAAC;YACvC,OAAO,mBAAmB,CAAC,SAAS,CAAC,CAAC;QACxC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/llm/session-factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-factory.d.ts","sourceRoot":"","sources":["../../src/llm/session-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,iBAAiB,EACjB,WAAW,EACX,qBAAqB,EACtB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gDAAgD,CAAC;AACnF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wCAAwC,CAAC;AACtE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gDAAgD,CAAC;AAIzF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAMxD;;;;;;;;;;;;;;;;;GAiBG;AACH,iBAAS,oBAAoB,CAC3B,QAAQ,EAAE,cAAc,EACxB,UAAU,EAAE,kBAAkB,EAC9B,OAAO,CAAC,EAAE,OAAO,GAChB,YAAY,CAEd;AAuCD;;;;;;;;;;;;;GAaG;AACH,qBAAa,wBAAyB,YAAW,iBAAiB;IAChE,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAA0B;IAE9D;;;OAGG;gBACS,IAAI,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,WAAW,CAAA;KAAE;IAIhD;;;;;;;;;OASG;IACG,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAItD;;;;;;;;;;OAUG;IACG,MAAM,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,UAAU,CAAC;CA0C/D;AAMD;;;;;;GAMG;AACH,OAAO,EAAE,oBAAoB,IAAI,+BAA+B,EAAE,CAAC"}
+{"version":3,"file":"session-factory.d.ts","sourceRoot":"","sources":["../../src/llm/session-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,iBAAiB,EACjB,WAAW,EACX,qBAAqB,EACtB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gDAAgD,CAAC;AACnF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wCAAwC,CAAC;AACtE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gDAAgD,CAAC;AAIzF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAMxD;;;;;;;;;;;;;;;;;GAiBG;AACH,iBAAS,oBAAoB,CAC3B,QAAQ,EAAE,cAAc,EACxB,UAAU,EAAE,kBAAkB,EAC9B,OAAO,CAAC,EAAE,OAAO,GAChB,YAAY,CAEd;AAuCD;;;;;;;;;;;;;GAaG;AACH,qBAAa,wBAAyB,YAAW,iBAAiB;IAChE,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAA0B;IAE9D;;;OAGG;gBACS,IAAI,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,WAAW,CAAA;KAAE;IAIhD;;;;;;;;;OASG;IACG,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAItD;;;;;;;;;;OAUG;IACG,MAAM,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,UAAU,CAAC;CA8C/D;AAMD;;;;;;GAMG;AACH,OAAO,EAAE,oBAAoB,IAAI,+BAA+B,EAAE,CAAC"}

package/dist/llm/session-factory.js

@@ -118,12 +118,16 @@ export class DefaultLlmSessionFactory {
         }
         if (opts.role) {
             const resolved = await resolveLLMForRole(opts.role);
-            if (!resolved.credential?.apiKey) {
+            if (!resolved.sealedCredential || !resolved.credential) {
                 throw new Error(`No credential available for role '${opts.role}' / provider '${resolved.provider}'`);
             }
+            // E10 (T11753): materialize the plaintext from the sealed handle ONLY here,
+            // at the wire — `transportForProvider` is one of the two sanctioned decrypt
+            // boundaries. The token is wired into the transport and never surfaced.
+            const token = (await resolved.sealedCredential.fetch()).value;
             const resolvedCredential = credentialResultToResolved({
                 provider: resolved.provider,
-                apiKey: resolved.credential.apiKey,
+                apiKey: token,
                 authType: resolved.credential.authType,
                 label: resolved.credentialLabel,
             });

package/dist/llm/session-factory.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-factory.js","sourceRoot":"","sources":["../../src/llm/session-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAWH,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAGvD,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAS,oBAAoB,CAC3B,QAAwB,EACxB,UAA8B,EAC9B,OAAiB;IAEjB,OAAO,WAAW,CAAC,4BAA4B,CAAC,QAAQ,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;AACjF,CAAC;AAED,8EAA8E;AAC9E,6BAA6B;AAC7B,8EAA8E;AAE9E;;;;;;;;;GASG;AACH,SAAS,0BAA0B,CAAC,MAKnC;IACC,OAAO;QACL,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,SAAS;QAChC,KAAK,EAAE,MAAM,CAAC,MAAM;QACpB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,SAAS,EAAE,IAAI;QACf,YAAY,EAAE,IAAI;QAClB,YAAY,EAAE,EAAE;QAChB,OAAO,EAAE,IAAI;QACb,UAAU,EAAE,IAAI;KACjB,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,wBAAwB;IAClB,mBAAmB,CAA0B;IAE9D;;;OAGG;IACH,YAAY,IAAoC;QAC9C,IAAI,CAAC,mBAAmB,GAAG,IAAI,EAAE,WAAW,CAAC;IAC/C,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,aAAa,CAAC,IAAY;QAC9B,OAAO,IAAI,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,MAAM,CAAC,IAA2B;QACtC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACpD,MAAM,IAAI,KAAK,CACb,kFAAkF,CACnF,CAAC;QACJ,CAAC;QAED,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,MAAM,QAAQ,GAAG,MAAM,iBAAiB,CACtC,IAAI,CAAC,IAA+C,CACrD,CAAC;YAEF,IAAI,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC;gBACjC,MAAM,IAAI,KAAK,CACb,qCAAqC,IAAI,CAAC,IAAI,iBAAiB,QAAQ,CAAC,QAAQ,GAAG,CACpF,CAAC;YACJ,CAAC;YAED,MAAM,kBAAkB,GAAG,0BAA0B,CAAC;gBACpD,QAAQ,EAAE,QAAQ,CAAC,QAAQ;gBAC3B,MAAM,EAAE,QAAQ,CAAC,UAAU,CAAC,MAAM;gBAClC,QAAQ,EAAE,QAAQ,CAAC,UAAU,CAAC,QAAQ;gBACtC,KAAK,EAAE,QAAQ,CAAC,eAAe;aAChC,CAAC,CAAC;YAEH,MAAM,SAAS,GAAG,oBAAoB,CAAC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC,CAAC;YAE9E,OAAO,IAAI,eAAe,CAAC;gBACzB,SAAS;gBACT,KAAK,EAAE,QAAQ,CAAC,KAAK;gBACrB,UAAU,EAAE,kBAAkB;gBAC9B,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,mBAAmB;aAC1D,CAAC,CAAC;QACL,CAAC;QAED,iFAAiF;QACjF,mEAAmE;QACnE,MAAM,IAAI,KAAK,CACb,yFAAyF;YACvF,mFAAmF,CACtF,CAAC;IACJ,CAAC;CACF;AAED,8EAA8E;AAC9E,iCAAiC;AACjC,8EAA8E;AAE9E;;;;;;GAMG;AACH,OAAO,EAAE,oBAAoB,IAAI,+BAA+B,EAAE,CAAC"}
+{"version":3,"file":"session-factory.js","sourceRoot":"","sources":["../../src/llm/session-factory.ts"],"names":[],"mappings":"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"}

package/dist/llm/system-key.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Runtime encode/decode for {@link SystemOfUse} string keys (E9 · T11751).
+ *
+ * The structured `{ kind, id }` {@link SystemOfUse} descriptor must cross
+ * string-only boundaries (config keys under `llm.systems[...]`, CLI args, audit
+ * logs, the runtime registry in `system-of-use-registry.ts`). This module is the
+ * single canonical codec between the descriptor and its flat string form.
+ *
+ * Encoding rules (driven entirely by the {@link OPEN_SYSTEM_KEY_PREFIXES} DATA
+ * declared in `@cleocode/contracts`, so the prefix set never drifts):
+ *
+ *   - OPEN axes (`tool` / `skill` / `cantbook-node` / `spawn-unit`) →
+ *     `<prefix><id>` (e.g. `{ kind: 'tool', id: 'web-search' }` ↔ `'tool:web-search'`).
+ *   - CLOSED axes (`role` / `orchestration` / `aux`) → the bare `id`
+ *     (e.g. `{ kind: 'aux', id: 'sentient' }` ↔ `'sentient'`). The flat label
+ *     vocabulary the resolver already accepts (`SystemOfUseLabel`) IS the closed
+ *     `aux`/`role` id, so closed keys round-trip without a prefix.
+ *
+ * Contracts-purity (Gate 10): this runtime codec lives in `@cleocode/core`, NOT
+ * in the type-only contracts package — it only READS the
+ * {@link OPEN_SYSTEM_KEY_PREFIXES} data map.
+ *
+ * @module llm/system-key
+ * @task T11751
+ * @epic T11745
+ */
+import { type SystemOfUse, type SystemOfUseKind } from '@cleocode/contracts';
+/**
+ * Encode a structured {@link SystemOfUse} descriptor into its canonical string
+ * key (the form stored in `llm.systems[...]` and the runtime registry).
+ *
+ * Open-axis descriptors gain their {@link OPEN_SYSTEM_KEY_PREFIXES} prefix;
+ * closed-axis descriptors (`role` / `orchestration` / `aux`) encode to the bare
+ * `id` so they round-trip with the flat resolver label vocabulary.
+ *
+ * @param system - The descriptor to encode.
+ * @returns The canonical string key.
+ * @task T11751
+ */
+export declare function formatSystemKey(system: SystemOfUse): string;
+/**
+ * Decode an open-axis string key back into its {@link SystemOfUse} descriptor.
+ *
+ * Returns `undefined` for a bare key with NO recognised open prefix — such keys
+ * are closed-axis ids (`role` / `orchestration` / `aux`) whose `kind` cannot be
+ * inferred from the string alone (the same `'sentient'` is an `aux` id and a
+ * resolver label). Callers that need the closed-axis descriptor must consult the
+ * value SSoTs (`AUX_SYSTEM_IDS` / `ROLE_SYSTEM_IDS` / `ORCHESTRATION_TIER_IDS`).
+ *
+ * @param key - The string key to decode.
+ * @returns The open-axis descriptor, or `undefined` for an un-prefixed key.
+ * @task T11751
+ */
+export declare function parseSystemKey(key: string): SystemOfUse | undefined;
+/**
+ * The {@link SystemOfUseKind} a string key encodes, inferred from its prefix.
+ *
+ * Open-prefixed keys return their open kind; un-prefixed keys are reported as
+ * `'aux'` (the closed lane the flat resolver labels live in). Pure inspection —
+ * does not assert the id is registered.
+ *
+ * @param key - The string key to inspect.
+ * @returns The inferred kind.
+ * @task T11751
+ */
+export declare function systemKeyKind(key: string): SystemOfUseKind;
+//# sourceMappingURL=system-key.d.ts.map

package/dist/llm/system-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-key.d.ts","sourceRoot":"","sources":["../../src/llm/system-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAIL,KAAK,WAAW,EAChB,KAAK,eAAe,EACrB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAM3D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAUnE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAG1D"}

package/dist/llm/system-key.js

@@ -0,0 +1,87 @@
+/**
+ * Runtime encode/decode for {@link SystemOfUse} string keys (E9 · T11751).
+ *
+ * The structured `{ kind, id }` {@link SystemOfUse} descriptor must cross
+ * string-only boundaries (config keys under `llm.systems[...]`, CLI args, audit
+ * logs, the runtime registry in `system-of-use-registry.ts`). This module is the
+ * single canonical codec between the descriptor and its flat string form.
+ *
+ * Encoding rules (driven entirely by the {@link OPEN_SYSTEM_KEY_PREFIXES} DATA
+ * declared in `@cleocode/contracts`, so the prefix set never drifts):
+ *
+ *   - OPEN axes (`tool` / `skill` / `cantbook-node` / `spawn-unit`) →
+ *     `<prefix><id>` (e.g. `{ kind: 'tool', id: 'web-search' }` ↔ `'tool:web-search'`).
+ *   - CLOSED axes (`role` / `orchestration` / `aux`) → the bare `id`
+ *     (e.g. `{ kind: 'aux', id: 'sentient' }` ↔ `'sentient'`). The flat label
+ *     vocabulary the resolver already accepts (`SystemOfUseLabel`) IS the closed
+ *     `aux`/`role` id, so closed keys round-trip without a prefix.
+ *
+ * Contracts-purity (Gate 10): this runtime codec lives in `@cleocode/core`, NOT
+ * in the type-only contracts package — it only READS the
+ * {@link OPEN_SYSTEM_KEY_PREFIXES} data map.
+ *
+ * @module llm/system-key
+ * @task T11751
+ * @epic T11745
+ */
+import { isOpenSystemKind, OPEN_SYSTEM_KEY_PREFIXES, } from '@cleocode/contracts';
+/**
+ * Encode a structured {@link SystemOfUse} descriptor into its canonical string
+ * key (the form stored in `llm.systems[...]` and the runtime registry).
+ *
+ * Open-axis descriptors gain their {@link OPEN_SYSTEM_KEY_PREFIXES} prefix;
+ * closed-axis descriptors (`role` / `orchestration` / `aux`) encode to the bare
+ * `id` so they round-trip with the flat resolver label vocabulary.
+ *
+ * @param system - The descriptor to encode.
+ * @returns The canonical string key.
+ * @task T11751
+ */
+export function formatSystemKey(system) {
+    if (isOpenSystemKind(system.kind)) {
+        return `${OPEN_SYSTEM_KEY_PREFIXES[system.kind]}${system.id}`;
+    }
+    // Closed axes (role / orchestration / aux) encode to the bare id.
+    return system.id;
+}
+/**
+ * Decode an open-axis string key back into its {@link SystemOfUse} descriptor.
+ *
+ * Returns `undefined` for a bare key with NO recognised open prefix — such keys
+ * are closed-axis ids (`role` / `orchestration` / `aux`) whose `kind` cannot be
+ * inferred from the string alone (the same `'sentient'` is an `aux` id and a
+ * resolver label). Callers that need the closed-axis descriptor must consult the
+ * value SSoTs (`AUX_SYSTEM_IDS` / `ROLE_SYSTEM_IDS` / `ORCHESTRATION_TIER_IDS`).
+ *
+ * @param key - The string key to decode.
+ * @returns The open-axis descriptor, or `undefined` for an un-prefixed key.
+ * @task T11751
+ */
+export function parseSystemKey(key) {
+    for (const kind of Object.keys(OPEN_SYSTEM_KEY_PREFIXES)) {
+        const prefix = OPEN_SYSTEM_KEY_PREFIXES[kind];
+        if (key.startsWith(prefix)) {
+            const id = key.slice(prefix.length);
+            if (!id)
+                return undefined;
+            return { kind, id };
+        }
+    }
+    return undefined;
+}
+/**
+ * The {@link SystemOfUseKind} a string key encodes, inferred from its prefix.
+ *
+ * Open-prefixed keys return their open kind; un-prefixed keys are reported as
+ * `'aux'` (the closed lane the flat resolver labels live in). Pure inspection —
+ * does not assert the id is registered.
+ *
+ * @param key - The string key to inspect.
+ * @returns The inferred kind.
+ * @task T11751
+ */
+export function systemKeyKind(key) {
+    const parsed = parseSystemKey(key);
+    return parsed ? parsed.kind : 'aux';
+}
+//# sourceMappingURL=system-key.js.map

package/dist/llm/system-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-key.js","sourceRoot":"","sources":["../../src/llm/system-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EACL,gBAAgB,EAChB,wBAAwB,GAIzB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAAC,MAAmB;IACjD,IAAI,gBAAgB,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QAClC,OAAO,GAAG,wBAAwB,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,EAAE,EAAE,CAAC;IAChE,CAAC;IACD,kEAAkE;IAClE,OAAO,MAAM,CAAC,EAAE,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,wBAAwB,CAAqB,EAAE,CAAC;QAC7E,MAAM,MAAM,GAAG,wBAAwB,CAAC,IAAI,CAAC,CAAC;QAC9C,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,MAAM,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACpC,IAAI,CAAC,EAAE;gBAAE,OAAO,SAAS,CAAC;YAC1B,OAAO,EAAE,IAAI,EAAE,EAAE,EAAiB,CAAC;QACrC,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;IACnC,OAAO,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC;AACtC,CAAC"}

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

@@ -0,0 +1,119 @@
+/**
+ * `registerSystemOfUse` — runtime extension point for the E9 system-of-use
+ * taxonomy (T11751 · AC1).
+ *
+ * ## Why a runtime registry
+ *
+ * {@link BUILTIN_SYSTEMS_OF_USE} is the static, closed-axis registry of the
+ * well-known systems (orchestration tiers + roles + aux subsystems). Plugins,
+ * extensions, and downstream packages need to declare NEW systems-of-use (e.g.
+ * a `tool:my-search` or a bespoke `aux`-like subsystem) and give each a default
+ * provider/model binding — WITHOUT editing the contracts SSoT.
+ *
+ * `registerSystemOfUse(key, displayName, defaults)` adds such a system to a
+ * process-level registry. The registered default binding is consulted by the
+ * single E9 resolution chokepoint (`resolveLLMForSystem` → `resolveLLMForRole`)
+ * **strictly BELOW user config** — after `llm.systems[key]`, `llm.default`, and
+ * `llm.defaultProfile` — so the user ALWAYS wins (AC1). A registered default
+ * only supplies a binding when the user has configured nothing for that key.
+ *
+ * ## Import-time purity
+ *
+ * This module performs NO registration at import time — the registry starts
+ * empty and is populated only by explicit `registerSystemOfUse(...)` calls. It
+ * holds no I/O, no config reads, and no side effects on load (so importing it
+ * is always safe). It is the runtime half intentionally split out of the
+ * type-only `@cleocode/contracts` (Gate 10).
+ *
+ * @module llm/system-of-use-registry
+ * @task T11751
+ * @epic T11745
+ */
+import { type RegisteredSystemOfUse, type SystemOfUseDefaults, type SystemOfUseKind, type SystemOfUsePickerEntry } from '@cleocode/contracts';
+import { formatSystemKey } from './system-key.js';
+/**
+ * A registered system-of-use whose `defaults` carry neither a `profile` nor a
+ * complete `provider`+`model` tuple is structurally incomplete: it can declare
+ * presence in the picker but cannot supply a resolution binding. Such a default
+ * is skipped at resolution time (the chain falls through) — never an error.
+ *
+ * @param defaults - The candidate default binding.
+ * @returns `true` when the default can actually bind a provider/model.
+ * @task T11751
+ */
+export declare function isResolvableSystemDefault(defaults: SystemOfUseDefaults): boolean;
+/**
+ * Register a new system-of-use with a default provider/model binding (AC1).
+ *
+ * The registration is merged UNDER user config: the resolver consults
+ * `defaults` only when the user has configured nothing more specific for `key`
+ * (no `llm.systems[key]`, no `llm.default`, no `llm.defaultProfile`). Re-calling
+ * with the same `key` REPLACES the prior registration (last-write-wins) so a
+ * package can update its own default idempotently.
+ *
+ * `key` MAY be a flat label (e.g. `'sentient'`) or an open-axis encoded key
+ * (`'tool:web-search'`). Passing a structured `SystemOfUse` descriptor is also
+ * supported via {@link registerSystemOfUseDescriptor}.
+ *
+ * @param key         - Encoded system-of-use key (non-empty).
+ * @param displayName - Human-readable name for the picker surface (non-empty).
+ * @param defaults    - Default binding consulted strictly below user config.
+ * @returns The stored {@link RegisteredSystemOfUse} record.
+ * @throws {RangeError} When `key` or `displayName` is empty.
+ * @task T11751
+ * @epic T11745
+ */
+export declare function registerSystemOfUse(key: string, displayName: string, defaults: SystemOfUseDefaults): RegisteredSystemOfUse;
+/**
+ * Register a system-of-use from a structured {@link SystemOfUse} descriptor,
+ * encoding it to its canonical string key via {@link formatSystemKey}.
+ *
+ * Convenience wrapper over {@link registerSystemOfUse} for callers that already
+ * hold a `{ kind, id }` descriptor (e.g. plugin-declared tools/skills).
+ *
+ * @param system      - The structured descriptor to register.
+ * @param displayName - Human-readable name for the picker surface.
+ * @param defaults    - Default binding consulted strictly below user config.
+ * @returns The stored {@link RegisteredSystemOfUse} record.
+ * @task T11751
+ */
+export declare function registerSystemOfUseDescriptor(system: Parameters<typeof formatSystemKey>[0], displayName: string, defaults: SystemOfUseDefaults): RegisteredSystemOfUse;
+/**
+ * Look up the runtime-registered default binding for an encoded system key.
+ *
+ * Returns `undefined` when no system is registered under `key` OR when its
+ * default is structurally incomplete (so the resolver falls through). This is
+ * the read surface the E9 resolver calls AFTER exhausting all user-config tiers.
+ *
+ * @param key - Encoded system-of-use key (may be undefined — returns undefined).
+ * @returns The resolvable {@link SystemOfUseDefaults}, or `undefined`.
+ * @task T11751
+ */
+export declare function getRegisteredSystemDefault(key: string | undefined): SystemOfUseDefaults | undefined;
+/**
+ * Enumerate every system-of-use for the TUI / Studio profile picker (AC2):
+ * the static {@link BUILTIN_SYSTEMS_OF_USE} table followed by every
+ * runtime-registered system, de-duplicated by key (a registration for a builtin
+ * key overrides the builtin entry — "user/runtime wins" for the picker label).
+ *
+ * Each entry carries its encoded `key`, a `displayName`, the discriminant
+ * `kind`, and its `source` (`'builtin'` | `'registered'`) so the picker can
+ * render and group them. Registered entries also surface their `defaults`.
+ *
+ * @param kind - Optional kind filter — when set, only that axis is returned.
+ * @returns The merged, ordered picker entries.
+ * @task T11751
+ * @epic T11745
+ */
+export declare function listSystemsOfUse(kind?: SystemOfUseKind): SystemOfUsePickerEntry[];
+/**
+ * Clear all runtime registrations.
+ *
+ * Intended for test isolation — production code never needs to un-register a
+ * system. Builtins are unaffected (they live in the contracts SSoT, not here).
+ *
+ * @internal
+ * @task T11751
+ */
+export declare function clearRegisteredSystemsOfUse(): void;
+//# sourceMappingURL=system-of-use-registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"system-of-use-registry.d.ts","sourceRoot":"","sources":["../../src/llm/system-of-use-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC5B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,eAAe,EAAiB,MAAM,iBAAiB,CAAC;AAajE;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAGhF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,mBAAmB,GAC5B,qBAAqB,CAyBvB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,CAAC,EAC7C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,mBAAmB,GAC5B,qBAAqB,CAEvB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB,mBAAmB,GAAG,SAAS,CAMjC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,CAAC,EAAE,eAAe,GAAG,sBAAsB,EAAE,CA2BjF;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,IAAI,IAAI,CAElD"}

package/dist/llm/system-of-use-registry.js

@@ -0,0 +1,200 @@
+/**
+ * `registerSystemOfUse` — runtime extension point for the E9 system-of-use
+ * taxonomy (T11751 · AC1).
+ *
+ * ## Why a runtime registry
+ *
+ * {@link BUILTIN_SYSTEMS_OF_USE} is the static, closed-axis registry of the
+ * well-known systems (orchestration tiers + roles + aux subsystems). Plugins,
+ * extensions, and downstream packages need to declare NEW systems-of-use (e.g.
+ * a `tool:my-search` or a bespoke `aux`-like subsystem) and give each a default
+ * provider/model binding — WITHOUT editing the contracts SSoT.
+ *
+ * `registerSystemOfUse(key, displayName, defaults)` adds such a system to a
+ * process-level registry. The registered default binding is consulted by the
+ * single E9 resolution chokepoint (`resolveLLMForSystem` → `resolveLLMForRole`)
+ * **strictly BELOW user config** — after `llm.systems[key]`, `llm.default`, and
+ * `llm.defaultProfile` — so the user ALWAYS wins (AC1). A registered default
+ * only supplies a binding when the user has configured nothing for that key.
+ *
+ * ## Import-time purity
+ *
+ * This module performs NO registration at import time — the registry starts
+ * empty and is populated only by explicit `registerSystemOfUse(...)` calls. It
+ * holds no I/O, no config reads, and no side effects on load (so importing it
+ * is always safe). It is the runtime half intentionally split out of the
+ * type-only `@cleocode/contracts` (Gate 10).
+ *
+ * @module llm/system-of-use-registry
+ * @task T11751
+ * @epic T11745
+ */
+import { BUILTIN_SYSTEMS_OF_USE, } from '@cleocode/contracts';
+import { getLogger } from '../logger.js';
+import { formatSystemKey, systemKeyKind } from './system-key.js';
+const logger = getLogger('llm-system-of-use-registry');
+/**
+ * Process-level registry of runtime-registered systems-of-use, keyed by encoded
+ * system key. Starts EMPTY — populated only by {@link registerSystemOfUse}.
+ *
+ * Module-private: callers reach it through the exported functions so the
+ * "user wins" / "register vs read" contract is enforced in one place.
+ */
+const REGISTRY = new Map();
+/**
+ * A registered system-of-use whose `defaults` carry neither a `profile` nor a
+ * complete `provider`+`model` tuple is structurally incomplete: it can declare
+ * presence in the picker but cannot supply a resolution binding. Such a default
+ * is skipped at resolution time (the chain falls through) — never an error.
+ *
+ * @param defaults - The candidate default binding.
+ * @returns `true` when the default can actually bind a provider/model.
+ * @task T11751
+ */
+export function isResolvableSystemDefault(defaults) {
+    if (defaults.profile)
+        return true;
+    return Boolean(defaults.provider && defaults.model);
+}
+/**
+ * Register a new system-of-use with a default provider/model binding (AC1).
+ *
+ * The registration is merged UNDER user config: the resolver consults
+ * `defaults` only when the user has configured nothing more specific for `key`
+ * (no `llm.systems[key]`, no `llm.default`, no `llm.defaultProfile`). Re-calling
+ * with the same `key` REPLACES the prior registration (last-write-wins) so a
+ * package can update its own default idempotently.
+ *
+ * `key` MAY be a flat label (e.g. `'sentient'`) or an open-axis encoded key
+ * (`'tool:web-search'`). Passing a structured `SystemOfUse` descriptor is also
+ * supported via {@link registerSystemOfUseDescriptor}.
+ *
+ * @param key         - Encoded system-of-use key (non-empty).
+ * @param displayName - Human-readable name for the picker surface (non-empty).
+ * @param defaults    - Default binding consulted strictly below user config.
+ * @returns The stored {@link RegisteredSystemOfUse} record.
+ * @throws {RangeError} When `key` or `displayName` is empty.
+ * @task T11751
+ * @epic T11745
+ */
+export function registerSystemOfUse(key, displayName, defaults) {
+    if (!key.trim()) {
+        throw new RangeError('registerSystemOfUse: `key` must be a non-empty string');
+    }
+    if (!displayName.trim()) {
+        throw new RangeError('registerSystemOfUse: `displayName` must be a non-empty string');
+    }
+    const record = {
+        key,
+        displayName,
+        // Defensive copy — the registry owns its records and never aliases the
+        // caller's object (so a later caller mutation cannot rewrite a binding).
+        defaults: { ...defaults },
+    };
+    REGISTRY.set(key, record);
+    if (!isResolvableSystemDefault(defaults)) {
+        logger.debug({ key }, 'registerSystemOfUse: registered with a non-binding default (picker-only) ' +
+            '— resolution will fall through past this entry');
+    }
+    return record;
+}
+/**
+ * Register a system-of-use from a structured {@link SystemOfUse} descriptor,
+ * encoding it to its canonical string key via {@link formatSystemKey}.
+ *
+ * Convenience wrapper over {@link registerSystemOfUse} for callers that already
+ * hold a `{ kind, id }` descriptor (e.g. plugin-declared tools/skills).
+ *
+ * @param system      - The structured descriptor to register.
+ * @param displayName - Human-readable name for the picker surface.
+ * @param defaults    - Default binding consulted strictly below user config.
+ * @returns The stored {@link RegisteredSystemOfUse} record.
+ * @task T11751
+ */
+export function registerSystemOfUseDescriptor(system, displayName, defaults) {
+    return registerSystemOfUse(formatSystemKey(system), displayName, defaults);
+}
+/**
+ * Look up the runtime-registered default binding for an encoded system key.
+ *
+ * Returns `undefined` when no system is registered under `key` OR when its
+ * default is structurally incomplete (so the resolver falls through). This is
+ * the read surface the E9 resolver calls AFTER exhausting all user-config tiers.
+ *
+ * @param key - Encoded system-of-use key (may be undefined — returns undefined).
+ * @returns The resolvable {@link SystemOfUseDefaults}, or `undefined`.
+ * @task T11751
+ */
+export function getRegisteredSystemDefault(key) {
+    if (!key)
+        return undefined;
+    const record = REGISTRY.get(key);
+    if (!record)
+        return undefined;
+    if (!isResolvableSystemDefault(record.defaults))
+        return undefined;
+    return record.defaults;
+}
+/**
+ * Enumerate every system-of-use for the TUI / Studio profile picker (AC2):
+ * the static {@link BUILTIN_SYSTEMS_OF_USE} table followed by every
+ * runtime-registered system, de-duplicated by key (a registration for a builtin
+ * key overrides the builtin entry — "user/runtime wins" for the picker label).
+ *
+ * Each entry carries its encoded `key`, a `displayName`, the discriminant
+ * `kind`, and its `source` (`'builtin'` | `'registered'`) so the picker can
+ * render and group them. Registered entries also surface their `defaults`.
+ *
+ * @param kind - Optional kind filter — when set, only that axis is returned.
+ * @returns The merged, ordered picker entries.
+ * @task T11751
+ * @epic T11745
+ */
+export function listSystemsOfUse(kind) {
+    const byKey = new Map();
+    // 1. Builtins first (stable order from the contracts SSoT).
+    for (const sys of BUILTIN_SYSTEMS_OF_USE) {
+        const key = formatSystemKey(sys);
+        byKey.set(key, {
+            key,
+            displayName: defaultDisplayName(sys.kind, sys.id),
+            kind: sys.kind,
+            source: 'builtin',
+        });
+    }
+    // 2. Runtime registrations override/extend (registered wins on key collision).
+    for (const record of REGISTRY.values()) {
+        byKey.set(record.key, {
+            key: record.key,
+            displayName: record.displayName,
+            kind: systemKeyKind(record.key),
+            source: 'registered',
+            defaults: record.defaults,
+        });
+    }
+    const entries = [...byKey.values()];
+    return kind ? entries.filter((e) => e.kind === kind) : entries;
+}
+/**
+ * Clear all runtime registrations.
+ *
+ * Intended for test isolation — production code never needs to un-register a
+ * system. Builtins are unaffected (they live in the contracts SSoT, not here).
+ *
+ * @internal
+ * @task T11751
+ */
+export function clearRegisteredSystemsOfUse() {
+    REGISTRY.clear();
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Derive a human-readable default display name for a builtin system. Plain
+ * id-with-kind-prefix; the picker may localise/override on top of this.
+ */
+function defaultDisplayName(kind, id) {
+    return `${kind}: ${id}`;
+}
+//# sourceMappingURL=system-of-use-registry.js.map