@cleocode/core 2026.9.24 → 2026.9.25

package/dist/store/sync/schema.js

@@ -0,0 +1,130 @@
+/**
+ * The change journal's own schema, applied lazily.
+ *
+ * The DDL lives in `packages/core/migrations/sync-journal/<folder>/migration.sql`,
+ * one folder per migration, like the drizzle lineages. It is NOT a drizzle
+ * lineage: it runs only when a `sync.*` flag is first enabled on a store
+ * ({@link ensureSyncSchema}), so a store with every flag off (the default)
+ * never gains a table or a journal row. Applied folders are recorded in
+ * `_sync_meta` under `schema:<folder>` with the sha256 of the folder's SQL,
+ * never in `__drizzle_migrations`. A folder whose SQL changed after it was
+ * applied is refused with {@link SyncSchemaHashDriftError}, never skipped.
+ *
+ * @task T12342
+ * @module store/sync/schema
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveCorePackageMigrationsFolder } from '../resolve-migrations-folder.js';
+/** The migrations sub-directory that holds the sync schema. */
+export const SYNC_SCHEMA_SET = 'sync-journal';
+/** Key prefix under which `_sync_meta` records an applied schema folder. */
+const APPLIED_PREFIX = 'schema:';
+/**
+ * An applied sync schema folder whose SQL no longer matches what was applied
+ * (in the spirit of `E_MIGRATION_HASH_DRIFT`). Editing an applied folder is
+ * never correct: add a new folder instead.
+ */
+export class SyncSchemaHashDriftError extends Error {
+    folder;
+    applied;
+    current;
+    code = 'E_SYNC_SCHEMA_HASH_DRIFT';
+    constructor(folder, applied, current) {
+        super(`sync schema folder ${folder} was applied with sha256 ${applied}, but its SQL now hashes ` +
+            `to ${current}. An applied folder must never change; add a new folder instead.`);
+        this.folder = folder;
+        this.applied = applied;
+        this.current = current;
+        this.name = 'SyncSchemaHashDriftError';
+    }
+}
+const sha256 = (text) => createHash('sha256').update(text).digest('hex');
+/** Whether a table exists in the `main` schema. Read-only. */
+export function hasTable(db, table) {
+    return (db.prepare("SELECT 1 FROM main.sqlite_master WHERE type = 'table' AND name = ?").get(table) !==
+        undefined);
+}
+/** The sync schema folders, oldest first. */
+export function syncSchemaFolders(root = resolveCorePackageMigrationsFolder(SYNC_SCHEMA_SET)) {
+    if (!existsSync(root)) {
+        throw new Error(`sync schema folder not found: ${root}`);
+    }
+    return readdirSync(root, { withFileTypes: true })
+        .filter((d) => d.isDirectory() && existsSync(join(root, d.name, 'migration.sql')))
+        .map((d) => d.name)
+        .sort()
+        .map((name) => {
+        const sql = readFileSync(join(root, name, 'migration.sql'), 'utf8');
+        return { name, sql, hash: sha256(sql) };
+    });
+}
+/**
+ * The schema folders already applied to this store, with the sha256 each was
+ * applied with. Read-only: a store with no `_sync_meta` has none.
+ */
+export function appliedSyncSchemaHashes(db) {
+    if (!hasTable(db, '_sync_meta'))
+        return new Map();
+    const rows = db
+        .prepare('SELECT key, value FROM _sync_meta WHERE key LIKE ? ORDER BY key')
+        .all(`${APPLIED_PREFIX}%`);
+    return new Map(rows.map((r) => [r.key.slice(APPLIED_PREFIX.length), r.value]));
+}
+/** The names of the schema folders already applied to this store. Read-only. */
+export function appliedSyncSchema(db) {
+    return [...appliedSyncSchemaHashes(db).keys()];
+}
+/**
+ * The folders still to apply, after checking every applied one for drift.
+ *
+ * @throws {SyncSchemaHashDriftError} When an applied folder's SQL changed.
+ */
+function pending(folders, applied) {
+    for (const f of folders) {
+        const was = applied.get(f.name);
+        if (was !== undefined && was !== f.hash)
+            throw new SyncSchemaHashDriftError(f.name, was, f.hash);
+    }
+    return folders.filter((f) => !applied.has(f.name));
+}
+/**
+ * Apply every sync schema folder this store has not applied yet, in one
+ * transaction (a savepoint when the caller already holds one).
+ *
+ * The applied set is read again INSIDE the transaction, under the write
+ * lock, so two processes enabling a flag at once apply each folder once.
+ *
+ * @param db - The store handle.
+ * @param options - `root` overrides the schema folder (tests); `now` stamps
+ *   the journal rows; `beforeLock` runs between the unlocked pre-check and
+ *   taking the lock (a test seam for the two-process race).
+ * @returns The folders applied by this call.
+ * @throws {SyncSchemaHashDriftError} When an applied folder's SQL changed.
+ */
+export function ensureSyncSchema(db, options = {}) {
+    const folders = syncSchemaFolders(options.root);
+    // Unlocked pre-check: the common case (all applied) takes no write lock.
+    if (pending(folders, appliedSyncSchemaHashes(db)).length === 0)
+        return [];
+    options.beforeLock?.();
+    const stamp = (options.now ?? new Date()).toISOString();
+    const nested = db.isTransaction;
+    db.exec(nested ? 'SAVEPOINT sync_schema' : 'BEGIN IMMEDIATE');
+    try {
+        const todo = pending(folders, appliedSyncSchemaHashes(db));
+        for (const f of todo) {
+            db.exec(f.sql);
+            db.prepare('INSERT INTO _sync_meta (key, value, updated_at) VALUES (?, ?, ?) ' +
+                'ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at').run(`${APPLIED_PREFIX}${f.name}`, f.hash, stamp);
+        }
+        db.exec(nested ? 'RELEASE sync_schema' : 'COMMIT');
+        return todo.map((f) => f.name);
+    }
+    catch (err) {
+        db.exec(nested ? 'ROLLBACK TO sync_schema; RELEASE sync_schema' : 'ROLLBACK');
+        throw err;
+    }
+}
+//# sourceMappingURL=schema.js.map

