@cleocode/contracts 2026.10.4 → 2026.10.5

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

@@ -119,6 +119,34 @@ function rulePending(task: string): SyncWriteInvariantPending {
   return { task, reason: 'the typed merge-rule registry does not define it yet (T12344 item)' };
 }
 
+/** Where every implemented typed merge rule is enforced at apply (T12344). */
+const MERGE_ENGINE_GATE = {
+  module: 'packages/core/src/store/sync/merge/engine.ts',
+  functionName: 'applyOp',
+} as const;
+
+/**
+ * A typed merge rule the merge-rule registry defines (`SYNC_MERGE_RULES`),
+ * enforced by the merge engine on every applied op: no longer pending.
+ */
+function implemented(entry: SyncWriteInvariant): SyncWriteInvariant {
+  const { pending: _pending, ...rest } = entry;
+  return { ...rest, runtimeGate: MERGE_ENGINE_GATE };
+}
+
+/** A post-apply check the apply runs (T12344 PR-5): no longer pending. */
+function implementedCheck(entry: SyncWriteInvariant, functionName: string): SyncWriteInvariant {
+  const { pending: _pending, ...rest } = entry;
+  return {
+    ...rest,
+    check: {
+      module: 'packages/core/src/store/sync/apply/post-apply.ts',
+      functionName,
+      footprint: entry.check?.footprint ?? [],
+    },
+  };
+}
+
 function trigger(
   id: string,
   tables: readonly string[],
@@ -256,13 +284,16 @@ export const SYNC_WRITE_INVARIANTS: readonly SyncWriteInvariant[] = Object.freez
   ),
 
   // §3.6.5: post-apply check families (T12344 items).
