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

package/src/internal/planning.ts

@@ -0,0 +1,262 @@
+/**
+ * Plan construction shared by every `ControlRuntime` implementation.
+ *
+ * The plan digest is what an approval is bound to, so the memory runtime and
+ * the durable runtime must compute it the same way or an approval taken on one
+ * would not validate on the other. Keeping the construction here is what makes
+ * that a compile-time fact rather than a convention.
+ *
+ * @since 0.1.0
+ */
+
+import { canonicalize } from "@smthrs/canonical"
+import { Sha256 } from "@smthrs/crypto"
+import * as Sha256Digest from "@smthrs/crypto/Sha256"
+import type * as PersistedPlan from "@smthrs/plan/Plan"
+import { Effect, Schema } from "effect"
+import type { ApprovalTarget, PlanInput } from "../Control.ts"
+import { CodeDrift } from "../ControlError.ts"
+import type {
+  Envelope,
+  FlowId,
+  IdempotencyKey,
+  PlanCard,
+  PlanGraph,
+  PlanNode,
+  Principal,
+  Receipt,
+  RunId,
+  RunSummary
+} from "../ControlSchema.ts"
+
+/**
+ * The drift between the code a run recorded and the code that would resume
+ * it, or `undefined` when there is none. A run that recorded no digest (a flow
+ * without one, or a row older than the field) is not checked for flow drift,
+ * and one that recorded no engine version is not checked for engine drift.
+ *
+ * @since 1.0.0
+ * @private
+ */
+export const codeDriftOf = (
+  run: RunSummary,
+  flow: { readonly executionDigest?: string | undefined } | undefined,
+  engineVersion: string | undefined
+): CodeDrift | undefined => {
+  const flowDrift = run.executionDigest !== undefined && flow?.executionDigest !== run.executionDigest
+  const engineDrift = run.engineVersion !== undefined && engineVersion !== undefined &&
+    engineVersion !== run.engineVersion
+  if (!flowDrift && !engineDrift) return undefined
+  return new CodeDrift({
+    runId: run.runId,
+    flowId: run.flowId,
+    ...(flowDrift ? { recorded: run.executionDigest } : {}),
+    ...(flowDrift && flow?.executionDigest !== undefined ? { current: flow.executionDigest } : {}),
+    ...(engineDrift ? { recordedEngine: run.engineVersion, currentEngine: engineVersion } : {})
+  })
+}
+
+/**
+ * The code identity a resume the operator allowed to drift records on the run,
+ * so later checks compare against the code it now runs.
+ *
+ * @since 1.0.0
+ * @private
+ */
+export const adoptedCode = (
+  run: RunSummary,
+  flow: { readonly executionDigest?: string | undefined } | undefined,
+  engineVersion: string | undefined
+): Pick<RunSummary, "executionDigest" | "engineVersion"> => ({
+  executionDigest: flow?.executionDigest,
+  engineVersion: engineVersion ?? run.engineVersion
+})
+
+/**
+ * The envelope a flow with no declared capabilities carries.
+ *
+ * @since 0.1.0
+ * @private
+ */
+export const emptyEnvelope: Envelope = {
+  capabilities: [],
+  flows: [],
+  budget: {}
+}
+
+/**
+ * Canonical bytes for a value.
+ * Throws on a non-serializable value; every caller either wraps it in
+ * `Effect.try` or has already validated the value.
+ *
+ * @since 0.1.0
+ * @private
+ */
+export const canonical = (value: unknown): string => canonicalize(value)
+
+/**
+ * The durable key a caller's idempotency key is stored under.
+ *
+ * Namespaced by the effective actor: the submitted principal, or the runtime's
+ * configured fallback when the caller named none. The principal's clock is
+ * omitted, so an equal retry lands on the same key.
+ *
+ * @since 0.1.0
+ * @private
+ */
+export const mutationKey = (
+  operation: string,
+  key: IdempotencyKey,
+  principal: Pick<Principal, "id" | "kind">
+): string =>
+  `${operation}:actor:${Sha256Digest.digestSync(canonical({ id: principal.id, kind: principal.kind }))}:${key}`
+
+/**
+ * The content digest of a value's canonical bytes.
+ *
+ * @since 0.1.0
+ * @private
+ */
+export const digest = (value: unknown) => Schema.decodeUnknownEffect(Sha256)(canonical(value)).pipe(Effect.orDie)
+
+/**
+ * Envelope equality by canonical bytes, not by reference or key order.
+ *
+ * @since 0.1.0
+ * @private
+ */
+export const sameEnvelope = (left: Envelope, right: Envelope): boolean => canonical(left) === canonical(right)
+
+/**
+ * A flow's envelope with a planner's budget fields laid over its declared ones.
+ *
+ * @since 1.0.0-rc.1
+ * @private
+ */
+export const budgeted = (envelope: Envelope, budget: Envelope["budget"] | undefined): Envelope =>
+  budget === undefined ? envelope : { ...envelope, budget: { ...envelope.budget, ...budget } }
+
+/**
+ * What one plan request asks for, for idempotency: a key replayed with another
+ * budget is another plan.
+ *
+ * @since 1.0.0-rc.1
+ * @private
+ */
+export const planFingerprint = (input: PlanInput): string =>
+  canonical({
+    flowId: input.flowId,
+    input: input.input,
+    ...(input.budget === undefined ? {} : { budget: input.budget })
+  })
+
+/**
+ * An accepted receipt, carrying a run id when one exists.
+ *
+ * @since 0.1.0
+ * @private
+ */
+export const accepted = (receiptId: string, runId?: RunId): Receipt => {
+  /* v8 ignore next 3 -- both runtimes call this from `launch`, which has the run it just started; the parameter stays optional for the receipt's shape rather than for a caller */
+  return runId === undefined
+    ? { _tag: "Accepted", receiptId }
+    : { _tag: "Accepted", receiptId, runId }
+}
+
+/**
+ * The receipt a replayed mutation returns, derived from the recorded one.
+ *
+ * @since 0.1.0
+ * @private
+ */
+export const alreadyApplied = (key: IdempotencyKey, receipt: Receipt): Receipt => {
+  const receiptId = receipt._tag === "Accepted" || receipt._tag === "AlreadyApplied" ? receipt.receiptId : key
+  const runId = receipt._tag === "Accepted" || receipt._tag === "AlreadyApplied" || receipt._tag === "Terminal"
+    ? receipt.runId
+    : undefined
+  const input = receipt._tag === "Accepted" || receipt._tag === "AlreadyApplied"
+    ? {
+      ...(receipt.inputConsumed === undefined ? {} : { inputConsumed: receipt.inputConsumed }),
+      ...(receipt.inputBody === undefined ? {} : { inputBody: receipt.inputBody })
+    }
+    : {}
+  return runId === undefined
+    ? { _tag: "AlreadyApplied", receiptId, ...input }
+    : { _tag: "AlreadyApplied", receiptId, runId, ...input }
+}
+
+/**
+ * The plan inputs a card is derived from.
+ *
+ * @since 0.1.0
+ * @private
+ */
+export interface PlanSource {
+  readonly planId: string
+  readonly flowId: FlowId
+  readonly decodedInput: unknown
+  readonly envelope: Envelope
+  readonly deployClass: boolean
+  readonly executionDigest?: string | undefined
+  /** The persisted plan value and cache verdicts produced by the host. */
+  readonly handoff?: {
+    readonly plan: PersistedPlan.Plan
+    readonly statuses?: Readonly<Record<string, PlanNode["status"]>> | undefined
+    readonly graph?: PlanGraph | undefined
+  } | undefined
+  readonly idempotencyKey?: IdempotencyKey | undefined
+}
+
+/**
+ * Builds the immutable plan card and the approval target bound to its digest.
+ *
+ * @since 0.1.0
+ * @private
+ */
+export const planCard = (source: PlanSource) =>
+  Effect.gen(function*() {
+    const plan = source.handoff?.plan
+    const nodes: ReadonlyArray<PlanNode> = plan === undefined
+      ? []
+      : plan.nodes.map((node) => ({
+        ...node,
+        status: source.handoff?.statuses?.[node.id] ?? "run"
+      }))
+    const planDigest = yield* digest({
+      flowId: source.flowId,
+      input: source.decodedInput,
+      envelope: source.envelope,
+      deployClass: source.deployClass,
+      ...(source.executionDigest === undefined ? {} : { executionDigest: source.executionDigest }),
+      // The persisted plan digest covers keys, edges, effects, conflicts,
+      // priorities, and generations. Hashing only node keys loses executable
+      // graph changes whose content keys legitimately stay stable.
+      persistedPlan: plan?.digest ?? null
+    })
+    const target: ApprovalTarget = {
+      _tag: "Plan",
+      planId: source.planId,
+      digest: planDigest,
+      envelope: source.envelope
+    }
+    return {
+      planId: source.planId,
+      flowId: source.flowId,
+      digest: planDigest,
+      inputSummary: canonical(source.decodedInput),
+      envelope: source.envelope,
+      deployClass: source.deployClass,
+      ...(source.executionDigest === undefined ? {} : { executionDigest: source.executionDigest }),
+      ...(plan === undefined ? {} : { plan }),
+      nodes,
+      // Outside `digest` above on purpose: the edges are how a reader draws
+      // the plan, not what the plan will do, so gaining them must not
+      // invalidate an approval taken before the host reported them.
+      ...(source.handoff?.graph === undefined ? {} : { graph: source.handoff.graph }),
+      approval: {
+        target,
+        scope: "run" as const,
+        idempotencyKey: source.idempotencyKey ?? `approve:${source.planId}`
+      }
+    } satisfies PlanCard
+  })

