@smthrs/control 0.0.0-stage → 1.0.0-rc.3

package/dist/cjs/ScopedToken.js

@@ -0,0 +1,135 @@
+"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 ScopedToken_exports = {};
+__export(ScopedToken_exports, {
+  Claims: () => Claims,
+  authenticator: () => authenticator,
+  authorizes: () => authorizes,
+  isScopedToken: () => isScopedToken,
+  mint: () => mint,
+  prefix: () => prefix,
+  procedures: () => procedures,
+  scopeNames: () => scopeNames,
+  scopes: () => scopes,
+  verify: () => verify
+});
+module.exports = __toCommonJS(ScopedToken_exports);
+var import_effect = require("effect");
+var import_ControlError = require("./ControlError.js");
+var import_ControlRpcs = require("./ControlRpcs.js");
+const prefix = "smt1";
+const scopes = {
+  "read:runs": ["List", "Watch", "Projection.Snapshot", "Projection.Subscribe"],
+  "write:runs": ["Plan", "Run", "Steer", "Signal", "Cancel", "Resume", "Run.Fork", "Run.Verify"],
+  "approve:runs": ["Approve", "Deny", "Approval.Submit"]
+};
+const scopeNames = Object.keys(scopes);
+const Claims = import_effect.Schema.Struct({
+  v: import_effect.Schema.Literal(1),
+  /** A random identifier, so two tokens with the same grant differ. */
+  id: import_effect.Schema.String,
+  procedures: import_effect.Schema.Array(import_effect.Schema.String),
+  runId: import_effect.Schema.optional(import_effect.Schema.String),
+  flowId: import_effect.Schema.optional(import_effect.Schema.String),
+  /** Minted at, milliseconds since the epoch. */
+  iat: import_effect.Schema.Number,
+  /** Expires at, milliseconds since the epoch; refused once `now >= exp`. */
+  exp: import_effect.Schema.Number
+});
+const encodeClaims = import_effect.Schema.encodeUnknownSync(Claims);
+const decodeClaims = import_effect.Schema.decodeUnknownResult(Claims);
+const encoder = new TextEncoder();
+const subtle = () => {
+  const available = globalThis.crypto?.subtle;
+  if (available === void 0) throw new Error("Web Crypto is not available on this host");
+  return available;
+};
+const hmacKey = (key, usage) => subtle().importKey("raw", encoder.encode(key), { name: "HMAC", hash: "SHA-256" }, false, [usage]);
+const isScopedToken = (credential) => credential.startsWith(`${prefix}.`);
+const procedures = (names) => [...new Set(names.flatMap((name) => scopes[name]))];
+const mint = (options) => import_effect.Effect.suspend(() => {
+  if (options.key.length === 0) return import_effect.Effect.die(new Error("A scoped token needs a non-empty signing key"));
+  if (options.scopes.length === 0) return import_effect.Effect.die(new Error("A scoped token needs at least one scope"));
+  if (!Number.isFinite(options.ttlMillis) || options.ttlMillis <= 0) {
+    return import_effect.Effect.die(new Error("A scoped token needs a positive lifetime"));
+  }
+  const now = options.now?.() ?? Date.now();
+  const id = import_effect.Encoding.encodeHex(crypto.getRandomValues(new Uint8Array(12)));
+  const claims = {
+    v: 1,
+    id,
+    procedures: procedures(options.scopes),
+    ...options.runId === void 0 ? {} : { runId: options.runId },
+    ...options.flowId === void 0 ? {} : { flowId: options.flowId },
+    iat: now,
+    exp: now + Math.floor(options.ttlMillis)
+  };
+  const body = import_effect.Encoding.encodeBase64Url(JSON.stringify(encodeClaims(claims)));
+  return import_effect.Effect.promise(async () => {
+    const key = await hmacKey(options.key, "sign");
+    const signature = new Uint8Array(await subtle().sign("HMAC", key, encoder.encode(`${prefix}.${body}`)));
+    return { token: `${prefix}.${body}.${import_effect.Encoding.encodeBase64Url(signature)}`, claims };
+  });
+});
+const refused = (message) => import_effect.Effect.fail(new import_ControlError.Unauthorized({ message }));
+const verify = (key, token, now) => import_effect.Effect.suspend(() => {
+  const parts = token.split(".");
+  if (key.length === 0 || parts.length !== 3 || parts[0] !== prefix || parts[1].length === 0) {
+    return refused("A valid scoped token is required");
+  }
+  const signature = import_effect.Encoding.decodeBase64Url(parts[2]);
+  if (import_effect.Result.isFailure(signature)) return refused("A valid scoped token is required");
+  return import_effect.Effect.promise(async () => {
+    const hmac = await hmacKey(key, "verify");
+    return subtle().verify("HMAC", hmac, new Uint8Array(signature.success), encoder.encode(`${prefix}.${parts[1]}`));
+  }).pipe(
+    import_effect.Effect.flatMap((valid) => {
+      if (!valid) return refused("A valid scoped token is required");
+      const text = import_effect.Encoding.decodeBase64UrlString(parts[1]);
+      if (import_effect.Result.isFailure(text)) return refused("A valid scoped token is required");
+      let parsed;
+      try {
+        parsed = JSON.parse(text.success);
+      } catch {
+        return refused("A valid scoped token is required");
+      }
+      const claims = decodeClaims(parsed);
+      if (import_effect.Result.isFailure(claims)) return refused("A valid scoped token is required");
+      if (!(now < claims.success.exp)) return refused("The scoped token has expired");
+      return import_effect.Effect.succeed(claims.success);
+    })
+  );
+});
+const field = (value, name) => typeof value === "object" && value !== null ? value[name] : void 0;
+const namedRun = (payload) => field(payload, "runId") ?? field(field(payload, "target"), "runId") ?? field(field(payload, "selector"), "runId") ?? field(field(payload, "filters"), "runId");
+const namedFlow = (payload) => field(payload, "flowId") ?? field(field(payload, "filters"), "flowId");
+const authorizes = (claims, call) => claims.procedures.includes(call.rpc) && (claims.runId === void 0 || namedRun(call.payload) === claims.runId) && (claims.flowId === void 0 || namedFlow(call.payload) === claims.flowId);
+const authenticator = (options) => ({
+  authenticate: (headers, call) => {
+    const credential = (0, import_ControlRpcs.bearerCredential)(headers);
+    if (credential === void 0 || !isScopedToken(credential)) return refused("A valid scoped token is required");
+    const now = options.now?.() ?? Date.now();
+    return verify(options.key, credential, now).pipe(
+      import_effect.Effect.flatMap(
+        (claims) => call !== void 0 && !authorizes(claims, call) ? refused(`The scoped token does not authorize ${call.rpc}`) : import_effect.Effect.succeed({ ...options.principal, stampedAt: now })
+      )
+    );
+  }
+});
+//# sourceMappingURL=ScopedToken.js.map

