orbit-agent-runtime 0.8.0

package/dist/test/trace_journal_persistence.test.js

@@ -0,0 +1,175 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_test_1 = require("node:test");
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_fs_1 = require("node:fs");
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const index_1 = require("../src/index");
+async function tempTracePath(name) {
+    const dir = await node_fs_1.promises.mkdtemp(path.join(os.tmpdir(), "orbit-tracej-"));
+    return path.join(dir, name);
+}
+function journalWithEntries() {
+    const journal = new index_1.TraceJournal();
+    journal.append({ entryClass: "boot", traceMarkId: "t1", factPayload: { stage: "channels" } });
+    journal.append({
+        entryClass: "guard.trip",
+        traceMarkId: "t2",
+        pluginUnitId: "p1",
+        agentBoxId: "box-1",
+        factPayload: { reason: "quota" }
+    });
+    return journal;
+}
+(0, node_test_1.test)("trace checkpoint: save + load roundtrips the audit journal intact", async () => {
+    const file = await tempTracePath("audit.jsonl");
+    const original = journalWithEntries();
+    strict_1.default.equal(await (0, index_1.saveTraceJournal)(original, file), 2);
+    const loaded = await (0, index_1.loadTraceJournal)(file);
+    strict_1.default.deepEqual(loaded.snapshot(), original.snapshot());
+    strict_1.default.equal(loaded.byTraceMark("t2").length, 1);
+    strict_1.default.equal(loaded.byAgentBox("box-1").length, 1);
+    strict_1.default.equal(loaded.byPluginUnit("p1").length, 1);
+    await node_fs_1.promises.rm(path.dirname(file), { recursive: true, force: true });
+});
+(0, node_test_1.test)("trace checkpoint: file format is JSONL with a header line", async () => {
+    const file = await tempTracePath("audit.jsonl");
+    await (0, index_1.saveTraceJournal)(journalWithEntries(), file);
+    const lines = (await node_fs_1.promises.readFile(file, "utf8")).split("\n").filter((l) => l.trim() !== "");
+    strict_1.default.equal(lines.length, 3);
+    strict_1.default.deepEqual(JSON.parse(lines[0]), { magic: "orbit-trace", version: 1, entryCount: 2 });
+    const first = JSON.parse(lines[1]);
+    strict_1.default.equal(first.entryClass, "boot");
+    await node_fs_1.promises.rm(path.dirname(file), { recursive: true, force: true });
+});
+(0, node_test_1.test)("trace checkpoint: save creates parent directories and leaves no .tmp behind", async () => {
+    const dir = await node_fs_1.promises.mkdtemp(path.join(os.tmpdir(), "orbit-tracej-dir-"));
+    const file = path.join(dir, "nested", "deep", "audit.jsonl");
+    await (0, index_1.saveTraceJournal)(journalWithEntries(), file);
+    strict_1.default.deepEqual(await node_fs_1.promises.readdir(path.dirname(file)), ["audit.jsonl"]);
+    await node_fs_1.promises.rm(dir, { recursive: true, force: true });
+});
+(0, node_test_1.test)("trace checkpoint: an empty journal roundtrips as empty", async () => {
+    const file = await tempTracePath("empty.jsonl");
+    strict_1.default.equal(await (0, index_1.saveTraceJournal)(new index_1.TraceJournal(), file), 0);
+    const loaded = await (0, index_1.loadTraceJournal)(file);
+    strict_1.default.equal(loaded.entries().length, 0);
+    await node_fs_1.promises.rm(path.dirname(file), { recursive: true, force: true });
+});
+(0, node_test_1.test)("trace checkpoint: a missing file throws TraceFileInvalidError", async () => {
+    await strict_1.default.rejects((0, index_1.loadTraceJournal)(path.join(os.tmpdir(), "orbit-tracej-nope.jsonl")), (err) => {
+        strict_1.default.ok(err instanceof index_1.TraceFileInvalidError);
+        strict_1.default.match(err.message, /not found/);
+        return true;
+    });
+});
+(0, node_test_1.test)("trace checkpoint: foreign files are rejected (bad magic)", async () => {
+    const file = await tempTracePath("foreign.jsonl");
+    await node_fs_1.promises.writeFile(file, '{"hello":"world"}\n', "utf8");
+    await strict_1.default.rejects((0, index_1.loadTraceJournal)(file), (err) => {
+        strict_1.default.ok(err instanceof index_1.TraceFileInvalidError);
+        strict_1.default.match(err.message, /bad magic/);
+        return true;
+    });
+    await node_fs_1.promises.rm(path.dirname(file), { recursive: true, force: true });
+});
+(0, node_test_1.test)("trace checkpoint: an entryCount mismatch is rejected", async () => {
+    const file = await tempTracePath("mismatch.jsonl");
+    await (0, index_1.saveTraceJournal)(journalWithEntries(), file);
+    const lines = (await node_fs_1.promises.readFile(file, "utf8")).split("\n").filter((l) => l.trim() !== "");
+    lines[0] = JSON.stringify({ magic: "orbit-trace", version: 1, entryCount: 99 });
+    await node_fs_1.promises.writeFile(file, `${lines.join("\n")}\n`, "utf8");
+    await strict_1.default.rejects((0, index_1.loadTraceJournal)(file), (err) => {
+        strict_1.default.ok(err instanceof index_1.TraceFileInvalidError);
+        strict_1.default.match(err.message, /entryCount/);
+        return true;
+    });
+    await node_fs_1.promises.rm(path.dirname(file), { recursive: true, force: true });
+});
+(0, node_test_1.test)("trace checkpoint: an unsupported version is rejected", async () => {
+    const file = await tempTracePath("future.jsonl");
+    await node_fs_1.promises.writeFile(file, `${JSON.stringify({ magic: "orbit-trace", version: 99, entryCount: 0 })}\n`, "utf8");
+    await strict_1.default.rejects((0, index_1.loadTraceJournal)(file), (err) => {
+        strict_1.default.ok(err instanceof index_1.TraceFileInvalidError);
+        strict_1.default.match(err.message, /unsupported trace version/);
+        return true;
+    });
+    await node_fs_1.promises.rm(path.dirname(file), { recursive: true, force: true });
+});
+(0, node_test_1.test)("trace checkpoint: malformed entry lines are rejected with line numbers", async () => {
+    const file = await tempTracePath("broken.jsonl");
+    await node_fs_1.promises.writeFile(file, '{"magic":"orbit-trace","version":1,"entryCount":1}\nnot-json\n', "utf8");
+    await strict_1.default.rejects((0, index_1.loadTraceJournal)(file), (err) => {
+        strict_1.default.ok(err instanceof index_1.TraceFileInvalidError);
+        strict_1.default.equal(err.lineNo, 2);
+        return true;
+    });
+    await node_fs_1.promises.rm(path.dirname(file), { recursive: true, force: true });
+});
+(0, node_test_1.test)("trace checkpoint: an entry missing factPayload is rejected", async () => {
+    const file = await tempTracePath("nopayload.jsonl");
+    const lines = [
+        JSON.stringify({ magic: "orbit-trace", version: 1, entryCount: 1 }),
+        JSON.stringify({ entryUid: "u1", entryClass: "boot", occurredAt: 1, traceMarkId: "t1" })
+    ];
+    await node_fs_1.promises.writeFile(file, `${lines.join("\n")}\n`, "utf8");
+    await strict_1.default.rejects((0, index_1.loadTraceJournal)(file), (err) => {
+        strict_1.default.ok(err instanceof index_1.TraceFileInvalidError);
+        strict_1.default.match(err.message, /factPayload/);
+        return true;
+    });
+    await node_fs_1.promises.rm(path.dirname(file), { recursive: true, force: true });
+});
+(0, node_test_1.test)("trace checkpoint: every entry is preserved (not just the last one)", async () => {
+    const file = await tempTracePath("many.jsonl");
+    const journal = new index_1.TraceJournal();
+    for (let i = 0; i < 25; i += 1) {
+        journal.append({ entryClass: `class-${i}`, traceMarkId: `t${i}`, factPayload: { i } });
+    }
+    await (0, index_1.saveTraceJournal)(journal, file);
+    const loaded = await (0, index_1.loadTraceJournal)(file);
+    strict_1.default.equal(loaded.entries().length, 25);
+    loaded.entries().forEach((entry, i) => {
+        strict_1.default.equal(entry.entryClass, `class-${i}`);
+        strict_1.default.deepEqual(entry.factPayload, { i });
+    });
+    await node_fs_1.promises.rm(path.dirname(file), { recursive: true, force: true });
+});
+//# sourceMappingURL=trace_journal_persistence.test.js.map