package/src/internal/sqlSchemaErrors.ts

@@ -0,0 +1,37 @@
+/**
+ * Exact optional-schema failure classification across SQL driver wrappers.
+ * @since 1.0.0
+ */
+
+/**
+ * Driver messages stay separate so wrapper context cannot identify a different failure.
+ * The depth bound terminates cyclic driver causes.
+ * @since 1.0.0
+ * @private
+ */
+export const causeMessages = (value: unknown, depth = 4): ReadonlyArray<string> => {
+  if (typeof value === "string") return [value]
+  if (depth === 0 || typeof value !== "object" || value === null) return []
+  const fields = value as { readonly message?: unknown; readonly cause?: unknown; readonly reason?: unknown }
+  return [
+    ...(typeof fields.message === "string" ? [fields.message] : []),
+    ...causeMessages(fields.reason, depth - 1),
+    ...causeMessages(fields.cause, depth - 1)
+  ]
+}
+
+/**
+ * Only the relation named by a driver's missing-table diagnostic may be absent.
+ * @since 1.0.0
+ * @private
+ */
+export const missingTable = (table: string) => (cause: unknown): boolean =>
+  causeMessages(cause).some((message) => {
+    const relation = /^no such table: (\S+)$/.exec(message)?.[1]
+      ?? /^relation "([^"]+)" does not exist$/.exec(message)?.[1]
+    // These queries name unqualified relations. A qualified name can refer
+    // to a different schema's dependency, so do not discard its qualifier.
+    if (relation !== undefined) return relation === table
+    // MySQL always names the database in its table diagnostic.
+    return /^Table '[^.']+\.([^']+)' doesn't exist$/.exec(message)?.[1] === table
+  })