package/dist/cjs/ScopedToken.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/ScopedToken.ts"],
+  "sourcesContent": ["/**\n * Scoped, expiring gateway tokens.\n *\n * A gateway's configured bearer credential grants everything the gateway\n * serves, for as long as it is configured. A scoped token is a grant the\n * holder of that credential mints for someone else: a closed list of\n * procedures, optionally confined to one run or one flow, and an expiry. It\n * is signed with HMAC-SHA256 under the bearer credential, so a gateway\n * verifies it with the key it already holds and stores nothing; rotating the\n * bearer credential revokes every token minted under it.\n *\n * The wire form is `smt1.<claims>.<signature>`, both parts unpadded base64url,\n * the claims a canonical JSON document. A token names procedures rather than\n * scope words so that what it authorizes is readable off the token itself and\n * does not change when a scope grows.\n *\n * Web Crypto does the signing, so the same module runs on Node, Bun, and in a\n * browser that holds a token.\n *\n * @since 1.0.0\n */\n\nimport { Effect, Encoding, Result, Schema } from \"effect\"\nimport { Unauthorized } from \"./ControlError.ts\"\nimport { type Authenticator, bearerCredential, type Call } from \"./ControlRpcs.ts\"\nimport type { Principal } from \"./ControlSchema.ts\"\n\n/**\n * The version prefix every scoped token starts with.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const prefix = \"smt1\"\n\n/**\n * The scopes `smthrs token mint --scope` accepts, and the procedures each\n * one names.\n *\n * `read:runs` covers every read the control plane and the gateway serve.\n * `write:runs` covers the mutations that start, steer, signal, cancel, and\n * resume a run, and the gateway's `Run.Fork` and `Run.Verify`, which branch a\n * run or drive the project's flow code over a copy of it. `approve:runs` covers the approval decisions on both mounts.\n * A token holding `approve:runs` still needs the host's `ApprovalAuthority`\n * to delegate to its principal, exactly as the bearer does.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const scopes = {\n  \"read:runs\": [\"List\", \"Watch\", \"Projection.Snapshot\", \"Projection.Subscribe\"],\n  \"write:runs\": [\"Plan\", \"Run\", \"Steer\", \"Signal\", \"Cancel\", \"Resume\", \"Run.Fork\", \"Run.Verify\"],\n  \"approve:runs\": [\"Approve\", \"Deny\", \"Approval.Submit\"]\n} as const satisfies Record<string, ReadonlyArray<string>>\n\n/**\n * One scope name.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Scope = keyof typeof scopes\n\n/**\n * Every scope name, in the order {@link scopes} declares them.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const scopeNames: ReadonlyArray<Scope> = Object.keys(scopes) as Array<Scope>\n\n/**\n * What a token grants, as signed.\n *\n * @category models\n * @since 1.0.0\n */\nexport const Claims = Schema.Struct({\n  v: Schema.Literal(1),\n  /** A random identifier, so two tokens with the same grant differ. */\n  id: Schema.String,\n  procedures: Schema.Array(Schema.String),\n  runId: Schema.optional(Schema.String),\n  flowId: Schema.optional(Schema.String),\n  /** Minted at, milliseconds since the epoch. */\n  iat: Schema.Number,\n  /** Expires at, milliseconds since the epoch; refused once `now >= exp`. */\n  exp: Schema.Number\n})\n\n/**\n * What a token grants, as signed.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Claims = typeof Claims.Type\n\n/**\n * What `mint` needs.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface MintOptions {\n  /** The signing key: the gateway's configured bearer credential. */\n  readonly key: string\n  readonly scopes: ReadonlyArray<Scope>\n  /** How long the token lives, in milliseconds; must be positive. */\n  readonly ttlMillis: number\n  /** Confine every call to this run. */\n  readonly runId?: string | undefined\n  /** Confine every call to this flow. */\n  readonly flowId?: string | undefined\n  readonly now?: (() => number) | undefined\n}\n\n/**\n * A minted token beside the claims it carries.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface Minted {\n  readonly token: string\n  readonly claims: Claims\n}\n\nconst encodeClaims = Schema.encodeUnknownSync(Claims)\nconst decodeClaims = Schema.decodeUnknownResult(Claims)\nconst encoder = new TextEncoder()\n\nconst subtle = (): SubtleCrypto => {\n  const available = (globalThis.crypto as Crypto | undefined)?.subtle\n  if (available === undefined) throw new Error(\"Web Crypto is not available on this host\")\n  return available\n}\n\nconst hmacKey = (key: string, usage: \"sign\" | \"verify\") =>\n  subtle().importKey(\"raw\", encoder.encode(key), { name: \"HMAC\", hash: \"SHA-256\" }, false, [usage])\n\n/**\n * Whether a bearer credential is spelled as a scoped token.\n *\n * @category predicates\n * @since 1.0.0\n */\nexport const isScopedToken = (credential: string): boolean => credential.startsWith(`${prefix}.`)\n\n/**\n * The procedures a list of scopes names, each once, in scope order.\n *\n * @category getters\n * @since 1.0.0\n */\nexport const procedures = (\n  names: ReadonlyArray<Scope>\n): ReadonlyArray<string> => [...new Set(names.flatMap((name) => scopes[name]))]\n\n/**\n * Mints one token under the key.\n *\n * An empty key, no scopes, or a non-positive lifetime is a caller defect: it\n * cannot produce a token anyone should hold, so it dies rather than signs.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const mint = (options: MintOptions): Effect.Effect<Minted> =>\n  Effect.suspend(() => {\n    if (options.key.length === 0) return Effect.die(new Error(\"A scoped token needs a non-empty signing key\"))\n    if (options.scopes.length === 0) return Effect.die(new Error(\"A scoped token needs at least one scope\"))\n    if (!Number.isFinite(options.ttlMillis) || options.ttlMillis <= 0) {\n      return Effect.die(new Error(\"A scoped token needs a positive lifetime\"))\n    }\n    const now = options.now?.() ?? Date.now()\n    const id = Encoding.encodeHex(crypto.getRandomValues(new Uint8Array(12)))\n    const claims: Claims = {\n      v: 1,\n      id,\n      procedures: procedures(options.scopes),\n      ...(options.runId === undefined ? {} : { runId: options.runId }),\n      ...(options.flowId === undefined ? {} : { flowId: options.flowId }),\n      iat: now,\n      exp: now + Math.floor(options.ttlMillis)\n    }\n    const body = Encoding.encodeBase64Url(JSON.stringify(encodeClaims(claims)))\n    return Effect.promise(async () => {\n      const key = await hmacKey(options.key, \"sign\")\n      const signature = new Uint8Array(await subtle().sign(\"HMAC\", key, encoder.encode(`${prefix}.${body}`)))\n      return { token: `${prefix}.${body}.${Encoding.encodeBase64Url(signature)}`, claims }\n    })\n  })\n\nconst refused = (message: string) => Effect.fail(new Unauthorized({ message }))\n\n/**\n * Verifies a token's signature and expiry under the key and returns its\n * claims. Every malformation, a wrong key, and an expired token all fail with\n * the same `Unauthorized`, so the token is not a parsing oracle.\n *\n * @param now the moment to judge `exp` against, in milliseconds\n * @category verification\n * @since 1.0.0\n */\nexport const verify = (key: string, token: string, now: number): Effect.Effect<Claims, Unauthorized> =>\n  Effect.suspend(() => {\n    const parts = token.split(\".\")\n    if (key.length === 0 || parts.length !== 3 || parts[0] !== prefix || parts[1]!.length === 0) {\n      return refused(\"A valid scoped token is required\")\n    }\n    const signature = Encoding.decodeBase64Url(parts[2]!)\n    if (Result.isFailure(signature)) return refused(\"A valid scoped token is required\")\n    return Effect.promise(async () => {\n      const hmac = await hmacKey(key, \"verify\")\n      return subtle().verify(\"HMAC\", hmac, new Uint8Array(signature.success), encoder.encode(`${prefix}.${parts[1]}`))\n    }).pipe(\n      Effect.flatMap((valid) => {\n        if (!valid) return refused(\"A valid scoped token is required\")\n        const text = Encoding.decodeBase64UrlString(parts[1]!)\n        if (Result.isFailure(text)) return refused(\"A valid scoped token is required\")\n        let parsed: unknown\n        try {\n          parsed = JSON.parse(text.success)\n        } catch {\n          return refused(\"A valid scoped token is required\")\n        }\n        const claims = decodeClaims(parsed)\n        if (Result.isFailure(claims)) return refused(\"A valid scoped token is required\")\n        if (!(now < claims.success.exp)) return refused(\"The scoped token has expired\")\n        return Effect.succeed(claims.success)\n      })\n    )\n  })\n\nconst field = (value: unknown, name: string): unknown =>\n  typeof value === \"object\" && value !== null ? (value as Record<string, unknown>)[name] : undefined\n\n/** The run a payload names, wherever the control and gateway schemas put it. */\nconst namedRun = (payload: unknown): unknown =>\n  field(payload, \"runId\") ??\n    field(field(payload, \"target\"), \"runId\") ??\n    field(field(payload, \"selector\"), \"runId\") ??\n    field(field(payload, \"filters\"), \"runId\")\n\n/** The flow a payload names. */\nconst namedFlow = (payload: unknown): unknown => field(payload, \"flowId\") ?? field(field(payload, \"filters\"), \"flowId\")\n\n/**\n * Whether verified claims authorize one call.\n *\n * The procedure must be named. A token confined to a run authorizes only a\n * call that names that run, and one confined to a flow only a call that names\n * that flow: a call that names neither, such as an unfiltered `List`, is\n * refused rather than widened.\n *\n * @category verification\n * @since 1.0.0\n */\nexport const authorizes = (claims: Claims, call: Call): boolean =>\n  claims.procedures.includes(call.rpc) &&\n  (claims.runId === undefined || namedRun(call.payload) === claims.runId) &&\n  (claims.flowId === undefined || namedFlow(call.payload) === claims.flowId)\n\n/**\n * What the scoped-token authenticator needs.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface AuthenticatorOptions {\n  /** The verifying key: the gateway's configured bearer credential. */\n  readonly key: string\n  /** The principal every valid scoped token is stamped as. */\n  readonly principal: Omit<Principal, \"stampedAt\">\n  readonly now?: (() => number) | undefined\n}\n\n/**\n * Authenticates a bearer credential spelled as a scoped token: the signature\n * and expiry always, and the procedure plus run or flow confinement whenever\n * the boundary knows which call it is guarding. An edge that authenticates an\n * upgrade knows no call, so it admits the socket and leaves each frame to the\n * in-band check.\n *\n * A credential that is not a scoped token is refused here; compose with\n * `ControlRpcs.bearerAuthenticator` through `ControlRpcs.anyAuthenticator`\n * to accept both.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const authenticator = (options: AuthenticatorOptions): Authenticator => ({\n  authenticate: (headers, call) => {\n    const credential = bearerCredential(headers)\n    if (credential === undefined || !isScopedToken(credential)) return refused(\"A valid scoped token is required\")\n    const now = options.now?.() ?? Date.now()\n    return verify(options.key, credential, now).pipe(\n      Effect.flatMap((claims) =>\n        call !== undefined && !authorizes(claims, call)\n          ? refused(`The scoped token does not authorize ${call.rpc}`)\n          : Effect.succeed({ ...options.principal, stampedAt: now })\n      )\n    )\n  }\n})\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/cjs/SqlControlRuntime.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Durable `ControlRuntime` over `@smthrs/journal`'s fenced `RunStore` and a
+ * SQL database.
+ *
+ * `layerMemory` models the production seams but keeps everything in a `Map`, so
+ * nothing it decides survives the process. This adapter supplies the durable
+ * boundary the header of `ControlRuntime` describes.
+ *
+ * ## Where ownership lives
+ *
+ * The run lifecycle is not re-implemented here. `RunStore` already owns it, and
+ * it is the piece that is hard to get right: every ownership move is a single
+ * SQL compare-and-swap, so a stale writer loses the `UPDATE` rather than
+ * racing a read-then-write. This module maps the control plane's vocabulary
+ * onto it:
+ *
+ * | control status | `RunStore` status | ownership |
+ * | --- | --- | --- |
+ * | `accepted`, `running` | `running` | held by this process |
+ * | `accepted` after an executor declines | `suspended` | released |
+ * | `parked`, `waiting-approval` | `suspended` | released |
+ * | `cancelled` / `completed` / `failed` | same | released, terminal |
+ *
+ * The authoritative `RunSummary` is written into the row's `state_json` by the
+ * same fenced `UPDATE` that moves the status, so a projection can never be read
+ * out of step with the lifecycle. `RunStore` has no list operation, so
+ * `control_runs` is kept as a plain id index and each summary is read back
+ * through the store rather than duplicated.
+ *
+ * ## Fences
+ *
+ * A fence is a serialized `OwnerId`. `hostId` and `pid` identify the process;
+ * the `nonce` is regenerated on **every** claim, so a fence taken before a
+ * park is not the fence held after the resume that follows it, and the stale
+ * one is refused by the CAS. This is the `rangeID`-style monotonic fence from
+ * `reference/temporal`'s history service, narrowed to a per-run token.
+ *
+ * ## Browser safety
+ *
+ * Nothing here imports `node:*`. Identity comes from `globalThis.crypto`, and
+ * persistence is the driver-neutral SQL contract, so this module runs anywhere
+ * `@smthrs/database` has a driver. Fibers are the exception and are
+ * deliberately process-local: a fiber is a live continuation, not a row, and
+ * cancellation is interruption of the fiber that this process owns.
+ *
+ * @since 0.1.0
+ */
+import { DurableWriter } from "@smthrs/database/DurableWriter";
+import { Ownership, RunStore } from "@smthrs/run-store";
+import { Crypto, Effect, Layer } from "effect";
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+import * as ApprovalAuthority from "./ApprovalAuthority.ts";
+import { PersistenceError } from "./ControlError.ts";
+import type { MemoryFlow, Service } from "./ControlRuntime.ts";
+import { ControlRuntime } from "./ControlRuntime.ts";
+import { Principal } from "./ControlSchema.ts";
+/**
+ * A flow the durable runtime can plan.
+ *
+ * The same shape the memory runtime takes, so a composition can hand the same
+ * catalog to either.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type DurableFlow = MemoryFlow;
+/**
+ * Durable runtime configuration.
+ *
+ * `owner` is the process identity every claim is stamped with. When omitted,
+ * one valid synthetic identity is minted for this runtime only, so separately
+ * constructed runtimes cannot cross each other's fences. Hosts that can
+ * report their real process identity should still supply it so liveness probes
+ * can reason about the operating-system process.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Options {
+    readonly flows?: ReadonlyArray<DurableFlow> | undefined;
+    /**
+     * Reads the current flow catalog for each plan and listing. When supplied,
+     * this replaces `flows`, including the default system catalog. A host with
+     * a refreshable registry should return one complete snapshot per call.
+     * Existing plans retain the definition they were approved against.
+     */
+    readonly loadFlows?: (() => Effect.Effect<ReadonlyArray<DurableFlow>, PersistenceError>) | undefined;
+    /**
+     * Reads each flow's code as it is on disk now, for the drift check that runs
+     * before a run is re-driven and for the code an allowed drift adopts. A host
+     * whose `loadFlows` answers from a cached snapshot supplies this, so a flow
+     * edited or deleted after the run parked is refused before the claim rather
+     * than found by the executor after it. Defaults to `loadFlows`.
+     */
+    readonly currentFlows?: (() => Effect.Effect<ReadonlyArray<DurableFlow>, PersistenceError>) | undefined;
+    /** Verifies a durable pinned source closure before consenting to resume it. */
+    readonly pinnedFlow?: ((flowId: string, digest: string) => Effect.Effect<boolean | undefined, PersistenceError>) | undefined;
+    /**
+     * Makes one flow's code on disk now the code this host executes, for a
+     * resume the operator allowed to drift, and answers the identity the host
+     * can now run, or `undefined` when it can run none. A host whose executor
+     * serves a loaded snapshot supplies this: recording a digest its executor
+     * does not hold accepted the resume and then failed the run (#2740).
+     * Defaults to the flow's entry in `currentFlows`.
+     */
+    readonly adoptFlow?: ((flowId: string, runId: string) => Effect.Effect<DurableFlow | undefined, PersistenceError>) | undefined;
+    readonly owner?: Ownership.OwnerId | undefined;
+    /**
+     * Whether the process a running run's owner names is still working. With
+     * it, `resume` takes over a running run whose owner is gone (a host killed
+     * mid-run) once that owner's lease has expired, instead of answering
+     * `ClaimLost`; the run store verifies the expired lease. Without it a
+     * running run belongs to its recorded owner for good.
+     */
+    readonly isAlive?: Ownership.LivenessCheck | undefined;
+    readonly principal?: Omit<Principal, "stampedAt"> | undefined;
+    readonly approvalAuthority?: ApprovalAuthority.Service | undefined;
+    /** The engine version stamped on every run this runtime starts. */
+    readonly engineVersion?: string | undefined;
+}
+/**
+ * Creates every control-plane table.
+ *
+ * `RunStore`'s own migrations are the journal package's business and are
+ * applied by its layer. A read-only client installs nothing.
+ *
+ * @category migrations
+ * @since 0.1.0
+ */
+export declare const migrate: Effect.Effect<void, PersistenceError, SqlClient.SqlClient>;
+/**
+ * Constructs a durable runtime over the ambient database and run store.
+ *
+ * Not exported under this name: `make` below is the single public constructor.
+ * Exporting both put two names for one function on the package's public
+ * surface, and only one of them was documented.
+ */
+declare const makeRuntime: (options?: Options) => Effect.Effect<Service, PersistenceError, Crypto.Crypto | DurableWriter | SqlClient.SqlClient | RunStore.RunStore>;
+/**
+ * Provides a durable runtime over the ambient database and run store.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layer: (options?: Options) => Layer.Layer<ControlRuntime, PersistenceError, Crypto.Crypto | DurableWriter | SqlClient.SqlClient | RunStore.RunStore>;
+/**
+ * Provides a durable runtime and the run store it needs over the ambient
+ * database.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerWithStore: (options?: Options) => Layer.Layer<ControlRuntime, PersistenceError, Crypto.Crypto | DurableWriter | SqlClient.SqlClient>;
+/**
+ * Constructs a durable runtime over the ambient database and run store.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export { makeRuntime as make };
+//# sourceMappingURL=SqlControlRuntime.d.ts.map

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

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