package/dist/test/trace_journal_persistence.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace_journal_persistence.test.js","sourceRoot":"","sources":["../../test/trace_journal_persistence.test.ts"],"names":[],"mappings":"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"}

package/dist/test/trace_persistence.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=trace_persistence.test.d.ts.map

package/dist/test/trace_persistence.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace_persistence.test.d.ts","sourceRoot":"","sources":["../../test/trace_persistence.test.ts"],"names":[],"mappings":""}

package/dist/test/trace_persistence.test.js

@@ -0,0 +1,216 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_test_1 = require("node:test");
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_fs_1 = require("node:fs");
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const core_hub_1 = require("@orbit/core-hub");
+const core_hub_2 = require("@orbit/core-hub");
+const core_hub_3 = require("@orbit/core-hub");
+const infra_common_1 = require("@orbit/infra-common");
+const infra_common_2 = require("@orbit/infra-common");
+async function tempTracePath(name) {
+    const dir = await node_fs_1.promises.mkdtemp(path.join(os.tmpdir(), "orbit-trace-"));
+    return path.join(dir, name);
+}
+function journalWithCalls() {
+    const journal = new core_hub_1.RecordJournal();
+    journal.append({
+        channelKind: infra_common_2.ChannelKind.LLM_ACCESS,
+        funcName: "chatRound",
+        inputDigest: (0, infra_common_1.digestInputs)("hello"),
+        outputSnapshot: "hello-back",
+        durationMs: 320
+    });
+    journal.append({
+        channelKind: infra_common_2.ChannelKind.FILE_SYSTEM,
+        funcName: "readTextFile",
+        inputDigest: (0, infra_common_1.digestInputs)("a.txt"),
+        outputSnapshot: "file-content",
+        durationMs: 2
+    });
+    return journal;
+}
+(0, node_test_1.test)("persistence: save + load roundtrips a journal intact", async () => {
+    const file = await tempTracePath("trace.jsonl");
+    const original = journalWithCalls();
+    const count = await (0, core_hub_3.saveRecordJournal)(original, file);
+    strict_1.default.equal(count, 2);
+    const loaded = await (0, core_hub_3.loadRecordJournal)(file);
+    strict_1.default.equal(loaded.size(), 2);
+    const engine = new core_hub_2.ReplayEngine(loaded);
+    const out = engine.replayCall(infra_common_2.ChannelKind.LLM_ACCESS, "chatRound", (0, infra_common_1.digestInputs)("hello"), 0);
+    strict_1.default.equal(out, "hello-back");
+    const fileOut = engine.replayCall(infra_common_2.ChannelKind.FILE_SYSTEM, "readTextFile", (0, infra_common_1.digestInputs)("a.txt"), 1);
+    strict_1.default.equal(fileOut, "file-content");
+    await node_fs_1.promises.rm(path.dirname(file), { recursive: true, force: true });
+});
+(0, node_test_1.test)("persistence: file format is JSONL with a header line", async () => {
+    const file = await tempTracePath("trace.jsonl");
+    await (0, core_hub_3.saveRecordJournal)(journalWithCalls(), file);
+    const lines = (await node_fs_1.promises.readFile(file, "utf8")).split("\n").filter((l) => l.trim() !== "");
+    strict_1.default.equal(lines.length, 3);
+    const header = JSON.parse(lines[0]);
+    strict_1.default.deepEqual(header, { magic: "orbit-trace", version: 1, recordCount: 2 });
+    const first = JSON.parse(lines[1]);
+    strict_1.default.equal(first.funcName, "chatRound");
+    strict_1.default.equal(first.orderIndex, 0);
+    await node_fs_1.promises.rm(path.dirname(file), { recursive: true, force: true });
+});
+(0, node_test_1.test)("persistence: save creates parent directories and is atomic (no .tmp left behind)", async () => {
+    const dir = await node_fs_1.promises.mkdtemp(path.join(os.tmpdir(), "orbit-trace-dir-"));
+    const file = path.join(dir, "nested", "deep", "trace.jsonl");
+    await (0, core_hub_3.saveRecordJournal)(journalWithCalls(), file);
+    const entries = await node_fs_1.promises.readdir(path.dirname(file));
+    strict_1.default.deepEqual(entries, ["trace.jsonl"]);
+    await node_fs_1.promises.rm(dir, { recursive: true, force: true });
+});
+(0, node_test_1.test)("persistence: empty journal saves and loads back empty", async () => {
+    const file = await tempTracePath("empty.jsonl");
+    await (0, core_hub_3.saveRecordJournal)(new core_hub_1.RecordJournal(), file);
+    const loaded = await (0, core_hub_3.loadRecordJournal)(file);
+    strict_1.default.equal(loaded.size(), 0);
+    await node_fs_1.promises.rm(path.dirname(file), { recursive: true, force: true });
+});
+(0, node_test_1.test)("persistence: missing file throws TraceFileInvalidError", async () => {
+    await strict_1.default.rejects((0, core_hub_3.loadRecordJournal)(path.join(os.tmpdir(), "orbit-trace-nope.jsonl")), (err) => {
+        strict_1.default.ok(err instanceof core_hub_3.TraceFileInvalidError);
+        strict_1.default.match(err.message, /not found/);
+        return true;
+    });
+});
+(0, node_test_1.test)("persistence: non-trace files are rejected (bad magic)", async () => {
+    const file = await tempTracePath("foreign.jsonl");
+    await node_fs_1.promises.writeFile(file, '{"hello":"world"}\n', "utf8");
+    await strict_1.default.rejects((0, core_hub_3.loadRecordJournal)(file), (err) => {
+        strict_1.default.ok(err instanceof core_hub_3.TraceFileInvalidError);
+        strict_1.default.match(err.message, /bad magic/);
+        return true;
+    });
+    await node_fs_1.promises.rm(path.dirname(file), { recursive: true, force: true });
+});
+(0, node_test_1.test)("persistence: recordCount mismatch is rejected", async () => {
+    const file = await tempTracePath("mismatch.jsonl");
+    const original = journalWithCalls();
+    await (0, core_hub_3.saveRecordJournal)(original, file);
+    const lines = (await node_fs_1.promises.readFile(file, "utf8")).split("\n").filter((l) => l.trim() !== "");
+    const header = JSON.parse(lines[0]);
+    header.recordCount = 99;
+    lines[0] = JSON.stringify(header);
+    await node_fs_1.promises.writeFile(file, `${lines.join("\n")}\n`, "utf8");
+    await strict_1.default.rejects((0, core_hub_3.loadRecordJournal)(file), (err) => {
+        strict_1.default.ok(err instanceof core_hub_3.TraceFileInvalidError);
+        strict_1.default.match(err.message, /recordCount/);
+        return true;
+    });
+    await node_fs_1.promises.rm(path.dirname(file), { recursive: true, force: true });
+});
+(0, node_test_1.test)("persistence: tampered record content is caught by replay digest", async () => {
+    const file = await tempTracePath("tampered.jsonl");
+    await (0, core_hub_3.saveRecordJournal)(journalWithCalls(), file);
+    const lines = (await node_fs_1.promises.readFile(file, "utf8")).split("\n").filter((l) => l.trim() !== "");
+    const record = JSON.parse(lines[1]);
+    record.outputSnapshot = "tampered";
+    lines[1] = JSON.stringify(record);
+    await node_fs_1.promises.writeFile(file, `${lines.join("\n")}\n`, "utf8");
+    // Structural load succeeds; the tampering surfaces at replay as a drift.
+    const loaded = await (0, core_hub_3.loadRecordJournal)(file);
+    const engine = new core_hub_2.ReplayEngine(loaded);
+    const out = engine.replayCall(infra_common_2.ChannelKind.LLM_ACCESS, "chatRound", (0, infra_common_1.digestInputs)("hello"), 0);
+    strict_1.default.equal(out, "tampered");
+    const report = engine.reconcile(journalWithCalls().snapshot(), loaded.snapshot());
+    strict_1.default.equal(report.digestChainConsistent, false);
+    strict_1.default.equal(report.driftAtOrderIndex, 0);
+    await node_fs_1.promises.rm(path.dirname(file), { recursive: true, force: true });
+});
+(0, node_test_1.test)("persistence: orderIndex discontinuity is rejected", async () => {
+    const file = await tempTracePath("gap.jsonl");
+    const lines = [
+        JSON.stringify({ magic: "orbit-trace", version: 1, recordCount: 2 }),
+        JSON.stringify({
+            entryUid: "a",
+            orderIndex: 0,
+            channelKind: infra_common_2.ChannelKind.LLM_ACCESS,
+            funcName: "chatRound",
+            inputDigest: "d0",
+            outputSnapshot: "x",
+            durationMs: 1
+        }),
+        JSON.stringify({
+            entryUid: "b",
+            orderIndex: 5,
+            channelKind: infra_common_2.ChannelKind.LLM_ACCESS,
+            funcName: "chatRound",
+            inputDigest: "d1",
+            outputSnapshot: "y",
+            durationMs: 1
+        })
+    ];
+    await node_fs_1.promises.writeFile(file, `${lines.join("\n")}\n`, "utf8");
+    await strict_1.default.rejects((0, core_hub_3.loadRecordJournal)(file), (err) => {
+        strict_1.default.ok(err instanceof core_hub_3.TraceFileInvalidError);
+        strict_1.default.match(err.message, /continuity/);
+        return true;
+    });
+    await node_fs_1.promises.rm(path.dirname(file), { recursive: true, force: true });
+});
+(0, node_test_1.test)("persistence: malformed JSON lines are rejected with line numbers", async () => {
+    const file = await tempTracePath("broken.jsonl");
+    await node_fs_1.promises.writeFile(file, '{"magic":"orbit-trace","version":1,"recordCount":1}\nnot-json\n', "utf8");
+    await strict_1.default.rejects((0, core_hub_3.loadRecordJournal)(file), (err) => {
+        strict_1.default.ok(err instanceof core_hub_3.TraceFileInvalidError);
+        strict_1.default.equal(err.lineNo, 2);
+        return true;
+    });
+    await node_fs_1.promises.rm(path.dirname(file), { recursive: true, force: true });
+});
+(0, node_test_1.test)("persistence: a truncated (half-written) file fails recordCount validation", async () => {
+    const file = await tempTracePath("truncated.jsonl");
+    await (0, core_hub_3.saveRecordJournal)(journalWithCalls(), file);
+    const lines = (await node_fs_1.promises.readFile(file, "utf8")).split("\n").filter((l) => l.trim() !== "");
+    await node_fs_1.promises.writeFile(file, `${lines.slice(0, 2).join("\n")}\n`, "utf8"); // header + 1 of 2 records
+    await strict_1.default.rejects((0, core_hub_3.loadRecordJournal)(file), (err) => {
+        strict_1.default.ok(err instanceof core_hub_3.TraceFileInvalidError);
+        strict_1.default.match(err.message, /recordCount/);
+        return true;
+    });
+    await node_fs_1.promises.rm(path.dirname(file), { recursive: true, force: true });
+});
+//# sourceMappingURL=trace_persistence.test.js.map

