@cleocode/contracts 2026.9.23 → 2026.9.25

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/session.ts

@@ -132,6 +132,17 @@ export interface Session {
    * @defaultValue undefined
    */
   parentSessionId?: string | null;
+  /**
+   * ID of the orchestrator session that SPAWNED this one, recorded by the
+   * spawn itself (T12502). Unlike {@link Session.parentSessionId}, which a
+   * process declares for itself at `session start`, only the spawn writes
+   * this edge, so the task-claim chokepoint trusts it to let a spawn family
+   * pass a live lease between its members. Read-only on the session record:
+   * the whole-row session upsert never writes it.
+   *
+   * @defaultValue undefined
+   */
+  spawnedBySessionId?: string | null;
   /** Provider-specific agent identifier string. @defaultValue undefined */
   agentIdentifier?: string | null;
   /** ISO 8601 timestamp of when the handoff was consumed. @defaultValue undefined */
@@ -233,9 +244,16 @@ export class SessionView {
     return this._sessions.length;
   }
 
-  /** Find the currently active session (if any). */
+  /**
+   * First `active` session in THIS collection — a scan over the rows the
+   * caller loaded, NOT the caller's own session (T12500). With several agents
+   * active it names an arbitrary one of them.
+   *
+   * @deprecated For "my session" use `resolveBoundSession` (mutations) or
+   *   `resolveSessionForRead` (reads, labels an unbound guess).
+   */
   findActive(): Session | undefined {
-    return this._sessions.find((s) => s.status === 'active');
+    return this._sessions.find((s) => s.status === 'active'); // get-active-session-allowed: collection scan over caller-supplied rows, not identity (T12500)
   }
 
   /** Find a session by ID. */

package/src/task.ts

@@ -435,8 +435,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). */
@@ -723,9 +743,22 @@ export interface Task {
    */
   pipelineStage?: string | null;
 
-  /** Agent ID that has claimed/is assigned to this task. Null when unclaimed. @defaultValue undefined */
+  /**
+   * First-class human / owner assignee (`cleo assignee`, Studio boards).
+   * Separate from the agent work lease in {@link Task.claim}: `cleo start`,
+   * `cleo claim` and spawn never write it (T12502). @defaultValue undefined
+   */
   assignee?: string | null;
 
+  /**
+   * The agent work lease held on this task, when one is recorded (T12502).
+   * Absent when the task is unclaimed. Distinct from the human
+   * {@link Task.assignee}. Read-only on the task object: full-row writes
+   * never carry it, only the claim chokepoint changes it.
+   * @defaultValue undefined
+   */
+  claim?: TaskClaim;
+
   /**
    * Abort reason when a worker was stopped due to runaway detection (T1658).
    *
@@ -1020,3 +1053,26 @@ export interface TaskWorkState {
   /** ID of the primary session managing this work state. @defaultValue undefined */
   primarySession?: string | null;
 }
+
+/**
+ * A leased agent claim on a task (T12502 · epic T12497).
+ *
+ * Taken by `cleo start`, `cleo claim` and spawn with a compare-and-set in the
+ * same write transaction; renewed by the holder session's activity or
+ * `cleo claim <id> --renew`; released by `cleo stop`, completion,
+ * cancellation, archive and the holder session ending. A claim whose
+ * `leaseExpiresAt` has passed stays recorded until another session takes it
+ * over explicitly (`--take-over`, audited).
+ *
+ * @task T12502
+ */
+export interface TaskClaim {
+  /** Session holding the lease. */
+  sessionId: string;
+  /** Agent identity of the holder (`CLEO_AGENT_ID` / spawn handle), or `null`. */
+  agentId: string | null;
+  /** ISO-8601 UTC instant the lease was taken. */
+  claimedAt: string;
+  /** ISO-8601 UTC instant the lease lapses unless renewed. */
+  leaseExpiresAt: string;
+}

package/src/tools/score-task-priority.ts

@@ -26,7 +26,7 @@ export interface ScoreTaskInput {
   labels?: string[];
   /** Severity axis (orthogonal to priority); unset for most tasks. */
   severity?: TaskSeverity | null;
-  /** Kind axis; a `bug` with no severity is scored at the default bug severity (T12661). */
+  /** Kind axis; not part of the order — an unset severity is unknown, never imputed from `kind` (D11161). */
   kind?: TaskKind | null;
 }