package/dist/store/sync/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/store/sync/schema.ts"],"names":[],"mappings":"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"}

package/dist/store/sync/skew-hold.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The per-replica FIFO skew hold (journal spec §1.3, M2).
+ *
+ * A received transaction whose HLC is more than the skew bound ahead of the
+ * local wall clock is held: not applied, and it does not advance the clock.
+ * Every later transaction from the SAME origin replica is held behind it, in
+ * `(replicaSeq, index)` order, even when its own HLC is in bounds, so that
+ * replica's causal order is preserved. Other replicas keep flowing. The held
+ * head is re-evaluated on every drain, and the queue releases in order once
+ * the head is within bounds. Nothing is ever dropped.
+ *
+ * This is the in-memory ordering core. Staging the held transactions durably
+ * (`held-skew`) and reporting them through `cleo doctor sync` belong to the
+ * pull slice (S5).
+ *
+ * @task T12342
+ * @module store/sync/skew-hold
+ */
+/** One received transaction, as far as ordering is concerned. */
+export interface InboundTxn {
+    /** Origin replica id. */
+    readonly replica: string;
+    /** The origin's gap-free segment sequence number. */
+    readonly replicaSeq: number;
+    /** Position of the transaction inside its segment. */
+    readonly index: number;
+    /** The transaction's HLC (its largest op HLC), encoded. */
+    readonly hlc: string;
+}
+/** A replica whose queue is blocked by an out-of-bound head. */
+export interface HeldReplica {
+    readonly replica: string;
+    /** The transaction that is too far ahead. */
+    readonly head: InboundTxn;
+    /** How many transactions wait, the head included. */
+    readonly waiting: number;
+    /** How far the head is ahead of the local wall clock, in ms. */
+    readonly aheadMs: number;
+}
+/**
+ * Per-replica FIFO queues that release transactions in origin order and hold
+ * a replica's whole queue behind an out-of-bound head.
+ */
+export declare class SkewHold {
+    private readonly maxDriftMs;
+    private readonly queues;
+    /**
+     * @param maxDriftMs - The skew bound; defaults to {@link MAX_DRIFT_MS}.
+     */
+    constructor(maxDriftMs?: number);
+    /**
+     * Queue a received transaction behind earlier ones from the same replica.
+     * A transaction the queue already holds (same replica, seq and index) is
+     * ignored, so a re-pull is idempotent.
+     */
+    offer(txn: InboundTxn): void;
+    /**
+     * Release every transaction that may apply now, in per-replica order, and
+     * report the replicas that stay held.
+     *
+     * @param nowMs - The local wall clock.
+     * @returns `ready` (to apply, grouped by replica in origin order) and `held`.
+     */
+    drain(nowMs: number): {
+        ready: InboundTxn[];
+        held: HeldReplica[];
+    };
+    /** How many transactions are queued, over all replicas. */
+    get size(): number;
+}
+//# sourceMappingURL=skew-hold.d.ts.map