package/dist/test/trace_persistence.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace_persistence.test.js","sourceRoot":"","sources":["../../test/trace_persistence.test.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,yCAAiC;AACjC,gEAAwC;AACxC,qCAAyC;AACzC,4CAA8B;AAC9B,gDAAkC;AAClC,8CAAgD;AAChD,8CAA+C;AAC/C,8CAA8F;AAC9F,sDAAmD;AACnD,sDAAkD;AAElD,KAAK,UAAU,aAAa,CAAC,IAAY;IACvC,MAAM,GAAG,GAAG,MAAM,kBAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,cAAc,CAAC,CAAC,CAAC;IACrE,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AAC9B,CAAC;AAED,SAAS,gBAAgB;IACvB,MAAM,OAAO,GAAG,IAAI,wBAAa,EAAE,CAAC;IACpC,OAAO,CAAC,MAAM,CAAC;QACb,WAAW,EAAE,0BAAW,CAAC,UAAU;QACnC,QAAQ,EAAE,WAAW;QACrB,WAAW,EAAE,IAAA,2BAAY,EAAC,OAAO,CAAC;QAClC,cAAc,EAAE,YAAY;QAC5B,UAAU,EAAE,GAAG;KAChB,CAAC,CAAC;IACH,OAAO,CAAC,MAAM,CAAC;QACb,WAAW,EAAE,0BAAW,CAAC,WAAW;QACpC,QAAQ,EAAE,cAAc;QACxB,WAAW,EAAE,IAAA,2BAAY,EAAC,OAAO,CAAC;QAClC,cAAc,EAAE,cAAc;QAC9B,UAAU,EAAE,CAAC;KACd,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,IAAA,gBAAI,EAAC,sDAAsD,EAAE,KAAK,IAAI,EAAE;IACtE,MAAM,IAAI,GAAG,MAAM,aAAa,CAAC,aAAa,CAAC,CAAC;IAChD,MAAM,QAAQ,GAAG,gBAAgB,EAAE,CAAC;IACpC,MAAM,KAAK,GAAG,MAAM,IAAA,4BAAiB,EAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IACtD,gBAAM,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAEvB,MAAM,MAAM,GAAG,MAAM,IAAA,4BAAiB,EAAC,IAAI,CAAC,CAAC;IAC7C,gBAAM,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;IAC/B,MAAM,MAAM,GAAG,IAAI,uBAAY,CAAC,MAAM,CAAC,CAAC;IACxC,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC,0BAAW,CAAC,UAAU,EAAE,WAAW,EAAE,IAAA,2BAAY,EAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;IAC7F,gBAAM,CAAC,KAAK,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;IAChC,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,CAAC,0BAAW,CAAC,WAAW,EAAE,cAAc,EAAE,IAAA,2BAAY,EAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;IACrG,gBAAM,CAAC,KAAK,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;IACtC,MAAM,kBAAE,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AACpE,CAAC,CAAC,CAAC;AAEH,IAAA,gBAAI,EAAC,sDAAsD,EAAE,KAAK,IAAI,EAAE;IACtE,MAAM,IAAI,GAAG,MAAM,aAAa,CAAC,aAAa,CAAC,CAAC;IAChD,MAAM,IAAA,4BAAiB,EAAC,gBAAgB,EAAE,EAAE,IAAI,CAAC,CAAC;IAClD,MAAM,KAAK,GAAG,CAAC,MAAM,kBAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3F,gBAAM,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAC9B,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAA4D,CAAC;IAC/F,gBAAM,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC,CAAC;IAC/E,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAA6C,CAAC;IAC/E,gBAAM,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;IAC1C,gBAAM,CAAC,KAAK,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;IAClC,MAAM,kBAAE,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AACpE,CAAC,CAAC,CAAC;AAEH,IAAA,gBAAI,EAAC,kFAAkF,EAAE,KAAK,IAAI,EAAE;IAClG,MAAM,GAAG,GAAG,MAAM,kBAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,kBAAkB,CAAC,CAAC,CAAC;IACzE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC;IAC7D,MAAM,IAAA,4BAAiB,EAAC,gBAAgB,EAAE,EAAE,IAAI,CAAC,CAAC;IAClD,MAAM,OAAO,GAAG,MAAM,kBAAE,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACrD,gBAAM,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC;IAC3C,MAAM,kBAAE,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AACrD,CAAC,CAAC,CAAC;AAEH,IAAA,gBAAI,EAAC,uDAAuD,EAAE,KAAK,IAAI,EAAE;IACvE,MAAM,IAAI,GAAG,MAAM,aAAa,CAAC,aAAa,CAAC,CAAC;IAChD,MAAM,IAAA,4BAAiB,EAAC,IAAI,wBAAa,EAAE,EAAE,IAAI,CAAC,CAAC;IACnD,MAAM,MAAM,GAAG,MAAM,IAAA,4BAAiB,EAAC,IAAI,CAAC,CAAC;IAC7C,gBAAM,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;IAC/B,MAAM,kBAAE,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AACpE,CAAC,CAAC,CAAC;AAEH,IAAA,gBAAI,EAAC,wDAAwD,EAAE,KAAK,IAAI,EAAE;IACxE,MAAM,gBAAM,CAAC,OAAO,CAClB,IAAA,4BAAiB,EAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,wBAAwB,CAAC,CAAC,EACnE,CAAC,GAAY,EAAE,EAAE;QACf,gBAAM,CAAC,EAAE,CAAC,GAAG,YAAY,gCAAqB,CAAC,CAAC;QAChD,gBAAM,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QACvC,OAAO,IAAI,CAAC;IACd,CAAC,CACF,CAAC;AACJ,CAAC,CAAC,CAAC;AAEH,IAAA,gBAAI,EAAC,uDAAuD,EAAE,KAAK,IAAI,EAAE;IACvE,MAAM,IAAI,GAAG,MAAM,aAAa,CAAC,eAAe,CAAC,CAAC;IAClD,MAAM,kBAAE,CAAC,SAAS,CAAC,IAAI,EAAE,qBAAqB,EAAE,MAAM,CAAC,CAAC;IACxD,MAAM,gBAAM,CAAC,OAAO,CAAC,IAAA,4BAAiB,EAAC,IAAI,CAAC,EAAE,CAAC,GAAY,EAAE,EAAE;QAC7D,gBAAM,CAAC,EAAE,CAAC,GAAG,YAAY,gCAAqB,CAAC,CAAC;QAChD,gBAAM,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QACvC,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;IACH,MAAM,kBAAE,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AACpE,CAAC,CAAC,CAAC;AAEH,IAAA,gBAAI,EAAC,+CAA+C,EAAE,KAAK,IAAI,EAAE;IAC/D,MAAM,IAAI,GAAG,MAAM,aAAa,CAAC,gBAAgB,CAAC,CAAC;IACnD,MAAM,QAAQ,GAAG,gBAAgB,EAAE,CAAC;IACpC,MAAM,IAAA,4BAAiB,EAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IACxC,MAAM,KAAK,GAAG,CAAC,MAAM,kBAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3F,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAA4D,CAAC;IAC/F,MAAM,CAAC,WAAW,GAAG,EAAE,CAAC;IACxB,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAClC,MAAM,kBAAE,CAAC,SAAS,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC1D,MAAM,gBAAM,CAAC,OAAO,CAAC,IAAA,4BAAiB,EAAC,IAAI,CAAC,EAAE,CAAC,GAAY,EAAE,EAAE;QAC7D,gBAAM,CAAC,EAAE,CAAC,GAAG,YAAY,gCAAqB,CAAC,CAAC;QAChD,gBAAM,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;QACzC,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;IACH,MAAM,kBAAE,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AACpE,CAAC,CAAC,CAAC;AAEH,IAAA,gBAAI,EAAC,iEAAiE,EAAE,KAAK,IAAI,EAAE;IACjF,MAAM,IAAI,GAAG,MAAM,aAAa,CAAC,gBAAgB,CAAC,CAAC;IACnD,MAAM,IAAA,4BAAiB,EAAC,gBAAgB,EAAE,EAAE,IAAI,CAAC,CAAC;IAClD,MAAM,KAAK,GAAG,CAAC,MAAM,kBAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3F,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAgC,CAAC;IACnE,MAAM,CAAC,cAAc,GAAG,UAAU,CAAC;IACnC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAClC,MAAM,kBAAE,CAAC,SAAS,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAE1D,yEAAyE;IACzE,MAAM,MAAM,GAAG,MAAM,IAAA,4BAAiB,EAAC,IAAI,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,IAAI,uBAAY,CAAC,MAAM,CAAC,CAAC;IACxC,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC,0BAAW,CAAC,UAAU,EAAE,WAAW,EAAE,IAAA,2BAAY,EAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;IAC7F,gBAAM,CAAC,KAAK,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IAC9B,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,gBAAgB,EAAE,CAAC,QAAQ,EAAE,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;IAClF,gBAAM,CAAC,KAAK,CAAC,MAAM,CAAC,qBAAqB,EAAE,KAAK,CAAC,CAAC;IAClD,gBAAM,CAAC,KAAK,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAC,CAAC,CAAC;IAC1C,MAAM,kBAAE,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AACpE,CAAC,CAAC,CAAC;AAEH,IAAA,gBAAI,EAAC,mDAAmD,EAAE,KAAK,IAAI,EAAE;IACnE,MAAM,IAAI,GAAG,MAAM,aAAa,CAAC,WAAW,CAAC,CAAC;IAC9C,MAAM,KAAK,GAAG;QACZ,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;QACpE,IAAI,CAAC,SAAS,CAAC;YACb,QAAQ,EAAE,GAAG;YACb,UAAU,EAAE,CAAC;YACb,WAAW,EAAE,0BAAW,CAAC,UAAU;YACnC,QAAQ,EAAE,WAAW;YACrB,WAAW,EAAE,IAAI;YACjB,cAAc,EAAE,GAAG;YACnB,UAAU,EAAE,CAAC;SACd,CAAC;QACF,IAAI,CAAC,SAAS,CAAC;YACb,QAAQ,EAAE,GAAG;YACb,UAAU,EAAE,CAAC;YACb,WAAW,EAAE,0BAAW,CAAC,UAAU;YACnC,QAAQ,EAAE,WAAW;YACrB,WAAW,EAAE,IAAI;YACjB,cAAc,EAAE,GAAG;YACnB,UAAU,EAAE,CAAC;SACd,CAAC;KACH,CAAC;IACF,MAAM,kBAAE,CAAC,SAAS,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC1D,MAAM,gBAAM,CAAC,OAAO,CAAC,IAAA,4BAAiB,EAAC,IAAI,CAAC,EAAE,CAAC,GAAY,EAAE,EAAE;QAC7D,gBAAM,CAAC,EAAE,CAAC,GAAG,YAAY,gCAAqB,CAAC,CAAC;QAChD,gBAAM,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;QACxC,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;IACH,MAAM,kBAAE,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AACpE,CAAC,CAAC,CAAC;AAEH,IAAA,gBAAI,EAAC,kEAAkE,EAAE,KAAK,IAAI,EAAE;IAClF,MAAM,IAAI,GAAG,MAAM,aAAa,CAAC,cAAc,CAAC,CAAC;IACjD,MAAM,kBAAE,CAAC,SAAS,CAAC,IAAI,EAAE,iEAAiE,EAAE,MAAM,CAAC,CAAC;IACpG,MAAM,gBAAM,CAAC,OAAO,CAAC,IAAA,4BAAiB,EAAC,IAAI,CAAC,EAAE,CAAC,GAAY,EAAE,EAAE;QAC7D,gBAAM,CAAC,EAAE,CAAC,GAAG,YAAY,gCAAqB,CAAC,CAAC;QAChD,gBAAM,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QAC5B,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;IACH,MAAM,kBAAE,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AACpE,CAAC,CAAC,CAAC;AAEH,IAAA,gBAAI,EAAC,2EAA2E,EAAE,KAAK,IAAI,EAAE;IAC3F,MAAM,IAAI,GAAG,MAAM,aAAa,CAAC,iBAAiB,CAAC,CAAC;IACpD,MAAM,IAAA,4BAAiB,EAAC,gBAAgB,EAAE,EAAE,IAAI,CAAC,CAAC;IAClD,MAAM,KAAK,GAAG,CAAC,MAAM,kBAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3F,MAAM,kBAAE,CAAC,SAAS,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,0BAA0B;IACjG,MAAM,gBAAM,CAAC,OAAO,CAAC,IAAA,4BAAiB,EAAC,IAAI,CAAC,EAAE,CAAC,GAAY,EAAE,EAAE;QAC7D,gBAAM,CAAC,EAAE,CAAC,GAAG,YAAY,gCAAqB,CAAC,CAAC;QAChD,gBAAM,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;QACzC,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;IACH,MAAM,kBAAE,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AACpE,CAAC,CAAC,CAAC"}

