@zq-silk/yui 0.13.9 → 0.14.0

package/dist/telemetry/sqliteTelemetryStore.js

@@ -1,12 +1,12 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import Database from "better-sqlite3";
-import { DEFAULT_RUN_CAP, DEFAULT_TERMINAL_KEEP } from "./telemetryConfig.js";
+import { DEFAULT_TURN_CAP, DEFAULT_TERMINAL_KEEP } from "./telemetryConfig.js";
 import { migrateSqliteSchema } from "../storage/sqliteSchema.js";
-import { COMMITTED_DATABASE_FILENAME } from "../storage/upgrade/sqliteStateMigration.js";
+import { CURRENT_DATABASE_FILENAME as COMMITTED_DATABASE_FILENAME } from "../storage/currentTaskStore.js";
 /**
  * Default sidecar implementation: the telemetry tables live inside the Home's
- * authoritative `yui.db` (schema migrations 1 and 5), so a database-only Home
+ * authoritative `yui.db`, so a Home has one durable database
  * has one file to manage, back up, and migrate. The store opens its own
  * connection to that file: the write path is a single serialized writer (the
  * "WAL worker") and stays isolated from the business store's connection.
@@ -16,9 +16,9 @@ import { COMMITTED_DATABASE_FILENAME } from "../storage/upgrade/sqliteStateMigra
  * batches. Queue overflow and database failures increment `dropped` and record
  * a health warning — the semantic lane is never affected.
  *
- * The telemetry tables are maintained by the centralized schema migrations:
- * `telemetry` (migration 1, §4.4) holds the bounded latest-per-key window and
- * `telemetry_aggregate` (migration 5) holds the authoritative per-Run/generation
+ * The telemetry tables are maintained by the centralized schema baseline:
+ * `telemetry` holds the bounded latest-per-key window and
+ * `telemetry_aggregate` holds the authoritative per-Turn/generation
  * summary, maintained by triggers so it survives window pruning.
  */
 const MAX_PAGE_LIMIT = 500;
