@zq-silk/yui 0.5.2 → 0.6.0

package/dist/storage/storageVersions.js

@@ -5,7 +5,14 @@
  * and `taskStore.ts` can all import them without creating a circular dependency.
  * `storageSchema.ts` re-exports them for backward compatibility.
  */
-/** Version of the on-disk layout (`schema.json`, root `state.json`, and locks). */
-export const CURRENT_STORAGE_LAYOUT_VERSION = 6;
+/**
+ * Version of the on-disk layout (`schema.json`, root `state.json`, and locks).
+ *
+ * Layout 7 is the SQLite WAL control-plane layout (task-21 §8): the authoritative
+ * store moves from the aggregate `state.json` document to `yui.db`. A layout-6
+ * Home is migrated offline by the staged state.json→SQLite migration; layout 7
+ * is the current layout this release reads and writes.
+ */
+export const CURRENT_STORAGE_LAYOUT_VERSION = 7;
 /** Version of the authoritative aggregate stored in `state.json`. */
 export const CURRENT_AGGREGATE_SCHEMA_VERSION = 18;

package/dist/storage/storeRpc.js

@@ -0,0 +1,277 @@
+/**
+ * Bounded RPC seam for the persistence Worker Thread (task-21, work-item-5).
+ *
+ * The main thread talks to the persistence worker (storage/persistenceWorker)
+ * over a `MessageChannel` port. The backpressure, cancellation, and
+ * fault-boundary machinery lives in the shared `core/boundedRpc` module; this
+ * module adds the storage dialect:
+ *
+ *   - {@link AsyncTaskStore} ........ the async counterpart to `TaskStore`
+ *     (design §6): every method returns a promise; the worker owns the
+ *     `SqliteTaskStore` connection, the main thread never touches the db.
+ *   - {@link AsyncTaskStoreClient} .. the client: serializes requests, applies
+ *     the storage idempotency/dialect rules on top of the shared bounded RPC
+ *     (outbox §5.4, `AbortSignal` cancellation §3.1, restart + replay §3.1).
+ *   - {@link StoreCommand} .......... one variant per `TaskStore` op, so
+ *     `transactionAsync` ships an ordered batch that the worker runs inside one
+ *     `BEGIN IMMEDIATE … COMMIT` (§3.2).
+ *
+ * The file `TaskStore` remains the default for CLI tools and tests; the worker
+ * backend is opt-in via `YUI_STORE_BACKEND=sqlite` + `YUI_STORE_WORKER=1`
+ * ({@link resolveStoreWorkerEnabled}). Rollback to the file store is a config
+ * flip (§6).
+ */
+import { BoundedRpcClient, nextRequestId } from "../core/boundedRpc.js";
+import { StorageCancelledError, StorageConflictError, StorageRecordError } from "./taskStore.js";
+// -- Read-only classification ------------------------------------------------
+/**
+ * TaskStore methods that do not mutate. Reads use the worker's read pool
+ * (separate WAL connections that never take the write lock, §3.2). Everything
+ * else is routed to the writer connection.
+ */
+const READ_ONLY_STORE_METHODS = new Set([
+    "rootDirectory",
+    "getConfig",
+    "getHomeIdentity",
+    "getReviewConfig",
+    "getRevision",
+    "listConfiguredAgents",
+    "getConfiguredAgent",
+    "listProjects",
+    "getProject",
+    "listAgentProfiles",
+    "getAgentProfile",
+    "listGlobalRoles",
+    "getGlobalRole",
+    "getGlobalRoleSessionSet",
+    "listGlobalRoleSessionSets",
+    "listTasks",
+    "getTask",
+    "listActiveTaskIds",
+    "getTaskBrief",
+    "listChangeSets",
+    "getChangeSet",
+    "listIntegrationAttempts",
+    "getIntegrationAttempt",
+    "listRoles",
+    "getRole",
+    "listManagedWorkspaces",
+    "listManagedWorkspace",
+    "getManagedWorkspace",
+    "getTaskWorkspace",
+    "getWorkItemWorkspace",
+    "getReviewRoundWorkspace",
+    "getIntegrationWorkspace",
+    "getRoleSessionSet",
+    "getTaskRoleSessionSet",
+    "listRoleSessionSets",
+    "getRoleSession",
+    "getWorkItem",
+    "listWorkItems",
+    "getAgentRun",
+    "listAgentRuns",
+    "peekNextAgentRunId",
+    "getReviewRound",
+    "listReviewRuns",
+    "getActiveAgentRun",
+    "getActiveExecutionLaneRun",
+    "listMessages",
+    "getInputRequest",
+    "listInputRequests",
+    "listAllInputRequests",
+    "listDecisions",
+    "getDecision",
+    "listMilestones",
+    "getMilestone",
+    "listEvents",
+    "getWorkMailbox",
+    "listWorkMailboxes",
+    "getPendingWakeup",
+    "listPendingWakeups",
+    "getLeaderFailure",
+    "getOperatorNotification",
+    "listTelemetry",
+    "countTelemetry",
+    "hasOutboxEntry",
+    "listPendingOutbox"
+]);
+function isReadOnlyMethod(method) {
+    return READ_ONLY_STORE_METHODS.has(method);
+}
+// -- Error deserialization (storage dialect) ---------------------------------
+function deserializeError(serialized) {
+    const { name, message } = serialized;
+    if (name === "StorageConflictError")
+        return new StorageConflictError(message);
+    if (name === "StorageRecordError")
+        return new StorageRecordError(message);
+    if (name === "StorageCancelledError" || name === "AbortError") {
+        return new StorageCancelledError(message);
+    }
+    const error = new Error(message);
+    error.name = name;
+    return error;
+}
+// -- Storage protocol adapter -------------------------------------------------
+function storageProtocol(home, options) {
+    return {
+        initRequest: () => ({
+            kind: "init",
+            home,
+            ...(options.readPoolSize === undefined ? {} : { readPoolSize: options.readPoolSize }),
+            ...(options.observerModule === undefined
+                ? {}
+                : { observerModule: String(options.observerModule) })
+        }),
+        cancelRequest: (requestId) => ({ kind: "cancel", requestId }),
+        shutdownRequest: () => ({ kind: "shutdown" }),
+        isReady: (response) => response.kind === "ready",
+        responseRequestId: (response) => {
+            if (response.kind === "ready") {
+                throw new Error("ready response has no requestId.");
+            }
+            return response.requestId;
+        },
+        settle: (response, settlement) => {
+            if (response.kind === "result") {
+                settlement.resolve(response.result);
+                return;
+            }
+            if (response.kind === "already-applied") {
+                // The effect committed before a crash; the retry is deduped (§5.4). The
+                // original result is not retained; callers needing it re-read. Observer
+                // callers treat `undefined` as "applied".
+                settlement.resolve(undefined);
+                return;
+            }
+            if (response.kind === "error") {
+                settlement.reject(deserializeError(response.error));
+            }
+        },
+        abortError: (beforeSend) => new StorageCancelledError(beforeSend ? "Request aborted before it was sent." : "Request aborted.")
+    };
+}
+// -- Client ------------------------------------------------------------------
+/**
+ * The main-thread client for the persistence worker. Implements
+ * {@link AsyncTaskStore} (via a Proxy that forwards `TaskStore` methods as `call`
+ * RPCs) plus {@link transactionAsync}, {@link invokeObserver}, and {@link close}.
+ */
+export class AsyncTaskStoreClient {
+    #home;
+    #options;
+    #rpc;
+    constructor(home, options = {}) {
+        this.#home = home;
+        this.#options = options;
+        this.#rpc = new BoundedRpcClient(storageProtocol(home, options), {
+            maxInFlight: options.maxInFlight,
+            maxQueue: options.maxQueue,
+            workerScript: options.workerScript ?? new URL("./persistenceWorker.js", import.meta.url)
+        });
+    }
+    /** Invoke a TaskStore method over the RPC (used by the Proxy). */
+    callStore(method, args, options) {
+        const requestId = options?.requestId ?? nextRequestId();
+        return this.#rpc.send(requestId, {
+            kind: "call",
+            requestId,
+            method,
+            args,
+            readOnly: isReadOnlyMethod(method)
+        }, { signal: options?.signal });
+    }
+    /** Run a command batch atomically in the worker (§3.2). */
+    transactionAsync(commands, options) {
+        const requestId = options?.requestId ?? nextRequestId();
+        const wireCommands = commands.map((command) => ({
+            op: command.op,
+            args: command.args
+        }));
+        return this.#rpc.send(requestId, {
+            kind: "transaction",
+            requestId,
+            commands: wireCommands,
+            ...(options?.expectedRevision === undefined ? {} : { expectedRevision: options.expectedRevision })
+        }, { signal: options?.signal });
+    }
+    /**
+     * Invoke a controller observer method hosted by the worker (the
+     * `FileSchedulerStoreAdapter` observer surface). The adapter's folds run in
+     * the worker, off the main event loop.
+     */
+    invokeObserver(method, args, options) {
+        const requestId = options?.requestId ?? nextRequestId();
+        return this.#rpc.send(requestId, { kind: "observer", requestId, method, args }, { signal: options?.signal });
+    }
+    /** Close the worker and release its connections. */
+    close() {
+        return this.#rpc.close();
+    }
+    /** Currently in-flight requests (metrics/tests). */
+    get inFlight() {
+        return this.#rpc.inFlight;
+    }
+    /** Currently queued requests waiting for a slot (metrics/tests). */
+    get queueDepth() {
+        return this.#rpc.queueDepth;
+    }
+    /**
+     * Test-only fault injection: abruptly terminate the worker (simulating a
+     * crash) so the exit handler restarts it and replays unacknowledged requests
+     * (§3.1 fault boundary). The pending requests stay pending; they resolve
+     * after the restart + replay.
+     */
+    crashForTest() {
+        return this.#rpc.crashForTest();
+    }
+}
+/**
+ * Open an {@link AsyncTaskStore} backed by the persistence worker. The returned
+ * object is a Proxy that forwards `TaskStore` methods as RPCs; `transactionAsync`
+ * and `close` are handled directly.
+ */
+export function openAsyncTaskStoreClient(home, options = {}) {
+    const client = new AsyncTaskStoreClient(home, options);
+    const proxy = new Proxy(client, {
+        get(target, property) {
+            if (property === "then")
+                return undefined; // not promise-like
+            if (property in target) {
+                // Access on the target (not the proxy) so getters that touch private
+                // fields (#slots, etc.) resolve against the class instance.
+                const value = Reflect.get(target, property);
+                if (typeof value === "function")
+                    return value.bind(target);
+                return value;
+            }
+            if (typeof property === "string") {
+                return (...args) => {
+                    const options = args.length > 0 && isRpcCallOptions(args[args.length - 1])
+                        ? args.pop()
+                        : undefined;
+                    return target.callStore(property, args, options);
+                };
+            }
+            return undefined;
+        }
+    });
+    return proxy;
+}
+function isRpcCallOptions(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const record = value;
+    return "requestId" in record || "signal" in record;
+}
+/**
+ * Resolve whether the persistence worker backend is enabled (design §6).
+ * The worker requires the SQLite backend (`YUI_STORE_BACKEND=sqlite`) and is
+ * opt-in via `YUI_STORE_WORKER=1`. The file store remains the default.
+ */
+export function resolveStoreWorkerEnabled(env = process.env) {
+    if (env.YUI_STORE_BACKEND?.toLowerCase() !== "sqlite")
+        return false;
+    const flag = env.YUI_STORE_WORKER;
+    return flag === "1" || flag?.toLowerCase() === "true";
+}