package/src/migrations/0001_control_tables.ts

@@ -0,0 +1,99 @@
+/**
+ * Initial durable control-plane schema.
+ *
+ * @since 0.1.0
+ */
+
+import * as Dialect from "@smthrs/database/Dialect"
+import * as Effect from "effect/Effect"
+import * as SqlClient from "effect/unstable/sql/SqlClient"
+
+const statements = (sql: SqlClient.SqlClient) =>
+  [
+    sql`CREATE TABLE IF NOT EXISTS control_plans (
+    ${Dialect.rowId(sql)}
+    plan_id TEXT PRIMARY KEY,
+    card_json TEXT NOT NULL,
+    decoded_input_json TEXT NOT NULL,
+    decision TEXT NOT NULL
+  )`,
+    sql`CREATE TABLE IF NOT EXISTS control_plan_keys (
+    idempotency_key TEXT PRIMARY KEY,
+    fingerprint TEXT NOT NULL,
+    plan_id TEXT NOT NULL
+  )`,
+    sql`CREATE TABLE IF NOT EXISTS control_tokens (
+    target_tag TEXT NOT NULL,
+    run_id TEXT NOT NULL,
+    target_id TEXT NOT NULL,
+    token_id TEXT NOT NULL,
+    target_json TEXT NOT NULL,
+    resolved ${Dialect.integer(sql)} NOT NULL,
+    decision_principal_json TEXT,
+    PRIMARY KEY (target_tag, run_id, target_id),
+    CHECK (target_tag IN ('Plan', 'Node')),
+    CHECK ((target_tag = 'Plan' AND run_id = '') OR (target_tag = 'Node' AND length(run_id) > 0)),
+    CHECK (length(target_id) > 0 AND token_id = target_id)
+  )`,
+    sql`CREATE TABLE IF NOT EXISTS control_grants (
+    target_tag TEXT NOT NULL,
+    run_id TEXT NOT NULL,
+    target_id TEXT NOT NULL,
+    token_id TEXT NOT NULL,
+    envelope_json TEXT NOT NULL,
+    scope TEXT NOT NULL,
+    installed_at_ms ${Dialect.integer(sql)} NOT NULL,
+    PRIMARY KEY (target_tag, run_id, target_id),
+    CHECK (target_tag IN ('Plan', 'Node')),
+    CHECK ((target_tag = 'Plan' AND run_id = '') OR (target_tag = 'Node' AND length(run_id) > 0)),
+    CHECK (length(target_id) > 0 AND token_id = target_id)
+  )`,
+    sql`CREATE TABLE IF NOT EXISTS control_mutations (
+    mutation_key TEXT PRIMARY KEY,
+    fingerprint TEXT NOT NULL,
+    receipt_json TEXT NOT NULL
+  )`,
+    sql`CREATE TABLE IF NOT EXISTS control_runs (
+    run_id TEXT PRIMARY KEY,
+    created_seq ${Dialect.integer(sql)} NOT NULL
+  )`,
+    sql`CREATE TABLE IF NOT EXISTS control_run_resumes (
+    run_id TEXT PRIMARY KEY,
+    requested_seq ${Dialect.integer(sql)} NOT NULL,
+    requested_at_ms ${Dialect.integer(sql)} NOT NULL
+  )`,
+    sql`CREATE TABLE IF NOT EXISTS control_run_messages (
+    seq ${Dialect.identity(sql)},
+    run_id TEXT NOT NULL,
+    kind TEXT NOT NULL,
+    payload_json TEXT NOT NULL
+  )`,
+    sql`CREATE TABLE IF NOT EXISTS control_sequences (
+    name TEXT PRIMARY KEY,
+    value ${Dialect.integer(sql)} NOT NULL
+  )`,
+    sql`CREATE TABLE IF NOT EXISTS control_credentials (
+    id TEXT PRIMARY KEY,
+    name TEXT NOT NULL,
+    ciphertext TEXT NOT NULL,
+    nonce TEXT NOT NULL,
+    version ${Dialect.integer(sql)} NOT NULL,
+    updated_at_ms ${Dialect.integer(sql)} NOT NULL
+  )`
+  ] as const
+
+/**
+ * Creates every table owned by `@smthrs/control`.
+ *
+ * `IF NOT EXISTS` lets the recorded migration and each standalone adapter's
+ * bootstrap share this exact schema without competing over table creation.
+ *
+ * @category migrations
+ * @since 0.1.0
+ */
+export const initial: Effect.Effect<void, unknown, SqlClient.SqlClient> = Effect.gen(function*() {
+  const sql = yield* SqlClient.SqlClient
+  for (const statement of statements(sql)) {
+    yield* statement
+  }
+})

