@zq-silk/yui 0.6.0 → 0.6.2

package/dist/observability/runtimeIdentity.js

@@ -0,0 +1,367 @@
+/**
+ * Read-only runtime identity facts for `controller status` and `execution audit`.
+ *
+ * Issue 11 boundary: this module only collects facts (manifest, process
+ * realpath/env, on-disk store evidence, Git). It never mutates state, never
+ * starts or stops a Controller, and never asks a producer to change. A fact
+ * that cannot be resolved is the literal string `"unsupported"` (the Issue 11
+ * fallback rule), and contradictory facts fail closed as findings with exact
+ * remediation actions.
+ */
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { join } from "node:path";
+import Database from "better-sqlite3";
+import { CURRENT_AGGREGATE_SCHEMA_VERSION, CURRENT_STORAGE_LAYOUT_VERSION } from "../storage/storageVersions.js";
+import { resolveTaskStoreBackendForHome } from "../storage/sqliteStore.js";
+import { resolveStoreWorkerEnabledForHome } from "../storage/storeRpc.js";
+export const UNSUPPORTED = "unsupported";
+/**
+ * Feature flag for the Issue 11 read-only status/audit presentation.
+ *
+ * Everything behind this flag is observe-only: identity fields, storage
+ * evidence, and metrics snapshots. The flag defaults ON because the fields
+ * change no behavior; set `YUI_STATUS_IDENTITY=0` (or `false`) to hide the new
+ * sections and the fail-closed health exit. `execution audit` is an explicit
+ * command and is not gated by this flag.
+ */
+export function resolveStatusIdentityEnabled(env = process.env) {
+    const value = env.YUI_STATUS_IDENTITY;
+    if (value === undefined)
+        return true;
+    const normalized = value.trim().toLowerCase();
+    return normalized !== "0" && normalized !== "false" && normalized !== "off";
+}
+export function evaluateStorageHealth(identity) {
+    const contradictions = identity.findings.filter(({ severity }) => severity === "contradiction");
+    const needsRepair = identity.findings.filter(({ severity }) => severity === "needs-repair");
+    const warnings = identity.findings.filter(({ severity }) => severity === "warning");
+    const status = contradictions.length > 0
+        ? "fail"
+        : needsRepair.length > 0
+            ? "degraded"
+            : "ok";
+    return { status, healthy: status === "ok", contradictions, needsRepair, warnings };
+}
+export function createProductionRuntimeIdentityPorts(packageRoot, entryPath, env = process.env) {
+    return {
+        env,
+        packageRoot,
+        entryPath,
+        readText: (path) => {
+            try {
+                return readFileSync(path, "utf8");
+            }
+            catch {
+                return null;
+            }
+        },
+        fileSize: (path) => {
+            try {
+                return statSync(path).size;
+            }
+            catch {
+                return null;
+            }
+        },
+        exists: (path) => existsSync(path),
+        realpath: (path) => {
+            try {
+                return realpathSync(path);
+            }
+            catch {
+                return null;
+            }
+        },
+        gitHead: (root) => readGitHead(root)
+    };
+}
+function readGitHead(packageRoot) {
+    try {
+        const result = spawnSync("git", ["-C", packageRoot, "rev-parse", "HEAD"], { encoding: "utf8", timeout: 1_500, stdio: ["ignore", "pipe", "ignore"] });
+        if (result.status !== 0)
+            return null;
+        const head = result.stdout.trim();
+        return /^[a-f0-9]{7,40}$/u.test(head) ? head : null;
+    }
+    catch {
+        return null;
+    }
+}
+function sha256Hex(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+export function collectRuntimeBuildIdentity(ports) {
+    const packageJsonText = ports.readText(join(ports.packageRoot, "package.json"));
+    let packageName = "unknown";
+    let packageVersion = "0.0.0";
+    let packageDigest = UNSUPPORTED;
+    if (packageJsonText !== null) {
+        packageDigest = `sha256:${sha256Hex(packageJsonText)}`;
+        try {
+            const parsed = JSON.parse(packageJsonText);
+            if (typeof parsed.name === "string" && parsed.name.length > 0) {
+                packageName = parsed.name;
+            }
+            if (typeof parsed.version === "string" && parsed.version.length > 0) {
+                packageVersion = parsed.version;
+            }
+        }
+        catch {
+            // Damaged package metadata still leaves the digest as evidence.
+        }
+    }
+    const entryRealpath = ports.realpath(ports.entryPath);
+    const entryText = entryRealpath === null ? null : ports.readText(entryRealpath);
+    return {
+        packageName,
+        packageVersion,
+        packageDigest,
+        entryPath: entryRealpath ?? UNSUPPORTED,
+        entryDigest: entryText === null
+            ? UNSUPPORTED
+            : `sha256:${sha256Hex(entryText)}`,
+        sourceCommit: ports.gitHead(ports.packageRoot) ?? UNSUPPORTED,
+        nodeVersion: process.version,
+        platform: `${process.platform}/${process.arch}`
+    };
+}
+export function createProductionStorageIdentityPorts(env = process.env) {
+    return {
+        env,
+        readText: (path) => {
+            try {
+                return readFileSync(path, "utf8");
+            }
+            catch {
+                return null;
+            }
+        },
+        fileSize: (path) => {
+            try {
+                return statSync(path).size;
+            }
+            catch {
+                return null;
+            }
+        },
+        exists: (path) => existsSync(path),
+        probeDatabaseHealth: (path) => {
+            if (!existsSync(path))
+                return null;
+            try {
+                const db = new Database(path, { readonly: true });
+                try {
+                    const integrity = db.pragma("quick_check", { simple: true });
+                    return integrity === "ok" ? "ok" : "corrupt";
+                }
+                finally {
+                    db.close();
+                }
+            }
+            catch {
+                return "unopenable";
+            }
+        }
+    };
+}
+/**
+ * Collect durable-vs-physical storage evidence for one Home. The manifest
+ * declares a logical layout; the directory carries physical evidence
+ * (state.json vs yui.db + WAL). Contradictions between the two are the
+ * pseudo-layout-7 class of failure and fail closed.
+ */
+export function collectStorageIdentity(home, ports = createProductionStorageIdentityPorts()) {
+    const manifestPath = join(home, "schema.json");
+    const manifestText = ports.readText(manifestPath);
+    let manifestStatus = "uninitialized";
+    let logicalLayout = UNSUPPORTED;
+    let aggregateSchemaVersion = UNSUPPORTED;
+    if (manifestText !== null) {
+        manifestStatus = "current";
+        try {
+            const manifest = JSON.parse(manifestText);
+            if (typeof manifest.storageVersion === "number"
+                && Number.isFinite(manifest.storageVersion)) {
+                logicalLayout = manifest.storageVersion;
+            }
+            if (typeof manifest.aggregateSchemaVersion === "number"
+                && Number.isFinite(manifest.aggregateSchemaVersion)) {
+                aggregateSchemaVersion = manifest.aggregateSchemaVersion;
+            }
+            if (typeof logicalLayout === "number"
+                && (logicalLayout > CURRENT_STORAGE_LAYOUT_VERSION
+                    || (typeof aggregateSchemaVersion === "number"
+                        && aggregateSchemaVersion > CURRENT_AGGREGATE_SCHEMA_VERSION))) {
+                manifestStatus = "unsupported";
+            }
+        }
+        catch {
+            manifestStatus = "invalid";
+            logicalLayout = UNSUPPORTED;
+            aggregateSchemaVersion = UNSUPPORTED;
+        }
+    }
+    const statePath = join(home, "state.json");
+    const statePresent = ports.exists(statePath);
+    const stateBytes = ports.fileSize(statePath);
+    const dbPath = join(home, "yui.db");
+    const dbPresent = ports.exists(dbPath);
+    const dbBytes = ports.fileSize(dbPath);
+    const walPresent = ports.exists(`${dbPath}-wal`);
+    const shmPresent = ports.exists(`${dbPath}-shm`);
+    const configuredBackend = resolveTaskStoreBackendForHome(home, ports.env);
+    const workerEnabled = resolveStoreWorkerEnabledForHome(home, ports.env);
+    const dbHealth = dbPresent ? ports.probeDatabaseHealth(dbPath) : null;
+    const hasMigrationReceipt = ports.exists(join(home, "migration-receipt.json"));
+    const findings = [];
+    // A readable state.json is a JSON object (the file store's record container).
+    // Pseudo-layout-7 is only repairable when state.json is a valid fallback.
+    const stateText = statePresent ? ports.readText(statePath) : null;
+    let stateReadable = false;
+    if (stateText !== null) {
+        try {
+            const parsed = JSON.parse(stateText);
+            stateReadable = typeof parsed === "object" && parsed !== null && !Array.isArray(parsed);
+        }
+        catch {
+            stateReadable = false;
+        }
+    }
+    const layout7 = manifestStatus === "current"
+        && typeof logicalLayout === "number"
+        && logicalLayout >= CURRENT_STORAGE_LAYOUT_VERSION;
+    if (layout7 && !dbPresent) {
+        if (stateReadable) {
+            // Pseudo-layout-7: manifest claims SQLite WAL but yui.db was never
+            // materialized. state.json is the readable fallback; `yui upgrade`
+            // rebuilds yui.db from it. This is the recognized NEEDS_STORAGE_REPAIR
+            // state, not a hard contradiction — the file store is legitimately
+            // serving until repair runs.
+            findings.push({
+                code: "pseudo-layout-7",
+                severity: "needs-repair",
+                message: `Manifest declares layout ${logicalLayout} (SQLite WAL) but `
+                    + `${dbPath} does not exist; state.json is the only authoritative `
+                    + "copy (pseudo-layout-7).",
+                remediation: "Run `yui upgrade` to rebuild yui.db from state.json."
+            });
+        }
+        else {
+            findings.push({
+                code: "no-authoritative-backend",
+                severity: "contradiction",
+                message: `Manifest declares layout ${logicalLayout} but neither `
+                    + "yui.db nor a readable state.json exists; there is no "
+                    + "authoritative backend.",
+                remediation: "Restore one copy from a backup; do not guess which is newer."
+            });
+        }
+    }
+    if (dbPresent && dbHealth !== null && dbHealth !== "ok") {
+        findings.push({
+            code: "database-unhealthy",
+            severity: "contradiction",
+            message: `yui.db exists but failed integrity check (${dbHealth}).`,
+            remediation: "Restore yui.db from backup, or run `yui upgrade` to rebuild "
+                + "it from state.json."
+        });
+    }
+    if (dbPresent && statePresent && !hasMigrationReceipt && layout7) {
+        findings.push({
+            code: "dual-copy-conflict",
+            severity: "contradiction",
+            message: "Both state.json and yui.db exist without a migration receipt; "
+                + "the authoritative copy is ambiguous.",
+            remediation: "Restore one copy from a backup; do not guess which is newer."
+        });
+    }
+    if (configuredBackend === "sqlite" && !dbPresent) {
+        findings.push({
+            code: "backend-sqlite-without-database",
+            severity: "contradiction",
+            message: "YUI_STORE_BACKEND=sqlite is set but no yui.db exists; the "
+                + "SQLite store cannot open this Home.",
+            remediation: "Run `yui upgrade` to create yui.db, or unset "
+                + "YUI_STORE_BACKEND to keep using the file store explicitly."
+        });
+    }
+    if (configuredBackend === "file"
+        && dbPresent
+        && manifestStatus === "current") {
+        findings.push({
+            code: "database-present-but-file-backend",
+            severity: "warning",
+            message: "yui.db exists but the file backend is selected; this process "
+                + "is serving state.json, not the database.",
+            remediation: "Unset YUI_STORE_BACKEND to let the Home manifest select "
+                + "SQLite, or remove the stale yui.db."
+        });
+    }
+    const rawWorkerFlag = ports.env.YUI_STORE_WORKER;
+    if (rawWorkerFlag !== undefined
+        && !workerEnabled
+        && configuredBackend !== "sqlite") {
+        findings.push({
+            code: "worker-flag-without-sqlite",
+            severity: "warning",
+            message: `YUI_STORE_WORKER=${rawWorkerFlag} is set but the worker `
+                + "requires YUI_STORE_BACKEND=sqlite; the worker is off.",
+            remediation: "Set YUI_STORE_BACKEND=sqlite to activate the worker, or "
+                + "unset YUI_STORE_WORKER."
+        });
+    }
+    // Only fire for pre-layout-7 Homes where the file store is the legitimate
+    // backend. A layout-7 Home without state.json is already covered by
+    // no-authoritative-backend above (the file store is just a fallback there).
+    if (configuredBackend === "file"
+        && !statePresent
+        && manifestStatus === "current"
+        && !(typeof logicalLayout === "number" && logicalLayout >= CURRENT_STORAGE_LAYOUT_VERSION)) {
+        findings.push({
+            code: "file-store-missing-state",
+            severity: "contradiction",
+            message: "The file backend is selected but state.json is missing.",
+            remediation: "Restore state.json from backup, or run the storage "
+                + "migration to create yui.db."
+        });
+    }
+    return {
+        home,
+        manifestStatus,
+        logicalLayout,
+        aggregateSchemaVersion,
+        configuredBackend,
+        workerEnabled,
+        physicalStateJson: {
+            present: statePresent,
+            bytes: stateBytes ?? UNSUPPORTED
+        },
+        physicalDatabase: {
+            present: dbPresent,
+            bytes: dbBytes ?? UNSUPPORTED,
+            wal: walPresent,
+            shm: shmPresent,
+            health: dbHealth ?? UNSUPPORTED
+        },
+        hasMigrationReceipt,
+        findings
+    };
+}
+/**
+ * Count telemetry events the runtime inbox rejected into
+ * `runtime/inbox-invalid/`. Dropped telemetry must stay countable and must
+ * never affect the semantic lane (Issue 11 §4). A missing directory means no
+ * drops (the inbox was never used); an unreadable directory is `unsupported`.
+ */
+export function countDroppedInboxEvents(home, listDirectory = (path) => readdirSync(path)) {
+    if (!existsSync(join(home, "runtime", "inbox-invalid")))
+        return 0;
+    try {
+        return listDirectory(join(home, "runtime", "inbox-invalid")).length;
+    }
+    catch {
+        return UNSUPPORTED;
+    }
+}

package/dist/release/fakeReleasePorts.js

@@ -0,0 +1,55 @@
+/**
+ * The deterministic double for every external system (GitHub, npm, Home,
+ * Controller). No real network, process, or filesystem side effect: the
+ * engine's at-most-once and recovery guarantees are proven against this.
+ */
+export function createFakeReleasePorts(scripts) {
+    const counters = new Map();
+    for (const stepId of Object.keys(scripts)) {
+        counters.set(stepId, { execute: 0, query: 0, keys: [] });
+    }
+    const tally = (stepId) => {
+        let calls = counters.get(stepId);
+        if (calls === undefined) {
+            calls = { execute: 0, query: 0, keys: [] };
+            counters.set(stepId, calls);
+        }
+        return calls;
+    };
+    const next = (queue, stepId, kind, consumed) => {
+        if (queue === undefined || consumed >= queue.length) {
+            throw new Error(`Fake release ports: no more scripted ${kind} outcomes for step ${stepId}.`);
+        }
+        const entry = queue[consumed];
+        return typeof entry === "function" ? entry() : entry;
+    };
+    return {
+        async executeStep(input) {
+            const calls = tally(input.step.id);
+            const effect = next(scripts[input.step.id]?.execute, input.step.id, "execute", calls.execute);
+            calls.execute += 1;
+            calls.keys.push(input.idempotencyKey);
+            return effect;
+        },
+        async queryStepEffect(input) {
+            const calls = tally(input.step.id);
+            const query = next(scripts[input.step.id]?.query, input.step.id, "query", calls.query);
+            calls.query += 1;
+            return query;
+        },
+        calls(stepId) {
+            const calls = tally(stepId);
+            return { execute: calls.execute, query: calls.query, keys: Object.freeze([...calls.keys]) };
+        },
+        exhausted() {
+            for (const [stepId, script] of Object.entries(scripts)) {
+                const calls = counters.get(stepId);
+                if ((script.execute?.length ?? 0) !== calls.execute)
+                    return false;
+                if ((script.query?.length ?? 0) !== calls.query)
+                    return false;
+            }
+            return true;
+        }
+    };
+}