@zq-silk/yui 0.6.0 → 0.6.2

package/dist/task/repairWave.js

@@ -0,0 +1,137 @@
+const SEVERITY_RANK = {
+    p1: 5,
+    critical: 4,
+    high: 3,
+    p2: 2,
+    medium: 1,
+    low: 0
+};
+const PATH_PATTERN = /(?:[\w.-]+\/)+[\w.-]+\.(?:ts|tsx|js|mjs|cjs|json|md|py|sh|yml|yaml|toml|css|html)(?::\d+)?/gu;
+/**
+ * Extract open findings from a ReviewRound. Structured ExecutionFindings on
+ * the Review's ExecutionGroup lanes win; when none exist, fall back to
+ * parsing P1/P2 lines from the Review report text.
+ */
+export function extractReviewFindings(round) {
+    const structured = (round.executionGroup?.lanes ?? [])
+        .flatMap((lane) => lane.result?.findings ?? [])
+        .filter((finding) => finding.status === "open");
+    if (structured.length > 0) {
+        return structured.map((finding) => ({
+            id: finding.id,
+            severity: finding.severity,
+            summary: finding.summary,
+            paths: extractPaths(finding.summary),
+            source: "structured"
+        }));
+    }
+    return parseReportFindings(round.report ?? "");
+}
+export function planRepairWave(reviewRoundId, findings) {
+    if (findings.length === 0) {
+        return { reviewRoundId, openFindingCount: 0, groups: [] };
+    }
+    const parent = new Array(findings.length).fill(0).map((_, index) => index);
+    const find = (index) => {
+        let current = index;
+        while (parent[current] !== current)
+            current = parent[current];
+        return current;
+    };
+    const union = (left, right) => {
+        const leftRoot = find(left);
+        const rightRoot = find(right);
+        if (leftRoot !== rightRoot)
+            parent[rightRoot] = leftRoot;
+    };
+    const unpathable = [];
+    for (let index = 0; index < findings.length; index += 1) {
+        if (findings[index].paths.length === 0)
+            unpathable.push(index);
+    }
+    // Unprovable findings merge together: the planner cannot prove they are
+    // disjoint from anything, so serializing them is the fail-closed choice.
+    for (let index = 1; index < unpathable.length; index += 1) {
+        union(unpathable[0], unpathable[index]);
+    }
+    for (let left = 0; left < findings.length; left += 1) {
+        for (let right = left + 1; right < findings.length; right += 1) {
+            if (sharePath(findings[left], findings[right]))
+                union(left, right);
+        }
+    }
+    const byRoot = new Map();
+    for (let index = 0; index < findings.length; index += 1) {
+        const root = find(index);
+        byRoot.set(root, [...(byRoot.get(root) ?? []), index]);
+    }
+    const groups = [...byRoot.values()]
+        .map((members, position) => {
+        const waveFindings = members.map((index) => findings[index]);
+        const paths = [...new Set(waveFindings.flatMap((finding) => finding.paths))]
+            .sort();
+        const reason = paths.length === 0
+            ? "No parseable paths; merged conservatively"
+            : waveFindings.length === 1
+                ? `Distinct path ${paths[0]}; parallel-safe`
+                : `Shared path(s) ${paths.join(", ")}; merged`;
+        return {
+            id: `repair-${position + 1}`,
+            findingIds: waveFindings.map((finding) => finding.id),
+            paths,
+            reason
+        };
+    })
+        .sort((left, right) => {
+        const leftRank = Math.max(...left.findingIds.map((id) => SEVERITY_RANK[findings.find((finding) => finding.id === id).severity]));
+        const rightRank = Math.max(...right.findingIds.map((id) => SEVERITY_RANK[findings.find((finding) => finding.id === id).severity]));
+        if (leftRank !== rightRank)
+            return rightRank - leftRank;
+        return left.id.localeCompare(right.id, undefined, { numeric: true });
+    })
+        .map((group, index) => ({ ...group, id: `repair-${index + 1}` }));
+    return {
+        reviewRoundId,
+        openFindingCount: findings.length,
+        groups
+    };
+}
+function sharePath(left, right) {
+    if (left.paths.length === 0 || right.paths.length === 0)
+        return false;
+    const rightPaths = new Set(right.paths.map(filePart));
+    return left.paths.some((path) => rightPaths.has(filePart(path)));
+}
+function filePart(path) {
+    return path.split(":")[0];
+}
+export function extractPaths(text) {
+    const matches = text.match(PATH_PATTERN) ?? [];
+    return [...new Set(matches)].sort();
+}
+/**
+ * Fallback finding extraction for Reviews without structured findings: parse
+ * P1/P2 lines from the report body. A line like "P1: src/foo.ts:12 ..." or
+ * "- P2 src/bar.ts ..." becomes one finding.
+ */
+export function parseReportFindings(report) {
+    const findings = [];
+    const lines = report.split(/\r?\n/u);
+    let index = 0;
+    for (const line of lines) {
+        const match = /^\s*(?:[-*]\s*)?(P[12])\b[:\s-]+(.+)$/u.exec(line);
+        if (match === null)
+            continue;
+        index += 1;
+        const severity = match[1].toLowerCase();
+        const summary = match[2].trim();
+        findings.push({
+            id: `report-p${severity === "p1" ? 1 : 2}-${index}`,
+            severity,
+            summary,
+            paths: extractPaths(summary),
+            source: "report"
+        });
+    }
+    return findings;
+}