package/src/migrations/0002_run_keys.ts

@@ -0,0 +1,23 @@
+/**
+ * Durable run idempotency claims, including upgrades of existing databases.
+ *
+ * @since 1.0.0
+ */
+
+import * as Effect from "effect/Effect"
+import * as SqlClient from "effect/unstable/sql/SqlClient"
+
+/**
+ * Adds the run-key claim table without changing existing control data.
+ *
+ * @category migrations
+ * @since 1.0.0
+ */
+export const runKeys = Effect.gen(function*() {
+  const sql = yield* SqlClient.SqlClient
+  yield* sql`CREATE TABLE IF NOT EXISTS control_run_keys (
+    idempotency_key TEXT PRIMARY KEY,
+    fingerprint TEXT NOT NULL,
+    claimant TEXT NOT NULL
+  )`
+})

package/src/migrations/0003_signal_commands.ts

@@ -0,0 +1,27 @@
+/**
+ * Durable signal admission and immutable wait bindings.
+ * @since 1.0.0
+ */
+
+import * as Dialect from "@smthrs/database/Dialect"
+import * as Effect from "effect/Effect"
+import * as SqlClient from "effect/unstable/sql/SqlClient"
+
+/**
+ * Adds the signal inbox without replaying legacy messages that lack delivery identity.
+ * @category migrations
+ * @since 1.0.0
+ */
+export const signalCommands = Effect.gen(function*() {
+  const sql = yield* SqlClient.SqlClient
+  yield* sql`CREATE TABLE IF NOT EXISTS control_signal_commands (
+    seq ${Dialect.identity(sql)},
+    command_id TEXT NOT NULL UNIQUE,
+    run_id TEXT NOT NULL,
+    payload_json TEXT NOT NULL,
+    wait_token TEXT,
+    state TEXT NOT NULL DEFAULT 'pending' CHECK (state IN ('pending', 'delivered', 'rejected', 'terminal'))
+  )`
+  yield* sql`CREATE UNIQUE INDEX IF NOT EXISTS control_signal_commands_wait ON control_signal_commands(wait_token) WHERE wait_token IS NOT NULL`
+  yield* sql`CREATE INDEX IF NOT EXISTS control_signal_commands_pending ON control_signal_commands(state, seq)`
+})

