@smthrs/kernel 0.0.0-stage → 1.0.0-rc.4

package/dist/cjs/ProcessConfinement.js

@@ -0,0 +1,94 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var ProcessConfinement_exports = {};
+__export(ProcessConfinement_exports, {
+  ProcessConfinement: () => ProcessConfinement,
+  layerNoop: () => layerNoop,
+  makeNoop: () => makeNoop,
+  profile: () => profile
+});
+module.exports = __toCommonJS(ProcessConfinement_exports);
+var import_Capability = require("@smthrs/capability/Capability");
+var import_effect = require("effect");
+class ProcessConfinement extends import_effect.Context.Service()("@smthrs/kernel/ProcessConfinement") {
+}
+const makeNoop = ProcessConfinement.of({ confine: (command) => import_effect.Effect.succeed(command) });
+const layerNoop = import_effect.Layer.succeed(ProcessConfinement)(makeNoop);
+const decidable = (pattern, action) => (0, import_Capability.withinMatchBudget)(pattern, new import_Capability.Capability({ action, resource: "x".repeat(import_Capability.maxResourceLength) }));
+const universal = (pattern) => pattern.resource === "*" ? new import_Capability.CapabilityPattern({ action: pattern.action, resource: "**" }) : pattern;
+const coversCeiling = (ceiling, target) => ceiling.groups.every(
+  (group) => group.some((pattern) => decidable(pattern, target.action) && (0, import_Capability.subsumes)(universal(pattern), target))
+);
+const actionRelevant = (pattern, action) => (0, import_Capability.matches)(new import_Capability.CapabilityPattern({ action: pattern.action, resource: "**" }), new import_Capability.Capability({ action, resource: "" }));
+const prove = (policy, target) => {
+  if (!coversCeiling(policy.ceiling, target)) return false;
+  let decision = "ask";
+  let configured = "ask";
+  for (const [index, group] of policy.groups.entries()) {
+    for (const { rule, ceiling } of group) {
+      if (!decidable(rule.pattern, target.action)) return false;
+      if (!actionRelevant(rule.pattern, target.action)) continue;
+      if (target.action === "net:private" && rule.effect === "allow" && rule.pattern.action !== "net:private") continue;
+      if (coversCeiling(ceiling, target) && (0, import_Capability.subsumes)(universal(rule.pattern), target)) decision = rule.effect;
+      else if (rule.effect !== "allow") decision = "unknown";
+      if (index === 0) configured = decision;
+    }
+  }
+  return configured !== "deny" && configured !== "unknown" && decision === "allow";
+};
+const profile = (grants, workspaceRoot, path) => import_effect.Effect.gen(function* () {
+  const policy = yield* grants.policy;
+  const root = path.resolve(workspaceRoot);
+  const resources = [
+    ...policy.groups.flatMap(
+      (group) => group.flatMap(({ rule, ceiling }) => [rule.pattern, ...ceiling.groups.flat()])
+    ),
+    ...policy.ceiling.groups.flat()
+  ];
+  const candidates = /* @__PURE__ */ new Set();
+  for (const { resource } of resources) {
+    if (resource === "**" || resource === "*") {
+      candidates.add(".");
+      continue;
+    }
+    if (!resource.endsWith("/**") || /[*?]/.test(resource.slice(0, -3))) continue;
+    const base = resource.slice(0, -3);
+    if (!path.isAbsolute(base) || path.normalize(base) !== base) continue;
+    const relative = path.relative(root, base);
+    if (path.isAbsolute(relative) || relative.split(path.sep)[0] === "..") continue;
+    candidates.add(relative === "" ? "." : relative.split(path.sep).join("/"));
+  }
+  const opened = (action) => [...candidates].filter((relative) => {
+    const directory = relative === "." ? root : path.resolve(root, relative);
+    const resource = `${directory}/**`;
+    return prove(policy, new import_Capability.CapabilityPattern({ action, resource })) && (action !== "fs:write" || prove(policy, new import_Capability.CapabilityPattern({ action: "fs:read", resource })) && prove(policy, new import_Capability.CapabilityPattern({ action: "fs:write", resource: directory })));
+  }).filter(
+    (relative, _, all) => !all.some((parent) => parent !== relative && (parent === "." || relative.startsWith(`${parent}/`)))
+  ).sort();
+  return Object.freeze({
+    workspaceRoot: root,
+    reads: Object.freeze(opened("fs:read")),
+    writes: Object.freeze(opened("fs:write")),
+    readOnly: Object.freeze([]),
+    network: ["net:get", "net:post", "net:private"].every(
+      (action) => prove(policy, new import_Capability.CapabilityPattern({ action, resource: "**" }))
+    ) ? "open" : "none"
+  });
+});
+//# sourceMappingURL=ProcessConfinement.js.map

