@cleocode/contracts 2026.10.3 → 2026.10.5-rc.ci.672

package/src/row-identity.ts

@@ -130,3 +130,101 @@ export interface RowIdentitySpec {
   /** Task that declared the table. */
   readonly task: string;
 }
+
+/**
+ * One signal behind a store's row-identity share state (T13231).
+ *
+ * - `synced-marker`: `row_identity_synced` is set (a receive or a send happened);
+ * - `sync-flag`: `sync.seal`, `sync.push` or `sync.pull` is on;
+ * - `journal-rows`: a change-journal table holds rows (every `_sync_*` table
+ *   except `_sync_meta`, `_sync_replica` and `_sync_clock`; they key rows by uid);
+ * - `journal-meta`: `_sync_meta` holds `suspect:` or `baseline:` keys;
+ * - `identity-aliases`: an alias table holds rows (uids were re-keyed);
+ * - `rebound`: the store was copied, moved or restored (`_sync_replica`);
+ * - `vault-pushed`: a vault push or restore of this root is recorded locally;
+ * - `nexus-linked-no-vault`: linked to Cleo Nexus with no local vault record;
+ * - `nexus-checkpoint`: Cleo Nexus holds a checkpoint or journal segment of the project;
+ * - `nexus-unreachable`: Cleo Nexus could not be asked;
+ * - `unreadable`: a record needed for the verdict could not be read.
+ */
+export type RowIdentityShareSignalCode =
+  | 'synced-marker'
+  | 'sync-flag'
+  | 'journal-rows'
+  | 'journal-meta'
+  | 'identity-aliases'
+  | 'rebound'
+  | 'vault-pushed'
+  | 'nexus-linked-no-vault'
+  | 'nexus-checkpoint'
+  | 'nexus-unreachable'
+  | 'unreadable';
+
+/** One signal behind a share verdict (T13231). */
+export interface RowIdentityShareSignal {
+  readonly code: RowIdentityShareSignalCode;
+  /** `shared`: the uids may have left the store; `unknown`: that cannot be ruled out. */
+  readonly kind: 'shared' | 'unknown';
+  readonly detail: string;
+}
+
+/**
+ * Whether a store's row identity may have left it (T13231).
+ *
+ * - `shared`: its uids have, or may have, reached another store;
+ * - `unknown`: that cannot be ruled out;
+ * - `unshared`: provably local, so a from-scratch refill changes nothing any
+ *   other store holds.
+ */
+export interface RowIdentityShareState {
+  readonly state: 'shared' | 'unknown' | 'unshared';
+  /** Every signal that decided it (empty when unshared). */
+  readonly signals: readonly RowIdentityShareSignal[];
+  /** The signals' details, one line each (empty when unshared). */
+  readonly reasons: readonly string[];
+}
+
+/** What Cleo Nexus answered for one linked origin (`cleo doctor row-identity`, T13231). */
+export interface RowIdentityNexusAnswer {
+  readonly apiUrl: string;
+  readonly remoteProjectId: string;
+  readonly streamId: string;
+  /** `none`: no checkpoint and no journal segment; `present`: some; `error`: not answered. */
+  readonly answer: 'none' | 'present' | 'error';
+  readonly checkpoints: number;
+  readonly headSeq: number;
+  /** Why it was not answered (`error` only). */
+  readonly error?: string;
+}
+
+/** Rows whose identity a full refill re-derives, per table. */
+export type RowIdentityRefillCounts = Readonly<Record<string, number>>;
+
+/**
+ * `cleo doctor row-identity --refill`: the verdict, its evidence and the plan
+ * (T13231). `applied` is false on a dry run and on a refusal.
+ */
+export interface RowIdentityRefillReport {
+  readonly projectRoot: string;
+  /** Whether the store's recipe marker is current (no refill is due). */
+  readonly recipeCurrent: boolean;
+  /** Whether `CLEO_ROW_UID_FILL` is on in this process (`--apply` needs it). */
+  readonly fillEnabled: boolean;
+  /** The local verdict (link, vault state, journal state). */
+  readonly local: RowIdentityShareState;
+  /** Cleo Nexus, one answer per linked origin (empty when unlinked). */
+  readonly nexus: readonly RowIdentityNexusAnswer[];
+  /** The verdict with the Nexus answers folded in. */
+  readonly verdict: RowIdentityShareState;
+  /** Rows per declared table that carry an identity value the refill clears. */
+  readonly planned: RowIdentityRefillCounts;
+  /** `refill`: due and allowed; `none`: nothing to do; `refuse`: shared or unknown. */
+  readonly action: 'refill' | 'none' | 'refuse';
+  /** What to do next, one line each. */
+  readonly remedy: readonly string[];
+  readonly applied: boolean;
+  /** `--apply`: the pre-refill snapshot. */
+  readonly snapshot: string | null;
+  /** `--apply`: how to undo the refill. */
+  readonly undo: string | null;
+}