package/src/migrations/0004_approval_decisions.ts

@@ -0,0 +1,25 @@
+/**
+ * Preserve the actual decision without guessing erased legacy answers.
+ * @since 1.0.0
+ */
+
+import * as Dialect from "@smthrs/database/Dialect"
+import * as Effect from "effect/Effect"
+import * as SqlClient from "effect/unstable/sql/SqlClient"
+
+/**
+ * Idempotent for both recorded migrations and standalone runtime bootstrap.
+ * @category migrations
+ * @since 1.0.0
+ */
+export const approvalDecisions = Effect.gen(function*() {
+  const sql = yield* SqlClient.SqlClient
+  yield* sql.withTransaction(Effect.gen(function*() {
+    const columns = yield* Dialect.columns(sql, "control_tokens")
+    if (columns.some((column) => column.name === "decision_json")) return
+    // NULL is intentional: old terminal tokens erased their answer. Their
+    // decoder refuses recovery instead of inferring approval from a grant.
+    // An undecided token still has its unambiguous resolved=0 representation.
+    yield* sql`ALTER TABLE control_tokens ADD COLUMN decision_json TEXT`
+  }))
+})

package/src/migrations/0005_signal_principals.ts

@@ -0,0 +1,27 @@
+/**
+ * Record who admitted each signal command.
+ * @since 1.0.0
+ */
+
+import * as Dialect from "@smthrs/database/Dialect"
+import * as Effect from "effect/Effect"
+import * as SqlClient from "effect/unstable/sql/SqlClient"
+
+/**
+ * Adds the admitting principal to the signal inbox.
+ *
+ * NULL is intentional for existing rows: a command admitted before this column
+ * has no recorded identity, so it cannot answer a human wait, which requires
+ * `ApprovalAuthority` to authorize the admitting principal.
+ *
+ * @category migrations
+ * @since 1.0.0
+ */
+export const signalPrincipals = Effect.gen(function*() {
+  const sql = yield* SqlClient.SqlClient
+  yield* sql.withTransaction(Effect.gen(function*() {
+    const columns = yield* Dialect.columns(sql, "control_signal_commands")
+    if (columns.some((column) => column.name === "principal_json")) return
+    yield* sql`ALTER TABLE control_signal_commands ADD COLUMN principal_json TEXT`
+  }))
+})

package/src/migrations/0006_run_principals.ts

