@cnstra/persist-postgres 0.2.0 → 0.5.0

package/dist/index.mjs

@@ -1,15 +1,13 @@
 import {
-  DEFAULT_PREFIX,
+  CNSPostgresSchemaPartitionRotation,
+  CNSPostgresStimulationSchema,
   __name,
-  __publicField,
-  assertSafePrefix,
-  ensureSchema,
-  persistPostgresSchemaSql
-} from "./chunk-5FLIKV6I.mjs";
+  __publicField
+} from "./chunk-BPKIKGKB.mjs";
 
 // src/CNSPostgresStimulationRepository.ts
 import { Pool } from "pg";
-import { computeRosterFacets, encodeRosterCursor } from "@cnstra/persist";
+import { encodeCNSRosterCursor, CNS_HISTOGRAM_BUCKETS } from "@cnstra/persist";
 var j = /* @__PURE__ */ __name((v) => JSON.stringify(v != null ? v : null), "j");
 var num = /* @__PURE__ */ __name((v) => Number(v), "num");
 var numOrNull = /* @__PURE__ */ __name((v) => v == null ? null : Number(v), "numOrNull");
@@ -20,8 +18,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;
@@ -38,13 +40,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) {
@@ -64,68 +74,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
-      ]);
-      await db.query(`DELETE FROM ${p}stimulation_frontier WHERE stimulation_id = $1`, [
-        s.stimulationId
+        (_a = s.scopeName) != null ? _a : null,
+        j(s.progress),
+        now
       ]);
-      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,
@@ -135,65 +164,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`, [
-      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`, [
+    const res = await this.db.query(`SELECT stimulation_id, entry, status, scope_name, progress FROM ${p}stimulation WHERE stimulation_id = $1`, [
       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
+      scope,
+      since
     ]);
-    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
-    ]);
-    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
@@ -201,32 +202,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,
@@ -239,49 +300,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 {
@@ -304,26 +343,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 ? encodeRosterCursor(lastRow) : null,
+      nextCursor: hasMore && lastRow ? encodeCNSRosterCursor(lastRow) : null,
       total
     };
   }
   async queryFacets(filter, opts) {
-    const { entries } = await this.selectRoster(filter);
-    return 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 ${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 / ${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
       ]);
@@ -336,49 +468,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;
@@ -400,7 +576,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),
@@ -408,28 +584,27 @@ 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");
 export {
   CNSPostgresStimulationRepository,
-  DEFAULT_PREFIX,
-  assertSafePrefix,
-  ensureSchema,
-  persistPostgresSchemaSql
+  CNSPostgresStimulationSchema
 };
 //# sourceMappingURL=index.mjs.map