@noopolis/daimon 0.1.1 → 0.2.0

package/dist/runtime/wakeFuse.js

@@ -0,0 +1,367 @@
+import { constants } from "node:fs";
+import { open, readFile, readdir, rename, stat, unlink } from "node:fs/promises";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { resolveTurnUsageLedgerPath, TURN_USAGE_LEDGER, TURN_USAGE_MAX_IDENTIFIER_CHARS, TURN_USAGE_ROTATE_BYTES } from "./turnUsageLedger.js";
+export const WAKE_FUSE_VERSION = "noopolis.daimon.wake-fuse.v1";
+export const WAKE_FUSE_DIRECTORY_ENV = "DAIMON_WAKE_FUSE_DIRECTORY";
+export const DEFAULT_WAKE_FUSE_MAX_WAKES = 100;
+export const DEFAULT_WAKE_FUSE_MAX_TOKENS = 5_000_000;
+const TRIP_MARKER = "fuse.trip.json";
+let warnedDisarmed = false;
+/**
+ * Durable catastrophic-wake admission fuse for one organization/container.
+ *
+ * Operator trip: `docker exec <container> touch /var/lib/spawnfile/daimon/usage/fuse.stop`.
+ * Unlike `recordTurnUsage` ("advisory: never rejects"), every storage or
+ * evaluation failure here rejects admission: this safety boundary fails closed.
+ */
+export class WakeFuse {
+    armed;
+    directory;
+    epoch;
+    epochStartedAt;
+    maxWakes;
+    maxTokens;
+    admissions;
+    usageLedgerPath;
+    now;
+    serial = Promise.resolve();
+    reason;
+    tripMarkerMissing = false;
+    constructor(armed, directory, epoch, epochStartedAt, maxWakes, maxTokens, admissions, usageLedgerPath, now) {
+        this.armed = armed;
+        this.directory = directory;
+        this.epoch = epoch;
+        this.epochStartedAt = epochStartedAt;
+        this.maxWakes = maxWakes;
+        this.maxTokens = maxTokens;
+        this.admissions = admissions;
+        this.usageLedgerPath = usageLedgerPath;
+        this.now = now;
+    }
+    static async open(options) {
+        const environment = options.environment ?? process.env;
+        const setting = environment.DAIMON_WAKE_FUSE;
+        if (setting !== undefined && setting !== "off")
+            throw new Error("DAIMON_WAKE_FUSE must be exactly 'off' when set");
+        if (environment.DAIMON_WAKE_FUSE_EPOCH !== undefined && nonBlank(environment.DAIMON_WAKE_FUSE_EPOCH) === undefined)
+            throw new Error("DAIMON_WAKE_FUSE_EPOCH must be non-blank");
+        const epoch = nonBlank(environment.DAIMON_WAKE_FUSE_EPOCH)
+            // Agent ids are the stable organization identity available to Daimon.
+            ?? `organization-${createHash("sha256").update(options.organizationKey).digest("hex")}`;
+        const maxWakes = ceiling(environment.DAIMON_WAKE_FUSE_MAX_WAKES, DEFAULT_WAKE_FUSE_MAX_WAKES, "DAIMON_WAKE_FUSE_MAX_WAKES");
+        const maxTokens = ceiling(environment.DAIMON_WAKE_FUSE_MAX_TOKENS, DEFAULT_WAKE_FUSE_MAX_TOKENS, "DAIMON_WAKE_FUSE_MAX_TOKENS");
+        const directory = resolveWakeFuseDirectory(environment);
+        const now = options.now ?? (() => new Date());
+        const usageLedgerPath = resolveTurnUsageLedgerPath(environment);
+        if (setting === "off") {
+            if (!warnedDisarmed) {
+                warnedDisarmed = true;
+                console.error("DAIMON WAKE FUSE IS OFF: wake admission is unbounded");
+            }
+            return new WakeFuse(false, directory, epoch, now().toISOString(), maxWakes, maxTokens, new Set(), usageLedgerPath, now);
+        }
+        // Unbounded defaults would reproduce exactly the failure this module prevents.
+        await readdir(directory);
+        await ensureUsageLedgerUsable(usageLedgerPath);
+        const records = await readFuseRecords(directory);
+        const existingStart = records.filter((record) => record.kind === "epoch_start" && record.epoch === epoch).at(-1);
+        const epochStartedAt = existingStart?.at ?? now().toISOString();
+        if (existingStart === undefined)
+            await append(directory, { v: WAKE_FUSE_VERSION, kind: "epoch_start", epoch, at: epochStartedAt });
+        const admissions = new Set(records
+            .filter((record) => record.kind === "admission" && record.epoch === epoch)
+            .map((record) => key(record.agent, record.delivery)));
+        const fuse = new WakeFuse(true, directory, epoch, epochStartedAt, maxWakes, maxTokens, admissions, usageLedgerPath, now);
+        if (await exists(path.join(directory, "fuse.stop")))
+            fuse.reason = "operator_stop";
+        else
+            fuse.reason = await readTripMarker(directory, epoch);
+        return fuse;
+    }
+    admit(agentId, deliveryId, limits = {}) {
+        if (!this.armed)
+            return Promise.resolve({ state: "admitted" });
+        // One organization is one container/control-host process. This promise
+        // chain is organization-wide in-process serialization, not cross-process locking.
+        const result = this.serial.catch(() => undefined).then(async () => await this.admitNow(agentId, deliveryId, limits));
+        this.serial = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    async snapshot(agentId, limits = {}) {
+        const used = this.admissions.size;
+        const agentUsed = [...this.admissions].filter((entry) => entry.startsWith(`${bounded(agentId)}\u0000`)).length;
+        const tokens = this.armed ? await sumTokens(this.usageLedgerPath, this.epochStartedAt) : 0;
+        const agentTokens = this.armed ? await sumTokens(this.usageLedgerPath, this.epochStartedAt, agentId) : 0;
+        const reason = this.reason ?? (this.armed ? used >= this.maxWakes ? "wake_ceiling" : tokens >= this.maxTokens ? "token_ceiling" : limits.maxExecutions !== undefined && agentUsed >= limits.maxExecutions ? "agent_execution_ceiling" : limits.maxTokens !== undefined && agentTokens >= limits.maxTokens ? "agent_token_ceiling" : undefined : undefined);
+        return { armed: this.armed, epoch: this.epoch, state: reason === undefined ? "available" : reason === "operator_stop" || reason === "ledger_unavailable" ? "stopped" : "paused", ...(reason === undefined ? {} : { reason }), executions_used: used, executions_remaining: Math.max(0, this.maxWakes - used), tokens_used: tokens, tokens_remaining: Math.max(0, this.maxTokens - tokens), agent_executions_used: agentUsed, agent_tokens_used: agentTokens, ...(limits.maxExecutions === undefined ? {} : { agent_executions_remaining: Math.max(0, limits.maxExecutions - agentUsed) }), ...(limits.maxTokens === undefined ? {} : { agent_tokens_remaining: Math.max(0, limits.maxTokens - agentTokens) }) };
+    }
+    async pollOperatorStop() {
+        if (!this.armed || this.reason === "operator_stop" || this.reason === "ledger_unavailable")
+            return this.reason;
+        try {
+            if (await exists(path.join(this.directory, "fuse.stop")))
+                await this.trip("operator_stop");
+        }
+        catch {
+            await this.trip("ledger_unavailable");
+        }
+        return this.reason;
+    }
+    tripped() { return this.reason; }
+    async close() { await this.serial; }
+    async admitNow(agentId, deliveryId, limits) {
+        if (this.reason !== undefined)
+            return await this.trip(this.reason);
+        try {
+            if (await exists(path.join(this.directory, "fuse.stop")))
+                return await this.trip("operator_stop");
+            const admissionKey = key(bounded(agentId), bounded(deliveryId));
+            if (this.admissions.has(admissionKey))
+                return { state: "admitted" };
+            const budget = await this.snapshot(agentId, limits);
+            if (budget.agent_executions_remaining === 0)
+                return { state: "paused", reason: "agent_execution_ceiling" };
+            if (budget.agent_tokens_remaining === 0)
+                return { state: "paused", reason: "agent_token_ceiling" };
+            if (this.admissions.size >= this.maxWakes)
+                return await this.trip("wake_ceiling");
+            // Lagging indicator: usage is written after turn completion, so in-flight
+            // spend can overshoot by one concurrent round. The wake ceiling bounds it;
+            // design §5.2 owns the later pre-spawn reservation.
+            if (await sumTokens(this.usageLedgerPath, this.epochStartedAt) >= this.maxTokens)
+                return await this.trip("token_ceiling");
+            const record = { v: WAKE_FUSE_VERSION, kind: "admission", epoch: this.epoch, at: this.now().toISOString(), agent: bounded(agentId), delivery: bounded(deliveryId) };
+            await append(this.directory, record);
+            this.admissions.add(admissionKey);
+            return { state: "admitted" };
+        }
+        catch {
+            return await this.trip("ledger_unavailable");
+        }
+    }
+    async trip(reason) {
+        if (this.reason === undefined || (reason === "operator_stop" || reason === "ledger_unavailable") && this.reason !== "operator_stop" && this.reason !== "ledger_unavailable") {
+            this.reason = reason;
+            this.tripMarkerMissing = true;
+        }
+        if (this.tripMarkerMissing) {
+            try {
+                await writeTripMarker(this.directory, { v: WAKE_FUSE_VERSION, kind: "trip", epoch: this.epoch, at: this.now().toISOString(), reason: this.reason });
+                this.tripMarkerMissing = false;
+            }
+            catch {
+                // Keep the in-memory fuse closed and retry durability on every later
+                // admit/trip. Marker I/O must never turn a tripped verdict into an
+                // unhandled rejection at the HTTP boundary.
+            }
+        }
+        return { state: "tripped", reason: this.reason };
+    }
+}
+export function resolveWakeFuseDirectory(environment = process.env) {
+    const override = environment[WAKE_FUSE_DIRECTORY_ENV]?.trim();
+    return override !== undefined && override.startsWith("/") ? override : TURN_USAGE_LEDGER.directoryPath;
+}
+function ceiling(value, fallback, name) {
+    if (value === undefined)
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed <= 0)
+        throw new Error(`${name} must be a positive integer`);
+    return parsed;
+}
+function nonBlank(value) { const trimmed = value?.trim(); return trimmed ? trimmed : undefined; }
+function bounded(value) { return [...value].slice(0, TURN_USAGE_MAX_IDENTIFIER_CHARS).join(""); }
+function key(agent, delivery) { return `${agent}\u0000${delivery}`; }
+function admissionsPath(directory) { return path.join(directory, "admissions.jsonl"); }
+async function append(directory, record) {
+    const file = admissionsPath(directory);
+    try {
+        if ((await stat(file)).size >= TURN_USAGE_ROTATE_BYTES)
+            await rename(file, `${file}.1`);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const bytes = Buffer.from(`${JSON.stringify(record)}\n`, "utf8");
+    const handle = await open(file, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW, TURN_USAGE_LEDGER.fileMode);
+    try {
+        const result = await handle.write(bytes, 0, bytes.length);
+        if (result.bytesWritten !== bytes.length)
+            throw new Error("wake fuse admission append was torn");
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await syncDirectory(directory);
+}
+async function syncDirectory(directory) { const handle = await open(directory, constants.O_RDONLY); try {
+    await handle.sync();
+}
+finally {
+    await handle.close();
+} }
+async function readFuseRecords(directory) {
+    const records = [];
+    for (const file of [`${admissionsPath(directory)}.1`, admissionsPath(directory)]) {
+        for (const line of await lines(file)) {
+            try {
+                const value = JSON.parse(line);
+                if (value.v !== WAKE_FUSE_VERSION || typeof value.epoch !== "string" || typeof value.at !== "string" || Number.isNaN(Date.parse(value.at)))
+                    continue;
+                if (value.kind === "epoch_start")
+                    records.push(value);
+                else if (value.kind === "admission" && typeof value.agent === "string" && typeof value.delivery === "string")
+                    records.push(value);
+            }
+            catch { /* malformed historical fuse lines do not count */ }
+        }
+    }
+    return records;
+}
+async function sumTokens(ledgerPath, since, agentId) {
+    let total = 0;
+    // Rows carrying a `turn` idempotency key count once per turn, whichever file holds them.
+    const turns = new Set();
+    for (const file of [`${ledgerPath}.1`, ledgerPath]) {
+        for (const line of await lines(file)) {
+            try {
+                const value = JSON.parse(line);
+                // Evaluator inference rows belong to their own ledger; one here (a misconfigured path) is never subject spend.
+                if (value.kind === "inference")
+                    continue;
+                if (typeof value.turn === "string") {
+                    if (turns.has(value.turn))
+                        continue;
+                    turns.add(value.turn);
+                }
+                if ((agentId === undefined || value.agent === agentId) && typeof value.at === "string" && !Number.isNaN(Date.parse(value.at)) && value.at >= since && typeof value.total === "number" && Number.isFinite(value.total) && value.total >= 0)
+                    total += value.total;
+            }
+            catch { /* usage accounting is advisory input; malformed lines are skipped */ }
+        }
+    }
+    return total;
+}
+async function writeTripMarker(directory, marker) {
+    const target = path.join(directory, TRIP_MARKER);
+    const temporary = path.join(directory, `.${TRIP_MARKER}.${process.pid}.${randomUUID()}`);
+    const bytes = Buffer.from(`${JSON.stringify(marker)}\n`, "utf8");
+    try {
+        const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, TURN_USAGE_LEDGER.fileMode);
+        try {
+            const result = await handle.write(bytes, 0, bytes.length);
+            if (result.bytesWritten !== bytes.length)
+                throw new Error("wake fuse trip marker write was torn");
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(temporary, target);
+        await syncDirectory(directory);
+    }
+    finally {
+        await unlink(temporary).catch(() => undefined);
+    }
+}
+async function readTripMarker(directory, epoch) {
+    try {
+        const value = JSON.parse(await readFile(path.join(directory, TRIP_MARKER), "utf8"));
+        if (value.v !== WAKE_FUSE_VERSION || value.kind !== "trip" || typeof value.epoch !== "string" || typeof value.at !== "string" || Number.isNaN(Date.parse(value.at)) || !isTripReason(value.reason))
+            return "ledger_unavailable";
+        // A valid marker belongs to one explicit counting window. Selecting a new
+        // epoch deliberately clears it; a corrupt marker cannot prove that and fails closed.
+        return value.epoch === epoch ? value.reason : undefined;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        return "ledger_unavailable";
+    }
+}
+function isTripReason(value) { return value === "wake_ceiling" || value === "token_ceiling" || value === "operator_stop" || value === "ledger_unavailable"; }
+async function lines(file) { try {
+    return (await readFile(file, "utf8")).split("\n").filter(Boolean);
+}
+catch (error) {
+    if (error.code === "ENOENT")
+        return [];
+    throw error;
+} }
+/**
+ * An unenforceable usage ledger at arm time must never degrade to a silent
+ * zero. `sumTokens` (used on every later `admit`) deliberately treats a
+ * missing ledger as an empty one — if the ledger is deleted mid-epoch, the
+ * fuse still needs to keep functioning rather than wedge the organization —
+ * but that same tolerance is exactly how a 17.6M-token run passed a 5M
+ * ceiling untouched: the ledger was never created at all, so every sum read
+ * zero and the ceiling never had anything to compare against.
+ *
+ * Four states, distinguished by what actually makes the ceiling
+ * unenforceable versus merely unwritten yet:
+ *  - The ledger directory is missing, or present but not writable by this
+ *    uid: the ceiling is genuinely unenforceable. Fails loudly, the same
+ *    treatment `readdir(directory)` above already gives a missing
+ *    admissions directory.
+ *  - The directory is present and writable but the ledger file itself is
+ *    absent: Spawnfile's entrypoint provisions and chows the directory as a
+ *    persistent volume before the first turn ever writes usage
+ *    (`renderDaimonUsageLedgerProvisioning`), so a brand-new organization
+ *    legitimately has zero recorded spend. That is a true zero, not an
+ *    unknown one — but only once this durably creates the (empty) ledger
+ *    itself and verifies the result is readable, rather than assuming a
+ *    missing file means zero.
+ *  - The ledger file exists and is readable: arm normally; `sumTokens` sums
+ *    whatever is in it.
+ *  - The ledger file exists but is unreadable (EACCES, EISDIR, ...): fails
+ *    loudly, exactly as before.
+ */
+async function ensureUsageLedgerUsable(ledgerPath) {
+    try {
+        await readFile(ledgerPath, "utf8");
+        return;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== "ENOENT") {
+            throw new Error(`DAIMON_WAKE_FUSE cannot start: usage ledger at ${ledgerPath} is missing or unreadable (${code ?? String(error)}); refusing to admit wakes against an unenforceable token ceiling`);
+        }
+    }
+    // Ledger file absent. Create it empty, matching the mode the broker itself
+    // writes usage records with, so a fresh organization can start.
+    try {
+        const handle = await open(ledgerPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, TURN_USAGE_LEDGER.fileMode);
+        await handle.close();
+    }
+    catch (error) {
+        const code = error.code;
+        // EEXIST means a concurrent writer created it first (e.g. a racing turn
+        // append); that is not a creation failure, so fall through to verify.
+        if (code !== "EEXIST") {
+            throw new Error(`DAIMON_WAKE_FUSE cannot start: usage ledger at ${ledgerPath} is missing and could not be created (${code ?? String(error)}); refusing to admit wakes against an unenforceable token ceiling`);
+        }
+    }
+    // Never assume the create succeeded: read the file back before treating
+    // the ceiling as enforceable.
+    try {
+        await readFile(ledgerPath, "utf8");
+    }
+    catch (error) {
+        const code = error.code ?? String(error);
+        throw new Error(`DAIMON_WAKE_FUSE cannot start: usage ledger at ${ledgerPath} is missing or unreadable (${code}); refusing to admit wakes against an unenforceable token ceiling`);
+    }
+}
+async function exists(file) { try {
+    await stat(file);
+    return true;
+}
+catch (error) {
+    if (error.code === "ENOENT")
+        return false;
+    throw error;
+} }

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@noopolis/daimon",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Noopolis native per-agent runtime harness built on Pi.",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "daimon-runtime": "dist/runtime/cli.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -18,6 +21,10 @@
     "./observability": {
       "types": "./dist/observability/index.d.ts",
       "import": "./dist/observability/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/index.js"
     }
   },
   "files": [
@@ -32,36 +39,37 @@
     "access": "public"
   },
   "scripts": {
-    "build": "rm -rf dist && tsc --project tsconfig.build.json",
+    "build": "rm -rf dist && tsc --project tsconfig.build.json && node --import tsx scripts/emitRuntimeContractManifest.ts && node --experimental-strip-types src/runtime/native/copyArtifact.ts",
+    "build:test-runtime": "rm -rf dist-test-runtime && tsc --project tsconfig.test-runtime.json",
     "clean": "rm -rf dist",
     "prepack": "npm run build",
     "prepublishOnly": "npm run typecheck && npm test",
-    "typecheck": "tsc --project tsconfig.json --noEmit",
-    "test": "node --import tsx --test \"src/**/*.test.ts\"",
+    "typecheck": "tsc --project tsconfig.json --noEmit && tsc --project scripts/tsconfig.json --noEmit",
+    "verify:contract-manifest": "node --import tsx scripts/emitRuntimeContractManifest.ts --check",
+    "verify:native": "node --experimental-strip-types src/runtime/native/verifyArtifacts.ts",
+    "verify:production-closure": "node --experimental-strip-types scripts/verifyProductionClosure.ts",
+    "test": "node --import tsx --test \"src/**/*.test.ts\" scripts/scriptSourcePolicy.test.ts",
+    "emit-causal-fixture": "tsx src/observability/emitCausalFixture.ts",
+    "emit-causal-fixture:spoof": "tsx src/observability/emitCausalFixture.ts --spoof",
+    "live:codex-session": "node --import tsx scripts/liveCodexSession.ts",
+    "live:grok-broker": "node --import tsx scripts/liveGrokBrokerSession.ts",
     "e2e:pi-agent": "tsx src/examples/pi-agent.ts",
     "e2e:pi-memory-org": "tsx src/examples/pi-memory-org.ts",
-    "e2e:mixed-engine-org": "tsx src/examples/mixed-engine-org.ts",
     "e2e:jungian-play-org": "tsx src/examples/jungian-play-org.ts",
-    "e2e:jungian-triad-org": "tsx src/examples/jungian-triad-org.ts",
-    "image:runtime:local": "docker build -f Dockerfile.runtime -t noopolis/spawnfile-runtime-daimon:0.1.1-local --build-arg DAIMON_VERSION=0.1.1 --build-arg MNEME_VERSION=0.1.0 --build-arg PI_VERSION=0.79.10 ."
+    "e2e:jungian-triad-org": "tsx src/examples/jungian-triad-org.ts"
   },
   "engines": {
     "node": ">=22.19.0"
   },
   "dependencies": {
     "@earendil-works/pi-ai": "^0.79.10",
-    "@earendil-works/pi-coding-agent": "^0.79.10"
-  },
-  "peerDependencies": {
-    "@noopolis/mneme": "^0.1.0"
-  },
-  "peerDependenciesMeta": {
-    "@noopolis/mneme": {
-      "optional": true
-    }
+    "@earendil-works/pi-coding-agent": "^0.79.10",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@noopolis/mneme": "^0.1.1",
+    "ajv": "^8.17.1",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@noopolis/mneme": "^0.1.0",
     "@types/node": "^24.12.4",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"

package/dist/examples/mixed-engine-org.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=mixed-engine-org.d.ts.map

package/dist/examples/mixed-engine-org.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"mixed-engine-org.d.ts","sourceRoot":"","sources":["../../src/examples/mixed-engine-org.ts"],"names":[],"mappings":""}