package/src/store-restore.ts

@@ -0,0 +1,70 @@
+/**
+ * `cleo restore backup --snapshot <file> | --id <backupId>`: restore the live
+ * project `cleo.db` (which holds the tasks AND brain tables) from a named
+ * snapshot or a backup id, safely (T13240).
+ *
+ * @task T13240
+ */
+
+/** Where the snapshot came from. */
+export interface StoreRestoreSource {
+  /** `snapshot`: a file named on the command line; `backup`: a backup id from `cleo backup list`. */
+  readonly kind: 'snapshot' | 'backup';
+  /** The file restored from (resolved, absolute). */
+  readonly path: string;
+  /** The backup id (`backup` only). */
+  readonly backupId: string | null;
+}
+
+/** What the snapshot verification found. */
+export interface StoreRestoreVerification {
+  /** `PRAGMA integrity_check` on a private copy of the snapshot: `ok`, or the first problems. */
+  readonly integrity: string;
+  /** Tasks in the snapshot (`tasks_tasks`). */
+  readonly tasks: number;
+  readonly sizeBytes: number;
+}
+
+/** The live store file that was replaced, kept so the restore can be undone. */
+export interface StoreRestoreKept {
+  /** Backup id the kept file is listed under (`cleo backup list`), restorable with `--id`. */
+  readonly backupId: string;
+  /** The kept store file. */
+  readonly path: string;
+  /** Whether the live WAL was folded into the kept file (otherwise its raw sidecars are kept beside it). */
+  readonly checkpointed: boolean;
+  /** Raw sidecar copies kept beside it (`-wal`, `-shm`, `-journal`), when not checkpointed. */
+  readonly sidecars: readonly string[];
+}
+
+/** Result of a store restore (or its dry run). */
+export interface StoreRestoreResult {
+  readonly dryRun: boolean;
+  /** `project` (`.cleo/cleo.db`) or `global` (`<CLEO_HOME>/cleo.db`, T13245). */
+  readonly scope: 'project' | 'global';
+  readonly restored: boolean;
+  /** The live store file. */
+  readonly target: string;
+  readonly source: StoreRestoreSource;
+  readonly verification: StoreRestoreVerification;
+  /** The replaced store, kept (`null` on a dry run, or when there was no live store). */
+  readonly kept: StoreRestoreKept | null;
+  /** Live-file sidecars removed so the restored file is not read with the old journal. */
+  readonly removedSidecars: readonly string[];
+  /** How to undo the restore (`null` on a dry run, or when nothing was replaced). */
+  readonly undo: string | null;
+}
+
+/**
+ * `cleo backup recover tasks|brain|conduit`: the freshest valid snapshot of the
+ * project store, restored through the same safe path as `cleo restore backup`
+ * (T13245). All three roles name the one live file, `.cleo/cleo.db`.
+ */
+export interface StoreRecoverResult extends StoreRestoreResult {
+  /** The role asked for (`tasks`, `brain` or `conduit`); the store restored is `cleo.db` either way. */
+  readonly role: string;
+  /** Snapshots that failed `PRAGMA quick_check` before one passed (newest first). */
+  readonly rejected: readonly string[];
+  /** Hours between the chosen snapshot and now, or `null` when its time is unknown. */
+  readonly dataLossWindowHours: number | null;
+}

package/src/task.ts

@@ -23,6 +23,7 @@
 
 import type { AcceptanceGate, AcceptanceGateResult } from './acceptance-gate.js';
 import type { AcRow } from './data-accessor.js';
+import type { HeavyToolResourcePlan } from './resource-governor.js';
 import type { TaskStatus } from './status-registry.js';
 
 export type { TaskStatus };
@@ -365,6 +366,13 @@ export type EvidenceAtom =
       treeHash?: string;
       /** `true` when the result was served from the tool cache (no spawn). */
       cacheHit?: boolean;
+      /**
+       * The heap, worker count and workspace concurrency a memory-bound tool
+       * (`test`, `build`, `typecheck`, `lint`) was spawned with, and why
+       * (T13122, T13123) — including any inherited `NODE_OPTIONS` heap or
+       * worker count that was clamped to the budget. Absent for other tools.
+       */
+      resources?: HeavyToolResourcePlan;
     }
   | { kind: 'url'; url: string }
   | { kind: 'note'; note: string }
@@ -532,6 +540,12 @@ export type EvidenceAtom =
        * vouches for a PR that was not itself green.
        */
       descendantPrHeadSha?: string;
+      /**
+       * The PR edited a pinned workflow, so only default-branch `push` runs
+       * attested it; its own `pull_request` runs (which ran the edited
+       * workflow) were never consulted, and none is re-checked (T13174).
+       */
+      mainOnly?: boolean;
       /** Task the PR was verified to be linked to (T12634). */
       taskId?: string;
       /** Component PR the task is linked through; its CI ran as this integration PR's (T12671). */