package/dist/storage/taskStore.js

@@ -1165,6 +1165,15 @@ export class StorageRecordError extends Error {
 export class StorageConflictError extends Error {
     constructor(message) { super(message); this.name = "StorageConflictError"; }
 }
+/**
+ * Raised by the persistence worker when an `AbortSignal` cancels an in-flight
+ * command batch. The open transaction is rolled back; the database is unchanged.
+ * Already-committed transactions are not undone (their effects are idempotent
+ * and semantically owned by the caller, design §3.1).
+ */
+export class StorageCancelledError extends Error {
+    constructor(message) { super(message); this.name = "StorageCancelledError"; }
+}
 export function resolveYuiHome(env) {
     return env.YUI_HOME === undefined || env.YUI_HOME.length === 0
         ? join(homedir(), ".yui")

package/dist/storage/upgrade/homeClassification.js

@@ -23,9 +23,11 @@
  * non-empty families agree. This keeps a record-only-older Home on its version
  * axis without letting an empty target family masquerade as current.
  */
+import { existsSync } from "node:fs";
 import { classifyStorage } from "../migration/index.js";
 import { inspectStorageSchema } from "../storageSchema.js";
 import { FileTaskStore, StorageRecordError } from "../taskStore.js";
+import { SqliteTaskStore } from "../sqliteStore.js";
 import { inspectSourceVersionState } from "./homeMigrationTarget.js";
 /**
  * Classify a real Home. Reads `schema.json` (and, for a current Home,
@@ -102,26 +104,51 @@ export function classifyHome(options) {
     };
 }
 /**
- * Load a Home whose every axis is already current through the strict
- * `FileTaskStore` gate to detect real structural/reference corruption. This is
- * only ever called when the source equals `latest` across all three axes, so a
- * version error cannot occur here and any throw is genuine corruption (bad
- * record shape, a broken reference graph).
+ * Load a Home whose every axis is already current through the strict store
+ * gate to detect real structural/reference corruption. This is only ever
+ * called when the source equals `latest` across all three axes, so a version
+ * error cannot occur here and any throw is genuine corruption (bad record
+ * shape, a broken reference graph, or a damaged SQLite database).
+ *
+ * A layout-7 Home whose authoritative store is `yui.db` is verified through
+ * {@link SqliteTaskStore}; a layout-7 Home that still uses the aggregate
+ * `state.json` (or a layout-6 Home in tests) is verified through
+ * {@link FileTaskStore}.
  */
 function detectCurrentHomeCorruption(home) {
     try {
-        const store = new FileTaskStore(home);
-        store.getConfig();
-        store.listTasks();
-        store.listProjects();
-        store.listConfiguredAgents();
-        store.listWorkMailboxes();
+        if (existsSync(`${home}/yui.db`)) {
+            const store = new SqliteTaskStore(home);
+            try {
+                store.getConfig();
+                store.listTasks();
+                store.listProjects();
+                store.listConfiguredAgents();
+                store.listWorkMailboxes();
+            }
+            finally {
+                store.close();
+            }
+        }
+        else {
+            const store = new FileTaskStore(home);
+            store.getConfig();
+            store.listTasks();
+            store.listProjects();
+            store.listConfiguredAgents();
+            store.listWorkMailboxes();
+        }
         return undefined;
     }
     catch (error) {
         if (error instanceof StorageRecordError) {
             return { corrupted: true, detail: error.message };
         }
+        // A SQLite-level error (corrupt database file, I/O fault) is structural
+        // damage, not a version mismatch.
+        if (error instanceof Error && (error.name === "SqliteError" || error.message.includes("SQLite"))) {
+            return { corrupted: true, detail: error.message };
+        }
         // A non-record error (e.g. an unexpected I/O fault) is surfaced, not
         // silently swallowed as "usable".
         throw error;