package/dist/store/sync/skew-hold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skew-hold.d.ts","sourceRoot":"","sources":["../../../src/store/sync/skew-hold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,iEAAiE;AACjE,MAAM,WAAW,UAAU;IACzB,yBAAyB;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qDAAqD;IACrD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,gEAAgE;AAChE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAOD;;;GAGG;AACH,qBAAa,QAAQ;IAMP,OAAO,CAAC,QAAQ,CAAC,UAAU;IALvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;IAE1D;;OAEG;gBAC0B,UAAU,GAAE,MAAqB;IAE9D;;;;OAIG;IACH,KAAK,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI;IAY5B;;;;;;OAMG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,UAAU,EAAE,CAAC;QAAC,IAAI,EAAE,WAAW,EAAE,CAAA;KAAE;IAmBlE,2DAA2D;IAC3D,IAAI,IAAI,IAAI,MAAM,CAIjB;CACF"}

package/dist/store/sync/skew-hold.js

@@ -0,0 +1,89 @@
+/**
+ * The per-replica FIFO skew hold (journal spec §1.3, M2).
+ *
+ * A received transaction whose HLC is more than the skew bound ahead of the
+ * local wall clock is held: not applied, and it does not advance the clock.
+ * Every later transaction from the SAME origin replica is held behind it, in
+ * `(replicaSeq, index)` order, even when its own HLC is in bounds, so that
+ * replica's causal order is preserved. Other replicas keep flowing. The held
+ * head is re-evaluated on every drain, and the queue releases in order once
+ * the head is within bounds. Nothing is ever dropped.
+ *
+ * This is the in-memory ordering core. Staging the held transactions durably
+ * (`held-skew`) and reporting them through `cleo doctor sync` belong to the
+ * pull slice (S5).
+ *
+ * @task T12342
+ * @module store/sync/skew-hold
+ */
+import { isWithinSkew, MAX_DRIFT_MS, parseHlc } from './hlc.js';
+function order(a, b) {
+    if (a.replicaSeq !== b.replicaSeq)
+        return a.replicaSeq - b.replicaSeq;
+    return a.index - b.index;
+}
+/**
+ * Per-replica FIFO queues that release transactions in origin order and hold
+ * a replica's whole queue behind an out-of-bound head.
+ */
+export class SkewHold {
+    maxDriftMs;
+    queues = new Map();
+    /**
+     * @param maxDriftMs - The skew bound; defaults to {@link MAX_DRIFT_MS}.
+     */
+    constructor(maxDriftMs = MAX_DRIFT_MS) {
+        this.maxDriftMs = maxDriftMs;
+    }
+    /**
+     * Queue a received transaction behind earlier ones from the same replica.
+     * A transaction the queue already holds (same replica, seq and index) is
+     * ignored, so a re-pull is idempotent.
+     */
+    offer(txn) {
+        const hlc = parseHlc(txn.hlc);
+        if (hlc.replica !== txn.replica) {
+            throw new Error(`transaction HLC ${txn.hlc} was not issued by replica ${txn.replica}`);
+        }
+        const q = this.queues.get(txn.replica) ?? [];
+        if (q.some((t) => t.replicaSeq === txn.replicaSeq && t.index === txn.index))
+            return;
+        q.push(txn);
+        q.sort(order);
+        this.queues.set(txn.replica, q);
+    }
+    /**
+     * Release every transaction that may apply now, in per-replica order, and
+     * report the replicas that stay held.
+     *
+     * @param nowMs - The local wall clock.
+     * @returns `ready` (to apply, grouped by replica in origin order) and `held`.
+     */
+    drain(nowMs) {
+        const ready = [];
+        const held = [];
+        for (const [replica, q] of [...this.queues].sort(([a], [b]) => (a < b ? -1 : 1))) {
+            while (q.length > 0) {
+                const head = q[0];
+                const h = parseHlc(head.hlc);
+                if (!isWithinSkew(h, nowMs, this.maxDriftMs)) {
+                    held.push({ replica, head, waiting: q.length, aheadMs: h.phys - Math.floor(nowMs) });
+                    break;
+                }
+                ready.push(head);
+                q.shift();
+            }
+            if (q.length === 0)
+                this.queues.delete(replica);
+        }
+        return { ready, held };
+    }
+    /** How many transactions are queued, over all replicas. */
+    get size() {
+        let n = 0;
+        for (const q of this.queues.values())
+            n += q.length;
+        return n;
+    }
+}
+//# sourceMappingURL=skew-hold.js.map

