@cleocode/contracts 2026.9.24 → 2026.9.26

package/src/data-accessor.ts

@@ -193,6 +193,14 @@ export interface AcRow {
   updatedAt: string | null;
   /** Optional sha256(text) snapshot; writers MAY populate, readers MUST treat null as "unknown". */
   contentHash: string | null;
+  /**
+   * Row uid (T12341): the criterion's identity across devices and across edits
+   * (`id` changes with the text; `uid` does not). `null` until the store fills
+   * it; absent from accessors that predate it.
+   */
+  uid?: string | null;
+  /** Birth fingerprint (T12341): write-once, carried with the uid across edits. */
+  birthFp?: string | null;
 }
 
 /** Machine-readable AC child-projection drift codes for doctor/audit output. */
@@ -264,6 +272,12 @@ export interface AcBindingRow {
   bindingType: 'direct' | 'satisfies' | 'coverage';
   /** ISO-8601 timestamp of binding creation. */
   createdAt: string;
+  /**
+   * The evidence was recorded against a different text of this criterion
+   * (T12341): the criterion kept its identity through an edit, but no gate may
+   * count this binding until the evidence is re-verified. Absent means valid.
+   */
+  stale?: boolean;
 }
 
 /** Query options for bounded reads from the append-only task audit log. @task T10594 */
@@ -459,13 +473,50 @@ export interface TaskConflictDetails {
  * Subset of DataAccessor methods available inside a transaction callback.
  * Write-only — reads use the outer accessor (snapshot isolation).
  */
+/**
+ * How {@link TransactionAccessor.insertNewTask} gives a task its row identity
+ * (T12341 spec §5.1, T12806).
+ *
+ * - `new` (the default): the task is created now; it gets a random UUIDv7.
+ * - `imported`: the task existed before this write (import, snapshot
+ *   restore). It carries `uid` / `birthFp` when the source has them and no
+ *   other row holds that uid; otherwise its uid is left NULL, so the
+ *   deterministic recipe derives it from the row's own key and birth. An
+ *   import never stamps an import-time uid.
+ */
+export interface TaskInsertIdentity {
+  readonly origin: 'new' | 'imported';
+  /** The uid the source row carried, when it carried one. */
+  readonly uid?: string | null;
+  /** The birth fingerprint that goes with `uid`. */
+  readonly birthFp?: string | null;
+}
+
+/** A task's row identity (T12341): `uid` and `birthFp`, NULL until filled. */
+export interface TaskRowIdentity {
+  readonly id: string;
+  readonly uid: string | null;
+  readonly birthFp: string | null;
+}
+
 export interface TransactionAccessor {
   upsertSingleTask(task: Task): Promise<void>;
   /**
    * Insert a NEW task; never overwrites. Throws `ID_COLLISION` when the id is
-   * already stored (T12724).
+   * already stored (T12724). `identity` says whether the task is new or
+   * imported ({@link TaskInsertIdentity}, T12806).
    */
-  insertNewTask(task: Task): Promise<void>;
+  insertNewTask(task: Task, identity?: TaskInsertIdentity): Promise<void>;
+  /**
+   * Settle a task's row identity after an overwrite import replaced it (call
+   * it after `upsertSingleTask` in the same transaction). The same task (same
+   * birth as before the overwrite) keeps its identity; a different one is
+   * re-derived, and the history and bindings of its criteria are re-keyed so
+   * their evidence keeps resolving. Refuses (`E_VALIDATION`) once identity
+   * values are shared with other devices: there the overwrite would silently
+   * re-point a shared uid at different work (T12806).
+   */
+  clearTaskIdentity?(taskId: string): Promise<void>;
   archiveSingleTask(taskId: string, fields: ArchiveFields): Promise<void>;
   removeSingleTask(taskId: string): Promise<void>;
   setMetaValue(key: string, value: unknown): Promise<void>;
@@ -501,6 +552,10 @@ export interface TransactionAccessor {
       targetTaskId?: string | null;
       projection?: string;
       contentHash?: string | null;
+      /** Row uid to keep (T12341); omitted → a new uid is minted. */
+      uid?: string | null;
+      /** Birth fingerprint to keep with the uid (T12341). */
+      birthFp?: string | null;
     }>,
   ): Promise<void>;
   /**
@@ -516,13 +571,48 @@ export interface TransactionAccessor {
    * @task T10508
    */
   deleteAcRowsForTask(taskId: string): Promise<void>;
+  /**
+   * Delete only the named AC rows of `taskId` (rows of other tasks are never
+   * touched). Used by the diff apply path so ACs that survive an edit keep
+   * their row — and therefore their evidence bindings.
+   *
+   * `keepBindingsForUids`: uids the same write carries onto new rows (an
+   * edited criterion keeps its uid, T12341); their bindings are kept, as
+   * stale evidence, instead of pruned.
+   * @task T12789
+   */
+  deleteAcRowsByIds(
+    taskId: string,
+    ids: readonly string[],
+    keepBindingsForUids?: readonly string[],
+  ): Promise<void>;
+  /**
+   * Update existing AC rows of their own task in place, keyed by `(id, taskId)`.
+   * Every mutable column is rewritten from the supplied row; `id` and
+   * `taskId` are never changed. A row that does not exist for that task is
+   * an error, never an insert.
+   * @task T12789
+   */
+  updateAcRows(
+    rows: Array<{
+      id: string;
+      taskId: string;
+      ordinal: number;
+      text: string;
+      kind?: 'text' | 'child_task' | 'evidence_bound';
+      sourceKey?: string;
+      targetTaskId?: string | null;
+      projection?: string;
+      contentHash?: string | null;
+    }>,
+  ): Promise<void>;
   /**
    * Append a history row to `task_acceptance_criteria_history` capturing the
    * AC text that is about to be superseded.
    * @task T10508
    */
   appendAcHistory(
-    rows: Array<{ acId: string; previousText: string; reason: string }>,
+    rows: Array<{ acId: string; previousText: string; reason: string; acUid?: string | null }>,
   ): Promise<void>;
   /**
    * Read all `evidence_ac_bindings` rows whose `ac_id` ∈ the given set.
@@ -554,6 +644,16 @@ export interface TransactionAccessor {
       bindingType: 'direct' | 'satisfies' | 'coverage';
     }>,
   ): Promise<void>;
+  /**
+   * Delete every `evidence_ac_bindings` row whose `ac_id` names no AC row
+   * (bindings left behind before AC removal pruned them), recording each
+   * removed row in the task audit log (`ac.bindings.pruned`) first. Backs
+   * `cleo doctor ac-bindings --fix`.
+   *
+   * @returns the removed bindings
+   * @task T12790
+   */
+  pruneOrphanAcBindings(): Promise<AcBindingRow[]>;
 }
 
 // Re-export AcRow at the module level for both transaction + outer accessor use.