package/dist/test/trip_protector.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=trip_protector.test.d.ts.map

package/dist/test/trip_protector.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trip_protector.test.d.ts","sourceRoot":"","sources":["../../test/trip_protector.test.ts"],"names":[],"mappings":""}

package/dist/test/trip_protector.test.js

@@ -0,0 +1,42 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_test_1 = require("node:test");
+const strict_1 = __importDefault(require("node:assert/strict"));
+const core_hub_1 = require("@orbit/core-hub");
+const infra_common_1 = require("@orbit/infra-common");
+(0, node_test_1.test)("连续失败达到阈值触发跳闸并快速拦截", async () => {
+    const trip = new core_hub_1.TripProtector(2, 10000);
+    const fail = async () => {
+        throw new Error("boom");
+    };
+    await strict_1.default.rejects(trip.execWithProtect(fail));
+    await strict_1.default.rejects(trip.execWithProtect(fail));
+    strict_1.default.equal(trip.snapshot().state, infra_common_1.TripState.TRIPPED);
+    await strict_1.default.rejects(trip.execWithProtect(fail), /trip protector active/);
+});
+(0, node_test_1.test)("冷却后进入探测，单次成功即恢复", async () => {
+    const trip = new core_hub_1.TripProtector(1, 30);
+    await strict_1.default.rejects(trip.execWithProtect(async () => {
+        throw new Error("boom");
+    }));
+    strict_1.default.equal(trip.snapshot().state, infra_common_1.TripState.TRIPPED);
+    await new Promise((resolve) => setTimeout(resolve, 40));
+    const ok = await trip.execWithProtect(async () => "ok");
+    strict_1.default.equal(ok, "ok");
+    strict_1.default.equal(trip.snapshot().state, infra_common_1.TripState.NORMAL);
+});
+(0, node_test_1.test)("成功后重置失败计数", async () => {
+    const trip = new core_hub_1.TripProtector(3, 10000);
+    const fail = async () => {
+        throw new Error("x");
+    };
+    await strict_1.default.rejects(trip.execWithProtect(fail));
+    await strict_1.default.rejects(trip.execWithProtect(fail));
+    await trip.execWithProtect(async () => "ok");
+    await strict_1.default.rejects(trip.execWithProtect(fail));
+    strict_1.default.equal(trip.snapshot().state, infra_common_1.TripState.NORMAL);
+});
+//# sourceMappingURL=trip_protector.test.js.map