package/dist/store/sync/skew-hold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skew-hold.js","sourceRoot":"","sources":["../../../src/store/sync/skew-hold.ts"],"names":[],"mappings":"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"}

package/dist/store/table-classification.d.ts

@@ -44,21 +44,23 @@
  * that is meaningless off-device: leases, queues, pids, paths, locations and
  * fs-keyed caches.
  *
- * ## Follow-up: current learned weights (does not block Gate A)
+ * ## STDP event history syncs (cleo-dev ruling 2026-09-29)
  *
- * `brain_plasticity_events` and `brain_weight_history` are local-only for row
- * sync (they are STDP event history, 14M+ inserts). A new device still needs
- * the CURRENT learned weights. Deliver them either as a compacted
- * "current weights" projection that syncs as `portable-personal`, or as a
- * periodic compacted snapshot blob. Until then a new device restores them
- * only from the tier-1 backup.
+ * `brain_plasticity_events` and `brain_weight_history` are `portable-personal`
+ * (journal spec review, Q11, under the owner's direction that the cloud backs
+ * up everything). The 2026-09-28 ruling had them local-only, with the current
+ * learned weights to follow as a projection or snapshot blob. They are
+ * append-only with 14M+ lifetime inserts, so they set the change journal's
+ * op-rate ceiling; how much event history replicates is the journal spec's
+ * open retention question (Q15).
  *
  * ## Sources
  *
  * The classes come from the classification draft
  * (`docs/research/table-classification-draft.md` in the cleo-nexus repo), the
  * core owner's rulings in its §F, and the core owner's two-tier ruling of
- * 2026-09-28 plus its follow-up ruling on the STDP tables. Table
+ * 2026-09-28, its follow-up rulings on the STDP tables, and its journal spec
+ * review rulings of 2026-09-29 (STDP and `token_usage`). Table
  * classification was delegated to agents by the owner, so these are cleo-dev
  * rulings; the ruling supersedes earlier ones where they conflict (each such
  * entry carries the old reasoning in its `note`). Rows marked