package/dist/cjs/ProcessConfinement.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/ProcessConfinement.ts"],
+  "sourcesContent": ["/** Operating-system confinement derived conservatively from effective grants.\n * @since 1.0.0-rc.1\n */\n\nimport {\n  type Action,\n  Capability,\n  CapabilityPattern,\n  matches,\n  maxResourceLength,\n  subsumes,\n  withinMatchBudget\n} from \"@smthrs/capability/Capability\"\nimport type { GrantStoreError } from \"@smthrs/capability/Permission\"\nimport { Context, Effect, Layer, type Path, type Scope } from \"effect\"\nimport type { PlatformError } from \"effect/PlatformError\"\nimport type * as ChildProcess from \"effect/unstable/process/ChildProcess\"\nimport type { Policy, PolicyRule, Service as GrantService } from \"./GrantStore.ts\"\n\n/** Workspace-relative trees; `.` names the workspace. No path opens its parent.\n * @category models\n * @since 1.0.0-rc.1\n */\nexport interface Profile {\n  readonly workspaceRoot: string\n  readonly reads: ReadonlyArray<string>\n  readonly writes: ReadonlyArray<string>\n  readonly readOnly: ReadonlyArray<string>\n  readonly network: \"none\" | \"open\"\n}\n/** Host wrapper for one process stage. Failure must occur before spawning.\n * @category models\n * @since 1.0.0-rc.1\n */\nexport interface Service {\n  readonly confine: (\n    command: ChildProcess.StandardCommand,\n    profile: Profile\n  ) => Effect.Effect<ChildProcess.StandardCommand, PlatformError, Scope.Scope>\n}\n/** Host confinement seam; missing service refuses spawning.\n * @category services\n * @since 1.0.0-rc.1\n */\nexport class ProcessConfinement\n  extends Context.Service<ProcessConfinement, Service>()(\"@smthrs/kernel/ProcessConfinement\")\n{}\n/** Explicit unconfined composition.\n * @category constructors\n * @since 1.0.0-rc.1\n */\nexport const makeNoop: Service = ProcessConfinement.of({ confine: (command) => Effect.succeed(command) })\n/** Explicit unconfined layer.\n * @category layers\n * @since 1.0.0-rc.1\n */\nexport const layerNoop: Layer.Layer<ProcessConfinement> = Layer.succeed(ProcessConfinement)(makeNoop)\n\nconst decidable = (pattern: CapabilityPattern, action: Action) =>\n  withinMatchBudget(pattern, new Capability({ action, resource: \"x\".repeat(maxResourceLength) }))\n\n// The capability matcher permits a single star to cross separators. Only\n// this universal spelling is equivalent to **; arbitrary globs stay closed.\nconst universal = (pattern: CapabilityPattern): CapabilityPattern =>\n  pattern.resource === \"*\" ? new CapabilityPattern({ action: pattern.action, resource: \"**\" }) : pattern\n\nconst coversCeiling = (ceiling: PolicyRule[\"ceiling\"], target: CapabilityPattern): boolean =>\n  ceiling.groups.every((group) =>\n    group.some((pattern) => decidable(pattern, target.action as Action) && subsumes(universal(pattern), target))\n  )\nconst actionRelevant = (pattern: CapabilityPattern, action: Action): boolean =>\n  matches(new CapabilityPattern({ action: pattern.action, resource: \"**\" }), new Capability({ action, resource: \"\" }))\n\n// A covering rule resolves the complete region. A narrower/conditional refusal\n// makes it unknown until a later covering rule resolves it. Unknown configured\n// denial vetoes all later grant groups, just as evaluate's configured veto does.\nconst prove = (policy: Policy, target: CapabilityPattern): boolean => {\n  if (!coversCeiling(policy.ceiling, target)) return false\n  let decision: \"allow\" | \"deny\" | \"ask\" | \"unknown\" = \"ask\"\n  let configured: \"allow\" | \"deny\" | \"ask\" | \"unknown\" = \"ask\"\n  for (const [index, group] of policy.groups.entries()) {\n    for (const { rule, ceiling } of group) {\n      if (!decidable(rule.pattern, target.action as Action)) return false\n      if (!actionRelevant(rule.pattern, target.action as Action)) continue\n      if (target.action === \"net:private\" && rule.effect === \"allow\" && rule.pattern.action !== \"net:private\") continue\n      if (coversCeiling(ceiling, target) && subsumes(universal(rule.pattern), target)) decision = rule.effect\n      else if (rule.effect !== \"allow\") decision = \"unknown\"\n      if (index === 0) configured = decision\n    }\n  }\n  return configured !== \"deny\" && configured !== \"unknown\" && decision === \"allow\"\n}\n\n/** Derives a subset of authority, never a widening. Literal filesystem grants,\n * complex globs and unrepresentable restrictions conservatively open nothing.\n * Writable trees also require read authority and write authority over their\n * exact directory root: native mounts permit reads and directory metadata\n * changes. Only whole-tree grants prove filesystem trees; unrestricted\n * authority for each of get/post/private is required to open network access.\n * @category resolution\n * @since 1.0.0-rc.1\n */\nexport const profile = (\n  grants: GrantService,\n  workspaceRoot: string,\n  path: Path.Path\n): Effect.Effect<Profile, GrantStoreError> =>\n  Effect.gen(function*() {\n    const policy = yield* grants.policy\n    const root = path.resolve(workspaceRoot)\n    const resources = [\n      ...policy.groups.flatMap((group) =>\n        group.flatMap(({ rule, ceiling }) => [rule.pattern, ...ceiling.groups.flat()])\n      ),\n      ...policy.ceiling.groups.flat()\n    ]\n    const candidates = new Set<string>()\n    for (const { resource } of resources) {\n      if (resource === \"**\" || resource === \"*\") {\n        candidates.add(\".\")\n        continue\n      }\n      if (!resource.endsWith(\"/**\") || /[*?]/.test(resource.slice(0, -3))) continue\n      const base = resource.slice(0, -3)\n      // Relative policy resources do not authorize absolute kernel resources.\n      if (!path.isAbsolute(base) || path.normalize(base) !== base) continue\n      const relative = path.relative(root, base)\n      if (path.isAbsolute(relative) || relative.split(path.sep)[0] === \"..\") continue\n      candidates.add(relative === \"\" ? \".\" : relative.split(path.sep).join(\"/\"))\n    }\n    const opened = (action: Action) =>\n      [...candidates].filter((relative) => {\n        const directory = relative === \".\" ? root : path.resolve(root, relative)\n        const resource = `${directory}/**`\n        return prove(policy, new CapabilityPattern({ action, resource })) &&\n          (action !== \"fs:write\" || (\n            prove(policy, new CapabilityPattern({ action: \"fs:read\", resource })) &&\n            prove(policy, new CapabilityPattern({ action: \"fs:write\", resource: directory }))\n          ))\n      })\n        .filter((relative, _, all) =>\n          !all.some((parent) => parent !== relative && (parent === \".\" || relative.startsWith(`${parent}/`)))\n        )\n        .sort()\n    return Object.freeze({\n      workspaceRoot: root,\n      reads: Object.freeze(opened(\"fs:read\")),\n      writes: Object.freeze(opened(\"fs:write\")),\n      readOnly: Object.freeze([]),\n      network: ([\"net:get\", \"net:post\", \"net:private\"] as const).every((action) =>\n          prove(policy, new CapabilityPattern({ action, resource: \"**\" }))\n        ) ?\n        \"open\" as const :\n        \"none\" as const\n    })\n  })\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/cjs/ProcessLedger.d.ts

@@ -0,0 +1,260 @@
+/**
+ * The host's ledger of the processes it spawned.
+ *
+ * A cancelled run must not leave a child agent running, and the engine cannot
+ * do anything about that on its own: cancellation interrupts fibers, and a
+ * fiber closing its scope only reaches the processes THIS incarnation of the
+ * host still holds a handle for. A host that crashed left its children with no
+ * one holding anything.
+ *
+ * The ledger is the missing half. Every spawn is recorded here in memory and
+ * written to the journal as an ownerless durable record. It is ownerless
+ * because it describes the host rather than a run, and first-writer-wins is
+ * exactly the semantics a spawn record wants. The next incarnation of the same
+ * `hostId` replays those records, subtracts the ones that reported an exit,
+ * and is left with {@link Service.orphans}: the process groups a dead owner
+ * abandoned, which a platform reaper can then signal.
+ *
+ * The kernel stays BELOW the engine: this module records pids and process
+ * groups and knows nothing about runs, attempts, or ownership fences. It also
+ * stays platform-neutral, because signalling a process group is a platform
+ * concern and lives in `@smthrs/platform-node`.
+ *
+ * Governing design:
+ * `docs/specs/Concepts/Host Adapters.md` and
+ * `docs/specs/Concepts/Journal Queue.md`.
+ *
+ * @since 1.0.0-rc.0
+ */
+import * as JournalModule from "@smthrs/journal/Journal";
+import type { JournalError } from "@smthrs/journal/Journal";
+import * as JournalEvent from "@smthrs/journal/JournalEvent";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+/**
+ * The event type recording that a host started a process.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export declare const SpawnedEventType = "flows.host.process-spawned.v1";
+/**
+ * The event type recording that a recorded process ended.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export declare const ExitedEventType = "flows.host.process-exited.v1";
+/**
+ * The event type recording that a later incarnation killed an abandoned
+ * process group.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export declare const ReapedEventType = "flows.host.process-reaped.v1";
+/**
+ * The event type recording that a later incarnation retired a record WITHOUT
+ * signalling anything.
+ *
+ * A stored pid outlives the process that wrote it, so a reaper that cannot
+ * prove the number still names the process the record describes must not
+ * signal it. Retiring the record is still correct: nothing will ever be able
+ * to prove it again, and leaving it would make every later incarnation
+ * re-examine a number the operating system has moved on from.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export declare const SkippedEventType = "flows.host.process-reap-skipped.v1";
+/**
+ * The producer id every ledger record is written under.
+ *
+ * Replay checks it: a record forged by another producer cannot make a host
+ * signal a process group.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export declare const sourceId = "@smthrs/kernel/ProcessLedger";
+/**
+ * The journal run a host's process records live on.
+ *
+ * Process records describe a host, not a run, so they get a run of their own,
+ * named after the host. Two incarnations of one `hostId` therefore share a
+ * history, which is what makes an abandoned process discoverable.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export declare const hostRunId: (hostId: string) => JournalEvent.RunId;
+/**
+ * What the spawner knows about a process the moment it starts.
+ *
+ * `pgid` is `null` when the child shares the host's own process group. Such a
+ * process cannot be group-signalled — signalling that group would signal the
+ * host itself — so the ledger records the absence rather than a number a
+ * reaper could misread.
+ *
+ * `commandDigest` names the executable and nothing else, as
+ * `CommandLine.executable` renders it. Arguments carry credentials
+ * (`curl -u user:password`, `mysql -phunter2`) and these records are permanent
+ * journal entries, so the ledger never writes an argument down. A reader that
+ * has to act on a record matches it by pid and process group; the program name
+ * is there to make the row legible.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface Spawned {
+    readonly pid: number;
+    readonly pgid: number | null;
+    readonly commandDigest: string;
+}
+/**
+ * Schema for a recorded process, as it round-trips through the journal.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export declare const ProcessRecord: Schema.Struct<{
+    readonly pid: Schema.Int;
+    readonly pgid: Schema.NullOr<Schema.Int>;
+    readonly hostId: Schema.String;
+    readonly ownerPid: Schema.Int;
+    readonly startedAtMs: Schema.Int;
+    readonly commandDigest: Schema.String;
+}>;
+/**
+ * One process a host started, with the identity of the incarnation that
+ * started it.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type ProcessRecord = typeof ProcessRecord.Type;
+/**
+ * Why a ledger history could not be replayed.
+ *
+ * - `journal_unreadable`: a page of the host's history could not be read.
+ * - `cursor_stalled`: the journal reported more history but did not advance.
+ *
+ * @category models
+ * @since 1.0.0-rc.1
+ */
+export declare const ProcessLedgerReplayErrorCode: Schema.Literals<readonly ["journal_unreadable", "cursor_stalled"]>;
+declare const ProcessLedgerReplayError_base: Schema.Class<ProcessLedgerReplayError, Schema.TaggedStruct<"@smthrs/kernel/ProcessLedgerReplayError", {
+    readonly code: Schema.Literals<readonly ["journal_unreadable", "cursor_stalled"]>;
+    readonly message: Schema.String;
+    readonly cause: Schema.optional<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The ledger could not read a previous incarnation's history to its end.
+ *
+ * An unread history is never reported as an empty one: a caller that treated
+ * it as empty would leave every abandoned child running with no owner.
+ *
+ * @category errors
+ * @since 1.0.0-rc.1
+ */
+export declare class ProcessLedgerReplayError extends ProcessLedgerReplayError_base {
+}
+/**
+ * Ledger operations.
+ *
+ * Every write that has a durable half REPORTS whether that half committed.
+ * The in-memory set is still updated first, so a caller that decides to carry
+ * on has an accurate view of this incarnation, but the failure is not
+ * swallowed: a spawn whose record did not commit is a child that no later
+ * incarnation can discover, which is the exact hole this ledger exists to
+ * close. {@link ContainedSpawner} therefore refuses such a spawn, and the
+ * reaper leaves a record it could not retire in place so a later incarnation
+ * tries again.
+ *
+ * A ledger built with no journal ({@link makeMemory}) never fails: it promises
+ * nothing durable in the first place.
+ *
+ * @category services
+ * @since 1.0.0-rc.0
+ */
+export interface Service {
+    /** Records a started process and returns the durable record written for it. */
+    readonly record: (spawned: Spawned) => Effect.Effect<ProcessRecord, JournalError>;
+    /** Records that a process ended, and drops it from {@link Service.live}. */
+    readonly release: (record: ProcessRecord) => Effect.Effect<void, JournalError>;
+    /** Records that an abandoned process group was signalled by this host. */
+    readonly reaped: (record: ProcessRecord) => Effect.Effect<void, JournalError>;
+    /**
+     * Retires a record this host refused to signal, naming why. The record
+     * leaves {@link Service.orphans} without anything having been killed.
+     */
+    readonly skipped: (record: ProcessRecord, reason: string) => Effect.Effect<void, JournalError>;
+    /** The processes this incarnation started and has not yet released. */
+    readonly live: Effect.Effect<ReadonlyArray<ProcessRecord>>;
+    /**
+     * The processes a previous incarnation of this host left running.
+     *
+     * Fails when that history cannot be read to its end, so an unreadable
+     * history is never mistaken for one with nothing left running.
+     */
+    readonly orphans: Effect.Effect<ReadonlyArray<ProcessRecord>, ProcessLedgerReplayError>;
+}
+declare const ProcessLedger_base: Context.ServiceClass<ProcessLedger, "@smthrs/kernel/ProcessLedger", Service>;
+/**
+ * The process-ledger service tag.
+ *
+ * @category services
+ * @since 1.0.0-rc.0
+ */
+export declare class ProcessLedger extends ProcessLedger_base {
+}
+/**
+ * Ledger configuration.
+ *
+ * `hostId` is the durable identity two incarnations share; `ownerPid` is the
+ * process id of THIS incarnation, which is how a replay tells its own live
+ * processes from an abandoned one's.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface Options {
+    readonly hostId: string;
+    readonly ownerPid: number;
+}
+/**
+ * Builds a journal-backed ledger.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export declare const make: (options: Options) => Effect.Effect<Service, never, JournalModule.Journal>;
+/**
+ * Builds a ledger that records nothing durably.
+ *
+ * A host without a journal still contains the processes it holds handles for —
+ * scope closure does that — but it inherits nothing from a previous
+ * incarnation, so {@link Service.orphans} is always empty.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export declare const makeMemory: (options: Options) => Effect.Effect<Service>;
+/**
+ * Provides a journal-backed ledger.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export declare const layer: (options: Options) => Layer.Layer<ProcessLedger, never, JournalModule.Journal>;
+/**
+ * Provides a ledger that records nothing durably.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export declare const layerMemory: (options: Options) => Layer.Layer<ProcessLedger>;
+export {};
+//# sourceMappingURL=ProcessLedger.d.ts.map

package/dist/cjs/ProcessLedger.d.ts.map

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

package/dist/cjs/ProcessLedger.js

@@ -0,0 +1,190 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var ProcessLedger_exports = {};
+__export(ProcessLedger_exports, {
+  ExitedEventType: () => ExitedEventType,
+  ProcessLedger: () => ProcessLedger,
+  ProcessLedgerReplayError: () => ProcessLedgerReplayError,
+  ProcessLedgerReplayErrorCode: () => ProcessLedgerReplayErrorCode,
+  ProcessRecord: () => ProcessRecord,
+  ReapedEventType: () => ReapedEventType,
+  SkippedEventType: () => SkippedEventType,
+  SpawnedEventType: () => SpawnedEventType,
+  hostRunId: () => hostRunId,
+  layer: () => layer,
+  layerMemory: () => layerMemory,
+  make: () => make,
+  makeMemory: () => makeMemory,
+  sourceId: () => sourceId
+});
+module.exports = __toCommonJS(ProcessLedger_exports);
+var JournalModule = __toESM(require("@smthrs/journal/Journal"), 1);
+var JournalEvent = __toESM(require("@smthrs/journal/JournalEvent"), 1);
+var Context = __toESM(require("effect/Context"), 1);
+var Effect = __toESM(require("effect/Effect"), 1);
+var Layer = __toESM(require("effect/Layer"), 1);
+var Schema = __toESM(require("effect/Schema"), 1);
+const SpawnedEventType = "flows.host.process-spawned.v1";
+const ExitedEventType = "flows.host.process-exited.v1";
+const ReapedEventType = "flows.host.process-reaped.v1";
+const SkippedEventType = "flows.host.process-reap-skipped.v1";
+const sourceId = "@smthrs/kernel/ProcessLedger";
+const hostRunId = (hostId) => `flows.host:${hostId}`;
+const ProcessRecord = Schema.Struct({
+  pid: Schema.Int,
+  pgid: Schema.NullOr(Schema.Int),
+  hostId: Schema.String,
+  ownerPid: Schema.Int,
+  startedAtMs: Schema.Int,
+  commandDigest: Schema.String
+});
+const ProcessLedgerReplayErrorCode = Schema.Literals(["journal_unreadable", "cursor_stalled"]);
+class ProcessLedgerReplayError extends Schema.TaggedError()(
+  "@smthrs/kernel/ProcessLedgerReplayError",
+  {
+    code: ProcessLedgerReplayErrorCode,
+    message: Schema.String,
+    cause: Schema.optional(Schema.Defect())
+  }
+) {
+}
+const decodeRecord = Schema.decodeUnknownResult(ProcessRecord);
+const encodeRecord = Schema.encodeSync(ProcessRecord);
+class ProcessLedger extends Context.Service()("@smthrs/kernel/ProcessLedger") {
+}
+const retires = (eventType) => eventType === ExitedEventType || eventType === ReapedEventType || eventType === SkippedEventType;
+const identity = (record) => `${record.pid}:${record.startedAtMs}`;
+const apply = (live, entry) => {
+  if (entry.sourceId !== sourceId) return void 0;
+  if (entry.eventType !== SpawnedEventType && !retires(entry.eventType)) return void 0;
+  const decoded = decodeRecord(entry.payload);
+  if (decoded._tag === "Failure") return entry;
+  if (entry.eventType === SpawnedEventType) {
+    live.set(identity(decoded.success), decoded.success);
+    return;
+  }
+  live.delete(identity(decoded.success));
+  return void 0;
+};
+const PAGE = 256;
+const journalSink = (options, journal) => ({
+  append: (eventType, record, extra) => journal.emitDurableUnfenced(
+    new JournalEvent.Input({
+      runId: hostRunId(options.hostId),
+      sourceId,
+      eventType,
+      payload: extra === void 0 ? encodeRecord(record) : { ...encodeRecord(record), ...extra }
+    })
+  ).pipe(
+    // The failure is REPORTED, not logged away. A swallowed write leaves a
+    // child that no incarnation of this host can discover, which is the one
+    // outcome containment exists to prevent; the caller decides what to do
+    // about it, and every caller in this repository declines to pretend the
+    // process was recorded.
+    Effect.tapCause((cause) => Effect.logWarning(`process ledger could not journal ${eventType}`, cause)),
+    Effect.asVoid
+  ),
+  replay: Effect.gen(function* () {
+    const live = /* @__PURE__ */ new Map();
+    let after;
+    for (; ; ) {
+      const page = yield* journal.entries({
+        runId: hostRunId(options.hostId),
+        limit: PAGE,
+        ...after === void 0 ? {} : { after }
+      }).pipe(
+        Effect.mapError(
+          (cause) => new ProcessLedgerReplayError({
+            code: "journal_unreadable",
+            message: `process ledger could not read the history of host ${options.hostId}`,
+            cause
+          })
+        )
+      );
+      for (const entry of page.entries) {
+        const malformed = apply(live, entry);
+        if (malformed !== void 0) {
+          yield* Effect.logWarning(
+            `process ledger skipped an undecodable ${malformed.eventType} record at seq ${malformed.seq}`
+          );
+        }
+      }
+      const last = page.entries.at(-1);
+      if (last === void 0 || !page.hasMore) break;
+      if (after !== void 0 && last.seq <= after) {
+        return yield* Effect.fail(
+          new ProcessLedgerReplayError({
+            code: "cursor_stalled",
+            message: `process ledger history of host ${options.hostId} stopped advancing at seq ${last.seq}`
+          })
+        );
+      }
+      after = last.seq;
+    }
+    return [...live.values()];
+  })
+});
+const memorySink = {
+  append: () => Effect.void,
+  replay: Effect.succeed([])
+};
+const makeWith = (options, sink) => {
+  const live = /* @__PURE__ */ new Map();
+  return ProcessLedger.of({
+    record: (spawned) => Effect.gen(function* () {
+      const startedAtMs = yield* Effect.clockWith((clock) => clock.currentTimeMillis);
+      const record = {
+        pid: spawned.pid,
+        pgid: spawned.pgid,
+        hostId: options.hostId,
+        ownerPid: options.ownerPid,
+        startedAtMs,
+        commandDigest: spawned.commandDigest
+      };
+      live.set(identity(record), record);
+      yield* sink.append(SpawnedEventType, record).pipe(
+        Effect.tapCause(() => Effect.sync(() => live.delete(identity(record))))
+      );
+      return record;
+    }),
+    release: (record) => Effect.suspend(() => {
+      live.delete(identity(record));
+      return sink.append(ExitedEventType, record);
+    }),
+    reaped: (record) => sink.append(ReapedEventType, record),
+    skipped: (record, reason) => sink.append(SkippedEventType, record, { reason }),
+    live: Effect.sync(() => [...live.values()]),
+    orphans: Effect.map(sink.replay, (records) => records.filter((record) => record.ownerPid !== options.ownerPid))
+  });
+};
+const make = (options) => Effect.map(JournalModule.Journal, (journal) => makeWith(options, journalSink(options, journal)));
+const makeMemory = (options) => Effect.sync(() => makeWith(options, memorySink));
+const layer = (options) => Layer.effect(ProcessLedger, make(options));
+const layerMemory = (options) => Layer.effect(ProcessLedger, makeMemory(options));
+//# sourceMappingURL=ProcessLedger.js.map

