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

package/dist/esm/ProcessLedger.js

@@ -0,0 +1,283 @@
+/**
+ * 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 * 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 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 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 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 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 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 const hostRunId = (hostId) => `flows.host:${hostId}`;
+/**
+ * Schema for a recorded process, as it round-trips through the journal.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export const ProcessRecord = Schema.Struct({
+    pid: Schema.Int,
+    pgid: Schema.NullOr(Schema.Int),
+    hostId: Schema.String,
+    ownerPid: Schema.Int,
+    startedAtMs: Schema.Int,
+    commandDigest: Schema.String
+});
+/**
+ * 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 const ProcessLedgerReplayErrorCode = Schema.Literals(["journal_unreadable", "cursor_stalled"]);
+/**
+ * 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 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);
+/**
+ * The process-ledger service tag.
+ *
+ * @category services
+ * @since 1.0.0-rc.0
+ */
+export class ProcessLedger extends Context.Service()("@smthrs/kernel/ProcessLedger") {
+}
+/** The event types that retire a record from the inherited set. */
+const retires = (eventType) => eventType === ExitedEventType || eventType === ReapedEventType || eventType === SkippedEventType;
+/** A pid may be reused before the previous process's scope releases its record. */
+const identity = (record) => `${record.pid}:${record.startedAtMs}`;
+/**
+ * One entry folded onto the live set.
+ *
+ * Returns the entry when it is one of the ledger's own records but its payload
+ * does not decode, so replay can report it. Such an entry names no process
+ * that could be signalled, so failing the whole replay over it would stop
+ * every later incarnation from reaping the well-formed records beside it.
+ */
+const apply = (live, entry) => {
+    if (entry.sourceId !== sourceId)
+        return undefined;
+    if (entry.eventType !== SpawnedEventType && !retires(entry.eventType))
+        return undefined;
+    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 undefined;
+};
+const PAGE = 256;
+const journalSink = (options, journal) => ({
+    append: (eventType, record, extra) => journal.emitDurableUnfenced(new JournalEvent.Input({
+        runId: hostRunId(options.hostId),
+        sourceId: sourceId,
+        eventType,
+        payload: extra === undefined ? 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 = new Map();
+        let after;
+        for (;;) {
+            const page = yield* journal.entries({
+                runId: hostRunId(options.hostId),
+                limit: PAGE,
+                ...(after === undefined ? {} : { 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 !== undefined) {
+                    yield* Effect.logWarning(`process ledger skipped an undecodable ${malformed.eventType} record at seq ${malformed.seq}`);
+                }
+            }
+            const last = page.entries.at(-1);
+            if (last === undefined || !page.hasMore)
+                break;
+            // A page that ends where the previous one did would be replayed
+            // forever, and stopping there would report a partial history as whole.
+            if (after !== undefined && 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 = 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);
+            // A failed append tells the caller the spawn was not recorded, and the
+            // caller kills the child. Keeping it live would lie to every later
+            // reader about a process this incarnation still holds.
+            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))
+    });
+};
+/**
+ * Builds a journal-backed ledger.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const make = (options) => Effect.map(JournalModule.Journal, (journal) => makeWith(options, journalSink(options, 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 const makeMemory = (options) => Effect.sync(() => makeWith(options, memorySink));
+/**
+ * Provides a journal-backed ledger.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export const layer = (options) => Layer.effect(ProcessLedger, make(options));
+/**
+ * Provides a ledger that records nothing durably.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export const layerMemory = (options) => Layer.effect(ProcessLedger, makeMemory(options));
+//# sourceMappingURL=ProcessLedger.js.map

package/dist/esm/ProcessLedger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProcessLedger.js","sourceRoot":"","sources":["../../src/ProcessLedger.ts"],"names":[],"mappings":"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","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 — signalling that group would signal the\n * host itself — 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 —\n * scope closure does that — 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"]}

package/dist/esm/Rooted.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Filesystem, path and process services bound to one root directory.
+ *
+ * Node resolves a relative path against `process.cwd()`. A host serves one
+ * directory whatever the process's own, so here every relative path, and every
+ * command spawned without a `cwd`, resolves against `root`. Absolute paths pass
+ * through unchanged, and so does a symlink's target, which is relative to the
+ * link rather than to any directory.
+ *
+ * @since 1.0.0
+ */
+import { FileSystem, Layer, Path } from "effect";
+import * as ChildProcess from "effect/unstable/process/ChildProcess";
+import * as ChildProcessSpawner from "effect/unstable/process/ChildProcessSpawner";
+/**
+ * `base` with every relative path resolved against the absolute `root`.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const path: (base: Path.Path, root: string) => Path.Path;
+/**
+ * `base` with every relative path resolved by `rooted`, a {@link path}.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const fileSystem: (base: FileSystem.FileSystem, rooted: Path.Path) => FileSystem.FileSystem;
+/**
+ * `value` with every stage's `cwd` resolved by `rooted`, a {@link path}; its
+ * root for a stage without one.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const command: (value: ChildProcess.Command, rooted: Path.Path) => ChildProcess.Command;
+/**
+ * `base` spawning each command as {@link command} roots it. A contained `base`
+ * stays contained.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const spawner: (base: ChildProcessSpawner.ChildProcessSpawner["Service"], rooted: Path.Path) => ChildProcessSpawner.ChildProcessSpawner["Service"];
+/**
+ * Decorates the `FileSystem`, `Path` and `ChildProcessSpawner` it is provided
+ * in place, so everything downstream resolves against `root`.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export declare const layer: (root: string) => Layer.Layer<FileSystem.FileSystem | Path.Path | ChildProcessSpawner.ChildProcessSpawner, never, FileSystem.FileSystem | Path.Path | ChildProcessSpawner.ChildProcessSpawner>;
+//# sourceMappingURL=Rooted.d.ts.map

package/dist/esm/Rooted.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Rooted.d.ts","sourceRoot":"","sources":["../../src/Rooted.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAmB,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AACjE,OAAO,KAAK,YAAY,MAAM,sCAAsC,CAAA;AACpE,OAAO,KAAK,mBAAmB,MAAM,6CAA6C,CAAA;AAGlF;;;;;GAKG;AACH,eAAO,MAAM,IAAI,GAAI,MAAM,IAAI,CAAC,IAAI,EAAE,MAAM,MAAM,KAAG,IAAI,CAAC,IAQzD,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,MAAM,UAAU,CAAC,UAAU,EAAE,QAAQ,IAAI,CAAC,IAAI,KAAG,UAAU,CAAC,UAqCtF,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,GAAI,OAAO,YAAY,CAAC,OAAO,EAAE,QAAQ,IAAI,CAAC,IAAI,KAAG,YAAY,CAAC,OAGa,CAAA;AAEnG;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,GAClB,MAAM,mBAAmB,CAAC,mBAAmB,CAAC,SAAS,CAAC,EACxD,QAAQ,IAAI,CAAC,IAAI,KAChB,mBAAmB,CAAC,mBAAmB,CAAC,SAAS,CACgD,CAAA;AAEpG;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,GAChB,MAAM,MAAM,KACX,KAAK,CAAC,KAAK,CACZ,UAAU,CAAC,UAAU,GAAG,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC,mBAAmB,EAC3E,KAAK,EACL,UAAU,CAAC,UAAU,GAAG,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC,mBAAmB,CAYxE,CAAA"}

package/dist/esm/Rooted.js

@@ -0,0 +1,104 @@
+/**
+ * Filesystem, path and process services bound to one root directory.
+ *
+ * Node resolves a relative path against `process.cwd()`. A host serves one
+ * directory whatever the process's own, so here every relative path, and every
+ * command spawned without a `cwd`, resolves against `root`. Absolute paths pass
+ * through unchanged, and so does a symlink's target, which is relative to the
+ * link rather than to any directory.
+ *
+ * @since 1.0.0
+ */
+import { Context, Effect, FileSystem, Layer, Path } from "effect";
+import * as ChildProcess from "effect/unstable/process/ChildProcess";
+import * as ChildProcessSpawner from "effect/unstable/process/ChildProcessSpawner";
+import * as Containment from "./internal/Containment.js";
+/**
+ * `base` with every relative path resolved against the absolute `root`.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const path = (base, root) => {
+    const resolve = (...segments) => base.resolve(root, ...segments);
+    return {
+        ...base,
+        resolve,
+        relative: (from, to) => base.relative(resolve(from), resolve(to)),
+        toFileUrl: (value) => base.toFileUrl(resolve(value))
+    };
+};
+/**
+ * `base` with every relative path resolved by `rooted`, a {@link path}.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const fileSystem = (base, rooted) => {
+    const at = (value) => rooted.resolve(value);
+    const temp = (options) => options?.directory === undefined ? options : { ...options, directory: at(options.directory) };
+    return {
+        ...base,
+        access: (value, options) => base.access(at(value), options),
+        copy: (from, to, options) => base.copy(at(from), at(to), options),
+        copyFile: (from, to) => base.copyFile(at(from), at(to)),
+        chmod: (value, mode) => base.chmod(at(value), mode),
+        chown: (value, uid, gid) => base.chown(at(value), uid, gid),
+        glob: (pattern, options) => base.glob(pattern, { ...options, root: at(options?.root ?? ".") }),
+        exists: (value) => base.exists(at(value)),
+        link: (from, to) => base.link(at(from), at(to)),
+        makeDirectory: (value, options) => base.makeDirectory(at(value), options),
+        makeTempDirectory: (options) => base.makeTempDirectory(temp(options)),
+        makeTempDirectoryScoped: (options) => base.makeTempDirectoryScoped(temp(options)),
+        makeTempFile: (options) => base.makeTempFile(temp(options)),
+        makeTempFileScoped: (options) => base.makeTempFileScoped(temp(options)),
+        open: (value, options) => base.open(at(value), options),
+        readDirectory: (value, options) => base.readDirectory(at(value), options),
+        readFile: (value) => base.readFile(at(value)),
+        readFileString: (value, encoding) => base.readFileString(at(value), encoding),
+        readLink: (value) => base.readLink(at(value)),
+        realPath: (value) => base.realPath(at(value)),
+        remove: (value, options) => base.remove(at(value), options),
+        rename: (from, to) => base.rename(at(from), at(to)),
+        sink: (value, options) => base.sink(at(value), options),
+        stat: (value) => base.stat(at(value)),
+        stream: (value, options) => base.stream(at(value), options),
+        symlink: (target, value) => base.symlink(target, at(value)),
+        truncate: (value, length) => base.truncate(at(value), length),
+        utimes: (value, atime, mtime) => base.utimes(at(value), atime, mtime),
+        watch: (value, options) => base.watch(at(value), options),
+        writeFile: (value, data, options) => base.writeFile(at(value), data, options),
+        writeFileString: (value, data, options) => base.writeFileString(at(value), data, options)
+    };
+};
+/**
+ * `value` with every stage's `cwd` resolved by `rooted`, a {@link path}; its
+ * root for a stage without one.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const command = (value, rooted) => ChildProcess.isStandardCommand(value)
+    ? ChildProcess.setCwd(value, rooted.resolve(value.options.cwd ?? "."))
+    : ChildProcess.pipeTo(command(value.left, rooted), command(value.right, rooted), value.options);
+/**
+ * `base` spawning each command as {@link command} roots it. A contained `base`
+ * stays contained.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const spawner = (base, rooted) => Containment.inherit(base, ChildProcessSpawner.make((value) => base.spawn(command(value, rooted))));
+/**
+ * Decorates the `FileSystem`, `Path` and `ChildProcessSpawner` it is provided
+ * in place, so everything downstream resolves against `root`.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export const layer = (root) => Layer.effectContext(Effect.gen(function* () {
+    const base = yield* Path.Path;
+    const rooted = path(base, base.resolve(root));
+    return Context.make(Path.Path, rooted).pipe(Context.add(FileSystem.FileSystem, fileSystem(yield* FileSystem.FileSystem, rooted)), Context.add(ChildProcessSpawner.ChildProcessSpawner, spawner(yield* ChildProcessSpawner.ChildProcessSpawner, rooted)));
+}));
+//# sourceMappingURL=Rooted.js.map

package/dist/esm/Rooted.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Rooted.js","sourceRoot":"","sources":["../../src/Rooted.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Filesystem, path and process services bound to one root directory.\n *\n * Node resolves a relative path against `process.cwd()`. A host serves one\n * directory whatever the process's own, so here every relative path, and every\n * command spawned without a `cwd`, resolves against `root`. Absolute paths pass\n * through unchanged, and so does a symlink's target, which is relative to the\n * link rather than to any directory.\n *\n * @since 1.0.0\n */\n\nimport { Context, Effect, FileSystem, Layer, Path } from \"effect\"\nimport * as ChildProcess from \"effect/unstable/process/ChildProcess\"\nimport * as ChildProcessSpawner from \"effect/unstable/process/ChildProcessSpawner\"\nimport * as Containment from \"./internal/Containment.ts\"\n\n/**\n * `base` with every relative path resolved against the absolute `root`.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const path = (base: Path.Path, root: string): Path.Path => {\n  const resolve = (...segments: ReadonlyArray<string>) => base.resolve(root, ...segments)\n  return {\n    ...base,\n    resolve,\n    relative: (from, to) => base.relative(resolve(from), resolve(to)),\n    toFileUrl: (value) => base.toFileUrl(resolve(value))\n  }\n}\n\n/**\n * `base` with every relative path resolved by `rooted`, a {@link path}.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const fileSystem = (base: FileSystem.FileSystem, rooted: Path.Path): FileSystem.FileSystem => {\n  const at = (value: string) => rooted.resolve(value)\n  const temp = <O extends { readonly directory?: string | undefined }>(options: O | undefined) =>\n    options?.directory === undefined ? options : { ...options, directory: at(options.directory) }\n  return {\n    ...base,\n    access: (value, options) => base.access(at(value), options),\n    copy: (from, to, options) => base.copy(at(from), at(to), options),\n    copyFile: (from, to) => base.copyFile(at(from), at(to)),\n    chmod: (value, mode) => base.chmod(at(value), mode),\n    chown: (value, uid, gid) => base.chown(at(value), uid, gid),\n    glob: (pattern, options) => base.glob(pattern, { ...options, root: at(options?.root ?? \".\") }),\n    exists: (value) => base.exists(at(value)),\n    link: (from, to) => base.link(at(from), at(to)),\n    makeDirectory: (value, options) => base.makeDirectory(at(value), options),\n    makeTempDirectory: (options) => base.makeTempDirectory(temp(options)),\n    makeTempDirectoryScoped: (options) => base.makeTempDirectoryScoped(temp(options)),\n    makeTempFile: (options) => base.makeTempFile(temp(options)),\n    makeTempFileScoped: (options) => base.makeTempFileScoped(temp(options)),\n    open: (value, options) => base.open(at(value), options),\n    readDirectory: (value, options) => base.readDirectory(at(value), options),\n    readFile: (value) => base.readFile(at(value)),\n    readFileString: (value, encoding) => base.readFileString(at(value), encoding),\n    readLink: (value) => base.readLink(at(value)),\n    realPath: (value) => base.realPath(at(value)),\n    remove: (value, options) => base.remove(at(value), options),\n    rename: (from, to) => base.rename(at(from), at(to)),\n    sink: (value, options) => base.sink(at(value), options),\n    stat: (value) => base.stat(at(value)),\n    stream: (value, options) => base.stream(at(value), options),\n    symlink: (target, value) => base.symlink(target, at(value)),\n    truncate: (value, length) => base.truncate(at(value), length),\n    utimes: (value, atime, mtime) => base.utimes(at(value), atime, mtime),\n    watch: (value, options) => base.watch(at(value), options),\n    writeFile: (value, data, options) => base.writeFile(at(value), data, options),\n    writeFileString: (value, data, options) => base.writeFileString(at(value), data, options)\n  }\n}\n\n/**\n * `value` with every stage's `cwd` resolved by `rooted`, a {@link path}; its\n * root for a stage without one.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const command = (value: ChildProcess.Command, rooted: Path.Path): ChildProcess.Command =>\n  ChildProcess.isStandardCommand(value)\n    ? ChildProcess.setCwd(value, rooted.resolve(value.options.cwd ?? \".\"))\n    : ChildProcess.pipeTo(command(value.left, rooted), command(value.right, rooted), value.options)\n\n/**\n * `base` spawning each command as {@link command} roots it. A contained `base`\n * stays contained.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const spawner = (\n  base: ChildProcessSpawner.ChildProcessSpawner[\"Service\"],\n  rooted: Path.Path\n): ChildProcessSpawner.ChildProcessSpawner[\"Service\"] =>\n  Containment.inherit(base, ChildProcessSpawner.make((value) => base.spawn(command(value, rooted))))\n\n/**\n * Decorates the `FileSystem`, `Path` and `ChildProcessSpawner` it is provided\n * in place, so everything downstream resolves against `root`.\n *\n * @category layers\n * @since 1.0.0\n */\nexport const layer = (\n  root: string\n): Layer.Layer<\n  FileSystem.FileSystem | Path.Path | ChildProcessSpawner.ChildProcessSpawner,\n  never,\n  FileSystem.FileSystem | Path.Path | ChildProcessSpawner.ChildProcessSpawner\n> =>\n  Layer.effectContext(Effect.gen(function*() {\n    const base = yield* Path.Path\n    const rooted = path(base, base.resolve(root))\n    return Context.make(Path.Path, rooted).pipe(\n      Context.add(FileSystem.FileSystem, fileSystem(yield* FileSystem.FileSystem, rooted)),\n      Context.add(\n        ChildProcessSpawner.ChildProcessSpawner,\n        spawner(yield* ChildProcessSpawner.ChildProcessSpawner, rooted)\n      )\n    )\n  }))\n"]}

package/dist/esm/Unreachable.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Typed host connectivity failures, including failed command diagnostics.
+ *
+ * @since 1.0.0
+ */
+import * as Schema from "effect/Schema";
+declare const Unreachable_base: Schema.Class<Unreachable, Schema.TaggedStruct<"@smthrs/kernel/Unreachable", {
+    readonly message: Schema.String;
+    readonly cause: Schema.optional<Schema.Unknown>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A temporarily unreachable resolver, connection, or HTTP service.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export declare class Unreachable extends Unreachable_base {
+}
+/**
+ * Classifies stderr from a failed host command; other exits keep their domain error.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const classifyExit: (stderr: string) => Unreachable | undefined;
+export {};
+//# sourceMappingURL=Unreachable.d.ts.map

package/dist/esm/Unreachable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Unreachable.d.ts","sourceRoot":"","sources":["../../src/Unreachable.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;;;;;AAEvC;;;;;GAKG;AACH,qBAAa,WAAY,SAAQ,gBAG/B;CAAG;AAKL;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,MAAM,KAAG,WAAW,GAAG,SACY,CAAA"}

package/dist/esm/Unreachable.js

@@ -0,0 +1,26 @@
+/**
+ * Typed host connectivity failures, including failed command diagnostics.
+ *
+ * @since 1.0.0
+ */
+import * as Schema from "effect/Schema";
+/**
+ * A temporarily unreachable resolver, connection, or HTTP service.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export class Unreachable extends Schema.TaggedError()("@smthrs/kernel/Unreachable", {
+    message: Schema.String,
+    cause: Schema.optional(Schema.Unknown)
+}) {
+}
+const outage = /Could not resolve host|Failed to connect to|Connection timed out|Operation timed out|Connection reset|Recv failure|Network is unreachable|Temporary failure in name resolution|SSL_ERROR_SYSCALL|The remote end hung up unexpectedly|\bEAI_AGAIN\b|\bENOTFOUND\b|\bHTTP(?:\/\d(?:\.\d)?)?\s*(?:(?:error|status|code)\s*[:=]?\s*)?[:=]?\s*(?:429|5\d{2})\b/i;
+/**
+ * Classifies stderr from a failed host command; other exits keep their domain error.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const classifyExit = (stderr) => outage.test(stderr) ? new Unreachable({ message: stderr }) : undefined;
+//# sourceMappingURL=Unreachable.js.map

package/dist/esm/Unreachable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Unreachable.js","sourceRoot":"","sources":["../../src/Unreachable.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;GAKG;AACH,MAAM,OAAO,WAAY,SAAQ,MAAM,CAAC,WAAW,EAAe,CAAC,4BAA4B,EAAE;IAC/F,OAAO,EAAE,MAAM,CAAC,MAAM;IACtB,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC;CACvC,CAAC;CAAG;AAEL,MAAM,MAAM,GACV,4VAA4V,CAAA;AAE9V;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,MAAc,EAA2B,EAAE,CACtE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,WAAW,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA","sourcesContent":["/**\n * Typed host connectivity failures, including failed command diagnostics.\n *\n * @since 1.0.0\n */\n\nimport * as Schema from \"effect/Schema\"\n\n/**\n * A temporarily unreachable resolver, connection, or HTTP service.\n *\n * @category errors\n * @since 1.0.0\n */\nexport class Unreachable extends Schema.TaggedError<Unreachable>()(\"@smthrs/kernel/Unreachable\", {\n  message: Schema.String,\n  cause: Schema.optional(Schema.Unknown)\n}) {}\n\nconst outage =\n  /Could not resolve host|Failed to connect to|Connection timed out|Operation timed out|Connection reset|Recv failure|Network is unreachable|Temporary failure in name resolution|SSL_ERROR_SYSCALL|The remote end hung up unexpectedly|\\bEAI_AGAIN\\b|\\bENOTFOUND\\b|\\bHTTP(?:\\/\\d(?:\\.\\d)?)?\\s*(?:(?:error|status|code)\\s*[:=]?\\s*)?[:=]?\\s*(?:429|5\\d{2})\\b/i\n\n/**\n * Classifies stderr from a failed host command; other exits keep their domain error.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const classifyExit = (stderr: string): Unreachable | undefined =>\n  outage.test(stderr) ? new Unreachable({ message: stderr }) : undefined\n"]}