@@ -606,9 +706,15 @@ export interface DataAccessor {
   /**
    * Insert a NEW task under a freshly allocated or computed id. Never
    * overwrites: throws `ID_COLLISION` when the id is already stored, and
-   * writes nothing (T12724).
+   * writes nothing (T12724). `identity`: {@link TaskInsertIdentity} (T12806).
+   */
+  insertNewTask(task: Task, identity?: TaskInsertIdentity): Promise<void>;
+
+  /**
+   * Row identities of the named tasks (archived included); a task without a
+   * row is omitted (T12806: a snapshot carries them).
    */
-  insertNewTask(task: Task): Promise<void>;
+  getTaskIdentities?(taskIds: readonly string[]): Promise<TaskRowIdentity[]>;
 
   /** Archive a single task by ID (sets status='archived' + archive metadata). */
   archiveSingleTask(taskId: string, fields: ArchiveFields): Promise<void>;
@@ -645,6 +751,14 @@ export interface DataAccessor {
    */
   getAcBindings(acIds: readonly string[]): Promise<AcBindingRow[]>;
 
+  /**
+   * Read every `evidence_ac_bindings` row whose `ac_id` names no row of
+   * `task_acceptance_criteria` — a binding for an AC that no longer exists.
+   * Read-only; backs `cleo doctor ac-bindings`.
+   * @task T12790
+   */
+  findOrphanAcBindings(): Promise<AcBindingRow[]>;
+
   // ---- Metadata (schema_meta KV store) ----
 
   /** Read a typed value from the metadata store. Returns null if not found. */

package/src/exit-codes.ts

@@ -68,6 +68,15 @@ export enum ExitCode {
    * holder. @task T12506
    */
   WORKTREE_LOCKED = 25,
+  /**
+   * A guarded write (`--if-match`, or a claim holder's write) named a display
+   * id the task no longer carries: sync re-numbered it after a display-id
+   * collision (T12341), and the id now names another task or none. Writing
+   * would hit the wrong task, so the write refuses. LAFS code
+   * `E_TASK_RENAMED`; the details carry the task's current id
+   * (`details.expected`). @task T12800
+   */
+  TASK_RENAMED = 26,
 
   // === SESSION ERRORS (30-39) ===
   SESSION_EXISTS = 30,

package/src/index.ts

@@ -369,8 +369,10 @@ export type {
   TaskConflictChange,
   TaskConflictDetails,
   TaskFieldUpdates,
+  TaskInsertIdentity,
   TaskPopulation,
   TaskQueryFilters,
+  TaskRowIdentity,
   TaskWriteGuard,
   TransactionAccessor,
 } from './data-accessor.js';
@@ -2286,6 +2288,14 @@ export type {
   TaskRefPriority,
   TaskSummary,
 } from './results.js';
+// === Row Identity Types (T12341 — uid merge keys) ===
+export type {
+  RowIdentityKind,
+  RowIdentityRef,
+  RowIdentitySpec,
+  StoredRefUid,
+  SymmetricEdge,
+} from './row-identity.js';
 // === Scaffold + Diagnostic Result Types (SG-ARCH-SOLID T9831 / E-CONTRACTS-FOUNDATION T9832) ===
 export type {
   CheckResult,
@@ -2502,6 +2512,7 @@ export type {
   CriterionEvidenceLink,
   EpicLifecycle,
   EvidenceAtom,
+  EvidenceMergeAnchor,
   EvidenceValidationContext,
   FileMeta,
   GateEvidence,
@@ -2982,6 +2993,7 @@ export type {
   NexusAccountOrganization,
   NexusAccountStatus,
   NexusAccountUser,
+  NexusLoginDevice,
   NexusLoginResult,
   NexusLogoutResult,
   NexusProjectLink,

package/src/nexus-account.ts

@@ -46,6 +46,27 @@ export const NEXUS_ACCOUNT_ERROR_CODES = [
   'E_NEXUS_REQUEST_FAILED',
   'E_NEXUS_NOT_A_PROJECT',
   'E_NEXUS_INVALID_LABEL',
+  // Device credentials (cleo-nexus device contract §3.3, §4.0.4; T12868).
+  /** No answer from the API (network error or timeout). */
+  'E_NEXUS_UNREACHABLE',
+  /** `cleo login nexus` while a revoke of this device is unconfirmed (§3.3, v2.9). */
+  'E_NEXUS_REVOKE_PENDING',
+  /** The device was signed out (E9, E11): 401 `device-signed-out`. */
+  'E_NEXUS_DEVICE_SIGNED_OUT',
+  /** The device was revoked (E10, E12): 401 `device-revoked`. */
+  'E_NEXUS_DEVICE_REVOKED',
+  /** A credential replaced or revoked elsewhere, or a `rotation-conflict` (R2). */
+  'E_NEXUS_CREDENTIAL_COMPROMISED',
+  /** The device credential lacks the scope (a read-only device): 403 `insufficient-scope`. */
+  'E_NEXUS_INSUFFICIENT_SCOPE',
+  /** A replica attach from a second device: 409 `replica-copied`. */
+  'E_NEXUS_REPLICA_COPIED',
+  /** Another cleo process holds the device file or an upgrade in flight; retry. */
+  'E_NEXUS_BUSY',
+  /** Several accounts hold a device credential on one origin and none was named. */
+  'E_NEXUS_ACCOUNT_AMBIGUOUS',
+  /** An option that needs device credentials (`--read-only`) without `CLEO_NEXUS_DEVICE=1`. */
+  'E_NEXUS_DEVICE_REQUIRED',
 ] as const;
 
 /** One of {@link NEXUS_ACCOUNT_ERROR_CODES}. */
@@ -112,6 +133,20 @@ export interface NexusAccountStatus {
   summary: string;
 }
 
+/** The enrolled device, as `cleo login nexus` reports it (device contract §3.3 step 10). */
+export interface NexusLoginDevice {
+  /** The Nexus device id (UUIDv7, scoped to this CLEO home, origin and user). */
+  deviceId: string;
+  /** Display name the server holds. */
+  name: string;
+  /** Server-side state (`active` right after a login). */
+  state: string;
+  /** Credential profile: `device` or `read-only`. */
+  profile: string | null;
+  /** `true` when E1 created the device row, `false` when it re-enrolled it. */
+  created: boolean | null;
+}
+
 /** Result of `cleo login nexus` (never carries the token). */
 export interface NexusLoginResult {
   /** API origin the session belongs to. */
@@ -126,6 +161,10 @@ export interface NexusLoginResult {
   credentialsPath: string;
   /** Non-fatal problems, e.g. the account lookup failed after a good login. */
   warnings: string[];
+  /** The enrolled device; present only with `CLEO_NEXUS_DEVICE=1` (device credentials). */
+  device?: NexusLoginDevice;
+  /** Scopes of the stored device credential; present only with `CLEO_NEXUS_DEVICE=1`. */
+  scopes?: string[];
 }
 
 /** Result of `cleo logout nexus`. */

package/src/operations/output-contracts-data.ts

@@ -118,7 +118,7 @@ const tasksShowOutputContract: OperationOutputContract = {
           updatedAt: {
             type: ['string', 'null'],
             description:
-              'Task version for optimistic concurrency: pass it to `cleo update|complete --if-match`.',
+              'Task version for optimistic concurrency: pass it to `cleo update|complete --if-match`. A stale version fails with E_CONFLICT (23); E_TASK_RENAMED (26) when sync re-numbered the task you read (details.expected is its new id).',
           },
           // T12502: the human assignee and the agent claim lease are separate.
           assignee: {

package/src/operations/tasks.ts

@@ -1616,7 +1616,13 @@ export interface TasksUpdateQueryParams {
   /**
    * Optimistic-concurrency guard: the task `updatedAt` the caller read. When
    * the stored version differs, the update fails with `E_CONFLICT` and the
-   * current version, instead of overwriting a newer write. @task T12503
+   * current version, instead of overwriting a newer write. When sync
+   * re-numbered the task the caller read (a display-id collision) and the
+   * version is exactly the one it had under this id, the update fails with
+   * `E_TASK_RENAMED` (exit 26) instead, `details.expected` naming the task's
+   * new id; nothing is written to the task that holds the id now.
+   * @task T12503
+   * @task T12800
    */
   expectedUpdatedAt?: string;
 }
@@ -1702,8 +1708,11 @@ export interface TasksCompleteQueryParams {
   /**
    * Optimistic-concurrency guard (`--if-match`): the task `updatedAt` the
    * caller read. When the stored version differs, completion fails with
-   * `E_CONFLICT` carrying the current version and the changed fields.
+   * `E_CONFLICT` carrying the current version and the changed fields, or
+   * with `E_TASK_RENAMED` (exit 26, `details.expected` = the new id) when
+   * sync re-numbered the task the caller read.
    * @task T12503
+   * @task T12800
    */
   expectedUpdatedAt?: string;
 }

package/src/row-identity.ts

@@ -0,0 +1,132 @@
+/**
+ * Row identity contracts — the uid every syncing row carries as its merge key
+ * (T12341).
+ *
+ * A table whose Gate A class syncs (`portable-*`) gets a `uid` column. The
+ * local primary key stays the local key and local foreign keys keep pointing
+ * at it; the uid is what a merge compares. The registry that declares, per
+ * table, how its uid is made lives in core (`store/row-identity.ts`); this
+ * module holds only the shapes.
+ *
+ * Spec: `cleo docs fetch t12341-uid-scheme`.
+ *
+ * Types only (arch gate 10): no runtime values are exported from here.
+ *
+ * @task T12341
+ * @epic T12323
+ * @module row-identity
+ */
+
+/**
+ * How a table's uid is made.
+ *
+ * - `minted` — the local key was allocated on one device (`T####`, an
+ *   autoincrement integer, a random id), so equal keys on two devices may be
+ *   different rows. A new row gets a random UUIDv7; a row without a uid (an
+ *   existing row, or one an older build wrote) gets a deterministic v7-layout
+ *   uid over (table, key, birth, owner uids, content).
+ * - `natural` — the key is content or a relationship (an edge, a label), so
+ *   equal keys mean the same row everywhere. The uid is a UUIDv8 over the key
+ *   with every reference replaced by the referenced row's uid.
+ *
+ * @task T12341
+ */
+export type RowIdentityKind = 'minted' | 'natural';
+
+/**
+ * A column that holds another row's local key.
+ *
+ * @task T12341
+ */
+export interface RowIdentityRef {
+  /** Physical column in this table. */
+  readonly column: string;
+  /** Physical table the column points into (its single-column local key). */
+  readonly table: string;
+}
+
+/**
+ * A stored copy of a fact about a referenced row, taken when the row is
+ * written: its uid (`ac_uid`, kept because an AC id is derived from the AC
+ * text and changes on edit), or the hash of its text (`ac_text_hash`, the
+ * text the evidence was recorded against).
+ *
+ * @task T12341
+ */
+export interface StoredRefUid {
+  /** Physical column holding the copied fact (e.g. `ac_uid`). */
+  readonly column: string;
+  /** Column holding the referenced local key (e.g. `ac_id`). */
+  readonly from: string;
+  /** Referenced table. */
+  readonly table: string;
+  /** What is copied: the referenced row's uid (default) or the hash of its `text`. */
+  readonly source?: 'uid' | 'text_hash';
+}
+
+/**
+ * A relation table whose rows are symmetric for some values of a type column:
+ * the endpoint uids are hashed in sorted order, so `A related B` and
+ * `B related A` are one edge.
+ *
+ * @task T12341
+ */
+export interface SymmetricEdge {
+  /** Column holding the relation type. */
+  readonly column: string;
+  /** Type values that are symmetric; every other value keeps direction. */
+  readonly values: readonly string[];
+}
+
+/**
+ * How one syncing table carries its uid.
+ *
+ * @task T12341
+ */
+export interface RowIdentitySpec {
+  /** Physical table name. */
+  readonly table: string;
+  /** How the uid is made. */
+  readonly kind: RowIdentityKind;
+  /** Local key columns, in hash order. */
+  readonly key: readonly string[];
+  /** `minted`: the column recording when the row was created. */
+  readonly birth?: string;
+  /** `minted`: references whose target uid is part of the row's identity. */
+  readonly owners?: readonly RowIdentityRef[];
+  /**
+   * `minted`, append-only tables only: columns hashed into the uid. Their
+   * rows never change, and their keys collide across devices by construction.
+   */
+  readonly content?: readonly string[];
+  /** `natural`: key columns that reference rows; their target uid is hashed. */
+  readonly keyRefs?: readonly RowIdentityRef[];
+  /**
+   * `minted`: facts of the row's creation hashed into its birth fingerprint
+   * (`birth_fp`), besides the canonical birth. Each entry is a column name,
+   * `@ownerFp:<column>` (the birth fingerprint of the owner that column
+   * references, so the children of two colliding owners fingerprint apart),
+   * or `@refFp:<column>` (the fingerprint of the row a stored reference uid
+   * column names, e.g. the AC behind `ac_uid`).
+   * Read from the row as it is when its identity is first assigned; frozen
+   * per recipe version.
+   */
+  readonly birthFacts?: readonly string[];
+  /** `natural` relation tables: the symmetric relation types. */
+  readonly symmetric?: SymmetricEdge;
+  /**
+   * `minted`: every uid is random, never derived from content, including for
+   * existing rows. Required for `portable-secret` tables.
+   */
+  readonly randomOnly?: boolean;
+  /** Other references, translated to uids on the wire (not hashed). */
+  readonly refs?: readonly RowIdentityRef[];
+  /** JSON-array columns of referenced keys, translated element by element. */
+  readonly jsonArrayRefs?: readonly RowIdentityRef[];
+  /** Stored copies of referenced uids. */
+  readonly storedRefUids?: readonly StoredRefUid[];
+  /** The key is a user-facing display id that a collision re-mints. */
+  readonly displayId?: boolean;
+  /** Task that declared the table. */
+  readonly task: string;
+}

package/src/task.ts

@@ -160,6 +160,19 @@ export type VerificationGate =
    */
   | 'nexusImpact';
 
+/**
+ * The part of a verified `pr:` atom that anchors `files:` bytes: its merge
+ * commit, when it merged, and what it changed (T12848).
+ */
+export interface EvidenceMergeAnchor {
+  /** Merge commit SHA whose tree holds the PR's artifact bytes. */
+  mergeCommitSha: string;
+  /** ISO 8601 merge timestamp; the latest merge wins when several PRs changed a path. */
+  mergedAt: string;
+  /** Paths the PR changed. */
+  changedPaths?: readonly string[];
+}
+
 /** Task and criterion scope used while validating evidence, independent of PR metadata. */
 export interface EvidenceValidationContext {
   /** Canonical current task intent; prose is never interpreted as a file declaration. */
@@ -168,8 +181,22 @@ export interface EvidenceValidationContext {
   gates: readonly VerificationGate[];
   /** Canonical criteria read for this verification operation. */
   criteria: ReadonlyArray<Pick<AcRow, 'id' | 'text' | 'updatedAt'>>;
-  /** Verified PR merge whose immutable artifact bytes must be inspected. */
+  /**
+   * Verified PR merge whose immutable artifact bytes must be inspected.
+   *
+   * @deprecated Since T12848 no caller sets it: a single SHA cannot anchor a
+   * write with several `pr:` atoms. Use {@link EvidenceValidationContext.artifactPrs},
+   * which anchors each `files:` path at the merge of the PR that changed it.
+   * Still honoured when `artifactPrs` is absent.
+   */
   artifactCommitSha?: string;
+  /**
+   * Every verified PR in the evidence write (T12848). When non-empty, each
+   * `files:` path is inspected at the merge commit of the PR that changed it,
+   * so several `pr:` atoms in one write each anchor their own artifacts.
+   * Takes precedence over {@link EvidenceValidationContext.artifactCommitSha}.
+   */
+  artifactPrs?: ReadonlyArray<EvidenceMergeAnchor>;
   /**
    * Validate without persisting anything: `pr:`/`ci:` lookups write neither
    * the PR-result cache nor the branch-protection cache (T12671 review — the
@@ -435,8 +462,28 @@ export type EvidenceAtom =
         /** Event of the judged run (`push`, `pull_request`, …), when known. */
         event?: string;
       }>;
-      /** Tree of the merge commit — the content every recorded check tested. */
+      /** Tree of the merge commit — the content every check judged on it (or on a tree-equal PR head) tested. */
       testedTree?: string;
+      /**
+       * Later default-branch commit whose green `push` runs stood in for a
+       * required check the merge commit's own run only had cancelled or
+       * skipped (T12742). Its CI tested the DESCENDANT's tree, not the merge
+       * tree: it descends from the merge commit, and no commit in
+       * `descendantRange` — merge or not — touched the PR's changed files or a
+       * pinned CI workflow. Checks judged there record it as their `sha`.
+       */
+      descendantSha?: string;
+      /**
+       * `<mergeCommitSha>..<descendantSha>`: the first-parent range proven to
+       * leave the PR's files and the pinned workflows untouched (T12742).
+       */
+      descendantRange?: string;
+      /**
+       * Final PR head whose latest `pull_request` runs were green for every
+       * check the descendant stood in for (T12742); a descendant never
+       * vouches for a PR that was not itself green.
+       */
+      descendantPrHeadSha?: string;
       /** 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). */