@cleocode/contracts 2026.10.13 → 2026.10.14

package/src/__tests__/memory-wire-shapes.test.ts

@@ -67,6 +67,7 @@ type _BrainCompactHitShape = {
   rrfScore?: number;
   bm25Score?: number;
   _next?: Record<string, string>;
+  scope?: 'project' | 'global';
 };
 
 type _AssertBrainCompactHitPinned = AssertEquals1<Equals<BrainCompactHit, _BrainCompactHitShape>>;
@@ -166,6 +167,7 @@ type _FetchedBrainEntryShape = {
   id: string;
   type: string;
   data: unknown;
+  scope?: 'project' | 'global';
 };
 
 type _AssertFetchedEntryPinned = AssertEquals1<Equals<FetchedBrainEntry, _FetchedBrainEntryShape>>;

package/src/acceptance-gate.ts

@@ -66,6 +66,12 @@ export interface AcceptanceGateRunOptions
    * its cache key. Required, with a one-gate batch, whenever `cache` is not `off`.
    */
   cacheInputsHash?: string;
+  /**
+   * The parts behind {@link AcceptanceGateRunOptions.cacheInputsHash}, kept
+   * beside a stored pass (outside its MAC) so a later miss can say whether the
+   * environment or a task file moved (T13693). Diagnostic only, never trusted.
+   */
+  cacheInputs?: AcceptanceGateCacheInputs;
   /**
    * The task's stored typed results before this run (T13525). With
    * `cache: 'only'`, a gate with no cache entry reuses its stored pass when
@@ -391,6 +397,14 @@ export type GateResultDetails =
 
 // ─── Result ──────────────────────────────────────────────────────────────────
 
+/** The parts of a typed gate's inputs digest a cache-miss diagnostic compares (T13693). */
+export interface AcceptanceGateCacheInputs {
+  /** Hash of the gate's effective environment, or null when it has no invocation. */
+  environmentHash: string | null;
+  /** The captured input files. */
+  artifacts: readonly AcceptanceGateArtifact[];
+}
+
 /**
  * Exact bytes observed for one declared task input or resolved verification harness.
  * @remarks A missing input is explicit, with both digest and size null. This inventory

package/src/config.ts

@@ -228,6 +228,14 @@ export interface BrainEmbeddingConfig {
   enabled: boolean;
   /** Embedding provider to use (default: 'local'). */
   provider: 'local' | 'openai';
+  /**
+   * Whether the local provider may download its model from the Hugging Face
+   * hub when it is not cached (default: false). Off, CLEO makes no connection
+   * for embeddings: a cached model still loads, an absent one is skipped.
+   *
+   * @task T13716
+   */
+  allowModelDownload?: boolean;
 }
 
 /**

package/src/dispatch/operations-registry.ts

@@ -4331,6 +4331,12 @@ export const OPERATIONS: OperationDef[] = [
         description: 'text parameter',
         cli: { positional: true },
       },
+      {
+        name: 'scope',
+        type: 'string',
+        required: false,
+        description: 'Store to write: project (default) or global, the synced main brain (T13720)',
+      },
     ] satisfies ParamDef[],
   },
   {
@@ -4356,6 +4362,12 @@ export const OPERATIONS: OperationDef[] = [
         required: true,
         description: 'rationale parameter',
       },
+      {
+        name: 'scope',
+        type: 'string',
+        required: false,
+        description: 'Store to write: project (default) or global, the synced main brain (T13720)',
+      },
     ] satisfies ParamDef[],
   },
   {

package/src/index.ts

@@ -898,7 +898,13 @@ export {
   isLafsSuccess,
 } from './lafs.js';
 // === ct-lean levels (T13663 / Epic T13418) ===
-export type { LeanConfig, LeanLevel, LeanLevelSource } from './lean.js';
+export type {
+  LeanConfig,
+  LeanDebtItem,
+  LeanDebtReport,
+  LeanLevel,
+  LeanLevelSource,
+} from './lean.js';
 // === Lease-IPC v1.1 (PARALLEL DbWriterLease contract — T11627 · SG-RUNTIME-UNIFICATION) ===
 export type {
   ChildKilledUnresponsiveResponse,
@@ -1132,6 +1138,7 @@ export type {
 export { BRAIN_OBSERVATION_SOURCE_TYPES } from './memory/observe.js';
 export type {
   BrainCompactHit,
+  MemoryScope,
   SearchBrainCompactParams,
   SearchBrainCompactResult,
 } from './memory/search.js';
@@ -2494,6 +2501,7 @@ export {
 // === Store restore (T13240 — restore cleo.db from a named snapshot or backup id) ===
 export type {
   StoreRecoverResult,
+  StoreRestoreDocsBytes,
   StoreRestoreKept,
   StoreRestoreResult,
   StoreRestoreSource,

package/src/invariants/sync-write-invariants.ts

@@ -338,7 +338,7 @@ export const SYNC_WRITE_INVARIANTS: readonly SyncWriteInvariant[] = Object.freez
     'derived.mirrors',
     'PAC-07',
     'T12928',
-    ['tasks_task_labels', 'brain_sticky_tags', 'docs_wikilinks', 'tasks_tasks'],
+    ['tasks_task_labels', 'brain_sticky_tags', 'tasks_tasks'],
     ['owning rows whose JSON or junction changed'],
     'junction tables equal their JSON source',
   ),

package/src/lean.ts

@@ -34,3 +34,38 @@ export interface LeanConfig {
    */
   level?: LeanLevel;
 }
