@zq-silk/yui 0.5.3 → 0.6.1

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,298 @@
+/**
+ * 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";
+import { resolveTaskStoreBackendForHome } from "./sqliteStore.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",
+    "readNextActionFacts",
+    "listActiveTaskIds",
+    "getTaskBrief",
+    "listChangeSets",
+    "getChangeSet",
+    "listIntegrationAttempts",
+    "getIntegrationAttempt",
+    "listRoles",
+    "getRole",
+    "listManagedWorkspaces",
+    "listManagedWorkspace",
+    "getManagedWorkspace",
+    "getTaskWorkspace",
+    "getWorkItemWorkspace",
+    "getReviewRoundWorkspace",
+    "getIntegrationWorkspace",
+    "getRoleSessionSet",
+    "getTaskRoleSessionSet",
+    "listRoleSessionSets",
+    "getRoleSession",
+    "getWorkItem",
+    "listWorkItems",
+    "getAgentRun",
+    "listAgentRuns",
+    "listPendingProviderRetries",
+    "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";
+}
+/**
+ * Resolve whether the persistence worker is enabled, from the Home's verified
+ * manifest (Issue 01). A Home-decided SQLite backend (layout 7, no explicit
+ * `YUI_STORE_BACKEND`) runs the worker by default — that is the product
+ * commitment layout 7 makes. An env-decided SQLite backend keeps the
+ * historical opt-in (`YUI_STORE_WORKER=1`). `YUI_STORE_WORKER=0/false`
+ * disables the worker in both cases (in-process SQLite still applies).
+ */
+export function resolveStoreWorkerEnabledForHome(home, env = process.env) {
+    if (resolveTaskStoreBackendForHome(home, env) !== "sqlite")
+        return false;
+    const flag = env.YUI_STORE_WORKER?.toLowerCase();
+    if (flag === "1" || flag === "true")
+        return true;
+    if (flag === "0" || flag === "false")
+        return false;
+    return env.YUI_STORE_BACKEND?.toLowerCase() !== "sqlite";
+}