package/dist/task/taskRecordReference.js

@@ -3,13 +3,18 @@ export const TASK_RECORD_ID_PREFIXES = {
     workItem: "work-item",
     agentRun: "agent-run",
     reviewRound: "review-round",
+    reviewFinding: "review-finding",
     changeSet: "change-set",
     integrationAttempt: "integration",
+    integrationQueue: "integration-queue",
+    durableJob: "job",
     message: "message",
     inputRequest: "input",
     decision: "decision",
     milestone: "milestone",
-    event: "event"
+    event: "event",
+    capabilityGrant: "capability-grant",
+    releaseWorkflow: "release-workflow"
 };
 export function formatTaskRecordReference(taskId, localId, kind) {
     const reference = validateTaskRecordReference({ taskId, localId }, kind);

package/dist/telemetry/sqliteTelemetryStore.js

@@ -0,0 +1,387 @@
+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 { migrateSqliteSchema } from "../storage/sqliteSchema.js";
+import { COMMITTED_DATABASE_FILENAME } from "../storage/upgrade/sqliteStateMigration.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
+ * 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.
+ *
+ * Writes are best-effort and never block the Controller event loop: `observe`
+ * only merges into a bounded in-memory queue; a background flush drains it in
+ * 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
+ * summary, maintained by triggers so it survives window pruning.
+ */
+const MAX_PAGE_LIMIT = 500;
+export class SqliteTelemetryStore {
+    mode;
+    #path;
+    #terminalKeep;
+    #runCap;
+    #maxPending;
+    #db = null;
+    #failed = false;
+    #lastError = null;
+    #dropped = 0;
+    #coalesced = 0;
+    #applied = 0;
+    #pending = new Map();
+    #flushScheduled = false;
+    #closed = false;
+    constructor(home, options = {}) {
+        this.mode = options.mode ?? "dual";
+        this.#path = join(home, COMMITTED_DATABASE_FILENAME);
+        this.#terminalKeep = options.terminalKeep ?? DEFAULT_TERMINAL_KEEP;
+        this.#runCap = options.runCap ?? DEFAULT_RUN_CAP;
+        this.#maxPending = options.maxPending ?? 10_000;
+    }
+    // -- TelemetrySink -------------------------------------------------------------
+    observe(entry) {
+        if (this.#closed)
+            return;
+        const db = this.#ensureDb();
+        if (db === null) {
+            this.#dropped++;
+            return;
+        }
+        const key = pendingKey(entry);
+        const existing = this.#pending.get(key);
+        if (existing !== undefined && !isNewer(entry, existing)) {
+            // Same hook replayed with an older/equal sequence: fold onto the row
+            // already queued. Replays never add rows.
+            this.#coalesced++;
+            return;
+        }
+        if (existing !== undefined)
+            this.#coalesced++;
+        if (this.#pending.size >= this.#maxPending && existing === undefined) {
+            this.#dropped++;
+            return;
+        }
+        this.#pending.set(key, entry);
+        this.#scheduleFlush();
+    }
+    health() {
+        return {
+            mode: this.mode,
+            available: !this.#failed && !this.#closed,
+            dropped: this.#dropped,
+            coalesced: this.#coalesced,
+            lastError: this.#lastError,
+            rows: this.#failed ? 0 : this.count()
+        };
+    }
+    async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        await this.#flushPending();
+        this.#db?.close();
+        this.#db = null;
+    }
+    // -- TelemetryReader -----------------------------------------------------------
+    count(taskId, runId) {
+        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) {
+            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;
+    }
+    list(taskId, runId, 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 items = rows.map(rowToEntry);
+        const total = this.count(taskId, runId);
+        const nextOffset = offset + items.length < total ? offset + items.length : null;
+        return { items, nextOffset };
+    }
+    aggregate(taskId, runId) {
+        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);
+        if (rows.length === 0)
+            return null;
+        return mergeAggregates(rows);
+    }
+    aggregateGeneration(taskId, roleName, runId, 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);
+        if (row === undefined)
+            return null;
+        return {
+            taskId: row.task_id,
+            roleName: row.role_name,
+            runId: row.run_id,
+            generation: row.generation,
+            firstAt: row.first_at,
+            lastAt: row.last_at,
+            count: row.count,
+            maxSequence: row.max_sequence,
+            errorCount: row.error_count
+        };
+    }
+    listRunAggregates(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);
+        return rows.map((row) => ({
+            taskId: row.task_id,
+            roleName: row.role_name,
+            runId: row.run_id,
+            generation: row.generation,
+            firstAt: row.first_at,
+            lastAt: row.last_at,
+            count: row.count,
+            maxSequence: row.max_sequence,
+            errorCount: row.error_count
+        }));
+    }
+    revision() {
+        return this.#applied;
+    }
+    latestProgressEvents(taskId) {
+        const db = this.#ensureDb();
+        if (db === null)
+            return [];
+        const rows = db.prepare(`SELECT task_id, role_name, run_id, generation, progress_id, sequence, payload, received_at FROM (
+         SELECT *, ROW_NUMBER() OVER (
+           PARTITION BY run_id
+           ORDER BY COALESCE(sequence, -1) DESC, received_at DESC, progress_id ASC
+         ) AS rn FROM telemetry WHERE task_id = ?
+       ) WHERE rn = 1`).all(taskId);
+        return rows.map((row) => {
+            const entry = rowToEntry(row);
+            const payload = { ...entry.payload };
+            payload.runId = entry.runId;
+            payload.progressId = entry.progressId;
+            // The semantic progress event carries progressAt = observation time;
+            // mirror that so liveness folds see the same timestamp.
+            payload.progressAt = entry.receivedAt;
+            return {
+                schemaVersion: 2,
+                id: `telemetry-progress-${entry.runId}-${entry.progressId}`,
+                taskId: entry.taskId,
+                type: "runtime.provider-turn-progress",
+                payload,
+                createdAt: entry.receivedAt
+            };
+        });
+    }
+    // -- retention -----------------------------------------------------------------
+    pruneGeneration(taskId, roleName, runId, 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 = ?
+           ORDER BY COALESCE(sequence, -1) DESC, received_at DESC, progress_id ASC
+           LIMIT ?
+         )`).run(taskId, roleName, runId, generation, taskId, roleName, runId, generation, keep);
+        return result.changes;
+    }
+    capRun(taskId, runId, cap = this.#runCap) {
+        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 = ?
+           ORDER BY COALESCE(sequence, -1) DESC, received_at DESC, progress_id ASC
+           LIMIT ?
+         )`).run(taskId, runId, taskId, runId, cap);
+        return result.changes;
+    }
+    importGeneration(entries, aggregate) {
+        const db = this.#ensureDb();
+        if (db === null) {
+            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)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(task_id, role_name, run_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)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(task_id, role_name, run_id, generation) DO UPDATE SET
+         first_at = excluded.first_at,
+         last_at = excluded.last_at,
+         count = excluded.count,
+         max_sequence = excluded.max_sequence,
+         error_count = excluded.error_count,
+         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);
+            }
+            upsertAggregate.run(aggregate.taskId, aggregate.roleName, aggregate.runId, aggregate.generation, aggregate.firstAt, aggregate.lastAt, aggregate.count, aggregate.maxSequence, aggregate.errorCount, aggregate.lastAt);
+        })();
+        this.#applied += entries.length;
+    }
+    async flush() {
+        await this.#flushPending();
+    }
+    // -- internals -----------------------------------------------------------------
+    #ensureDb() {
+        if (this.#db !== null)
+            return this.#db;
+        if (this.#failed || this.#closed)
+            return null;
+        try {
+            // The telemetry tables live in the Home's authoritative database; the
+            // store never creates `yui.db` itself. Wiring fails closed on Homes
+            // without a database instead of silently materializing an empty one.
+            if (!existsSync(this.#path)) {
+                throw new Error(`Telemetry database not found: ${this.#path}`);
+            }
+            const db = new Database(this.#path);
+            db.pragma("journal_mode = WAL");
+            db.pragma("synchronous = FULL");
+            db.pragma("foreign_keys = ON");
+            db.pragma("busy_timeout = 5000");
+            db.pragma("wal_autocheckpoint = 1000");
+            migrateSqliteSchema(db);
+            this.#db = db;
+            return db;
+        }
+        catch (error) {
+            this.#failed = true;
+            this.#lastError = error instanceof Error ? error.message : String(error);
+            return null;
+        }
+    }
+    #scheduleFlush() {
+        if (this.#flushScheduled)
+            return;
+        this.#flushScheduled = true;
+        const handle = setImmediate(() => {
+            this.#flushScheduled = false;
+            void this.#flushPending();
+        });
+        handle.unref?.();
+    }
+    async #flushPending() {
+        if (this.#pending.size === 0)
+            return;
+        const db = this.#ensureDb();
+        if (db === null) {
+            this.#dropped += this.#pending.size;
+            this.#pending.clear();
+            return;
+        }
+        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)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(task_id, role_name, run_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 {
+            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);
+                }
+            })();
+            this.#applied += batch.size;
+        }
+        catch (error) {
+            this.#lastError = error instanceof Error ? error.message : String(error);
+            this.#dropped += batch.size;
+        }
+    }
+}
+function pendingKey(entry) {
+    return `${entry.taskId}\u0000${entry.roleName}\u0000${entry.runId}\u0000${entry.generation}\u0000${entry.progressId}`;
+}
+/** True when `candidate` should replace `current` (sequence/receivedAt only move forward). */
+function isNewer(candidate, current) {
+    if (candidate.sequence !== undefined && current.sequence !== undefined) {
+        return candidate.sequence > current.sequence;
+    }
+    if (candidate.sequence !== undefined)
+        return true;
+    if (current.sequence !== undefined)
+        return false;
+    return Date.parse(candidate.receivedAt) >= Date.parse(current.receivedAt);
+}
+function rowToEntry(row) {
+    return {
+        taskId: row.task_id,
+        roleName: row.role_name,
+        runId: row.run_id,
+        generation: row.generation,
+        progressId: row.progress_id,
+        ...(row.sequence === null ? {} : { sequence: row.sequence }),
+        payload: JSON.parse(row.payload),
+        receivedAt: row.received_at
+    };
+}
+function mergeAggregates(rows) {
+    let firstAt = rows[0].first_at;
+    let lastAt = rows[0].last_at;
+    let count = 0;
+    let errorCount = 0;
+    let maxSequence = null;
+    let roleName = rows[0].role_name;
+    for (const row of rows) {
+        if (row.first_at < firstAt)
+            firstAt = row.first_at;
+        if (row.last_at > lastAt) {
+            lastAt = row.last_at;
+            roleName = row.role_name;
+        }
+        count += row.count;
+        errorCount += row.error_count;
+        if (row.max_sequence !== null && (maxSequence === null || row.max_sequence > maxSequence)) {
+            maxSequence = row.max_sequence;
+        }
+    }
+    return {
+        taskId: rows[0].task_id,
+        roleName,
+        runId: rows[0].run_id,
+        generation: "*",
+        firstAt,
+        lastAt,
+        count,
+        maxSequence,
+        errorCount
+    };
+}