package/dist/store/table-classification.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"table-classification.d.ts","sourceRoot":"","sources":["../../src/store/table-classification.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AAEH,OAAO,KAAK,EAEV,UAAU,EACV,mBAAmB,EAGnB,UAAU,EACV,kBAAkB,EACnB,MAAM,qBAAqB,CAAC;AA8rD7B;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,kBAKpC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,kBAKnC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,UAAU,EAM9C,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC,CAM5F,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,kBAAkB,CAEtE;AAcD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,mBAAmB,CAYlF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAEpE"}
+{"version":3,"file":"table-classification.d.ts","sourceRoot":"","sources":["../../src/store/table-classification.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AAEH,OAAO,KAAK,EAEV,UAAU,EACV,mBAAmB,EAGnB,UAAU,EACV,kBAAkB,EACnB,MAAM,qBAAqB,CAAC;AAgwD7B;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,kBAKpC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,kBAKnC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,UAAU,EAM9C,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC,CAM5F,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,kBAAkB,CAEtE;AAcD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,mBAAmB,CAYlF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAEpE"}

package/dist/store/table-classification.js

@@ -44,21 +44,23 @@
  * that is meaningless off-device: leases, queues, pids, paths, locations and
  * fs-keyed caches.
  *
- * ## Follow-up: current learned weights (does not block Gate A)
+ * ## STDP event history syncs (cleo-dev ruling 2026-09-29)
  *
- * `brain_plasticity_events` and `brain_weight_history` are local-only for row
- * sync (they are STDP event history, 14M+ inserts). A new device still needs
- * the CURRENT learned weights. Deliver them either as a compacted
- * "current weights" projection that syncs as `portable-personal`, or as a
- * periodic compacted snapshot blob. Until then a new device restores them
- * only from the tier-1 backup.
+ * `brain_plasticity_events` and `brain_weight_history` are `portable-personal`
+ * (journal spec review, Q11, under the owner's direction that the cloud backs
+ * up everything). The 2026-09-28 ruling had them local-only, with the current
+ * learned weights to follow as a projection or snapshot blob. They are
+ * append-only with 14M+ lifetime inserts, so they set the change journal's
+ * op-rate ceiling; how much event history replicates is the journal spec's
+ * open retention question (Q15).
  *
  * ## Sources
  *
  * The classes come from the classification draft
  * (`docs/research/table-classification-draft.md` in the cleo-nexus repo), the
  * core owner's rulings in its §F, and the core owner's two-tier ruling of
- * 2026-09-28 plus its follow-up ruling on the STDP tables. Table
+ * 2026-09-28, its follow-up rulings on the STDP tables, and its journal spec
+ * review rulings of 2026-09-29 (STDP and `token_usage`). Table
  * classification was delegated to agents by the owner, so these are cleo-dev
  * rulings; the ruling supersedes earlier ones where they conflict (each such
  * entry carries the old reasoning in its `note`). Rows marked
@@ -99,6 +101,24 @@ const PROJECT_TABLES = {
         status: 'draft',
         source: 'table-classification-draft.md',
     },
+    _sync_clock: {
+        class: 'local-only',
+        status: 'optional-transient',
+        source: 'journal spec t12342-t12343-journal-design §1.4-§1.5 (T12342)',
+        note: "the HLC clock of this store's replica; describes this physical file, so meaningless on another device. Created lazily by store/sync/schema.ts when a sync.* flag is first enabled",
+    },
+    _sync_meta: {
+        class: 'local-only',
+        status: 'optional-transient',
+        source: 'journal spec t12342-t12343-journal-design §1.4-§1.5 (T12342)',
+        note: 'store-level sync.* flags and journal bookkeeping; describes this physical file, so meaningless on another device. Created lazily by store/sync/schema.ts when a sync.* flag is first enabled',
+    },
+    _sync_replica: {
+        class: 'local-only',
+        status: 'optional-transient',
+        source: 'journal spec t12342-t12343-journal-design §1.4-§1.5 (T12342)',
+        note: 'the replica binding (inode, birthtime, nonce, device) of this store file; describes this physical file, so meaningless on another device. Created lazily by store/sync/schema.ts when a sync.* flag is first enabled',
+    },
     _writer_leases: { class: 'local-only', status: 'draft', source: 'table-classification-draft.md' },
     _writer_queue: { class: 'local-only', status: 'draft', source: 'table-classification-draft.md' },
     acceptance_projection_dirty: {
@@ -310,10 +330,10 @@ const PROJECT_TABLES = {
         source: 'table-classification-draft.md',
     },
     brain_plasticity_events: {
-        class: 'local-only',
+        class: 'portable-personal',
         status: 'resolved',
-        source: 'cleo-dev ruling 2026-09-28',
-        note: 'cleo-dev ruling (final, 2026-09-28): local-only for row sync (14M+ inserts ever, draft §D); still tier-1 backed up. A new device gets the CURRENT learned weights through a follow-up projection or snapshot blob (see the module doc), not this event history',
+        source: 'cleo-dev ruling 2026-09-29 (journal spec review, Q11)',
+        note: "supersedes the 2026-09-28 local-only ruling under the owner's direction that the cloud backs up everything: STDP event history is learned state a new device would otherwise lose. Append-only with 14M+ lifetime inserts, so it sets the journal's op-rate ceiling; retention is journal spec Q15",
     },
     brain_promotion_log: {
         class: 'portable-personal',
@@ -379,10 +399,10 @@ const PROJECT_TABLES = {
         note: 'named in the ruling; pre-T1402 name of brain_observations_staging, dropped by T12535',
     },
     brain_weight_history: {
-        class: 'local-only',
+        class: 'portable-personal',
         status: 'resolved',
-        source: 'cleo-dev ruling 2026-09-28',
-        note: 'cleo-dev ruling (final, 2026-09-28): local-only for row sync (14M+ inserts ever, draft §D); still tier-1 backed up. A new device gets the CURRENT learned weights through a follow-up projection or snapshot blob (see the module doc), not this event history',
+        source: 'cleo-dev ruling 2026-09-29 (journal spec review, Q11)',
+        note: "supersedes the 2026-09-28 local-only ruling under the owner's direction that the cloud backs up everything: STDP event history is learned state a new device would otherwise lose. Append-only with 14M+ lifetime inserts, so it sets the journal's op-rate ceiling; retention is journal spec Q15",
     },
     commit_files: {
         class: 'local-only',
@@ -919,6 +939,18 @@ const PROJECT_TABLES = {
             },
         ],
     },
+    tasks_display_id_aliases: {
+        class: 'portable-project',
+        status: 'resolved',
+        source: 'T12341 (row uids; spec t12341-uid-scheme §9)',
+        note: 'displaced display ids (a T#### re-minted on a merge collision) must resolve on every device and for every collaborator; ADR-094 alias pattern',
+    },
+    tasks_ac_uid_graveyard: {
+        class: 'local-only',
+        status: 'resolved',
+        source: 'T12341 (row uids; spec t12341-uid-scheme §6.5)',
+        note: 'repair scratch: uids of deleted acceptance criteria, so the next open re-links a criterion an older build recreated; pruned at every open',
+    },
     tasks_evidence_ac_bindings: {
         class: 'portable-project',
         status: 'draft',
@@ -941,6 +973,12 @@ const PROJECT_TABLES = {
         source: 'cleo-dev ruling 2026-09-28 (round 2)',
         note: 'per-agent goal state (turn budget, verdict); an agent resuming on another device needs it. No bare `goal` twin exists',
     },
+    tasks_identity_quarantine: {
+        class: 'local-only',
+        status: 'resolved',
+        source: 'T12341 (row uids; spec t12341-uid-scheme §6.4)',
+        note: 'staging for incoming rows a merge cannot place yet (uid or display-id collision awaiting its authority, or a reference awaiting one); re-pulled from sync if lost',
+    },
     tasks_lifecycle_evidence: {
         class: 'portable-project',
         status: 'draft',
@@ -1047,6 +1085,12 @@ const PROJECT_TABLES = {
         status: 'draft',
         source: 'table-classification-draft.md',
     },
+    tasks_row_identity_meta: {
+        class: 'local-only',
+        status: 'resolved',
+        source: 'T12341 (row uids; spec t12341-uid-scheme §12.1)',
+        note: 'the identity recipe version this store derived its uids with, and the sync layer marker; per-store state',
+    },
     tasks_session_handoff_entries: {
         class: 'portable-personal',
         status: 'draft',
@@ -1127,9 +1171,15 @@ const PROJECT_TABLES = {
     },
     tasks_token_usage: {
         class: 'portable-personal',
-        status: 'needs-owner-call',
-        source: 'cleo-dev ruling 2026-09-28',
-        note: 'ruling: token_usage is portable (cost history). Merge scope personal is my proposal (keyed by session, and sessions are personal)',
+        status: 'resolved',
+        source: 'cleo-dev ruling 2026-09-29 (journal spec review, Q9)',
+        note: 'ruling: token_usage is portable (cost history), merged per person (keyed by session, and sessions are personal)',
+    },
+    tasks_uid_aliases: {
+        class: 'portable-project',
+        status: 'resolved',
+        source: 'T12341 (row uids; spec t12341-uid-scheme §6.4)',
+        note: 'uid re-keys after a detected uid collision; every device must resolve the old uid',
     },
     tasks_warp_chain_instances: {
         class: 'portable-project',
@@ -1143,8 +1193,8 @@ const PROJECT_TABLES = {
     },
     token_usage: {
         class: 'portable-personal',
-        status: 'needs-owner-call',
-        source: 'cleo-dev ruling 2026-09-28',
+        status: 'resolved',
+        source: 'cleo-dev ruling 2026-09-29 (journal spec review, Q9)',
         note: 'live bare twin of tasks_token_usage; same ruling',
     },
     warp_chain_instances: {
@@ -1169,6 +1219,24 @@ const GLOBAL_TABLES = {
     __drizzle_migrations: { class: 'local-only', status: 'draft', source: 'draft §3' },
     _agent_registry_meta: { class: 'local-only', status: 'draft', source: 'draft §3' },
     _agent_registry_migrations: { class: 'local-only', status: 'draft', source: 'draft §3' },
+    _sync_clock: {
+        class: 'local-only',
+        status: 'optional-transient',
+        source: 'journal spec t12342-t12343-journal-design §1.4-§1.5 (T12342)',
+        note: "the HLC clock of this store's replica; describes this physical file, so meaningless on another device. Created lazily by store/sync/schema.ts when a sync.* flag is first enabled",
+    },
+    _sync_meta: {
+        class: 'local-only',
+        status: 'optional-transient',
+        source: 'journal spec t12342-t12343-journal-design §1.4-§1.5 (T12342)',
+        note: 'store-level sync.* flags and journal bookkeeping; describes this physical file, so meaningless on another device. Created lazily by store/sync/schema.ts when a sync.* flag is first enabled',
+    },
+    _sync_replica: {
+        class: 'local-only',
+        status: 'optional-transient',
+        source: 'journal spec t12342-t12343-journal-design §1.4-§1.5 (T12342)',
+        note: 'the replica binding (inode, birthtime, nonce, device) of this store file; describes this physical file, so meaningless on another device. Created lazily by store/sync/schema.ts when a sync.* flag is first enabled',
+    },
     _writer_leases: { class: 'local-only', status: 'draft', source: 'draft §3' },
     _writer_queue: { class: 'local-only', status: 'draft', source: 'draft §3' },
     accounts: {
@@ -1436,10 +1504,10 @@ const GLOBAL_TABLES = {
         note: 'writer verified: memory/specialists.ts (LLM Induction/CodePattern specialists) and sleep-consolidation.ts',
     },
     brain_plasticity_events: {
-        class: 'local-only',
+        class: 'portable-personal',
         status: 'resolved',
-        source: 'cleo-dev ruling 2026-09-28',
-        note: 'cleo-dev ruling (final, 2026-09-28): local-only for row sync (14M+ inserts ever, draft §D); still tier-1 backed up. A new device gets the CURRENT learned weights through a follow-up projection or snapshot blob (see the module doc), not this event history',
+        source: 'cleo-dev ruling 2026-09-29 (journal spec review, Q11)',
+        note: "supersedes the 2026-09-28 local-only ruling under the owner's direction that the cloud backs up everything: STDP event history is learned state a new device would otherwise lose. Append-only with 14M+ lifetime inserts, so it sets the journal's op-rate ceiling; retention is journal spec Q15",
     },
     brain_promotion_log: {
         class: 'portable-personal',
@@ -1486,10 +1554,10 @@ const GLOBAL_TABLES = {
         note: '"all brain_*" per the ruling, but it is feedback telemetry (10,152 rows) that drives quality scores; confirm',
     },
     brain_weight_history: {
-        class: 'local-only',
+        class: 'portable-personal',
         status: 'resolved',
-        source: 'cleo-dev ruling 2026-09-28',
-        note: 'cleo-dev ruling (final, 2026-09-28): local-only for row sync (14M+ inserts ever, draft §D); still tier-1 backed up. A new device gets the CURRENT learned weights through a follow-up projection or snapshot blob (see the module doc), not this event history',
+        source: 'cleo-dev ruling 2026-09-29 (journal spec review, Q11)',
+        note: "supersedes the 2026-09-28 local-only ruling under the owner's direction that the cloud backs up everything: STDP event history is learned state a new device would otherwise lose. Append-only with 14M+ lifetime inserts, so it sets the journal's op-rate ceiling; retention is journal spec Q15",
     },
     models_catalog: {
         class: 'local-only',