@cleocode/contracts 2026.5.62 → 2026.5.64

package/dist/release/version-bump.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Version-bump contracts — types describing how `cleo release ship` finds
+ * and updates version-bearing files across a project's ecosystem(s).
+ *
+ * The implementation lives in `@cleocode/core/release/version-bump.ts`. The
+ * types live here so contracts consumers (CLI, studio, downstream tools)
+ * can describe / validate the same shapes without depending on core.
+ *
+ * @adr ADR-063
+ */
+/** Supported version-bump strategies. */
+export type VersionBumpStrategy = 'plain' | 'json' | 'toml' | 'sed';
+/**
+ * Version bump target — a single file the release pipeline knows how to
+ * bump. Discovery returns these, an explicit config in
+ * `.cleo/config.json` (`release.versionBump.files`) populates them.
+ */
+export interface VersionBumpTarget {
+    /** Path relative to the project root. */
+    file: string;
+    /** Update strategy. */
+    strategy: VersionBumpStrategy;
+    /** JSON field path for `strategy='json'` (e.g. `version`, `package.version`). */
+    field?: string;
+    /** TOML key for `strategy='toml'` (default: `version`). */
+    key?: string;
+    /** TOML section for `strategy='toml'` (e.g. `package`, `workspace.package`). */
+    section?: string;
+    /** Sed pattern with `{{VERSION}}` placeholder for `strategy='sed'`. */
+    pattern?: string;
+}
+/** Bump type used by `calculateNewVersion`. */
+export type BumpType = 'patch' | 'minor' | 'major';
+/** Result for a single file's bump attempt. */
+export interface BumpResult {
+    /** Path relative to the project root. */
+    file: string;
+    /** Strategy used. */
+    strategy: VersionBumpStrategy | string;
+    /** Whether the bump succeeded. */
+    success: boolean;
+    /** Version found in the file before the bump, if it could be extracted. */
+    previousVersion?: string;
+    /** Version written to the file. */
+    newVersion?: string;
+    /** Human-readable error when `success === false`. */
+    error?: string;
+}
+/**
+ * Where the version-bump targets came from. Lets callers log / diagnose why
+ * a release commit included or omitted version files.
+ */
+export type VersionBumpTargetSource = 'config' | 'workspace' | 'none';
+/** Envelope returned by `resolveVersionBumpTargets`. */
+export interface ResolveVersionBumpTargetsResult {
+    /** Targets to bump. Empty when `source === 'none'`. */
+    targets: VersionBumpTarget[];
+    /**
+     * How the targets were resolved:
+     *   - `'config'`     — explicit `release.versionBump.files` entry
+     *   - `'workspace'`  — auto-discovered from filesystem markers
+     *   - `'none'`       — neither config nor a recognised workspace
+     */
+    source: VersionBumpTargetSource;
+}
+/** Bulk-bump result envelope. */
+export interface BumpVersionFromConfigResult {
+    /** Per-file results. */
+    results: BumpResult[];
+    /** `true` iff every result succeeded. */
+    allSuccess: boolean;
+}
+//# sourceMappingURL=version-bump.d.ts.map

package/dist/release/version-bump.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-bump.d.ts","sourceRoot":"","sources":["../../src/release/version-bump.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,yCAAyC;AACzC,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;AAEpE;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,iFAAiF;IACjF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,+CAA+C;AAC/C,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;AAEnD,+CAA+C;AAC/C,MAAM,WAAW,UAAU;IACzB,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,QAAQ,EAAE,mBAAmB,GAAG,MAAM,CAAC;IACvC,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,2EAA2E;IAC3E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mCAAmC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,GAAG,WAAW,GAAG,MAAM,CAAC;AAEtE,wDAAwD;AACxD,MAAM,WAAW,+BAA+B;IAC9C,uDAAuD;IACvD,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B;;;;;OAKG;IACH,MAAM,EAAE,uBAAuB,CAAC;CACjC;AAED,iCAAiC;AACjC,MAAM,WAAW,2BAA2B;IAC1C,wBAAwB;IACxB,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,yCAAyC;IACzC,UAAU,EAAE,OAAO,CAAC;CACrB"}

package/dist/release/version-bump.js