package/dist/test/trip_protector.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trip_protector.test.js","sourceRoot":"","sources":["../../test/trip_protector.test.ts"],"names":[],"mappings":";;;;;AAAA,yCAAiC;AACjC,gEAAwC;AACxC,8CAAgD;AAChD,sDAAgD;AAEhD,IAAA,gBAAI,EAAC,mBAAmB,EAAE,KAAK,IAAI,EAAE;IACnC,MAAM,IAAI,GAAG,IAAI,wBAAa,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,KAAK,IAAqB,EAAE;QACvC,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC;IAC1B,CAAC,CAAC;IACF,MAAM,gBAAM,CAAC,OAAO,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;IACjD,MAAM,gBAAM,CAAC,OAAO,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;IACjD,gBAAM,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,wBAAS,CAAC,OAAO,CAAC,CAAC;IACvD,MAAM,gBAAM,CAAC,OAAO,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE,uBAAuB,CAAC,CAAC;AAC5E,CAAC,CAAC,CAAC;AAEH,IAAA,gBAAI,EAAC,iBAAiB,EAAE,KAAK,IAAI,EAAE;IACjC,MAAM,IAAI,GAAG,IAAI,wBAAa,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACtC,MAAM,gBAAM,CAAC,OAAO,CAAC,IAAI,CAAC,eAAe,CAAC,KAAK,IAAI,EAAE;QACnD,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC,CAAC;IACJ,gBAAM,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,wBAAS,CAAC,OAAO,CAAC,CAAC;IACvD,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;IACxD,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,KAAK,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC;IACxD,gBAAM,CAAC,KAAK,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IACvB,gBAAM,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,wBAAS,CAAC,MAAM,CAAC,CAAC;AACxD,CAAC,CAAC,CAAC;AAEH,IAAA,gBAAI,EAAC,WAAW,EAAE,KAAK,IAAI,EAAE;IAC3B,MAAM,IAAI,GAAG,IAAI,wBAAa,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,KAAK,IAAqB,EAAE;QACvC,MAAM,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC;IACvB,CAAC,CAAC;IACF,MAAM,gBAAM,CAAC,OAAO,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;IACjD,MAAM,gBAAM,CAAC,OAAO,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;IACjD,MAAM,IAAI,CAAC,eAAe,CAAC,KAAK,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC;IAC7C,MAAM,gBAAM,CAAC,OAAO,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;IACjD,gBAAM,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,wBAAS,CAAC,MAAM,CAAC,CAAC;AACxD,CAAC,CAAC,CAAC"}