@@ -26,7 +26,7 @@ export class SqliteTelemetryStore {
     mode;
     #path;
     #terminalKeep;
-    #runCap;
+    #turnCap;
     #maxPending;
     #db = null;
     #failed = false;
@@ -41,7 +41,7 @@ export class SqliteTelemetryStore {
         this.mode = options.mode ?? "on";
         this.#path = join(home, COMMITTED_DATABASE_FILENAME);
         this.#terminalKeep = options.terminalKeep ?? DEFAULT_TERMINAL_KEEP;
-        this.#runCap = options.runCap ?? DEFAULT_RUN_CAP;
+        this.#turnCap = options.turnCap ?? DEFAULT_TURN_CAP;
         this.#maxPending = options.maxPending ?? 10_000;
     }
     // -- TelemetrySink -------------------------------------------------------------
@@ -89,52 +89,52 @@ export class SqliteTelemetryStore {
         this.#db = null;
     }
     // -- TelemetryReader -----------------------------------------------------------
-    count(taskId, runId) {
+    count(taskId, turnId) {
         const db = this.#ensureDb();
         if (db === null)
             return 0;
         if (taskId === undefined) {
             return db.prepare("SELECT COUNT(*) AS n FROM telemetry").get().n;
         }
-        if (runId === undefined) {
+        if (turnId === undefined) {
             return db.prepare("SELECT COUNT(*) AS n FROM telemetry WHERE task_id = ?").get(taskId).n;
         }
-        return db.prepare("SELECT COUNT(*) AS n FROM telemetry WHERE task_id = ? AND run_id = ?").get(taskId, runId).n;
+        return db.prepare("SELECT COUNT(*) AS n FROM telemetry WHERE task_id = ? AND turn_id = ?").get(taskId, turnId).n;
     }
-    list(taskId, runId, page = { limit: 100, offset: 0 }) {
+    list(taskId, turnId, page = { limit: 100, offset: 0 }) {
         const db = this.#ensureDb();
         if (db === null)
             return { items: [], nextOffset: null };
         const limit = Math.min(Math.max(1, Math.trunc(page.limit)), MAX_PAGE_LIMIT);
         const offset = Math.max(0, Math.trunc(page.offset));
-        const rows = runId === undefined
-            ? db.prepare("SELECT task_id, role_name, run_id, generation, progress_id, sequence, payload, received_at FROM telemetry WHERE task_id = ? ORDER BY received_at, progress_id LIMIT ? OFFSET ?").all(taskId, limit, offset)
-            : db.prepare("SELECT task_id, role_name, run_id, generation, progress_id, sequence, payload, received_at FROM telemetry WHERE task_id = ? AND run_id = ? ORDER BY received_at, progress_id LIMIT ? OFFSET ?").all(taskId, runId, limit, offset);
+        const rows = turnId === undefined
+            ? db.prepare("SELECT task_id, role_name, turn_id, generation, progress_id, sequence, payload, received_at FROM telemetry WHERE task_id = ? ORDER BY received_at, progress_id LIMIT ? OFFSET ?").all(taskId, limit, offset)
+            : db.prepare("SELECT task_id, role_name, turn_id, generation, progress_id, sequence, payload, received_at FROM telemetry WHERE task_id = ? AND turn_id = ? ORDER BY received_at, progress_id LIMIT ? OFFSET ?").all(taskId, turnId, limit, offset);
         const items = rows.map(rowToEntry);
-        const total = this.count(taskId, runId);
+        const total = this.count(taskId, turnId);
         const nextOffset = offset + items.length < total ? offset + items.length : null;
         return { items, nextOffset };
     }
-    aggregate(taskId, runId) {
+    aggregate(taskId, turnId) {
         const db = this.#ensureDb();
         if (db === null)
             return null;
-        const rows = db.prepare("SELECT task_id, role_name, run_id, generation, first_at, last_at, count, max_sequence, error_count FROM telemetry_aggregate WHERE task_id = ? AND run_id = ?").all(taskId, runId);
+        const rows = db.prepare("SELECT task_id, role_name, turn_id, generation, first_at, last_at, count, max_sequence, error_count FROM telemetry_aggregate WHERE task_id = ? AND turn_id = ?").all(taskId, turnId);
         if (rows.length === 0)
             return null;
         return mergeAggregates(rows);
     }
-    aggregateGeneration(taskId, roleName, runId, generation) {
+    aggregateGeneration(taskId, roleName, turnId, generation) {
         const db = this.#ensureDb();
         if (db === null)
             return null;
-        const row = db.prepare("SELECT task_id, role_name, run_id, generation, first_at, last_at, count, max_sequence, error_count FROM telemetry_aggregate WHERE task_id = ? AND role_name = ? AND run_id = ? AND generation = ?").get(taskId, roleName, runId, generation);
+        const row = db.prepare("SELECT task_id, role_name, turn_id, generation, first_at, last_at, count, max_sequence, error_count FROM telemetry_aggregate WHERE task_id = ? AND role_name = ? AND turn_id = ? AND generation = ?").get(taskId, roleName, turnId, generation);
         if (row === undefined)
             return null;
         return {
             taskId: row.task_id,
             roleName: row.role_name,
-            runId: row.run_id,
+            turnId: row.turn_id,
             generation: row.generation,
             firstAt: row.first_at,
             lastAt: row.last_at,
@@ -143,15 +143,15 @@ export class SqliteTelemetryStore {
             errorCount: row.error_count
         };
     }
-    listRunAggregates(taskId) {
+    listTurnAggregates(taskId) {
         const db = this.#ensureDb();
         if (db === null)
             return [];
-        const rows = db.prepare("SELECT task_id, role_name, run_id, generation, first_at, last_at, count, max_sequence, error_count FROM telemetry_aggregate WHERE task_id = ? ORDER BY run_id, generation").all(taskId);
+        const rows = db.prepare("SELECT task_id, role_name, turn_id, generation, first_at, last_at, count, max_sequence, error_count FROM telemetry_aggregate WHERE task_id = ? ORDER BY turn_id, generation").all(taskId);
         return rows.map((row) => ({
             taskId: row.task_id,
             roleName: row.role_name,
-            runId: row.run_id,
+            turnId: row.turn_id,
             generation: row.generation,
             firstAt: row.first_at,
             lastAt: row.last_at,
@@ -164,32 +164,32 @@ export class SqliteTelemetryStore {
         return this.#applied;
     }
     // -- retention -----------------------------------------------------------------
-    pruneGeneration(taskId, roleName, runId, generation, keep = this.#terminalKeep) {
+    pruneGeneration(taskId, roleName, turnId, generation, keep = this.#terminalKeep) {
         const db = this.#ensureDb();
         if (db === null)
             return 0;
         const result = db.prepare(`DELETE FROM telemetry
-       WHERE task_id = ? AND role_name = ? AND run_id = ? AND generation = ?
-         AND (task_id, role_name, run_id, generation, progress_id) NOT IN (
-           SELECT task_id, role_name, run_id, generation, progress_id FROM telemetry
-           WHERE task_id = ? AND role_name = ? AND run_id = ? AND generation = ?
+       WHERE task_id = ? AND role_name = ? AND turn_id = ? AND generation = ?
+         AND (task_id, role_name, turn_id, generation, progress_id) NOT IN (
+           SELECT task_id, role_name, turn_id, generation, progress_id FROM telemetry
+           WHERE task_id = ? AND role_name = ? AND turn_id = ? AND generation = ?
            ORDER BY COALESCE(sequence, -1) DESC, received_at DESC, progress_id ASC
            LIMIT ?
-         )`).run(taskId, roleName, runId, generation, taskId, roleName, runId, generation, keep);
+         )`).run(taskId, roleName, turnId, generation, taskId, roleName, turnId, generation, keep);
         return result.changes;
     }
-    capRun(taskId, runId, cap = this.#runCap) {
+    capTurn(taskId, turnId, cap = this.#turnCap) {
         const db = this.#ensureDb();
         if (db === null)
             return 0;
         const result = db.prepare(`DELETE FROM telemetry
-       WHERE task_id = ? AND run_id = ?
-         AND (task_id, role_name, run_id, generation, progress_id) NOT IN (
-           SELECT task_id, role_name, run_id, generation, progress_id FROM telemetry
-           WHERE task_id = ? AND run_id = ?
+       WHERE task_id = ? AND turn_id = ?
+         AND (task_id, role_name, turn_id, generation, progress_id) NOT IN (
+           SELECT task_id, role_name, turn_id, generation, progress_id FROM telemetry
+           WHERE task_id = ? AND turn_id = ?
            ORDER BY COALESCE(sequence, -1) DESC, received_at DESC, progress_id ASC
            LIMIT ?
-         )`).run(taskId, runId, taskId, runId, cap);
+         )`).run(taskId, turnId, taskId, turnId, cap);
         return result.changes;
     }
     importGeneration(entries, aggregate) {
@@ -198,18 +198,18 @@ export class SqliteTelemetryStore {
             this.#dropped += entries.length;
             return;
         }
-        const upsert = db.prepare(`INSERT INTO telemetry (task_id, role_name, run_id, generation, progress_id, sequence, payload, received_at)
+        const upsert = db.prepare(`INSERT INTO telemetry (task_id, role_name, turn_id, generation, progress_id, sequence, payload, received_at)
        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-       ON CONFLICT(task_id, role_name, run_id, generation, progress_id) DO UPDATE SET
+       ON CONFLICT(task_id, role_name, turn_id, generation, progress_id) DO UPDATE SET
          sequence = excluded.sequence,
          payload = excluded.payload,
          received_at = excluded.received_at
        WHERE COALESCE(excluded.sequence, -1) > COALESCE(telemetry.sequence, -1)
           OR (excluded.sequence IS telemetry.sequence AND excluded.received_at >= telemetry.received_at)`);
         const upsertAggregate = db.prepare(`INSERT INTO telemetry_aggregate
-         (task_id, role_name, run_id, generation, first_at, last_at, count, max_sequence, error_count, updated_at)
+         (task_id, role_name, turn_id, generation, first_at, last_at, count, max_sequence, error_count, updated_at)
        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-       ON CONFLICT(task_id, role_name, run_id, generation) DO UPDATE SET
+       ON CONFLICT(task_id, role_name, turn_id, generation) DO UPDATE SET
          first_at = excluded.first_at,
          last_at = excluded.last_at,
          count = excluded.count,
@@ -218,9 +218,9 @@ export class SqliteTelemetryStore {
          updated_at = excluded.updated_at`);
         db.transaction(() => {
             for (const entry of entries) {
-                upsert.run(entry.taskId, entry.roleName, entry.runId, entry.generation, entry.progressId, entry.sequence ?? null, JSON.stringify(entry.payload), entry.receivedAt);
+                upsert.run(entry.taskId, entry.roleName, entry.turnId, entry.generation, entry.progressId, entry.sequence ?? null, JSON.stringify(entry.payload), entry.receivedAt);
             }
-            upsertAggregate.run(aggregate.taskId, aggregate.roleName, aggregate.runId, aggregate.generation, aggregate.firstAt, aggregate.lastAt, aggregate.count, aggregate.maxSequence, aggregate.errorCount, aggregate.lastAt);
+            upsertAggregate.run(aggregate.taskId, aggregate.roleName, aggregate.turnId, aggregate.generation, aggregate.firstAt, aggregate.lastAt, aggregate.count, aggregate.maxSequence, aggregate.errorCount, aggregate.lastAt);
         })();
         this.#applied += entries.length;
     }
@@ -277,26 +277,26 @@ export class SqliteTelemetryStore {
         }
         const batch = new Map(this.#pending);
         this.#pending.clear();
-        const upsert = db.prepare(`INSERT INTO telemetry (task_id, role_name, run_id, generation, progress_id, sequence, payload, received_at)
+        const upsert = db.prepare(`INSERT INTO telemetry (task_id, role_name, turn_id, generation, progress_id, sequence, payload, received_at)
        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-       ON CONFLICT(task_id, role_name, run_id, generation, progress_id) DO UPDATE SET
+       ON CONFLICT(task_id, role_name, turn_id, generation, progress_id) DO UPDATE SET
          sequence = excluded.sequence,
          payload = excluded.payload,
          received_at = excluded.received_at
        WHERE COALESCE(excluded.sequence, -1) > COALESCE(telemetry.sequence, -1)
           OR (excluded.sequence IS telemetry.sequence AND excluded.received_at >= telemetry.received_at)`);
         try {
-            const touchedRuns = new Map();
+            const touchedTurns = new Map();
             db.transaction(() => {
                 for (const entry of batch.values()) {
-                    upsert.run(entry.taskId, entry.roleName, entry.runId, entry.generation, entry.progressId, entry.sequence ?? null, JSON.stringify(entry.payload), entry.receivedAt);
-                    touchedRuns.set(`${entry.taskId}\0${entry.runId}`, {
+                    upsert.run(entry.taskId, entry.roleName, entry.turnId, entry.generation, entry.progressId, entry.sequence ?? null, JSON.stringify(entry.payload), entry.receivedAt);
+                    touchedTurns.set(`${entry.taskId}\0${entry.turnId}`, {
                         taskId: entry.taskId,
-                        runId: entry.runId
+                        turnId: entry.turnId
                     });
                 }
-                for (const { taskId, runId } of touchedRuns.values()) {
-                    this.capRun(taskId, runId);
+                for (const { taskId, turnId } of touchedTurns.values()) {
+                    this.capTurn(taskId, turnId);
                 }
             })();
             this.#applied += batch.size;
@@ -308,7 +308,7 @@ export class SqliteTelemetryStore {
     }
 }
 function pendingKey(entry) {
-    return `${entry.taskId}\u0000${entry.roleName}\u0000${entry.runId}\u0000${entry.generation}\u0000${entry.progressId}`;
+    return `${entry.taskId}\u0000${entry.roleName}\u0000${entry.turnId}\u0000${entry.generation}\u0000${entry.progressId}`;
 }
 /** True when `candidate` should replace `current` (sequence/receivedAt only move forward). */
 function isNewer(candidate, current) {
@@ -325,7 +325,7 @@ function rowToEntry(row) {
     return {
         taskId: row.task_id,
         roleName: row.role_name,
-        runId: row.run_id,
+        turnId: row.turn_id,
         generation: row.generation,
         progressId: row.progress_id,
         ...(row.sequence === null ? {} : { sequence: row.sequence }),
@@ -356,7 +356,7 @@ function mergeAggregates(rows) {
     return {
         taskId: rows[0].task_id,
         roleName,
-        runId: rows[0].run_id,
+        turnId: rows[0].turn_id,
         generation: "*",
         firstAt,
         lastAt,

package/dist/telemetry/telemetryConfig.js

@@ -6,34 +6,34 @@
  * never changes canonical runtime-state persistence. Retention defaults are
  * the schema's own constants (§4.4); the environment only overrides them.
  */
-import { TELEMETRY_KEEP_PER_GENERATION, TELEMETRY_RUN_CAP } from "../storage/sqliteSchema.js";
+import { TELEMETRY_KEEP_PER_GENERATION, TELEMETRY_TURN_CAP } from "../storage/sqliteSchema.js";
 export const DEFAULT_TELEMETRY_MODE = "off";
-/** Terminal Run/generation progress rows retained after prune. */
+/** Terminal Turn/generation progress rows retained after prune. */
 export const DEFAULT_TERMINAL_KEEP = TELEMETRY_KEEP_PER_GENERATION;
-/** Hard cap of progress rows per Run while it is still active. */
-export const DEFAULT_RUN_CAP = TELEMETRY_RUN_CAP;
+/** Hard cap of progress rows per Turn while it is still active. */
+export const DEFAULT_TURN_CAP = TELEMETRY_TURN_CAP;
 /**
- * Absolute ceiling for the configurable Run cap. Retention can be tuned but
+ * Absolute ceiling for the configurable Turn cap. Retention can be tuned but
  * never disabled: every Home keeps a computable upper bound on telemetry
- * rows (Tasks × Runs × cap).
+ * rows (Tasks × Turns × cap).
  */
-export const MAX_RUN_CAP = 10_000_000;
+export const MAX_TURN_CAP = 10_000_000;
 /**
- * Resolve the terminal-Run retention window from the durable config value
+ * Resolve the terminal-Turn retention window from the durable config value
  * (default 200). Must be a positive integer.
  */
 export function resolveTerminalKeep(value) {
     return resolvePositiveInteger(value, DEFAULT_TERMINAL_KEEP, "telemetryTerminalKeep");
 }
 /**
- * Resolve the active-Run hard cap from the durable config value (default
- * 50,000). Must be a positive integer not exceeding {@link MAX_RUN_CAP};
+ * Resolve the active-Turn hard cap from the durable config value (default
+ * 50,000). Must be a positive integer not exceeding {@link MAX_TURN_CAP};
  * the cap cannot be disabled.
  */
-export function resolveRunCap(value) {
-    const cap = resolvePositiveInteger(value, DEFAULT_RUN_CAP, "telemetryRunCap");
-    if (cap > MAX_RUN_CAP) {
-        throw new TypeError(`telemetryRunCap must not exceed ${MAX_RUN_CAP.toLocaleString("en-US")} (retention cannot be disabled).`);
+export function resolveTurnCap(value) {
+    const cap = resolvePositiveInteger(value, DEFAULT_TURN_CAP, "telemetryTurnCap");
+    if (cap > MAX_TURN_CAP) {
+        throw new TypeError(`telemetryTurnCap must not exceed ${MAX_TURN_CAP.toLocaleString("en-US")} (retention cannot be disabled).`);
     }
     return cap;
 }

package/dist/telemetry/telemetryWiring.js

@@ -1,20 +1,14 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { resolveRunCap, resolveTerminalKeep } from "./telemetryConfig.js";
+import { resolveTurnCap, resolveTerminalKeep } from "./telemetryConfig.js";
 import { resolveTelemetryEnabled } from "../config/yuiConfig.js";
 import { SqliteTelemetryStore } from "./sqliteTelemetryStore.js";
-import { COMMITTED_DATABASE_FILENAME } from "../storage/upgrade/sqliteStateMigration.js";
+import { CURRENT_DATABASE_FILENAME as COMMITTED_DATABASE_FILENAME } from "../storage/currentTaskStore.js";
 /**
- * Open the telemetry sidecar for a Home, resolved from the durable Yui
- * config (default `legacy`). Returns null in legacy mode so callers keep the
- * exact master behavior and never touch the database.
- *
- * Telemetry lives in the Home's authoritative `yui.db`. A Home without a
- * database has not reached SQLite storage yet, so dual/bounded mode fails
- * closed at startup with a bounded diagnosis instead of silently creating an
- * empty database (which would corrupt Home classification). Once opened, the
- * store fails isolated: a broken sidecar only increments its dropped counter
- * and never blocks the semantic lane.
+ * Open optional telemetry from the current Home's authoritative `yui.db`.
+ * Disabled telemetry performs no database work. Once opened, telemetry fails
+ * isolated: a broken sink increments its dropped counter without blocking the
+ * semantic lane.
  */
 export function openSchedulerTelemetry(home, config) {
     if (!resolveTelemetryEnabled(config.telemetryEnabled))
@@ -23,12 +17,12 @@ export function openSchedulerTelemetry(home, config) {
     const dbPath = join(home, COMMITTED_DATABASE_FILENAME);
     if (!existsSync(dbPath)) {
         throw new Error(`telemetryEnabled=true requires SQLite storage, but ${dbPath} does not exist. `
-            + "Migrate this Home to the database backend first (yui upgrade).");
+            + "The current Home is incomplete; preserve it for diagnosis and initialize a new Home.");
     }
     const store = new SqliteTelemetryStore(home, {
         mode,
         terminalKeep: resolveTerminalKeep(config.telemetryTerminalKeep),
-        runCap: resolveRunCap(config.telemetryRunCap)
+        turnCap: resolveTurnCap(config.telemetryTurnCap)
     });
     return { mode, sink: store, reader: store, retention: store };
 }