package/dist/cjs/ProcessLedger.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/ProcessLedger.ts"],
+  "sourcesContent": ["/**\n * The host's ledger of the processes it spawned.\n *\n * A cancelled run must not leave a child agent running, and the engine cannot\n * do anything about that on its own: cancellation interrupts fibers, and a\n * fiber closing its scope only reaches the processes THIS incarnation of the\n * host still holds a handle for. A host that crashed left its children with no\n * one holding anything.\n *\n * The ledger is the missing half. Every spawn is recorded here in memory and\n * written to the journal as an ownerless durable record. It is ownerless\n * because it describes the host rather than a run, and first-writer-wins is\n * exactly the semantics a spawn record wants. The next incarnation of the same\n * `hostId` replays those records, subtracts the ones that reported an exit,\n * and is left with {@link Service.orphans}: the process groups a dead owner\n * abandoned, which a platform reaper can then signal.\n *\n * The kernel stays BELOW the engine: this module records pids and process\n * groups and knows nothing about runs, attempts, or ownership fences. It also\n * stays platform-neutral, because signalling a process group is a platform\n * concern and lives in `@smthrs/platform-node`.\n *\n * Governing design:\n * `docs/specs/Concepts/Host Adapters.md` and\n * `docs/specs/Concepts/Journal Queue.md`.\n *\n * @since 1.0.0-rc.0\n */\n\nimport * as JournalModule from \"@smthrs/journal/Journal\"\nimport type { JournalError } from \"@smthrs/journal/Journal\"\nimport * as JournalEvent from \"@smthrs/journal/JournalEvent\"\nimport * as Context from \"effect/Context\"\nimport * as Effect from \"effect/Effect\"\nimport * as Layer from \"effect/Layer\"\nimport * as Schema from \"effect/Schema\"\n\n/**\n * The event type recording that a host started a process.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport const SpawnedEventType = \"flows.host.process-spawned.v1\"\n\n/**\n * The event type recording that a recorded process ended.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport const ExitedEventType = \"flows.host.process-exited.v1\"\n\n/**\n * The event type recording that a later incarnation killed an abandoned\n * process group.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport const ReapedEventType = \"flows.host.process-reaped.v1\"\n\n/**\n * The event type recording that a later incarnation retired a record WITHOUT\n * signalling anything.\n *\n * A stored pid outlives the process that wrote it, so a reaper that cannot\n * prove the number still names the process the record describes must not\n * signal it. Retiring the record is still correct: nothing will ever be able\n * to prove it again, and leaving it would make every later incarnation\n * re-examine a number the operating system has moved on from.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport const SkippedEventType = \"flows.host.process-reap-skipped.v1\"\n\n/**\n * The producer id every ledger record is written under.\n *\n * Replay checks it: a record forged by another producer cannot make a host\n * signal a process group.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport const sourceId = \"@smthrs/kernel/ProcessLedger\"\n\n/**\n * The journal run a host's process records live on.\n *\n * Process records describe a host, not a run, so they get a run of their own,\n * named after the host. Two incarnations of one `hostId` therefore share a\n * history, which is what makes an abandoned process discoverable.\n *\n * @category constructors\n * @since 1.0.0-rc.0\n */\nexport const hostRunId = (hostId: string): JournalEvent.RunId => `flows.host:${hostId}` as JournalEvent.RunId\n\n/**\n * What the spawner knows about a process the moment it starts.\n *\n * `pgid` is `null` when the child shares the host's own process group. Such a\n * process cannot be group-signalled \u2014 signalling that group would signal the\n * host itself \u2014 so the ledger records the absence rather than a number a\n * reaper could misread.\n *\n * `commandDigest` names the executable and nothing else, as\n * `CommandLine.executable` renders it. Arguments carry credentials\n * (`curl -u user:password`, `mysql -phunter2`) and these records are permanent\n * journal entries, so the ledger never writes an argument down. A reader that\n * has to act on a record matches it by pid and process group; the program name\n * is there to make the row legible.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport interface Spawned {\n  readonly pid: number\n  readonly pgid: number | null\n  readonly commandDigest: string\n}\n\n/**\n * Schema for a recorded process, as it round-trips through the journal.\n *\n * @category schemas\n * @since 1.0.0-rc.0\n */\nexport const ProcessRecord = Schema.Struct({\n  pid: Schema.Int,\n  pgid: Schema.NullOr(Schema.Int),\n  hostId: Schema.String,\n  ownerPid: Schema.Int,\n  startedAtMs: Schema.Int,\n  commandDigest: Schema.String\n})\n\n/**\n * One process a host started, with the identity of the incarnation that\n * started it.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type ProcessRecord = typeof ProcessRecord.Type\n\n/**\n * Why a ledger history could not be replayed.\n *\n * - `journal_unreadable`: a page of the host's history could not be read.\n * - `cursor_stalled`: the journal reported more history but did not advance.\n *\n * @category models\n * @since 1.0.0-rc.1\n */\nexport const ProcessLedgerReplayErrorCode = Schema.Literals([\"journal_unreadable\", \"cursor_stalled\"])\n\n/**\n * The ledger could not read a previous incarnation's history to its end.\n *\n * An unread history is never reported as an empty one: a caller that treated\n * it as empty would leave every abandoned child running with no owner.\n *\n * @category errors\n * @since 1.0.0-rc.1\n */\nexport class ProcessLedgerReplayError extends Schema.TaggedError<ProcessLedgerReplayError>()(\n  \"@smthrs/kernel/ProcessLedgerReplayError\",\n  {\n    code: ProcessLedgerReplayErrorCode,\n    message: Schema.String,\n    cause: Schema.optional(Schema.Defect())\n  }\n) {}\n\nconst decodeRecord = Schema.decodeUnknownResult(ProcessRecord)\nconst encodeRecord = Schema.encodeSync(ProcessRecord)\n\n/**\n * Ledger operations.\n *\n * Every write that has a durable half REPORTS whether that half committed.\n * The in-memory set is still updated first, so a caller that decides to carry\n * on has an accurate view of this incarnation, but the failure is not\n * swallowed: a spawn whose record did not commit is a child that no later\n * incarnation can discover, which is the exact hole this ledger exists to\n * close. {@link ContainedSpawner} therefore refuses such a spawn, and the\n * reaper leaves a record it could not retire in place so a later incarnation\n * tries again.\n *\n * A ledger built with no journal ({@link makeMemory}) never fails: it promises\n * nothing durable in the first place.\n *\n * @category services\n * @since 1.0.0-rc.0\n */\nexport interface Service {\n  /** Records a started process and returns the durable record written for it. */\n  readonly record: (spawned: Spawned) => Effect.Effect<ProcessRecord, JournalError>\n  /** Records that a process ended, and drops it from {@link Service.live}. */\n  readonly release: (record: ProcessRecord) => Effect.Effect<void, JournalError>\n  /** Records that an abandoned process group was signalled by this host. */\n  readonly reaped: (record: ProcessRecord) => Effect.Effect<void, JournalError>\n  /**\n   * Retires a record this host refused to signal, naming why. The record\n   * leaves {@link Service.orphans} without anything having been killed.\n   */\n  readonly skipped: (record: ProcessRecord, reason: string) => Effect.Effect<void, JournalError>\n  /** The processes this incarnation started and has not yet released. */\n  readonly live: Effect.Effect<ReadonlyArray<ProcessRecord>>\n  /**\n   * The processes a previous incarnation of this host left running.\n   *\n   * Fails when that history cannot be read to its end, so an unreadable\n   * history is never mistaken for one with nothing left running.\n   */\n  readonly orphans: Effect.Effect<ReadonlyArray<ProcessRecord>, ProcessLedgerReplayError>\n}\n\n/**\n * The process-ledger service tag.\n *\n * @category services\n * @since 1.0.0-rc.0\n */\nexport class ProcessLedger extends Context.Service<ProcessLedger, Service>()(\"@smthrs/kernel/ProcessLedger\") {}\n\n/**\n * Ledger configuration.\n *\n * `hostId` is the durable identity two incarnations share; `ownerPid` is the\n * process id of THIS incarnation, which is how a replay tells its own live\n * processes from an abandoned one's.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport interface Options {\n  readonly hostId: string\n  readonly ownerPid: number\n}\n\n/** Where records are appended, and where a previous incarnation's are read. */\ninterface Sink {\n  readonly append: (\n    eventType: string,\n    record: ProcessRecord,\n    extra?: Record<string, unknown>\n  ) => Effect.Effect<void, JournalError>\n  readonly replay: Effect.Effect<ReadonlyArray<ProcessRecord>, ProcessLedgerReplayError>\n}\n\n/** The event types that retire a record from the inherited set. */\nconst retires = (eventType: string): boolean =>\n  eventType === ExitedEventType || eventType === ReapedEventType || eventType === SkippedEventType\n\n/** A pid may be reused before the previous process's scope releases its record. */\nconst identity = (record: ProcessRecord): string => `${record.pid}:${record.startedAtMs}`\n\n/**\n * One entry folded onto the live set.\n *\n * Returns the entry when it is one of the ledger's own records but its payload\n * does not decode, so replay can report it. Such an entry names no process\n * that could be signalled, so failing the whole replay over it would stop\n * every later incarnation from reaping the well-formed records beside it.\n */\nconst apply = (live: Map<string, ProcessRecord>, entry: JournalEvent.Entry): JournalEvent.Entry | undefined => {\n  if (entry.sourceId !== sourceId) return undefined\n  if (entry.eventType !== SpawnedEventType && !retires(entry.eventType)) return undefined\n  const decoded = decodeRecord(entry.payload)\n  if (decoded._tag === \"Failure\") return entry\n  if (entry.eventType === SpawnedEventType) {\n    live.set(identity(decoded.success), decoded.success)\n    return\n  }\n  live.delete(identity(decoded.success))\n  return undefined\n}\n\nconst PAGE = 256\n\nconst journalSink = (options: Options, journal: JournalModule.Service): Sink => ({\n  append: (eventType, record, extra) =>\n    journal.emitDurableUnfenced(\n      new JournalEvent.Input({\n        runId: hostRunId(options.hostId),\n        sourceId: sourceId as JournalEvent.SourceId,\n        eventType,\n        payload: extra === undefined ? encodeRecord(record) : { ...encodeRecord(record), ...extra }\n      })\n    ).pipe(\n      // The failure is REPORTED, not logged away. A swallowed write leaves a\n      // child that no incarnation of this host can discover, which is the one\n      // outcome containment exists to prevent; the caller decides what to do\n      // about it, and every caller in this repository declines to pretend the\n      // process was recorded.\n      Effect.tapCause((cause) => Effect.logWarning(`process ledger could not journal ${eventType}`, cause)),\n      Effect.asVoid\n    ),\n  replay: Effect.gen(function*() {\n    const live = new Map<string, ProcessRecord>()\n    let after: JournalEvent.Seq | undefined\n    for (;;) {\n      const page = yield* journal.entries({\n        runId: hostRunId(options.hostId),\n        limit: PAGE,\n        ...(after === undefined ? {} : { after })\n      }).pipe(\n        Effect.mapError((cause) =>\n          new ProcessLedgerReplayError({\n            code: \"journal_unreadable\",\n            message: `process ledger could not read the history of host ${options.hostId}`,\n            cause\n          })\n        )\n      )\n      for (const entry of page.entries) {\n        const malformed = apply(live, entry)\n        if (malformed !== undefined) {\n          yield* Effect.logWarning(\n            `process ledger skipped an undecodable ${malformed.eventType} record at seq ${malformed.seq}`\n          )\n        }\n      }\n      const last = page.entries.at(-1)\n      if (last === undefined || !page.hasMore) break\n      // A page that ends where the previous one did would be replayed\n      // forever, and stopping there would report a partial history as whole.\n      if (after !== undefined && last.seq <= after) {\n        return yield* Effect.fail(\n          new ProcessLedgerReplayError({\n            code: \"cursor_stalled\",\n            message: `process ledger history of host ${options.hostId} stopped advancing at seq ${last.seq}`\n          })\n        )\n      }\n      after = last.seq\n    }\n    return [...live.values()]\n  })\n})\n\nconst memorySink: Sink = {\n  append: () => Effect.void,\n  replay: Effect.succeed([])\n}\n\nconst makeWith = (options: Options, sink: Sink): Service => {\n  const live = new Map<string, ProcessRecord>()\n  return ProcessLedger.of({\n    record: (spawned) =>\n      Effect.gen(function*() {\n        const startedAtMs = yield* Effect.clockWith((clock) => clock.currentTimeMillis)\n        const record: ProcessRecord = {\n          pid: spawned.pid,\n          pgid: spawned.pgid,\n          hostId: options.hostId,\n          ownerPid: options.ownerPid,\n          startedAtMs,\n          commandDigest: spawned.commandDigest\n        }\n        live.set(identity(record), record)\n        // A failed append tells the caller the spawn was not recorded, and the\n        // caller kills the child. Keeping it live would lie to every later\n        // reader about a process this incarnation still holds.\n        yield* sink.append(SpawnedEventType, record).pipe(\n          Effect.tapCause(() => Effect.sync(() => live.delete(identity(record))))\n        )\n        return record\n      }),\n    release: (record) =>\n      Effect.suspend(() => {\n        live.delete(identity(record))\n        return sink.append(ExitedEventType, record)\n      }),\n    reaped: (record) => sink.append(ReapedEventType, record),\n    skipped: (record, reason) => sink.append(SkippedEventType, record, { reason }),\n    live: Effect.sync(() => [...live.values()]),\n    orphans: Effect.map(sink.replay, (records) => records.filter((record) => record.ownerPid !== options.ownerPid))\n  })\n}\n\n/**\n * Builds a journal-backed ledger.\n *\n * @category constructors\n * @since 1.0.0-rc.0\n */\nexport const make = (options: Options): Effect.Effect<Service, never, JournalModule.Journal> =>\n  Effect.map(JournalModule.Journal, (journal) => makeWith(options, journalSink(options, journal)))\n\n/**\n * Builds a ledger that records nothing durably.\n *\n * A host without a journal still contains the processes it holds handles for \u2014\n * scope closure does that \u2014 but it inherits nothing from a previous\n * incarnation, so {@link Service.orphans} is always empty.\n *\n * @category constructors\n * @since 1.0.0-rc.0\n */\nexport const makeMemory = (options: Options): Effect.Effect<Service> => Effect.sync(() => makeWith(options, memorySink))\n\n/**\n * Provides a journal-backed ledger.\n *\n * @category layers\n * @since 1.0.0-rc.0\n */\nexport const layer = (options: Options): Layer.Layer<ProcessLedger, never, JournalModule.Journal> =>\n  Layer.effect(ProcessLedger, make(options))\n\n/**\n * Provides a ledger that records nothing durably.\n *\n * @category layers\n * @since 1.0.0-rc.0\n */\nexport const layerMemory = (options: Options): Layer.Layer<ProcessLedger> =>\n  Layer.effect(ProcessLedger, makeMemory(options))\n"],
+  "mappings": "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",
+  "names": []
+}