package/examples/README.md

@@ -0,0 +1,34 @@
+# Examples
+
+Run each example with a plain `node` — no build step, no extra dependencies:
+
+```bash
+# 1. a custom deterministic channel: wire it in, record, replay byte-identically
+node examples/custom-channel.mjs
+
+# 2. a JS plugin adapter (PAE, L0): foreign in-process tools through the gateway
+node examples/js-pae-plugin.mjs
+
+# 3. an MCP adapter (PAE, L2): a real stdio child process, handshake-discovered
+node examples/mcp-adapter.mjs
+
+# 4. the orbit CLI record → replay → diff loop, driven exactly as a user would
+node examples/cli-record-replay.mjs
+```
+
+| Example | Shows |
+|---|---|
+| `custom-channel.mjs` | Implementing `IChannelProvider`, registering it, and proving the record → replay loop is byte-identical — plus drift detection when a call is tampered with |
+| `js-pae-plugin.mjs` | Mapping plain JS functions onto the capability contract via `JsPaeAdapter`; the adapter surface becomes a governed channel whose output replays verbatim |
+| `mcp-adapter.mjs` | Spawning a real MCP server child, `initialize` → `tools/list` handshake, recorded call, then replay **after the peer is dead** (the frozen output is injected, the child is never re-entered) |
+| `cli-record-replay.mjs` | The three-command reproducibility story: `orbit record` → `orbit replay` (zero channel calls) → `orbit diff` (digest-chain reconciliation) |
+
+The imports use relative paths so the examples run inside the repository;
+after `npm i orbit-agent-runtime` they become plain package imports:
+
+```js
+import { OrbitRuntimeHost, ChannelKind } from "orbit-agent-runtime";
+```
+
+Every example exits non-zero on any failed assertion, so they can be used as
+smoke checks in CI (`node examples/custom-channel.mjs && ...`).