package/dist/esm/Workspace.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The workspace root used to make filesystem capability resources stable.
+ *
+ * It lives beside the closed host list rather than in a platform package: a
+ * workspace root is a policy decision the kernel needs before it can name a
+ * filesystem capability, not something a platform can answer.
+ *
+ * Governing design:
+ * `docs/specs/Concepts/Effect Taxonomy.md` and
+ * `docs/specs/Concepts/Permission Kernel.md`.
+ *
+ * @since 1.0.0-rc.0
+ */
+import { Context, Layer } from "effect";
+/**
+ * Workspace-root configuration.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface Service {
+    readonly root: string;
+}
+declare const Workspace_base: Context.ServiceClass<Workspace, "@smthrs/kernel/Workspace", Service>;
+/**
+ * The workspace-root service tag.
+ *
+ * @category services
+ * @since 1.0.0-rc.0
+ */
+export declare class Workspace extends Workspace_base {
+}
+/**
+ * Constructs workspace-root configuration.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export declare const make: (root: string) => Service;
+/**
+ * Provides a workspace root.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export declare const layer: (root: string) => Layer.Layer<Workspace>;
+/**
+ * Constructs a relative workspace-root stub for tests.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export declare const makeNoop: Service;
+/**
+ * Provides a relative workspace-root stub for tests.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export declare const layerNoop: Layer.Layer<Workspace>;
+export {};
+//# sourceMappingURL=Workspace.d.ts.map

package/dist/esm/Workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Workspace.d.ts","sourceRoot":"","sources":["../../src/Workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAA;AAEvC;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;;AAED;;;;;GAKG;AACH,qBAAa,SAAU,SAAQ,cAAiE;CAAG;AAEnG;;;;;GAKG;AACH,eAAO,MAAM,IAAI,GAAI,MAAM,MAAM,KAAG,OAAiC,CAAA;AAErE;;;;;GAKG;AACH,eAAO,MAAM,KAAK,GAAI,MAAM,MAAM,KAAG,KAAK,CAAC,KAAK,CAAC,SAAS,CAAyC,CAAA;AAEnG;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,EAAE,OAAmB,CAAA;AAE1C;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,SAAS,CAAsC,CAAA"}