@@ -0,0 +1,12 @@
+/**
+ * Version-bump contracts — types describing how `cleo release ship` finds
+ * and updates version-bearing files across a project's ecosystem(s).
+ *
+ * The implementation lives in `@cleocode/core/release/version-bump.ts`. The
+ * types live here so contracts consumers (CLI, studio, downstream tools)
+ * can describe / validate the same shapes without depending on core.
+ *
+ * @adr ADR-063
+ */
+export {};
+//# sourceMappingURL=version-bump.js.map

package/dist/release/version-bump.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-bump.js","sourceRoot":"","sources":["../../src/release/version-bump.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/contracts",
-  "version": "2026.5.62",
+  "version": "2026.5.64",
   "description": "Domain types, interfaces, and contracts for the CLEO ecosystem",
   "type": "module",
   "main": "./dist/index.js",
@@ -82,7 +82,7 @@
   "dependencies": {
     "zod": "^4.3.6",
     "zod-to-json-schema": "^3.25.2",
-    "@cleocode/lafs": "2026.5.62"
+    "@cleocode/lafs": "2026.5.64"
   },
   "scripts": {
     "build": "tsc -b --force && node scripts/emit-schemas.mjs",

package/src/__tests__/llm-config-schema.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Schema roundtrip tests for the extended `LlmConfig` shape.
+ *
+ * Asserts that:
+ *
+ * 1. A literal `LlmConfig` object containing the new `default`, `roles`, and
+ *    the legacy `daemon` fields typechecks and survives a JSON
+ *    serialize/deserialize cycle without structural loss.
+ * 2. All five `RoleName` values (`extraction`, `consolidation`, `derivation`,
+ *    `hygiene`, `judgement`) are accepted as keys of `roles`.
+ * 3. Omitting `default` and/or `roles` still typechecks (both are optional).
+ *
+ * These tests guard the Phase 2 schema extension of
+ * T-LLM-CRED-CENTRALIZATION against accidental regressions.
+ *
+ * @task T9256
+ * @epic T-LLM-CRED-CENTRALIZATION
+ */
+
+import { describe, expect, it } from 'vitest';
+import type { LlmConfig, LlmDefaultConfig, LlmRoleConfig, RoleName } from '../config.js';
+
+describe('LlmConfig — Phase 2 schema extension (T9256)', () => {
+  it('accepts a fully-populated config with default, roles, and legacy daemon', () => {
+    const cfg: LlmConfig = {
+      daemon: { provider: 'anthropic', model: 'claude-sonnet-4-6' },
+      providers: {
+        anthropic: { apiKey: 'sk-test-anthropic' },
+        openai: { apiKey: 'sk-test-openai' },
+      },
+      default: { provider: 'anthropic', model: 'claude-sonnet-4-6' },
+      roles: {
+        extraction: {
+          provider: 'anthropic',
+          model: 'claude-haiku-4-5',
+          credentialLabel: 'ext-key',
+        },
+        consolidation: {
+          provider: 'openai',
+          model: 'gpt-4o',
+        },
+        derivation: {
+          provider: 'gemini',
+          model: 'gemini-2.5-pro',
+        },
+        hygiene: {
+          provider: 'moonshot',
+          model: 'kimi-k2',
+        },
+        judgement: {
+          provider: 'anthropic',
+          model: 'claude-opus-4-7',
+          credentialLabel: 'judge-key',
+        },
+      },
+    };
+
+    const roundtripped: LlmConfig = JSON.parse(JSON.stringify(cfg));
+    expect(roundtripped).toEqual(cfg);
+  });
+
+  it('preserves structural identity across JSON serialize/deserialize', () => {
+    const cfg: LlmConfig = {
+      default: { provider: 'anthropic', model: 'claude-sonnet-4-6' },
+      roles: {
+        extraction: { provider: 'anthropic', model: 'claude-haiku-4-5' },
+      },
+    };
+
+    const serialized = JSON.stringify(cfg);
+    const parsed = JSON.parse(serialized) as LlmConfig;
+
+    expect(parsed.default).toEqual(cfg.default);
+    expect(parsed.roles).toEqual(cfg.roles);
+    expect(parsed.roles?.extraction?.provider).toBe('anthropic');
+    expect(parsed.roles?.extraction?.model).toBe('claude-haiku-4-5');
+  });
+
+  it('accepts all five RoleName values as keys of roles', () => {
+    const roleNames: readonly RoleName[] = [
+      'extraction',
+      'consolidation',
+      'derivation',
+      'hygiene',
+      'judgement',
+    ] as const;
+
+    // Build a `roles` map populated with one entry per role name. The TS
+    // compiler enforces that only valid `RoleName` keys appear here — any
+    // typo would be a compile-time error.
+    const roles: Partial<Record<RoleName, LlmRoleConfig>> = {};
+    for (const name of roleNames) {
+      roles[name] = { provider: 'anthropic', model: 'claude-sonnet-4-6' };
+    }
+
+    const cfg: LlmConfig = { roles };
+    expect(Object.keys(cfg.roles ?? {})).toHaveLength(5);
+    for (const name of roleNames) {
+      expect(cfg.roles?.[name]?.provider).toBe('anthropic');
+      expect(cfg.roles?.[name]?.model).toBe('claude-sonnet-4-6');
+    }
+  });
+
+  it('typechecks when default and roles are both omitted', () => {
+    const cfg: LlmConfig = {
+      daemon: { provider: 'anthropic', model: 'claude-sonnet-4-6' },
+    };
+
+    expect(cfg.default).toBeUndefined();
+    expect(cfg.roles).toBeUndefined();
+    expect(cfg.daemon?.provider).toBe('anthropic');
+  });
+
+  it('typechecks an empty LlmConfig (all fields optional)', () => {
+    const cfg: LlmConfig = {};
+    expect(cfg).toEqual({});
+  });
+
+  it('allows a role entry without an optional credentialLabel', () => {
+    const role: LlmRoleConfig = {
+      provider: 'openai',
+      model: 'gpt-4o-mini',
+    };
+    expect(role.credentialLabel).toBeUndefined();
+  });
+
+  it('allows LlmDefaultConfig with only provider + model (no credential)', () => {
+    const def: LlmDefaultConfig = {
+      provider: 'anthropic',
+      model: 'claude-sonnet-4-6',
+    };
+    expect(def.provider).toBe('anthropic');
+    expect(def.model).toBe('claude-sonnet-4-6');
+  });
+});

package/src/config.ts

@@ -9,6 +9,8 @@
  * @task T5710
  */
 
+import type { ModelTransport } from './operations/llm.js';
+
 /** Output format options. */
 export type OutputFormat = 'json' | 'text' | 'jsonl' | 'markdown' | 'table';
 
@@ -282,7 +284,11 @@ export interface BrainTieringConfig {
 export interface BrainLlmExtractionConfig {
   /** Enable LLM-driven extraction gate (default: true). */
   enabled: boolean;
-  /** Anthropic model to use for extraction (default: 'claude-haiku-4-5-20251001'). */
+  /**
+   * Anthropic model to use for extraction. Default lives in
+   * `@cleocode/core/llm/role-resolver` (`IMPLICIT_FALLBACK_MODEL`) so the
+   * literal stays in a single source location (T9255 grep guard).
+   */
   model: string;
   /** Minimum importance score (0.0–1.0) below which extractions are dropped (default: 0.6). */
   minImportance: number;
@@ -325,10 +331,11 @@ export interface BrainConfig {
    * LLM-driven extraction gate settings.
    * When enabled and ANTHROPIC_API_KEY is present, session transcripts are
    * processed by an LLM to extract typed structured memories instead of the
-   * legacy keyword regex. Defaults are enabled: true and model is the cheap
-   * Haiku class so extraction cost stays bounded.
+   * legacy keyword regex. Defaults are enabled: true and model defaults to
+   * the centralised implicit fallback (cheap Haiku class) defined in
+   * `@cleocode/core/llm/role-resolver` so extraction cost stays bounded.
    *
-   * @defaultValue { enabled: true, model: 'claude-haiku-4-5-20251001', minImportance: 0.6, maxExtractions: 7, maxTranscriptChars: 60000 }
+   * @defaultValue { enabled: true, model: IMPLICIT_FALLBACK_MODEL, minImportance: 0.6, maxExtractions: 7, maxTranscriptChars: 60000 }
    */
   llmExtraction?: BrainLlmExtractionConfig;
 }
@@ -381,7 +388,7 @@ export interface DaemonLLMConfig {
    * LLM provider transport used by daemon loops.
    * @defaultValue 'anthropic'
    */
-  provider: 'anthropic' | 'openai' | 'gemini' | 'moonshot';
+  provider: ModelTransport;
   /**
    * Full model identifier for the selected provider.
    * @defaultValue 'claude-sonnet-4-6'
@@ -389,14 +396,85 @@ export interface DaemonLLMConfig {
   model: string;
 }
 
+/**
+ * Canonical model transport identifier — re-export of {@link ModelTransport}
+ * from `operations/llm.ts` so config-layer types stay in lock-step with the
+ * operations layer with no risk of drift.
+ *
+ * Previously declared as a separate string-literal union; collapsed in the
+ * T-LLM-CRED Phase 2 DRY/SOLID review (P1-2). Adding a new transport now
+ * requires editing only `operations/llm.ts`.
+ *
+ * @task T-LLM-CRED-CENTRALIZATION Phase 2 — DRY review P1-2
+ */
+export type LlmTransport = ModelTransport;
+
+/**
+ * Logical LLM role name used by role-aware resolvers (BRAIN, sentient, etc.).
+ *
+ * Each role can pin its own provider + model + credential label, with
+ * resolution falling back to `LlmConfig.default` and finally to the legacy
+ * `LlmConfig.daemon` block.
+ *
+ * @task T-LLM-CRED-CENTRALIZATION Phase 2 (T9256)
+ */
+export type RoleName = 'extraction' | 'consolidation' | 'derivation' | 'hygiene' | 'judgement';
+
+/**
+ * Canonical default LLM target for unscoped (non-role) calls.
+ *
+ * Replaces the role previously played by `LlmConfig.daemon`. The `daemon`
+ * field stays as a deprecated alias for one release cycle to give downstream
+ * consumers time to migrate.
+ *
+ * @task T-LLM-CRED-CENTRALIZATION Phase 2 (T9256)
+ */
+export interface LlmDefaultConfig {
+  /** LLM provider transport for the default model. */
+  provider: LlmTransport;
+  /** Full model identifier for the selected provider. */
+  model: string;
+}
+
+/**
+ * Per-role LLM configuration entry.
+ *
+ * Each role may optionally pin to a specific credential label (matching a
+ * `CredentialResult.label`) so that, e.g., the `extraction` role can use a
+ * different Anthropic API key than `judgement` without changing the global
+ * default.
+ *
+ * @task T-LLM-CRED-CENTRALIZATION Phase 2 (T9256)
+ */
+export interface LlmRoleConfig {
+  /** LLM provider transport for this role. */
+  provider: LlmTransport;
+  /** Full model identifier for the selected provider. */
+  model: string;
+  /**
+   * Optional credential label to pin this role to a specific credential
+   * entry resolved by `resolveCredentials()`. When omitted, the role
+   * inherits the default credential resolution order.
+   */
+  credentialLabel?: string;
+}
+
 /**
  * Top-level LLM configuration block inside CleoConfig.
  *
  * Stored at `llm` in config.json.
+ *
+ * Resolution order for role-scoped calls:
+ *   `roles[role]` → `default` → `daemon` (legacy).
  */
 export interface LlmConfig {
   /**
    * Daemon LLM settings (provider + model for background loops).
+   *
+   * @deprecated Use `default` instead. Retained as a fallback alias for
+   * one release cycle (T-LLM-CRED-CENTRALIZATION Phase 2 · T9256). New
+   * code must read `default` first and only fall through to `daemon` when
+   * `default` is absent.
    * @defaultValue { provider: 'anthropic', model: 'claude-sonnet-4-6' }
    */
   daemon?: DaemonLLMConfig;
@@ -405,6 +483,23 @@ export interface LlmConfig {
    * Keys are provider names: 'anthropic' | 'openai' | 'gemini' | 'moonshot'.
    */
   providers?: Record<string, LlmProviderEntry>;
+  /**
+   * Canonical default LLM for unscoped calls. Replaces the role previously
+   * played by `daemon`, which stays as a deprecated alias for one release
+   * cycle.
+   *
+   * @task T-LLM-CRED-CENTRALIZATION Phase 2 (T9256)
+   */
+  default?: LlmDefaultConfig;
+  /**
+   * Per-role LLM overrides. Each role optionally pins to a credential
+   * label.
+   *
+   * Resolution order: `roles[role]` → `default` → `daemon` (legacy).
+   *
+   * @task T-LLM-CRED-CENTRALIZATION Phase 2 (T9256)
+   */
+  roles?: Partial<Record<RoleName, LlmRoleConfig>>;
 }
 
 /** SignalDock transport mode. */

package/src/index.ts

@@ -219,7 +219,10 @@ export type {
   LifecycleConfig,
   LifecycleEnforcementMode,
   LlmConfig,
+  LlmDefaultConfig,
   LlmProviderEntry,
+  LlmRoleConfig,
+  LlmTransport,
   LoggingConfig,
   LogLevel,
   MemoryBridgeMode,
@@ -227,6 +230,7 @@ export type {
   OutputFormat,
   ProviderConfig,
   ResolvedValue,
+  RoleName,
   SessionConfig,
   SessionSummaryInput,
   SharingConfig,
@@ -614,6 +618,35 @@ export type {
   LifecycleStatusResult,
   StageRecord,
 } from './operations/lifecycle.js';
+// === LLM Credential + Role-Resolver Wire Types (T-LLM-CRED Phase 1/2 — T9255) ===
+export type {
+  AuthTypeWire,
+  CredentialResultWire,
+  CredentialSourceWire,
+  CredentialsStoreStrategyWire,
+  // `cleo llm` CLI / dispatch operation contracts (T9258)
+  LlmAddParams,
+  LlmAddResult,
+  LlmListParams,
+  LlmListResult,
+  LlmProfileParams,
+  LlmProfileResult,
+  LlmRemoveParams,
+  LlmRemoveResult,
+  LlmStoredCredentialView,
+  LlmTestParams,
+  LlmTestResult,
+  LlmUseParams,
+  LlmUseResult,
+  LlmWhoamiEntry,
+  LlmWhoamiParams,
+  LlmWhoamiResult,
+  ModelTransport,
+  ResolutionSource,
+  ResolvedLLM,
+  ResolveLLMForRoleOptions,
+  StoredAuthTypeWire,
+} from './operations/llm.js';
 // Multi-pass retrieval bundle types (PSYCHE Wave 4 · T1090)
 export type {
   PassMask,
@@ -1092,7 +1125,31 @@ export type {
   SyncResult,
   SyncStatus,
 } from './postgres-data-accessor.js';
+// === Project Context (ecosystem detection types) ===
+export type {
+  EcosystemHint,
+  FileNamingConvention,
+  ImportStyle,
+  ProjectContext,
+  ProjectType,
+  TestFramework,
+} from './project-context.js';
 export type { AdapterPathProvider } from './provider-paths.js';
+// === Release Channel ===
+export type { ChannelValidationResult, ReleaseChannel } from './release/channel.js';
+// === Release GitHub PR ===
+export type {
+  BranchProtectionResult,
+  CleoKnownLabel,
+  CleoLabelPalette,
+  LabelDefinition,
+  LabelEnsureResult,
+  PRCreateOptions,
+  PRLabelResolution,
+  PRMode,
+  PRResult,
+  RepoIdentity,
+} from './release/github-pr.js';
 // === Release Pipeline (T1597 / ADR-063) ===
 export type {
   PublishResult,
@@ -1102,6 +1159,16 @@ export type {
   ReleaseVersionScheme,
   VerifyResult,
 } from './release/pipeline.js';
+// === Release Version Bump ===
+export type {
+  BumpResult,
+  BumpType,
+  BumpVersionFromConfigResult,
+  ResolveVersionBumpTargetsResult,
+  VersionBumpStrategy,
+  VersionBumpTarget,
+  VersionBumpTargetSource,
+} from './release/version-bump.js';
 // === Result Types (Dashboard, Stats, Log, Context, Sequence, Analysis, Deps) ===
 export type {
   BottleneckTask,