@cnstra/persist-postgres 0.2.0 → 0.5.0

package/dist/index.js

@@ -23,10 +23,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
 var index_exports = {};
 __export(index_exports, {
   CNSPostgresStimulationRepository: () => CNSPostgresStimulationRepository,
-  DEFAULT_PREFIX: () => DEFAULT_PREFIX,
-  assertSafePrefix: () => assertSafePrefix,
-  ensureSchema: () => ensureSchema,
-  persistPostgresSchemaSql: () => persistPostgresSchemaSql
+  CNSPostgresStimulationSchema: () => CNSPostgresStimulationSchema
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -34,48 +31,260 @@ module.exports = __toCommonJS(index_exports);
 var import_pg = require("pg");
 var import_persist = require("@cnstra/persist");
 
-// src/migrate.ts
-var DEFAULT_PREFIX = "cns_";
-function assertSafePrefix(prefix) {
-  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(prefix)) {
-    throw new Error(`[@cnstra/persist-postgres] unsafe table prefix: ${JSON.stringify(prefix)}`);
+// ../postgres-schema/src/CNSPostgresSchemaMigrator.ts
+var _CNSPostgresSchemaMigrator = class _CNSPostgresSchemaMigrator {
+  constructor(options) {
+    __publicField(this, "options");
+    __publicField(this, "steps");
+    var _a;
+    this.options = options;
+    this.steps = [
+      ...options.steps
+    ].sort((left, right) => left.step - right.step);
+    this.steps.forEach((step, index) => {
+      if (step.step !== index + 1) throw new Error(`[${options.name}] schema steps must be numbered 1, 2, 3\u2026; found ${step.step} at position ${index + 1}`);
+    });
+    if (((_a = this.steps[0]) == null ? void 0 : _a.kind) !== "expand") throw new Error(`[${options.name}] schema step 1 must be an expand step`);
   }
-  return prefix;
-}
-__name(assertSafePrefix, "assertSafePrefix");
-function persistPostgresSchemaSql(prefix = DEFAULT_PREFIX) {
-  const p = assertSafePrefix(prefix);
-  return `
-CREATE TABLE IF NOT EXISTS ${p}stimulation (
+  migrationTable(tablePrefix) {
+    return `${tablePrefix}${this.options.name}_migration`;
+  }
+  async migrate(database, tablePrefix, options = {}) {
+    await database.transaction(async (connection) => {
+      await connection.query("SELECT pg_advisory_xact_lock($1, hashtext($2))", [
+        _CNSPostgresSchemaMigrator.LOCK_NAMESPACE,
+        tablePrefix + this.options.name
+      ]);
+      await connection.query(`SET LOCAL lock_timeout = '${_CNSPostgresSchemaMigrator.LOCK_TIMEOUT}'`);
+      const applied = await this.readAppliedSteps(connection, tablePrefix);
+      if (applied === void 0) await this.assertNoUntrackedTables(connection, tablePrefix);
+      const pending = this.pendingSteps(applied != null ? applied : /* @__PURE__ */ new Map(), applied === void 0 || options.contract === true);
+      if (pending.length > 0) await connection.query(this.sqlFor(tablePrefix, pending, applied === void 0));
+    });
+  }
+  async verify(connection, tablePrefix) {
+    const applied = await this.readAppliedSteps(connection, tablePrefix);
+    if (applied === void 0) {
+      throw new Error(`[${this.options.name}] the schema is not installed under prefix "${tablePrefix}": run migrate()`);
+    }
+    const missing = this.steps.filter((step) => step.kind === "expand" && !applied.has(step.step)).map((step) => step.step);
+    if (missing.length > 0) {
+      throw new Error(`[${this.options.name}] schema steps ${missing.join(", ")} are not applied under prefix "${tablePrefix}": run migrate()`);
+    }
+    const unknown = [
+      ...applied
+    ].filter(([step, kind]) => kind === "contract" && step > this.steps.length).map(([step]) => step);
+    if (unknown.length > 0) {
+      throw new Error(`[${this.options.name}] the database has contract steps ${unknown.join(", ")} that this version does not know: upgrade the package`);
+    }
+  }
+  migrationSql(tablePrefix, appliedSteps = [], options = {}) {
+    const fresh = appliedSteps.length === 0;
+    const applied = new Map(appliedSteps.map((step) => [
+      step,
+      "expand"
+    ]));
+    return this.sqlFor(tablePrefix, this.pendingSteps(applied, fresh || options.contract === true), fresh);
+  }
+  assertTablePrefix(tablePrefix, longestSuffix) {
+    const longest = Math.max(longestSuffix.length, `${this.options.name}_migration`.length);
+    const limit = _CNSPostgresSchemaMigrator.MAX_IDENTIFIER_LENGTH - longest;
+    if (!new RegExp(`^[A-Za-z_][A-Za-z0-9_]{0,${limit - 1}}$`).test(tablePrefix)) {
+      throw new Error(`[${this.options.name}] unsafe table prefix ${JSON.stringify(tablePrefix)}: letters, digits and _ only, at most ${limit} characters`);
+    }
+    return tablePrefix;
+  }
+  pendingSteps(applied, withContract) {
+    return this.steps.filter((step) => !applied.has(step.step) && (step.kind === "expand" || withContract));
+  }
+  sqlFor(tablePrefix, steps, createMigrationTable) {
+    const table = this.migrationTable(tablePrefix);
+    const parts = createMigrationTable ? [
+      `CREATE TABLE ${table} (step integer PRIMARY KEY, kind text NOT NULL CHECK (kind IN ('expand', 'contract')));`
+    ] : [];
+    for (const step of steps) {
+      parts.push(step.sql(tablePrefix), `INSERT INTO ${table} (step, kind) VALUES (${step.step}, '${step.kind}');`);
+    }
+    return parts.join("\n");
+  }
+  async readAppliedSteps(connection, tablePrefix) {
+    var _a;
+    const table = this.migrationTable(tablePrefix);
+    const exists = await connection.query("SELECT to_regclass($1)::text AS found", [
+      table
+    ]);
+    if (((_a = exists.rows[0]) == null ? void 0 : _a.found) == null) return void 0;
+    const rows = await connection.query(`SELECT step, kind FROM ${table}`);
+    return new Map(rows.rows.map((row) => [
+      Number(row.step),
+      row.kind
+    ]));
+  }
+  async assertNoUntrackedTables(connection, tablePrefix) {
+    const tables = this.options.tables(tablePrefix);
+    const found = await connection.query("SELECT name FROM unnest($1::text[]) AS name WHERE to_regclass(name) IS NOT NULL", [
+      tables
+    ]);
+    if (found.rows.length > 0) {
+      throw new Error(`[${this.options.name}] tables ${found.rows.map((row) => row.name).join(", ")} exist without ${this.migrationTable(tablePrefix)}: they were created by an earlier unversioned release; drop them or move the data before migrate()`);
+    }
+  }
+};
+__name(_CNSPostgresSchemaMigrator, "CNSPostgresSchemaMigrator");
+__publicField(_CNSPostgresSchemaMigrator, "LOCK_NAMESPACE", 6);
+__publicField(_CNSPostgresSchemaMigrator, "LOCK_TIMEOUT", "5s");
+__publicField(_CNSPostgresSchemaMigrator, "MAX_IDENTIFIER_LENGTH", 63);
+var CNSPostgresSchemaMigrator = _CNSPostgresSchemaMigrator;
+
+// ../postgres-schema/src/CNSPostgresSchemaPgDatabase.ts
+var _CNSPostgresSchemaPgDatabase = class _CNSPostgresSchemaPgDatabase {
+  constructor(open) {
+    __publicField(this, "open");
+    this.open = open;
+  }
+  static fromPool(pool) {
+    return new _CNSPostgresSchemaPgDatabase(async () => {
+      const client = await pool.connect();
+      return {
+        connection: client,
+        release: /* @__PURE__ */ __name((error) => client.release(error), "release")
+      };
+    });
+  }
+  async transaction(work) {
+    const { connection, release } = await this.open();
+    try {
+      await connection.query("BEGIN");
+      const result = await work(connection);
+      await connection.query("COMMIT");
+      release();
+      return result;
+    } catch (error) {
+      const rollback = await connection.query("ROLLBACK").then(() => void 0, (rollbackError) => rollbackError);
+      release(rollback instanceof Error ? rollback : void 0);
+      throw error;
+    }
+  }
+};
+__name(_CNSPostgresSchemaPgDatabase, "CNSPostgresSchemaPgDatabase");
+var CNSPostgresSchemaPgDatabase = _CNSPostgresSchemaPgDatabase;
+
+// ../postgres-schema/src/CNSPostgresSchemaPartitionRotation.ts
+var _CNSPostgresSchemaPartitionRotation = class _CNSPostgresSchemaPartitionRotation {
+  constructor(options) {
+    __publicField(this, "options");
+    __publicField(this, "rotatedFor", /* @__PURE__ */ new Map());
+    this.options = options;
+    if (!(options.premakeDays >= 1) || !Number.isInteger(options.premakeDays)) {
+      throw new Error(`[partition rotation] premakeDays must be a positive integer, got ${options.premakeDays}`);
+    }
+  }
+  async rotate(database, table, now, dropBefore, beforeDrop) {
+    const today = Math.floor(now / _CNSPostgresSchemaPartitionRotation.DAY_MS);
+    const days = `${today}:${Math.floor(dropBefore / _CNSPostgresSchemaPartitionRotation.DAY_MS)}`;
+    if (this.rotatedFor.get(table) === days) return [];
+    const dropped = await this.underLock(database, table, async (connection) => {
+      const expired = (await this.readRangePartitions(connection, table)).filter((partition) => partition.to <= dropBefore);
+      if (beforeDrop) for (const partition of expired) await beforeDrop(connection, partition.name);
+      for (const partition of expired) await connection.query(`DROP TABLE ${partition.name}`);
+      return expired.map((partition) => partition.name);
+    });
+    await this.underLock(database, table, async (connection) => {
+      const partitions = await this.readRangePartitions(connection, table);
+      for (let ahead = 1; ahead <= this.options.premakeDays; ahead++) {
+        const from = (today + ahead) * _CNSPostgresSchemaPartitionRotation.DAY_MS;
+        const to = from + _CNSPostgresSchemaPartitionRotation.DAY_MS;
+        if (partitions.some((partition) => partition.from < to && from < partition.to)) continue;
+        const name = `${table}_p${new Date(from).toISOString().slice(0, 10).replace(/-/g, "")}`;
+        await connection.query(`CREATE TABLE ${name} (LIKE ${table} INCLUDING DEFAULTS INCLUDING CONSTRAINTS)`);
+        await connection.query(`ALTER TABLE ${table} ATTACH PARTITION ${name} FOR VALUES FROM (${from}) TO (${to})`);
+      }
+    });
+    this.rotatedFor.set(table, days);
+    return dropped;
+  }
+  underLock(database, table, work) {
+    return database.transaction(async (connection) => {
+      await connection.query("SELECT pg_advisory_xact_lock($1, hashtext($2))", [
+        _CNSPostgresSchemaPartitionRotation.LOCK_NAMESPACE,
+        table
+      ]);
+      await connection.query(`SET LOCAL lock_timeout = '${_CNSPostgresSchemaPartitionRotation.LOCK_TIMEOUT}'`);
+      return work(connection);
+    });
+  }
+  async readRangePartitions(connection, table) {
+    const rows = await connection.query(`SELECT child.oid::regclass::text AS name, pg_get_expr(child.relpartbound, child.oid) AS bound
+             FROM pg_inherits
+             JOIN pg_class child ON child.oid = pg_inherits.inhrelid
+             WHERE pg_inherits.inhparent = $1::regclass`, [
+      table
+    ]);
+    const partitions = [];
+    for (const row of rows.rows) {
+      const range = /^FOR VALUES FROM \('?(-?[\d.e+]+)'?\) TO \('?(-?[\d.e+]+)'?\)$/.exec(row.bound);
+      if (range) partitions.push({
+        name: row.name,
+        from: Number(range[1]),
+        to: Number(range[2])
+      });
+    }
+    return partitions;
+  }
+};
+__name(_CNSPostgresSchemaPartitionRotation, "CNSPostgresSchemaPartitionRotation");
+__publicField(_CNSPostgresSchemaPartitionRotation, "LOCK_NAMESPACE", 8);
+__publicField(_CNSPostgresSchemaPartitionRotation, "LOCK_TIMEOUT", "5s");
+__publicField(_CNSPostgresSchemaPartitionRotation, "DAY_MS", 24 * 60 * 60 * 1e3);
+var CNSPostgresSchemaPartitionRotation = _CNSPostgresSchemaPartitionRotation;
+
+// src/schema/CNSPostgresStimulationSchema.ts
+var _CNSPostgresStimulationSchema = class _CNSPostgresStimulationSchema {
+  static assertTablePrefix(tablePrefix) {
+    return _CNSPostgresStimulationSchema.migrator.assertTablePrefix(tablePrefix, _CNSPostgresStimulationSchema.LONGEST_SUFFIX);
+  }
+  static tables(tablePrefix = _CNSPostgresStimulationSchema.DEFAULT_TABLE_PREFIX) {
+    const p = _CNSPostgresStimulationSchema.assertTablePrefix(tablePrefix);
+    return [
+      `${p}stimulation`,
+      `${p}stimulation_attempt`,
+      `${p}stimulation_task`
+    ];
+  }
+  static migrationTable(tablePrefix = _CNSPostgresStimulationSchema.DEFAULT_TABLE_PREFIX) {
+    return _CNSPostgresStimulationSchema.migrator.migrationTable(_CNSPostgresStimulationSchema.assertTablePrefix(tablePrefix));
+  }
+  static migrationSql(tablePrefix = _CNSPostgresStimulationSchema.DEFAULT_TABLE_PREFIX, appliedSteps = [], options) {
+    return _CNSPostgresStimulationSchema.migrator.migrationSql(_CNSPostgresStimulationSchema.assertTablePrefix(tablePrefix), appliedSteps, options);
+  }
+  static async migrate(pool, tablePrefix = _CNSPostgresStimulationSchema.DEFAULT_TABLE_PREFIX, options) {
+    await _CNSPostgresStimulationSchema.migrator.migrate(CNSPostgresSchemaPgDatabase.fromPool(pool), _CNSPostgresStimulationSchema.assertTablePrefix(tablePrefix), options);
+  }
+  static async verify(database, tablePrefix = _CNSPostgresStimulationSchema.DEFAULT_TABLE_PREFIX) {
+    await _CNSPostgresStimulationSchema.migrator.verify(database, _CNSPostgresStimulationSchema.assertTablePrefix(tablePrefix));
+  }
+  static initialSql(p) {
+    return `
+CREATE TABLE ${p}stimulation (
     stimulation_id text PRIMARY KEY,
     entry jsonb NOT NULL,
-    status text NOT NULL,
+    status text NOT NULL CHECK (status IN ('running', 'completed', 'failed', 'aborted')),
     scope_name text,
-    created_at timestamptz NOT NULL DEFAULT now(),
-    updated_at timestamptz NOT NULL DEFAULT now()
-);
-CREATE INDEX IF NOT EXISTS ${p}stimulation_updated_idx ON ${p}stimulation (updated_at DESC);
-CREATE INDEX IF NOT EXISTS ${p}stimulation_scope_idx ON ${p}stimulation (scope_name);
+    progress jsonb NOT NULL,
+    updated_at bigint NOT NULL,
+    started_at bigint NOT NULL DEFAULT 0,
+    hop_count int NOT NULL DEFAULT 0,
+    last_completed_at bigint
+) WITH (fillfactor = 70);
+CREATE INDEX ${p}stimulation_started_idx ON ${p}stimulation (started_at DESC, stimulation_id COLLATE "C" DESC);
+CREATE INDEX ${p}stimulation_scope_started_idx ON ${p}stimulation (scope_name, started_at DESC, stimulation_id COLLATE "C" DESC);
 
-CREATE TABLE IF NOT EXISTS ${p}stimulation_frontier (
-    stimulation_id text NOT NULL REFERENCES ${p}stimulation(stimulation_id) ON DELETE CASCADE,
-    ord int NOT NULL,
-    neuron_name text NOT NULL,
-    dendrite_collateral_name text NOT NULL,
-    input jsonb,
-    PRIMARY KEY (stimulation_id, ord)
-);
-
--- NOTE: no FK on stimulation_id \u2014 over the devtools wire the persistor's
--- saveStimulation and saveAttempt ride SEPARATE async batches processed
--- concurrently by the server, so an attempt insert can reach Postgres before its
--- stimulation row's transaction commits; a hard FK would reject it (23503). Same
--- exposure as ${p}task; delete() removes attempts explicitly instead of cascading.
-CREATE TABLE IF NOT EXISTS ${p}stimulation_attempt (
+-- No foreign keys below: attempts and tasks arrive over separate writes, often before their parent row.
+CREATE TABLE ${p}stimulation_attempt (
     stimulation_attempt_id text PRIMARY KEY,
     stimulation_id text NOT NULL,
     attempt_number int NOT NULL,
-    status text NOT NULL,
+    status text NOT NULL CHECK (status IN ('running', 'completed', 'failed', 'aborted')),
     started_at bigint NOT NULL,
     completed_at bigint,
     hop_count int NOT NULL,
@@ -84,35 +293,41 @@ CREATE TABLE IF NOT EXISTS ${p}stimulation_attempt (
     entry jsonb NOT NULL,
     UNIQUE (stimulation_id, attempt_number)
 );
-CREATE INDEX IF NOT EXISTS ${p}stimulation_attempt_idx ON ${p}stimulation_attempt (stimulation_id, attempt_number);
--- roster query: MIN(started_at)/keyset ordering per run.
-CREATE INDEX IF NOT EXISTS ${p}stimulation_attempt_started_idx ON ${p}stimulation_attempt (stimulation_id, started_at);
+CREATE INDEX ${p}stimulation_attempt_started_idx ON ${p}stimulation_attempt (started_at);
 
--- NOTE: no FK on stimulation_attempt_id \u2014 the persistor streams settled tasks
--- (appendTask) as hops complete, BEFORE the attempt marker is flushed (saveAttempt),
--- so a hard FK would reject the insert. delete() removes tasks explicitly instead.
-CREATE TABLE IF NOT EXISTS ${p}task (
+CREATE TABLE ${p}stimulation_task (
     stimulation_attempt_id text NOT NULL,
-    "index" int NOT NULL,
+    task_index int NOT NULL,
     neuron_name text NOT NULL,
     dendrite_collateral_name text NOT NULL,
     input_index int NOT NULL,
     output jsonb,
-    status text NOT NULL,
+    status text NOT NULL CHECK (status IN ('done', 'failed')),
     error text,
     started_at bigint NOT NULL,
-    duration int,
-    PRIMARY KEY (stimulation_attempt_id, "index")
-);
--- roster neurons lens: DISTINCT neuron_name per attempt / neuronName filter.
-CREATE INDEX IF NOT EXISTS ${p}task_neuron_idx ON ${p}task (neuron_name);
+    duration_ms bigint,
+    activation_context jsonb,
+    PRIMARY KEY (stimulation_attempt_id, task_index, started_at)
+) PARTITION BY RANGE (started_at);
+CREATE TABLE ${p}stimulation_task_default PARTITION OF ${p}stimulation_task DEFAULT;
 `;
-}
-__name(persistPostgresSchemaSql, "persistPostgresSchemaSql");
-async function ensureSchema(db, prefix = DEFAULT_PREFIX) {
-  await db.query(persistPostgresSchemaSql(prefix));
-}
-__name(ensureSchema, "ensureSchema");
+  }
+};
+__name(_CNSPostgresStimulationSchema, "CNSPostgresStimulationSchema");
+__publicField(_CNSPostgresStimulationSchema, "DEFAULT_TABLE_PREFIX", "cns_");
+__publicField(_CNSPostgresStimulationSchema, "LONGEST_SUFFIX", "stimulation_attempt_started_idx");
+__publicField(_CNSPostgresStimulationSchema, "migrator", new CNSPostgresSchemaMigrator({
+  name: "stimulation",
+  tables: /* @__PURE__ */ __name((tablePrefix) => _CNSPostgresStimulationSchema.tables(tablePrefix), "tables"),
+  steps: [
+    {
+      step: 1,
+      kind: "expand",
+      sql: /* @__PURE__ */ __name((tablePrefix) => _CNSPostgresStimulationSchema.initialSql(tablePrefix), "sql")
+    }
+  ]
+}));
+var CNSPostgresStimulationSchema = _CNSPostgresStimulationSchema;
 
 // src/CNSPostgresStimulationRepository.ts
 var j = /* @__PURE__ */ __name((v) => JSON.stringify(v != null ? v : null), "j");
@@ -125,8 +340,12 @@ var _CNSPostgresStimulationRepository = class _CNSPostgresStimulationRepository
     __publicField(this, "ownsPool");
     __publicField(this, "p");
     __publicField(this, "autoMigrate");
+    __publicField(this, "now");
+    __publicField(this, "taskPartitions", new CNSPostgresSchemaPartitionRotation({
+      premakeDays: 7
+    }));
     __publicField(this, "ready");
-    var _a, _b;
+    var _a, _b, _c;
     if (opts.pool) {
       this.pool = opts.pool;
       this.db = opts.pool;
@@ -143,13 +362,21 @@ var _CNSPostgresStimulationRepository = class _CNSPostgresStimulationRepository
     } else {
       throw new Error("[@cnstra/persist-postgres] needs `connectionString`, `pool`, or `queryable`");
     }
-    this.p = assertSafePrefix((_a = opts.tablePrefix) != null ? _a : DEFAULT_PREFIX);
+    this.p = CNSPostgresStimulationSchema.assertTablePrefix((_a = opts.tablePrefix) != null ? _a : CNSPostgresStimulationSchema.DEFAULT_TABLE_PREFIX);
     this.autoMigrate = (_b = opts.autoMigrate) != null ? _b : true;
+    if (this.autoMigrate && !this.pool) {
+      throw new Error("[@cnstra/persist-postgres] a `queryable` cannot hold the migration transaction: pass `pool` or `connectionString`, or set `autoMigrate: false` and run CNSPostgresStimulationSchema.migrate(pool) yourself");
+    }
+    this.now = (_c = opts.now) != null ? _c : Date.now;
   }
-  ensure() {
+  schemaReady() {
     var _a;
     if (!this.autoMigrate) return Promise.resolve();
-    return (_a = this.ready) != null ? _a : this.ready = ensureSchema(this.db, this.p);
+    (_a = this.ready) != null ? _a : this.ready = CNSPostgresStimulationSchema.migrate(this.pool, this.p).catch((error) => {
+      this.ready = void 0;
+      throw error;
+    });
+    return this.ready;
   }
   /** Run `fn` in a transaction when a Pool is available; else best-effort inline. */
   async tx(fn) {
@@ -169,68 +396,87 @@ var _CNSPostgresStimulationRepository = class _CNSPostgresStimulationRepository
   }
   // ── write ──
   async saveStimulation(s) {
-    await this.ensure();
+    await this.schemaReady();
     const { p } = this;
+    const now = this.now();
     await this.tx(async (db) => {
-      var _a;
-      await db.query(`INSERT INTO ${p}stimulation (stimulation_id, entry, status, scope_name, updated_at)
-                 VALUES ($1, $2::jsonb, $3, $4, now())
+      var _a, _b;
+      await this.lockStimulation(db, s.stimulationId);
+      const upserted = await db.query(`INSERT INTO ${p}stimulation (stimulation_id, entry, status, scope_name, progress, updated_at)
+                 VALUES ($1, $2::jsonb, $3, $4, $5::jsonb, $6)
                  ON CONFLICT (stimulation_id)
                  DO UPDATE SET entry = EXCLUDED.entry, status = EXCLUDED.status,
-                    scope_name = EXCLUDED.scope_name, updated_at = now()`, [
+                    scope_name = EXCLUDED.scope_name, progress = EXCLUDED.progress, updated_at = EXCLUDED.updated_at
+                 RETURNING (xmax = 0) AS inserted`, [
         s.stimulationId,
         j(s.entry),
         s.status,
-        (_a = s.scopeName) != null ? _a : null
+        (_a = s.scopeName) != null ? _a : null,
+        j(s.progress),
+        now
       ]);
-      await db.query(`DELETE FROM ${p}stimulation_frontier WHERE stimulation_id = $1`, [
-        s.stimulationId
-      ]);
-      for (let i = 0; i < s.progress.tasks.length; i++) {
-        const t = s.progress.tasks[i];
-        await db.query(`INSERT INTO ${p}stimulation_frontier
-                        (stimulation_id, ord, neuron_name, dendrite_collateral_name, input)
-                     VALUES ($1, $2, $3, $4, $5::jsonb)`, [
-          s.stimulationId,
-          i,
-          t.neuronName,
-          t.dendriteCollateralName,
-          t.input ? j(t.input) : null
-        ]);
-      }
+      if (((_b = upserted.rows[0]) == null ? void 0 : _b.inserted) !== false) await this.rollUpAttempts(db, s.stimulationId, now);
     });
   }
   async saveAttempt(a) {
-    await this.ensure();
+    await this.schemaReady();
+    const { p } = this;
+    await this.tx(async (db) => {
+      await this.lockStimulation(db, a.stimulationId);
+      await db.query(`INSERT INTO ${p}stimulation_attempt
+                    (stimulation_attempt_id, stimulation_id, attempt_number, status, started_at,
+                     completed_at, hop_count, has_error, replay_of, entry)
+                 VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10::jsonb)
+                 ON CONFLICT (stimulation_attempt_id) DO UPDATE SET
+                    status = EXCLUDED.status, completed_at = EXCLUDED.completed_at,
+                    hop_count = EXCLUDED.hop_count, has_error = EXCLUDED.has_error,
+                    replay_of = EXCLUDED.replay_of, entry = EXCLUDED.entry`, [
+        a.stimulationAttemptId,
+        a.stimulationId,
+        a.attemptNumber,
+        a.status,
+        a.startedAt,
+        a.completedAt,
+        a.hopCount,
+        a.hasError,
+        a.replayOf,
+        j(a.entry)
+      ]);
+      await this.rollUpAttempts(db, a.stimulationId, this.now());
+    });
+  }
+  async lockStimulation(db, stimulationId) {
+    await db.query("SELECT pg_advisory_xact_lock($1, hashtext($2))", [
+      _CNSPostgresStimulationRepository.LOCK_STIMULATION,
+      this.p + stimulationId
+    ]);
+  }
+  async rollUpAttempts(db, stimulationId, now) {
     const { p } = this;
-    await this.db.query(`INSERT INTO ${p}stimulation_attempt
-                (stimulation_attempt_id, stimulation_id, attempt_number, status, started_at,
-                 completed_at, hop_count, has_error, replay_of, entry)
-             VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10::jsonb)
-             ON CONFLICT (stimulation_attempt_id) DO UPDATE SET
-                status = EXCLUDED.status, completed_at = EXCLUDED.completed_at,
-                hop_count = EXCLUDED.hop_count, has_error = EXCLUDED.has_error,
-                replay_of = EXCLUDED.replay_of, entry = EXCLUDED.entry`, [
-      a.stimulationAttemptId,
-      a.stimulationId,
-      a.attemptNumber,
-      a.status,
-      a.startedAt,
-      a.completedAt,
-      a.hopCount,
-      a.hasError,
-      a.replayOf,
-      j(a.entry)
+    await db.query(`UPDATE ${p}stimulation s
+             SET started_at = COALESCE(a.started_at, 0),
+                 hop_count = COALESCE(a.hop_count, 0),
+                 last_completed_at = a.last_completed_at,
+                 updated_at = GREATEST(s.updated_at, $2)
+             FROM (
+                 SELECT MIN(started_at) AS started_at,
+                        SUM(hop_count) AS hop_count,
+                        (ARRAY_AGG(completed_at ORDER BY attempt_number DESC))[1] AS last_completed_at
+                 FROM ${p}stimulation_attempt WHERE stimulation_id = $1
+             ) a
+             WHERE s.stimulation_id = $1`, [
+      stimulationId,
+      now
     ]);
   }
   async appendTask(t) {
-    await this.ensure();
+    await this.schemaReady();
     const { p } = this;
-    await this.db.query(`INSERT INTO ${p}task
-                (stimulation_attempt_id, "index", neuron_name, dendrite_collateral_name,
-                 input_index, output, status, error, started_at, duration)
-             VALUES ($1,$2,$3,$4,$5,$6::jsonb,$7,$8,$9,$10)
-             ON CONFLICT (stimulation_attempt_id, "index") DO NOTHING`, [
+    await this.db.query(`INSERT INTO ${p}stimulation_task
+                (stimulation_attempt_id, task_index, neuron_name, dendrite_collateral_name,
+                 input_index, output, status, error, started_at, duration_ms, activation_context)
+             VALUES ($1,$2,$3,$4,$5,$6::jsonb,$7,$8,$9,$10,$11::jsonb)
+             ON CONFLICT (stimulation_attempt_id, task_index, started_at) DO NOTHING`, [
       t.stimulationAttemptId,
       t.index,
       t.neuronName,
@@ -240,65 +486,37 @@ var _CNSPostgresStimulationRepository = class _CNSPostgresStimulationRepository
       t.status,
       t.error,
       t.startedAt,
-      t.duration
+      t.duration,
+      t.activationContext ? j(t.activationContext) : null
     ]);
   }
   // ── read ──
   async getStimulation(stimulationId) {
-    await this.ensure();
+    await this.schemaReady();
     const { p } = this;
-    const stimRes = await this.db.query(`SELECT entry, status, scope_name FROM ${p}stimulation WHERE stimulation_id = $1`, [
+    const res = await this.db.query(`SELECT stimulation_id, entry, status, scope_name, progress FROM ${p}stimulation WHERE stimulation_id = $1`, [
       stimulationId
     ]);
-    const row = stimRes.rows[0];
-    if (!row) return void 0;
-    const frontier = await this.db.query(`SELECT ord, neuron_name, dendrite_collateral_name, input
-             FROM ${p}stimulation_frontier WHERE stimulation_id = $1 ORDER BY ord`, [
-      stimulationId
-    ]);
-    return {
-      stimulationId,
-      entry: row.entry,
-      status: row.status,
-      progress: this.buildProgress(frontier.rows),
-      ...row.scope_name != null ? {
-        scopeName: row.scope_name
-      } : {}
-    };
+    const row = res.rows[0];
+    return row ? rowToStimulation(row) : void 0;
   }
   async listStimulations(filter) {
-    var _a;
-    await this.ensure();
+    var _a, _b;
+    await this.schemaReady();
     const { p } = this;
     const scope = (_a = filter == null ? void 0 : filter.scopeName) != null ? _a : null;
-    const stimsRes = await this.db.query(`SELECT stimulation_id, entry, status, scope_name FROM ${p}stimulation
+    const since = (_b = filter == null ? void 0 : filter.since) != null ? _b : null;
+    const res = await this.db.query(`SELECT stimulation_id, entry, status, scope_name, progress FROM ${p}stimulation
              WHERE ($1::text IS NULL OR scope_name = $1)
+               AND ($2::bigint IS NULL OR updated_at >= $2)
              ORDER BY updated_at DESC`, [
-      scope
-    ]);
-    const stims = stimsRes.rows;
-    if (stims.length === 0) return [];
-    const ids = stims.map((r) => r.stimulation_id);
-    const frontierRes = await this.db.query(`SELECT stimulation_id, ord, neuron_name, dendrite_collateral_name, input
-             FROM ${p}stimulation_frontier WHERE stimulation_id = ANY($1) ORDER BY stimulation_id, ord`, [
-      ids
+      scope,
+      since
     ]);
-    const frontierBy = groupBy(frontierRes.rows, (r) => r.stimulation_id);
-    return stims.map((r) => {
-      var _a2;
-      return {
-        stimulationId: r.stimulation_id,
-        entry: r.entry,
-        status: r.status,
-        progress: this.buildProgress((_a2 = frontierBy.get(r.stimulation_id)) != null ? _a2 : []),
-        ...r.scope_name != null ? {
-          scopeName: r.scope_name
-        } : {}
-      };
-    });
+    return res.rows.map(rowToStimulation);
   }
   async getAttempts(stimulationId) {
-    await this.ensure();
+    await this.schemaReady();
     const { p } = this;
     const res = await this.db.query(`SELECT * FROM ${p}stimulation_attempt WHERE stimulation_id = $1 ORDER BY attempt_number`, [
       stimulationId
@@ -306,32 +524,92 @@ var _CNSPostgresStimulationRepository = class _CNSPostgresStimulationRepository
     return res.rows.map(rowToAttempt);
   }
   async getTasks(stimulationAttemptId) {
-    await this.ensure();
+    await this.schemaReady();
     const { p } = this;
-    const res = await this.db.query(`SELECT * FROM ${p}task WHERE stimulation_attempt_id = $1 ORDER BY "index"`, [
+    const res = await this.db.query(`SELECT * FROM ${p}stimulation_task WHERE stimulation_attempt_id = $1 ORDER BY task_index`, [
       stimulationAttemptId
     ]);
     return res.rows.map(rowToTask);
   }
+  /**
+   * Attempts of many stimulations in ONE query, so a page of runs costs one
+   * round trip rather than one per run.
+   */
+  async getAttemptsFor(stimulationIds) {
+    if (stimulationIds.length === 0) return [];
+    await this.schemaReady();
+    const { p } = this;
+    const res = await this.db.query(`SELECT * FROM ${p}stimulation_attempt
+             WHERE stimulation_id = ANY($1)
+             ORDER BY stimulation_id, attempt_number`, [
+      stimulationIds
+    ]);
+    return res.rows.map(rowToAttempt);
+  }
+  /** Tasks of many attempts in ONE query — see {@link getAttemptsFor}. */
+  async getTasksFor(stimulationAttemptIds) {
+    if (stimulationAttemptIds.length === 0) return [];
+    await this.schemaReady();
+    const { p } = this;
+    const res = await this.db.query(`SELECT * FROM ${p}stimulation_task
+             WHERE stimulation_attempt_id = ANY($1)
+             ORDER BY stimulation_attempt_id, task_index`, [
+      stimulationAttemptIds
+    ]);
+    return res.rows.map(rowToTask);
+  }
   // ── roster query capability (filter + keyset + facets pushed into SQL) ──
   /**
-   * Derive every filtered roster row in one CTE: `startedAt` = MIN(attempt),
-   * `completedAt` = the latest attempt's, `hopCount` = SUM, `hasError` from
-   * status, and the DISTINCT activated neuron names (for the neurons lens +
-   * filter). Newest-first (`startedAt DESC, stimulationId DESC`) so the keyset
-   * cursor is stable. `limit` is applied only when paginating (roster); facets
-   * pull the whole filtered set.
+   * The CTE every roster read stands on. The roster fields are kept on the
+   * stimulation row by `saveAttempt` / `saveStimulation`, so the window and the
+   * order come from `stimulation(started_at DESC, stimulation_id)`; the total
+   * still counts the whole filtered set. Shared so the facet tallies are counted
+   * over exactly the set the roster pages through.
+   * The task table is read only when `withNeurons` asks for the neuron names.
+   * It binds `$1..$7` (the filter); the keyset cursor belongs to the roster's tail.
    */
+  rosterCte(withNeurons) {
+    const { p } = this;
+    const neurons = withNeurons ? `COALESCE((
+                   SELECT ARRAY_AGG(DISTINCT t.neuron_name)
+                   FROM ${p}stimulation_task t
+                   JOIN ${p}stimulation_attempt a ON a.stimulation_attempt_id = t.stimulation_attempt_id
+                   WHERE a.stimulation_id = s.stimulation_id
+               ), ARRAY[]::text[])` : "ARRAY[]::text[]";
+    return `
+            WITH roster AS (
+                SELECT s.stimulation_id, s.entry, s.status, s.scope_name, s.started_at,
+                       CASE WHEN s.status = 'running' THEN NULL ELSE s.last_completed_at END AS completed_at,
+                       s.hop_count,
+                       (s.status = 'failed') AS has_error,
+                       ${neurons} AS neurons
+                FROM ${p}stimulation s
+                WHERE ($6::bigint IS NULL OR s.started_at >= $6)
+                  AND ($7::bigint IS NULL OR s.started_at <= $7)
+                  AND ($1::text IS NULL OR s.scope_name = $1)
+                  AND ($2::text IS NULL OR s.status = $2)
+                  AND ($3::text IS NULL OR s.entry->>'collateralName' = $3)
+                  AND ($5::text IS NULL OR strpos(lower(s.stimulation_id), $5) > 0)
+            ),
+            filtered AS (
+                SELECT *, COUNT(*) OVER() AS total_count FROM roster
+                WHERE ($4::text IS NULL OR $4 = ANY(neurons))
+            )`;
+  }
   async selectRoster(filter, opts) {
     var _a, _b, _c, _d, _e, _f;
-    await this.ensure();
+    await this.schemaReady();
     const { p } = this;
     let curStarted = null;
     let curId = null;
     if (opts == null ? void 0 : opts.cursor) {
-      const [ts, id] = Buffer.from(opts.cursor, "base64").toString("utf8").split("|");
-      curStarted = Number(ts);
-      curId = id != null ? id : "";
+      const decoded = Buffer.from(opts.cursor, "base64").toString("utf8");
+      const at = decoded.indexOf("|");
+      const started = Number(decoded.slice(0, at));
+      if (at >= 0 && Number.isFinite(started)) {
+        curStarted = started;
+        curId = decoded.slice(at + 1);
+      }
     }
     const params = [
       (_a = filter.scopeName) != null ? _a : null,
@@ -344,49 +622,27 @@ var _CNSPostgresStimulationRepository = class _CNSPostgresStimulationRepository
       curStarted,
       curId
     ];
-    const limitClause = (opts == null ? void 0 : opts.limit) != null ? ` LIMIT ${Math.max(0, opts.limit | 0)}` : "";
-    const sql = `
-            WITH agg AS (
-                SELECT a.stimulation_id,
-                       MIN(a.started_at) AS started_at,
-                       SUM(a.hop_count)  AS hop_count,
-                       (ARRAY_AGG(a.completed_at ORDER BY a.attempt_number DESC))[1] AS last_completed_at
-                FROM ${p}stimulation_attempt a
-                GROUP BY a.stimulation_id
-            ),
-            neu AS (
-                SELECT ta.stimulation_id,
-                       ARRAY_AGG(DISTINCT t.neuron_name) AS neurons
-                FROM ${p}task t
-                JOIN ${p}stimulation_attempt ta
-                     ON ta.stimulation_attempt_id = t.stimulation_attempt_id
-                GROUP BY ta.stimulation_id
-            ),
-            roster AS (
-                SELECT s.stimulation_id, s.entry, s.status, s.scope_name,
-                       COALESCE(agg.started_at, 0) AS started_at,
-                       CASE WHEN s.status = 'running' THEN NULL
-                            ELSE agg.last_completed_at END AS completed_at,
-                       COALESCE(agg.hop_count, 0) AS hop_count,
-                       (s.status = 'failed') AS has_error,
-                       COALESCE(neu.neurons, ARRAY[]::text[]) AS neurons
-                FROM ${p}stimulation s
-                LEFT JOIN agg ON agg.stimulation_id = s.stimulation_id
-                LEFT JOIN neu ON neu.stimulation_id = s.stimulation_id
-            )
-            SELECT *, COUNT(*) OVER() AS total_count FROM roster
-            WHERE ($1::text IS NULL OR scope_name = $1)
-              AND ($2::text IS NULL OR status = $2)
-              AND ($3::text IS NULL OR entry->>'collateralName' = $3)
-              AND ($4::text IS NULL OR $4 = ANY(neurons))
-              AND ($5::text IS NULL OR lower(stimulation_id) LIKE '%'||$5||'%')
-              AND ($6::bigint IS NULL OR started_at >= $6)
-              AND ($7::bigint IS NULL OR started_at <= $7)
-              AND ($8::bigint IS NULL OR (started_at, stimulation_id) < ($8, $9))
-            ORDER BY started_at DESC, stimulation_id DESC${limitClause}`;
+    const limitClause = (opts == null ? void 0 : opts.limit) != null && Number.isFinite(opts.limit) ? ` LIMIT ${Math.max(0, Math.floor(opts.limit))}` : "";
+    const sql = `${this.rosterCte(filter.neuronName != null)}
+            -- The count is taken INSIDE \`filtered\`, before the keyset predicate
+            -- narrows the set. Counting after it made \`total\` shrink with every
+            -- page, while the in-memory reference reports the whole filtered set \u2014
+            -- and the two are contractually identical.
+            SELECT * FROM filtered
+            WHERE ($8::bigint IS NULL OR (started_at, stimulation_id COLLATE "C") < ($8, $9::text COLLATE "C"))
+            ORDER BY started_at DESC, stimulation_id COLLATE "C" DESC${limitClause}`;
     const res = await this.db.query(sql, params);
     const rows = res.rows;
-    const total = rows.length ? Number(rows[0].total_count) : 0;
+    let total = rows.length ? Number(rows[0].total_count) : 0;
+    if (!rows.length && curStarted !== null) {
+      const countRes = await this.db.query(sql, [
+        ...params.slice(0, 7),
+        null,
+        null
+      ]);
+      const countRows = countRes.rows;
+      total = countRows.length ? Number(countRows[0].total_count) : 0;
+    }
     const entries = rows.map((r) => {
       var _a2, _b2;
       return {
@@ -409,26 +665,119 @@ var _CNSPostgresStimulationRepository = class _CNSPostgresStimulationRepository
     };
   }
   async queryRoster(filter, opts) {
-    const { entries, total } = await this.selectRoster(filter, opts);
-    const rows = entries.map((e) => e.row);
+    const { entries, total } = await this.selectRoster(filter, {
+      ...opts,
+      limit: opts.limit + 1
+    });
+    const hasMore = entries.length > opts.limit;
+    const rows = entries.slice(0, opts.limit).map((e) => e.row);
     const lastRow = rows[rows.length - 1];
-    const hasMore = rows.length >= opts.limit && rows.length < total;
     return {
       rows,
-      nextCursor: hasMore && lastRow ? (0, import_persist.encodeRosterCursor)(lastRow) : null,
+      nextCursor: hasMore && lastRow ? (0, import_persist.encodeCNSRosterCursor)(lastRow) : null,
       total
     };
   }
   async queryFacets(filter, opts) {
-    const { entries } = await this.selectRoster(filter);
-    return (0, import_persist.computeRosterFacets)(entries, opts);
+    var _a, _b, _c, _d, _e, _f;
+    await this.schemaReady();
+    const params = [
+      (_a = filter.scopeName) != null ? _a : null,
+      (_b = filter.status) != null ? _b : null,
+      (_c = filter.entryCollateralName) != null ? _c : null,
+      (_d = filter.neuronName) != null ? _d : null,
+      filter.text ? filter.text.toLowerCase() : null,
+      (_e = filter.since) != null ? _e : null,
+      (_f = filter.until) != null ? _f : null,
+      // The metric path as a jsonb path array (`a.b` → {a,b}); null when the
+      // chart is not summing anything.
+      (opts == null ? void 0 : opts.metricPath) ? opts.metricPath.split(".") : null
+    ];
+    const sql = `${this.rosterCte(true)},
+            -- The histogram's bucket width is derived from the set's own span, the
+            -- same ${import_persist.CNS_HISTOGRAM_BUCKETS}-bucket rule the reference implementation
+            -- uses. Computed here so the whole thing stays one round trip.
+            bounds AS (
+                SELECT MIN(started_at) AS mn, MAX(started_at) AS mx FROM filtered WHERE started_at > 0
+            ),
+            step AS (
+                SELECT mn,
+                       GREATEST(1, CEIL((mx - mn)::numeric / ${import_persist.CNS_HISTOGRAM_BUCKETS})::bigint) AS size
+                FROM bounds
+            )
+            SELECT 'entry' AS kind, entry->>'collateralName' AS key,
+                   COUNT(*)::bigint AS cnt,
+                   NULL::bigint AS ts_bucket, NULL::bigint AS completed,
+                   NULL::bigint AS failed, NULL::bigint AS running,
+                   NULL::numeric AS metric
+            FROM filtered GROUP BY 2
+            UNION ALL
+            SELECT 'status', status, COUNT(*)::bigint,
+                   NULL, NULL, NULL, NULL, NULL
+            FROM filtered GROUP BY 2
+            UNION ALL
+            -- One row per (run, neuron): the neuron rail counts runs that touched
+            -- a neuron, which is what UNNEST over the per-run DISTINCT array gives.
+            SELECT 'neuron', n, COUNT(*)::bigint,
+                   NULL, NULL, NULL, NULL, NULL
+            FROM filtered, UNNEST(neurons) AS n GROUP BY 2
+            UNION ALL
+            SELECT 'time', NULL, NULL,
+                   (step.mn + ((f.started_at - step.mn) / step.size) * step.size)::bigint,
+                   COUNT(*) FILTER (WHERE f.status = 'completed')::bigint,
+                   COUNT(*) FILTER (WHERE f.status = 'failed')::bigint,
+                   COUNT(*) FILTER (WHERE f.status NOT IN ('completed', 'failed'))::bigint,
+                   -- Only actual JSON numbers are summed, matching the reference's
+                   -- \`typeof v === 'number'\`: a payload field holding "12" as a
+                   -- string is not a metric and must not become one here.
+                   SUM(
+                       CASE WHEN $8::text[] IS NOT NULL
+                             AND jsonb_typeof(f.entry->'payload' #> $8::text[]) = 'number'
+                            THEN (f.entry->'payload' #> $8::text[])::text::numeric
+                       END
+                   )
+            FROM filtered f, step
+            WHERE f.started_at > 0
+            GROUP BY 4`;
+    const res = await this.db.query(sql, params);
+    const rows = res.rows;
+    const tally = /* @__PURE__ */ __name((kind) => rows.filter((r) => r.kind === kind && r.key != null).map((r) => ({
+      key: r.key,
+      count: Number(r.cnt)
+    })).sort((a, b) => b.count - a.count || (a.key < b.key ? -1 : 1)), "tally");
+    return {
+      byEntryCollateral: tally("entry").map((x) => ({
+        name: x.key,
+        count: x.count
+      })),
+      byStatus: tally("status").map((x) => ({
+        status: x.key,
+        count: x.count
+      })),
+      byNeuron: tally("neuron").map((x) => ({
+        name: x.key,
+        count: x.count
+      })),
+      byTime: rows.filter((r) => r.kind === "time" && r.ts_bucket != null).map((r) => ({
+        tsBucket: Number(r.ts_bucket),
+        completed: Number(r.completed),
+        failed: Number(r.failed),
+        running: Number(r.running),
+        // Absent rather than 0 when nothing was summed — the reference
+        // only sets `metric` once it has a number to put there.
+        ...r.metric == null ? {} : {
+          metric: Number(r.metric)
+        }
+      })).sort((a, b) => a.tsBucket - b.tsBucket)
+    };
   }
   // ── lifecycle ──
   async delete(stimulationId) {
-    await this.ensure();
+    await this.schemaReady();
     const { p } = this;
     await this.tx(async (db) => {
-      await db.query(`DELETE FROM ${p}task WHERE stimulation_attempt_id IN
+      await this.lockStimulation(db, stimulationId);
+      await db.query(`DELETE FROM ${p}stimulation_task WHERE stimulation_attempt_id IN
                     (SELECT stimulation_attempt_id FROM ${p}stimulation_attempt WHERE stimulation_id = $1)`, [
         stimulationId
       ]);
@@ -441,49 +790,93 @@ var _CNSPostgresStimulationRepository = class _CNSPostgresStimulationRepository
     });
   }
   /**
-   * Retention: prune stimulations not updated for `olderThanMs` (with their
-   * attempts/tasks/frontier). A run's `updated_at` stops advancing once it
-   * settles, so old finished runs age out while an active one stays fresh — the same
-   * semantics as the in-memory store's `ttlMs` and the pg-boss checkpoint's
-   * `deleteStale`. Run it on a schedule (cron). Returns the number removed.
+   * Retention: prune stimulations not updated for `olderThanMs`, with their
+   * attempts and tasks, in batches of one transaction each, then the attempts and
+   * tasks older than that whose parent row never arrived or is already gone; last,
+   * with a pool, drop the daily task partitions that ended before the window and
+   * create the next seven.
+   * Returns the number of stimulations removed.
    */
   async deleteStale(olderThanMs) {
-    await this.ensure();
+    await this.schemaReady();
     const { p } = this;
-    const params = [
-      Math.max(0, Math.floor(olderThanMs))
-    ];
-    const cond = `updated_at < now() - ($1::bigint * interval '1 millisecond')`;
-    const staleIds = `SELECT stimulation_id FROM ${p}stimulation WHERE ${cond}`;
-    return this.tx(async (db) => {
-      await db.query(`DELETE FROM ${p}task WHERE stimulation_attempt_id IN
-                    (SELECT stimulation_attempt_id FROM ${p}stimulation_attempt
-                     WHERE stimulation_id IN (${staleIds}))`, params);
-      await db.query(`DELETE FROM ${p}stimulation_attempt WHERE stimulation_id IN (${staleIds})`, params);
-      const res = await db.query(`DELETE FROM ${p}stimulation WHERE ${cond} RETURNING stimulation_id`, params);
-      return res.rows.length;
-    });
+    const now = this.now();
+    const cutoff = now - Math.max(0, Math.floor(olderThanMs));
+    let removedCount = 0;
+    let after = "";
+    for (; ; ) {
+      const batch = await this.tx(async (db) => {
+        const stale = await db.query(`SELECT stimulation_id FROM ${p}stimulation
+                     WHERE updated_at < $1 AND stimulation_id > $2
+                     ORDER BY stimulation_id LIMIT $3`, [
+          cutoff,
+          after,
+          _CNSPostgresStimulationRepository.RETENTION_BATCH
+        ]);
+        const candidates = stale.rows.map((row) => row.stimulation_id);
+        if (candidates.length === 0) return {
+          candidates,
+          removed: 0
+        };
+        await db.query(`SELECT pg_advisory_xact_lock($1, hashtext($2 || id)) FROM unnest($3::text[]) AS id ORDER BY id`, [
+          _CNSPostgresStimulationRepository.LOCK_STIMULATION,
+          p,
+          candidates
+        ]);
+        const removed = await db.query(`DELETE FROM ${p}stimulation WHERE stimulation_id = ANY($1) AND updated_at < $2 RETURNING stimulation_id`, [
+          candidates,
+          cutoff
+        ]);
+        const ids = removed.rows.map((row) => row.stimulation_id);
+        await db.query(`DELETE FROM ${p}stimulation_task t
+                     USING ${p}stimulation_attempt a
+                     WHERE a.stimulation_attempt_id = t.stimulation_attempt_id AND a.stimulation_id = ANY($1)`, [
+          ids
+        ]);
+        await db.query(`DELETE FROM ${p}stimulation_attempt WHERE stimulation_id = ANY($1)`, [
+          ids
+        ]);
+        return {
+          candidates,
+          removed: ids.length
+        };
+      });
+      removedCount += batch.removed;
+      if (batch.candidates.length < _CNSPostgresStimulationRepository.RETENTION_BATCH) break;
+      after = batch.candidates[batch.candidates.length - 1];
+    }
+    let rotationFailure;
+    if (this.pool) {
+      try {
+        await this.taskPartitions.rotate({
+          transaction: /* @__PURE__ */ __name((work) => this.tx((db) => work(db)), "transaction")
+        }, `${p}stimulation_task`, now, cutoff);
+      } catch (error) {
+        rotationFailure = {
+          error
+        };
+      }
+    }
+    await this.db.query(`DELETE FROM ${p}stimulation_attempt a
+             WHERE a.started_at < $1
+               AND NOT EXISTS (SELECT 1 FROM ${p}stimulation s WHERE s.stimulation_id = a.stimulation_id)`, [
+      cutoff
+    ]);
+    await this.db.query(`DELETE FROM ${p}stimulation_task t
+             WHERE t.started_at < $1
+               AND NOT EXISTS (SELECT 1 FROM ${p}stimulation_attempt a WHERE a.stimulation_attempt_id = t.stimulation_attempt_id)`, [
+      cutoff
+    ]);
+    if (rotationFailure) throw rotationFailure.error;
+    return removedCount;
   }
   async close() {
     if (this.ownsPool && this.pool) await this.pool.end();
   }
-  // ── helpers ──
-  buildProgress(frontier) {
-    const tasks = [
-      ...frontier
-    ].sort((a, b) => a.ord - b.ord).map((f) => ({
-      neuronName: f.neuron_name,
-      dendriteCollateralName: f.dendrite_collateral_name,
-      ...f.input != null ? {
-        input: f.input
-      } : {}
-    }));
-    return {
-      tasks
-    };
-  }
 };
 __name(_CNSPostgresStimulationRepository, "CNSPostgresStimulationRepository");
+__publicField(_CNSPostgresStimulationRepository, "LOCK_STIMULATION", 7);
+__publicField(_CNSPostgresStimulationRepository, "RETENTION_BATCH", 200);
 var CNSPostgresStimulationRepository = _CNSPostgresStimulationRepository;
 function rowToAttempt(a) {
   var _a;
@@ -505,7 +898,7 @@ function rowToTask(t) {
   var _a, _b;
   return {
     stimulationAttemptId: t.stimulation_attempt_id,
-    index: num(t.index),
+    index: num(t.task_index),
     neuronName: t.neuron_name,
     dendriteCollateralName: t.dendrite_collateral_name,
     inputIndex: num(t.input_index),
@@ -513,29 +906,28 @@ function rowToTask(t) {
     status: t.status,
     error: (_b = t.error) != null ? _b : null,
     startedAt: num(t.started_at),
-    duration: numOrNull(t.duration)
+    duration: numOrNull(t.duration_ms),
+    ...t.activation_context != null ? {
+      activationContext: t.activation_context
+    } : {}
   };
 }
 __name(rowToTask, "rowToTask");
-function groupBy(rows, key) {
-  const m = /* @__PURE__ */ new Map();
-  for (const r of rows) {
-    const k = key(r);
-    const b = m.get(k);
-    if (b) b.push(r);
-    else m.set(k, [
-      r
-    ]);
-  }
-  return m;
+function rowToStimulation(r) {
+  return {
+    stimulationId: r.stimulation_id,
+    entry: r.entry,
+    status: r.status,
+    progress: r.progress,
+    ...r.scope_name != null ? {
+      scopeName: r.scope_name
+    } : {}
+  };
 }
-__name(groupBy, "groupBy");
+__name(rowToStimulation, "rowToStimulation");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CNSPostgresStimulationRepository,
-  DEFAULT_PREFIX,
-  assertSafePrefix,
-  ensureSchema,
-  persistPostgresSchemaSql
+  CNSPostgresStimulationSchema
 });
 //# sourceMappingURL=index.js.map