-  pac(
-    'task.tree.shape',
-    'PAC-01',
-    'T12922',
-    ['tasks_tasks'],
-    ['rows with a changed parent_id or type', 'their direct children and ancestor chain'],
-    'saga→epic→task→subtask matrix, non-saga has a parent, depth ≤ 3, no self-parent',
+  implementedCheck(
+    pac(
+      'task.tree.shape',
+      'PAC-01',
+      'T12922',
+      ['tasks_tasks'],
+      ['rows with a changed parent_id or type', 'their direct children and ancestor chain'],
+      'saga→epic→task→subtask matrix, non-saga has a parent, depth ≤ 3, no self-parent',
+    ),
+    'checkTaskTreeShape',
   ),
   pac(
     'task.terminal-parent.live-children',
@@ -272,13 +303,12 @@ export const SYNC_WRITE_INVARIANTS: readonly SyncWriteInvariant[] = Object.freez
     ['rows whose status, stage or parent changed', 'their parent and siblings'],
     'no terminal parent with a live child; epic stage ≥ children; rollup re-evaluated',
   ),
-  pac(
+  trigger(
     'task.dependency.graph',
-    'PAC-03',
-    'T12924',
     ['tasks_task_dependencies', 'tasks_tasks'],
-    ['dependency edges inserted in the page', 'reachability from each depends_on'],
-    'dependencies are acyclic, with no self-edge',
+    ['tasks_task_dependencies_cycle_guard_insert', 'tasks_task_dependencies_cycle_guard_update'],
+    ['PAC-03'],
+    'dependencies are acyclic, with no self-edge: enforced by the T12886 cycle guards on apply (a guard conflict)',
   ),
   pac(
     'task.done.evidence',
@@ -368,39 +398,48 @@ export const SYNC_WRITE_INVARIANTS: readonly SyncWriteInvariant[] = Object.freez
     ['the owning rows'],
     'derived counters and cross-column facts agree with their rows',
   ),
-  pac(
-    'apply.preconditions',
-    'PAC-15',
-    'T12936',
-    ['tasks_tasks'],
-    ['the whole page'],
-    'no apply while the local twin collapse has failed; restore is a re-baseline',
+  implementedCheck(
+    pac(
+      'apply.preconditions',
+      'PAC-15',
+      'T12936',
+      ['tasks_tasks'],
+      ['the whole page'],
+      'no apply while the local twin collapse has failed; restore is a re-baseline',
+    ),
+    'checkApplyPreconditions',
   ),
 
   // §3.6.6: typed merge rules (T12344).
-  rule(
-    'task.status.absorbing',
-    'T12937',
-    'tasks_tasks',
-    ['status', 'completed_at', 'cancelled_at', 'cancellation_reason', 'pipeline_stage'],
-    ['V18', 'V20', 'C22', 'P40', 'P46', 'P47'],
-    'done, cancelled and archived are absorbing; leaving them needs an explicit op',
-  ),
-  rule(
-    'task.pipeline-stage.max',
-    'T12938',
-    'tasks_tasks',
-    ['pipeline_stage'],
-    ['V21', 'C20', 'P01', 'F3'],
-    'pipeline_stage is the maximum by STAGE_ORDER, except an explicit restore',
-  ),
-  rule(
-    'task.verification.frozen-on-done',
-    'T12939',
-    'tasks_tasks',
-    ['verification_json'],
-    ['C01', 'C02', 'C03', 'C17'],
-    'verification is frozen once done; otherwise merged per gate',
+  implemented(
+    rule(
+      'task.status.absorbing',
+      'T12937',
+      'tasks_tasks',
+      ['status', 'completed_at', 'cancelled_at', 'cancellation_reason', 'pipeline_stage'],
+      ['V18', 'V20', 'C22', 'P40', 'P46', 'P47'],
+      'done, cancelled and archived are absorbing; leaving them needs an explicit op',
+    ),
+  ),
+  implemented(
+    rule(
+      'task.pipeline-stage.max',
+      'T12938',
+      'tasks_tasks',
+      ['pipeline_stage'],
+      ['V21', 'C20', 'P01', 'F3'],
+      'pipeline_stage is the maximum by STAGE_ORDER, except an explicit restore',
+    ),
+  ),
+  implemented(
+    rule(
+      'task.verification.frozen-on-done',
+      'T12939',
+      'tasks_tasks',
+      ['verification_json'],
+      ['C01', 'C02', 'C03', 'C17'],
+      'verification is frozen once done; otherwise merged per gate',
+    ),
   ),
   rule(
     'session.status.terminal',

package/src/ledger/index.ts

@@ -0,0 +1,141 @@
+/**
+ * `@cleocode/contracts/ledger`: the decoded change-journal transaction and op
+ * shapes (journal spec `t12342-t12343-journal-design` §2.6).
+ *
+ * A sealed segment carries an array of {@link LedgerTxn}; each transaction
+ * carries {@link LedgerOp}s on sync-set rows, keyed by row uid. Values use the
+ * canonical typed wire encoding ({@link LedgerWireValue}), and counter deltas
+ * travel as `{ $inc }` ({@link LedgerValue}).
+ *
+ * Zod schemas, inferred types and const data only (arch gate 10). The sealer
+ * that produces these shapes and the merge engine that applies them live in
+ * `@cleocode/core` (`store/sync/`).
+ *
+ * @module ledger
+ * @task T12344
+ * @epic T12323
+ */
+
+import { z } from 'zod';
+import { Hlc } from '../cloud/ids.js';
+
+/** The transaction format version this build writes and reads (`LedgerTxn.v`). */
+export const LEDGER_TXN_VERSION = 1;
+
+/**
+ * A typed wire value: a string, null, a safe integer, or a typed escape for an
+ * integer beyond 2^53 (`$i`), a REAL (`$r`, `%!.17g` text, `Inf` accepted) or a
+ * BLOB (`$b`, base64).
+ */
+export const LedgerWireValue = z.union([
+  z.string(),
+  z.number(),
+  z.null(),
+  z.object({ $i: z.string() }).strict(),
+  z.object({ $r: z.string() }).strict(),
+  z.object({ $b: z.string() }).strict(),
+]);
+export type LedgerWireValue = z.infer<typeof LedgerWireValue>;
+
+/** A counter delta (`SYNC_COUNTER_COLUMNS`): applied by summing, never by plain LWW. */
+export const LedgerIncrement = z.object({ $inc: z.number() }).strict();
+export type LedgerIncrement = z.infer<typeof LedgerIncrement>;
+
+/** An after-value: a wire value or a counter delta. */
+export const LedgerValue = z.union([LedgerWireValue, LedgerIncrement]);
+export type LedgerValue = z.infer<typeof LedgerValue>;
+
+/** The op kinds: insert, update, delete, re-key. */
+export const LedgerOpKind = z.enum(['I', 'U', 'D', 'K']);
+export type LedgerOpKind = z.infer<typeof LedgerOpKind>;
+
+/** One op on one sync-set row (§2.6). */
+export const LedgerOp = z
+  .object({
+    /** Table. */
+    t: z.string().min(1),
+    /** Row uid; for K the OLD uid. */
+    u: z.string().min(1),
+    o: LedgerOpKind,
+    /** The op's HLC; also every field's HLC unless `fh` names a different one. */
+    h: Hlc,
+    /** K only: the new uid. */
+    nu: z.string().min(1).optional(),
+    /** birth_fp, on every op of a minted row; for K, the new value. */
+    bfp: z.string().optional(),
+    /** K only: the old birth_fp. */
+    obfp: z.string().optional(),
+    /** Per-field HLCs where they differ from `h`. */
+    fh: z.record(z.string(), Hlc).optional(),
+    /** Natural rows: the key, with refs as uids. */
+    k: z.record(z.string(), LedgerValue).optional(),
+    /** After-values (refs as uids; counters as `{ $inc }`). */
+    a: z.record(z.string(), LedgerValue).optional(),
+    /** Before-image (secrets excluded). */
+    b: z.record(z.string(), LedgerWireValue).optional(),
+  })
+  .strict()
+  .refine((op) => (op.o === 'K') === (op.nu !== undefined), {
+    message: 'nu is required on a K op and only there',
+  });
+export type LedgerOp = z.infer<typeof LedgerOp>;
+
+/** Who wrote a transaction; `op` names the command (e.g. `tasks.reopen`). */
+export const LedgerActor = z
+  .object({
+    agent: z.string().optional(),
+    session: z.string().optional(),
+    op: z.string().optional(),
+  })
+  .strict();
+export type LedgerActor = z.infer<typeof LedgerActor>;
+
+/** How a transaction's writes reached the store. */
+export const LedgerTxnVia = z.enum(['accessor', 'connection', 'foreign', 'repair', 'rebind']);
+export type LedgerTxnVia = z.infer<typeof LedgerTxnVia>;
+
+/** What a transaction is for. */
+export const LedgerTxnKind = z.enum([
+  'write',
+  'remint',
+  'rekey',
+  'repair',
+  'exodus',
+  'import',
+  'retire',
+]);
+export type LedgerTxnKind = z.infer<typeof LedgerTxnKind>;
+
+/**
+ * One sealed transaction (§2.6). `v` is checked by the receiver, not by this
+ * schema, so a newer format is refused with an explicit error rather than a
+ * parse failure.
+ */
+export const LedgerTxn = z
+  .object({
+    v: z.number().int().positive(),
+    /** `${replicaId}:${localTxnSeq}`. */
+    txn: z.string().min(1),
+    /** Only for split oversized groups: [part, of]. */
+    part: z.tuple([z.number().int().positive(), z.number().int().positive()]).optional(),
+    hlc: Hlc,
+    /** Merge key is (project, uid). */
+    project: z.string().nullable(),
+    scope: z.enum(['project', 'global']),
+    via: LedgerTxnVia,
+    kind: LedgerTxnKind,
+    actor: LedgerActor.nullable(),
+    ops: z.array(LedgerOp),
+    retire: z
+      .object({
+        replica: z.string(),
+        successor: z.string(),
+        lastReplicaSeq: z.number().int().nonnegative(),
+      })
+      .strict()
+      .optional(),
+    /** Ed25519 over the transaction signing message (§2.8). */
+    sig: z.string(),
+  })
+  .strict();
+export type LedgerTxn = z.infer<typeof LedgerTxn>;

package/src/nexus-account.ts

@@ -410,6 +410,15 @@ export interface NexusProjectLinkResult {
    * text is also in {@link NexusProjectLinkResult.warnings}.
    */
   attachError: { code: string; message: string; fix: string | null } | null;
+  /**
+   * The project data key version the server holds from this registration
+   * (onboarding B): `1` when the link sent a new project's first key with it,
+   * `null` when it sent none (the project already existed, the server does
+   * not take keys at registration, or this device has no account key; see
+   * {@link NexusProjectLinkResult.warnings}). With `null`, the first
+   * `cleo cloud push` creates the key.
+   */
+  initialKeyVersion: number | null;
   /** Non-fatal problems (for example, presence could not be sent). */
   warnings: string[];
 }

package/src/nexus-cloud.ts

@@ -264,10 +264,21 @@ export const nexusCloudStatusCheckSchema = z.object({
   detail: z.string(),
 });
 
+/**
+ * The E3 `features` entry of a server whose `POST /v1/projects` stores `initialKey`, a new project's
+ * first data key (onboarding B, cleo-nexus T095). `cleo project link` sends a key only to such a server.
+ */
+export const NEXUS_FEATURE_PROJECT_INITIAL_KEY = 'project.initial-key';
+
 /** `NexusStatus` (E3 `GET /v1/status`). */
 export const nexusCloudStatusSchema = z.object({
   serverTime: isoTime.optional(),
   apiVersion: z.string().optional(),
+  /**
+   * Optional server features (e.g. {@link NEXUS_FEATURE_PROJECT_INITIAL_KEY}). Absent from servers older
+   * than the list, which therefore support none of them.
+   */
+  features: z.array(z.string()).optional(),
   user: nexusCloudUserSchema,
   credential: nexusCloudCredentialSchema,
   device: nexusCloudDeviceSchema.nullable(),
@@ -393,6 +404,23 @@ export interface CloudProjectsResult {
   warnings: CloudWarning[];
 }
 
+/**
+ * A replica this device retired: the store file it named was replaced (a
+ * vault restore or pull) or rolled back, so a new replica took its place
+ * (journal spec §1.5). The server lists it as history until S4's signed
+ * `retire` transaction announces it (T13109).
+ */
+export interface CloudRetiredReplica {
+  /** The retired replica id. */
+  replicaId: string;
+  /** The replica that replaced it. */
+  successor: string;
+  /** When it was retired on this device. */
+  retiredAt: string;
+  /** The rebind reason(s), e.g. `vault-restore`; `null` when not recorded. */
+  reason: string | null;
+}
+
 /** `cleo cloud projects show [<id>]` (operation `cloud.projects.show`). */
 export interface CloudProjectShowResult extends NexusCloudProjectDetail {
   /** API origin asked. */
@@ -406,6 +434,8 @@ export interface CloudProjectShowResult extends NexusCloudProjectDetail {
    * fetched from E15 and `replicas` holds them all (up to the page budget).
    */
   replicaPaging: CloudPaging;
+  /** Listed replicas this device retired (from its local registry), newest first. */
+  retiredHere: CloudRetiredReplica[];
   /** Non-fatal problems. */
   warnings: CloudWarning[];
 }
@@ -448,6 +478,11 @@ export interface CloudStatusLocal {
   projectId: string | null;
   /** The active replica id of the current project's store (read-only; never bound here). */
   replicaId: string | null;
+  /**
+   * Earlier replicas of the current project's store that this device retired
+   * (from its local registry), newest first: the server still lists them.
+   */
+  retiredReplicas: CloudRetiredReplica[];
   /** `.cleo/nexus-link.json` when it holds an entry for the origin, else `null`. */
   linkPath: string | null;
   /** The device credential store (`nexus-device.json`). */
@@ -455,6 +490,25 @@ export interface CloudStatusLocal {
 }
 
 /** `CloudStatusResult` (§4.4): the data of the `cloud.status` envelope. */
+/**
+ * One device holding the project, as `cleo cloud status` lists it (T13290):
+ * a replica row reduced to who holds it and whether its presence is fresh.
+ */
+export interface CloudStatusHolder {
+  /** Nexus device id. */
+  deviceId: string;
+  /** The device's display name. */
+  deviceName: string;
+  /** The replica this device holds. */
+  replicaId: string;
+  /** Last presence report, or `null` when it never reported. */
+  presenceAt: string | null;
+  /** Presence within {@link NEXUS_PRESENCE_FRESH_SECONDS}. */
+  fresh: boolean;
+  /** This machine's own device. */
+  thisDevice: boolean;
+}
+
 export interface CloudStatusResult {
   /** The remote verdict, downgraded by local facts the server cannot see. */
   verdict: CloudStatusVerdict;
@@ -466,10 +520,140 @@ export interface CloudStatusResult {
   remote: NexusCloudStatus | null;
   /** This device's global store on the account's home stream (T12952); absent when not signed in. */
   global?: CloudStatusGlobalStore;
+  /**
+   * The local sync journal of each store this machine holds (T12998): the
+   * project store and the global store. Read on every path (signed in or not,
+   * online or offline); absent when no store could be read.
+   */
+  sync?: CloudStatusSync;
+  /**
+   * The devices holding the project (T13290), from the replica list; absent
+   * when there is no registered project to ask about or the list failed (a
+   * warning says so). Additive: older readers ignore it.
+   */
+  holders?: CloudStatusHolder[];
   /** Non-fatal problems. */
   warnings: CloudWarning[];
 }
 
+/**
+ * A sync fact this build cannot know yet, and why (T12998). The block's shape
+ * is fixed now, so the fields keep their names when the outbox (T12343) and
+ * segment push (S4) fill them in.
+ */
+export interface CloudSyncUnknown {
+  readonly known: false;
+  /** What is missing: the transactional outbox (T12343) or segment push/pull (S4). */
+  readonly needs: 'T12343' | 'S4';
+  /** One sentence for the operator. */
+  readonly reason: string;
+}
+
+/** A sync fact this build knows. */
+export interface CloudSyncKnown<T> {
+  readonly known: true;
+  readonly value: T;
+}
+
+/** A sync fact: known, or unknown with the reason (T12998). */
+export type CloudSyncFact<T> = CloudSyncKnown<T> | CloudSyncUnknown;
+
+/** The sync flags of a store (`_sync_meta`; all off when the journal is absent). */
+export interface CloudSyncFlags {
+  readonly capture: boolean;
+  readonly seal: boolean;
+  readonly push: boolean;
+  readonly pull: boolean;
+  readonly strict: boolean;
+}
+
+/** How far a stream lags the server. */
+export interface CloudSyncLag {
+  /** Ops on the server this store has not pulled, plus ops here not yet pushed. */
+  readonly ops: number;
+  /** Age of the oldest op not yet exchanged, in milliseconds. */
+  readonly ms: number;
+}
+
+/** One store's local sync journal, as `cleo cloud status` reports it (T12998). Read-only. */
+/** A local write a sync rebase holds unreplayed until its echo is decided (journal spec §3.5 Rule 5). */
+export interface CloudStatusHeldRow {
+  /** The table it writes. */
+  readonly table: string;
+  /** The row's uid. */
+  readonly uid: string;
+  /** The local transaction it belongs to. */
+  readonly txn: string;
+  /** When it was held (ISO-8601). */
+  readonly heldAt: string;
+  /** What refused its replay: the conflict preview. */
+  readonly reason: string;
+}
+
+/** `CloudStatusSyncStream.held`: the store's held writes (§3.5 Rule 5). */
+export interface CloudStatusHeld {
+  /** How many local ops are held. */
+  readonly count: number;
+  /** When the oldest was held (ISO-8601), or `null` when none is. */
+  readonly oldestAt: string | null;
+  /** Holds older than `warnDays`, oldest first (`cleo doctor sync-journal` lists the same). */
+  readonly long: readonly CloudStatusHeldRow[];
+  /** The age, in days, past which a hold is long. */
+  readonly warnDays: number;
+}
+
+export interface CloudStatusSyncStream {
+  /** Which store. */
+  readonly scope: 'project' | 'global';
+  /** Its stream (`project:<id>`, `home:<userId>`) when known locally, else `null`. */
+  readonly stream: string | null;
+  /** The store file. */
+  readonly dbPath: string;
+  /** The sync journal tables are installed in this store. */
+  readonly journalInstalled: boolean;
+  /** The store's sync flags. */
+  readonly flags: CloudSyncFlags;
+  /** Captured changes not yet sealed into ops (`_sync_capture` live rows). */
+  readonly unsealedOps: number;
+  /** When the oldest unsealed change was captured (epoch ms), or `null`. */
+  readonly oldestUnsealedAtMs: number | null;
+  /** The highest sealed local sequence (`_sync_txn.local_seq`), or `null` before the first seal. */
+  readonly lastSealedSeq: number | null;
+  /** Captures the sealer could not read and holds aside (`_sync_quarantine`), per table. */
+  readonly quarantined: Readonly<Record<string, number>>;
+  /** Tables marked suspect until a repair re-emits them. */
+  readonly suspectTables: readonly string[];
+  /** Local writes a sync rebase holds, until their echo is decided (§3.5 Rule 5). */
+  readonly held: CloudStatusHeld;
+  /** Sealed ops not yet handed to the outbox for sending. */
+  readonly unsentOps: CloudSyncFact<number>;
+  /** The last sequence this store pushed to the server. */
+  readonly lastPushedSeq: CloudSyncFact<number>;
+  /** The last server sequence this store pulled. */
+  readonly lastPulledSeq: CloudSyncFact<number>;
+  /** The server's head sequence for this stream. */
+  readonly serverHeadSeq: CloudSyncFact<number>;
+  /** Devices attached to this stream and when each last synced. */
+  readonly devices: CloudSyncFact<
+    ReadonlyArray<{ readonly deviceId: string; readonly lastSyncAt: string | null }>
+  >;
+  /** Conflicts held open on this stream. */
+  readonly openConflicts: CloudSyncFact<number>;
+  /** How far this store lags the server. */
+  readonly lag: CloudSyncFact<CloudSyncLag>;
+}
+
+/** `CloudStatusResult.sync` (T12998). */
+export interface CloudStatusSync {
+  /** One entry per store this machine holds (project, then global), when its file exists. */
+  readonly streams: readonly CloudStatusSyncStream[];
+  /**
+   * This build reads the local journal only; the server-side fields stay
+   * unknown until the outbox (T12343) and segment push/pull (S4) land.
+   */
+  readonly partial: true;
+}
+
 /** `cleo cloud status`: this device's global store (the main brain) on Cleo Nexus (T12952). */
 export interface CloudStatusGlobalStore {
   /** The server lists home-stream replicas. */
@@ -492,6 +676,8 @@ export interface CloudStatusOfflineDetails {
   summary: CloudStatusSummary;
   /** Warnings collected before the server stopped answering. */
   warnings: CloudWarning[];
+  /** The local sync journal, read before the server was asked (T12998). */
+  sync?: CloudStatusSync;
 }
 
 // ---------- error mapping (§4.0.4) ----------