package/examples/cli-record-replay.mjs

@@ -0,0 +1,74 @@
+/**
+ * Example 4 — the orbit CLI record → replay → diff loop.
+ *
+ * The CLI is the reproducibility story in three commands: record a script
+ * against a live kernel, replay the trace with zero channel calls, and diff
+ * two traces to locate the first digest-chain breakpoint.
+ *
+ * This file drives the CLI exactly as a user would, showing every command's
+ * output. Run: node examples/cli-record-replay.mjs
+ */
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+const REPO = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
+const ORBIT = path.join(REPO, "bin", "orbit.mjs");
+
+/** A small agent script exercising both the LLM and the KV channel. */
+const AGENT_SCRIPT = `
+export default async (ctx) => {
+  const a = await ctx.llm.chat("hello orbit");
+  const b = await ctx.call(ctx.ChannelKind.MEM_KV_STORE, "readEntry", "alpha");
+  const c = await ctx.call(ctx.ChannelKind.LLM_ACCESS, "chatRound", a);
+  return { a, b, c };
+};
+`;
+
+function run(args, label) {
+  console.log(`\n$ orbit ${args.join(" ")}`);
+  const res = spawnSync(process.execPath, [ORBIT, ...args], { cwd: REPO, encoding: "utf8" });
+  if (res.status !== 0) {
+    console.error(res.stderr || res.stdout);
+    process.exit(res.status ?? 1);
+  }
+  console.log((res.stdout || "").trim().split("\n").slice(0, 8).join("\n"));
+  return res.stdout;
+}
+
+async function main() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "orbit-example-"));
+  const script = path.join(dir, "agent.mjs");
+  const traceA = path.join(dir, "a.jsonl");
+  const traceB = path.join(dir, "b.jsonl");
+  fs.writeFileSync(script, AGENT_SCRIPT, "utf8");
+
+  console.log("=== example 4 · orbit CLI record → replay → diff ===");
+  console.log(`[trace] temp dir: ${dir}`);
+
+  // 1) Record: run the script against a live kernel, capture every channel
+  //    call into a trace file.
+  run(["record", script, "--out", traceA], "record");
+
+  // 2) Replay: re-run the recorded script with ZERO real channel calls and
+  //    reconcile the replayed chain against the original.
+  const replayOut = run(["replay", traceA], "replay");
+
+  // 3) Diff: a trace compared with itself must be perfectly consistent.
+  const diffOut = run(["diff", traceA, traceA], "diff");
+
+  if (!/consistent|identical|一致/i.test(replayOut + diffOut)) {
+    console.error("FAIL: replay/diff did not report a consistent chain");
+    process.exit(1);
+  }
+
+  fs.rmSync(dir, { recursive: true, force: true });
+  console.log("\nOK — record → replay → diff loop closed with a consistent chain");
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});