+
+/**
+ * One deliberate shortcut, read from a `shortcut: <ceiling>, <upgrade trigger>`
+ * comment (or the older `ponytail:` marker) in a git-tracked file (T13664).
+ */
+export interface LeanDebtItem {
+  /** Repo-relative path. */
+  readonly file: string;
+  /** 1-based line number. */
+  readonly line: number;
+  /** The marker word that matched (`shortcut`, `ponytail`, or a custom marker). */
+  readonly marker: string;
+  /** The comment text after the marker. */
+  readonly text: string;
+  /** The limit the shortcut names (text before the first comma). */
+  readonly ceiling: string;
+  /** When to revisit it (text after the first comma), or `null` when none is named. */
+  readonly upgrade: string | null;
+  /** `true` when no upgrade trigger is named: the rows that silently rot. */
+  readonly noTrigger: boolean;
+  /** Stable id from file + marker text, independent of the line number. */
+  readonly key: string;
+}
+
+/** The ledger `cleo lean debt` prints. */
+export interface LeanDebtReport {
+  /** Every marker found, grouped by file in path order. */
+  readonly items: readonly LeanDebtItem[];
+  /** How many markers name no upgrade trigger. */
+  readonly noTriggerCount: number;
+  /** Tasks filed by `--file-tasks` (empty otherwise). */
+  readonly filed: readonly { readonly key: string; readonly taskId: string }[];
+  /** Keys that already had a `lean-debt` task, so none was filed. */
+  readonly alreadyFiled: readonly string[];
+}

package/src/memory/fetch.ts

@@ -16,6 +16,8 @@
  * @see Layer 2: {@link ./timeline.ts}
  */
 
+import type { MemoryScope } from './search.js';
+
 // ── FetchBrainEntriesParams ─────────────────────────────────────────
 
 /**
@@ -47,6 +49,8 @@ export interface FetchedBrainEntry {
    * via a discriminated read or pass the value through to a renderer.
    */
   data: unknown;
+  /** Store the entry came from; absent means the project store (T13720). */
+  scope?: MemoryScope;
 }
 
 // ── FetchBrainEntriesResult ─────────────────────────────────────────

package/src/memory/search.ts

@@ -19,6 +19,16 @@
  * @see Layer 3: {@link ./fetch.ts}
  */
 
+// ── MemoryScope ─────────────────────────────────────────────────────
+
+/**
+ * Which store a BRAIN entry lives in: the project `cleo.db`, or the global
+ * `cleo.db` (the main brain, synced on the account's `home:<user>` stream).
+ *
+ * @task T13720
+ */
+export type MemoryScope = 'project' | 'global';
+
 // ── BrainCompactHit ─────────────────────────────────────────────────
 
 /**
@@ -62,6 +72,8 @@ export interface BrainCompactHit {
    * by `@cleocode/core`'s `mvi-helpers`.
    */
   _next?: Record<string, string>;
+  /** Store the hit came from; absent means the project store (T13720). */
+  scope?: MemoryScope;
 }
 
 // ── SearchBrainCompactParams ────────────────────────────────────────

package/src/operations/memory.ts

@@ -25,6 +25,7 @@
 
 import type { BrainCognitiveType, BrainMemoryTier, BrainSourceConfidence } from '../brain.js';
 import type { LAFSPage } from '../lafs.js';
+import type { MemoryScope } from '../memory/search.js';
 
 // ============================================================================
 // Shared Memory types (API wire format)
@@ -777,6 +778,8 @@ export interface MemoryObserveParams {
   attachmentRefs?: string[];
   /** Cross-reference to other memory or external IDs (T794). */
   crossRef?: string[];
+  /** Store to write: `project` (default) or `global`, the synced main brain (T13720). */
+  scope?: MemoryScope;
 }
 /** Result of `memory.observe`. */
 export interface MemoryObserveResult {
@@ -841,6 +844,8 @@ export interface MemoryDecisionStoreParams {
    * Defaults to `'agent'` when not specified.
    */
   decidedBy?: 'owner' | 'council' | 'agent';
+  /** Store to write: `project` (default) or `global`, the synced main brain (T13720). */
+  scope?: MemoryScope;
 }
 /** Result of `memory.decision.store`. */
 export interface MemoryDecisionStoreResult {

package/src/store-restore.ts

@@ -37,6 +37,21 @@ export interface StoreRestoreKept {
   readonly sidecars: readonly string[];
 }
 
+/**
+ * The docs byte surfaces restored from a backup id (T13704, T13708): the
+ * blob-store and attachment databases and the byte files `docs fetch` reads.
+ */
+export interface StoreRestoreDocsBytes {
+  /** `true` only when every recorded database and byte file was verified and placed. */
+  readonly complete: boolean;
+  /** Databases placed, relative to `.cleo/` (`blobs/manifest.db`, `attachments/index.db`). */
+  readonly dbsRestored: readonly string[];
+  /** Byte files verified (sha256) and placed. */
+  readonly filesRestored: number;
+  /** What was not placed, each `<path>: <why>` (missing, sha256 mismatch, integrity_check, busy). */
+  readonly failed: readonly string[];
+}
+
 /** Result of a store restore (or its dry run). */
 export interface StoreRestoreResult {
   readonly dryRun: boolean;
@@ -53,6 +68,19 @@ export interface StoreRestoreResult {
   readonly removedSidecars: readonly string[];
   /** How to undo the restore (`null` on a dry run, or when nothing was replaced). */
   readonly undo: string | null;
+  /**
+   * The docs byte surfaces restored with the store (`--id` of a backup that
+   * captured them, T13708). Absent otherwise.
+   */
+  readonly docsBytes?: StoreRestoreDocsBytes;
+  /**
+   * `true` when the store was placed but part of the backup was not (a docs
+   * byte that was missing or failed verification): the restore is not a
+   * clean success and the CLI exits non-zero (T13709).
+   */
+  readonly partial?: boolean;
+  /** What the partial restore left out, one line each. */
+  readonly warnings?: readonly string[];
 }
 
 /**