@@ -0,0 +1,31 @@
+/**
+ * Record who launched each run.
+ * @since 1.0.0
+ */
+
+import * as Dialect from "@smthrs/database/Dialect"
+import * as Effect from "effect/Effect"
+import * as SqlClient from "effect/unstable/sql/SqlClient"
+
+/**
+ * Adds the launching principal to the launch index.
+ *
+ * NULL is intentional for existing rows: a run launched before these columns
+ * has no recorded launcher, so only a reader that sees every run lists or
+ * watches it.
+ *
+ * @category migrations
+ * @since 1.0.0
+ */
+export const runPrincipals = Effect.gen(function*() {
+  const sql = yield* SqlClient.SqlClient
+  yield* sql.withTransaction(Effect.gen(function*() {
+    const columns = yield* Dialect.columns(sql, "control_runs")
+    if (!columns.some((column) => column.name === "principal_id")) {
+      yield* sql`ALTER TABLE control_runs ADD COLUMN principal_id TEXT`
+    }
+    if (!columns.some((column) => column.name === "principal_kind")) {
+      yield* sql`ALTER TABLE control_runs ADD COLUMN principal_kind TEXT`
+    }
+  }))
+})

package/src/migrations/0007_resume_consent.ts

@@ -0,0 +1,28 @@
+/**
+ * Record the operator consent a resume delegation carries.
+ * @since 1.0.0
+ */
+
+import * as Dialect from "@smthrs/database/Dialect"
+import * as Effect from "effect/Effect"
+import * as SqlClient from "effect/unstable/sql/SqlClient"
+
+/**
+ * Adds the journal sequence of an operator's explicit resume to the pending
+ * resume delegations.
+ *
+ * NULL is intentional for existing rows: a delegation recorded before this
+ * column is an approval or a wake, which is background intent.
+ *
+ * @category migrations
+ * @since 1.0.0
+ */
+export const resumeConsent = Effect.gen(function*() {
+  const sql = yield* SqlClient.SqlClient
+  yield* sql.withTransaction(Effect.gen(function*() {
+    const columns = yield* Dialect.columns(sql, "control_run_resumes")
+    if (!columns.some((column) => column.name === "consent_seq")) {
+      yield* sql`ALTER TABLE control_run_resumes ADD COLUMN consent_seq ${Dialect.integer(sql)}`
+    }
+  }))
+})

package/src/test/TestControl.ts

@@ -0,0 +1,47 @@
+/**
+ * Deterministic in-memory Control stack for package and consumer tests.
+ *
+ * @since 0.1.0
+ */
+
+import * as TestJournal from "@smthrs/journal/test/TestJournal"
+import { NotificationQueue } from "@smthrs/notifications"
+import { Registry } from "@smthrs/registry"
+import { Crypto, Effect, Layer } from "effect"
+import * as ControlExecutor from "../ControlExecutor.ts"
+import * as ControlLive from "../ControlLive.ts"
+import * as ControlRuntime from "../ControlRuntime.ts"
+
+const browserCrypto = Layer.succeed(
+  Crypto.Crypto,
+  Crypto.make({
+    /* v8 ignore next -- `Crypto.make` requires a random-byte primitive, and the deterministic runtime this bundle composes derives every identifier from a counter, so only `digest` is ever called here */
+    randomBytes: (size) => globalThis.crypto.getRandomValues(new Uint8Array(size)),
+    digest: (algorithm, data) =>
+      Effect.promise(() => globalThis.crypto.subtle.digest(algorithm, data.slice().buffer)).pipe(
+        Effect.map((buffer) => new Uint8Array(buffer))
+      )
+  })
+)
+
+/**
+ * Provides Control, ControlRuntime, the in-memory journal bundle, and an empty
+ * registry. Runtime flow metadata falls back to the reserved system catalog.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer = (
+  options?: ControlRuntime.MemoryOptions,
+  executor: ControlExecutor.Service = ControlExecutor.makeNoop()
+) => {
+  const journal = TestJournal.layer()
+  const dependencies = Layer.mergeAll(
+    ControlRuntime.layerMemory(options).pipe(Layer.provide(browserCrypto)),
+    journal,
+    NotificationQueue.layer.pipe(Layer.provide(journal)),
+    ControlExecutor.layer(executor),
+    Registry.layerNoop()
+  )
+  return Layer.provideMerge(ControlLive.layer, dependencies)
+}