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

package/CHANGELOG.md

@@ -0,0 +1,194 @@
+# @smthrs/control
+
+## [Unreleased]
+
+### Added
+
+- `ControlExecutor.Service.requestComplete` optionally closes a retained run
+  after its last native module completes, through the host executor.
+
+- `PlanInput.budget` can override budget fields, including the optional
+  `onExceeded` policy. Resume accepts `allowCodeDrift`; run and approval
+  operations can also fail with `CodeDrift`. Custom runtime implementations
+  must provide `codeDrift`; SQL runtime options accept `currentFlows`
+  for checking the current catalog (#1807, #1843).
+
+- A run records its flow's `executionDigest` and the host's `engineVersion`
+  (`SqlControlRuntime` and memory option `engineVersion`) on `RunSummary`.
+  `Control.resume` refuses a run whose flow's digest changed with `CodeDrift`
+  before claiming it, unless `allowCodeDrift` is set.
+
+- `Health.makeRegistry` takes an optional third argument, `evaluator`: the
+  judge the registered `jev.session` checker asks.
+
+- `SqlControlRuntime` takes `isAlive`: with it, `resume` takes over a running
+  run whose owner is gone (a host killed mid-run) once the dead owner's lease
+  has expired, instead of answering `ClaimLost`; the run store verifies the
+  expired lease.
+
+- `ControlExecutor.makeObserving` wraps an executor for a host that observes
+  runs and drives none: `readExecution`, `requestCancel`, `deliverSignal` and
+  `settleCancelledPark` pass through, and `launch` and `resumeRun` die. A host
+  with no completion judge composes one, so it can list and diagnose runs
+  without being able to admit one it could never judge.
+
+### Changed
+
+- **Breaking:** `JevSessionChecker` asks the host's `Evaluator` instead of
+  calling the Vercel AI Gateway itself. `jevEvaluationUrl`, `jevModelId` and
+  the `env`, `fetch` and `url` options are removed; `evaluator` replaces them.
+  Without an evaluator the probe fails with reason `unconfigured`.
+  `jevRequestTimeoutMs` is now 45000 (was 1500) and `jevProbeTimeoutMs` 50000
+  (was 2500).
+- A journal read that fails during `watch` answers `PersistenceError` with
+  operation `watch` and the journal's error as its `cause`. It used to answer
+  `Unavailable`, which reads as a missing feature. A closed journal still
+  answers `Unavailable`.
+- `WebCryptoCipher.open` answers `PersistenceError` with operation
+  `credential.open` when a record does not open, naming a malformed nonce or a
+  failed authentication (a different key, changed metadata, or tampered
+  ciphertext), and logs the reason. `WebCryptoCipher.make` refuses a key that
+  is not 32 base64-encoded bytes with `InvalidInput`. Both used to answer
+  `Unavailable`, which is now kept for a host without Web Crypto.
+- Breaking: `ApprovalAuthority.local` no longer delegates the in-memory test
+  identity `memory`/`test`. A caller naming kind `test` held full approval
+  authority under the production default. `ControlRuntime.layerMemory`
+  delegates that identity in its own default policy.
+- Removed the 195 internal `@slop` review markers from `src` and the published
+  declarations. `test/ReviewMarkers.test.ts` keeps them out.
+- Breaking: approval decisions require an independent `ApprovalAuthority` host
+  policy, checked before reads/replay and again at resolution. Custom agent,
+  gateway, and operator identities need explicit delegation; attribution and
+  authentication alone do not authorize approval. RPC approval errors include
+  `Unauthorized`. Policy storage failure leaves the gate closed.
+
+- Breaking: approval tokens now expose `Pending`, `Approved`, or `Denied`
+  instead of `resolved`. Terminal decisions retain their principal and time;
+  approvals also retain scope. `requireApproved` fails closed on pending or
+  denied requests. The documented gate no longer proceeds after denial or
+  mistakes a storage error for approval.
+- Migration 6004 stores the decision atomically with resolution. Legacy pending
+  requests remain pending; old terminal requests that erased their decision are
+  refused on recovery. Preserve old evidence and start a new run/request. This
+  does not migrate old executable identities or cached gate results.
+
+### Fixed
+
+- Durable sequence allocation rejects missing, nonpositive, or unsafe numeric
+  readbacks inside its transaction, so storage faults cannot create zero or
+  rounded plan, run, or resume identities.
+- Optional SQL table reads fall back only when the driver names that exact
+  missing relation. A broken view referencing a similarly named missing table
+  now reports a persistence failure instead of silently dropping run ancestry.
+
+- Fixed the CommonJS build of the migration set. `migrations/0001_control_tables`
+  now exports `initial` as a named binding and every importer reads it by name,
+  because esbuild's Node interop for a default import of a sibling module
+  resolved to the whole exports object instead of the Effect, so
+  `require("@smthrs/control")` failed at load with
+  `initial.pipe is not a function`.
+
+## [1.0.0-rc.0] - 2026-09-01
+
+### Added
+
+- Added `ControlExecutor`, the port that hands launches, cancellations,
+  signals, and resumes to a real run executor, so `ControlLive` drives an
+  engine instead of describing one.
+- Added `SqlControlRuntime`, the durable `ControlRuntime` over `@smthrs/journal`
+  and the fenced `@smthrs/run-store`, and the credential subsystem behind it
+  (`Credential`, `CredentialCipher`, `CredentialStore`, `SqlCredentialStore`,
+  `WebCryptoCipher`).
+- Added durable resume delegation: a decided run's restart is recorded for the
+  host that owns it and taken up on that host's next poll, rather than claimed
+  by a control plane with no executor (triage B-15).
+- Added cancellation attribution: `control.run.cancel-requested` carries the
+  authenticated principal and the operator's stated reason, and
+  `Cancellation.attribute` folds a run's own evidence and its ancestors' into
+  `RunSummary.cancellation`.
+- Added `NoMatchingWait`, so a signal naming a wait point no run has open is
+  refused where it arrives instead of being recorded as delivered.
+- Added `Monitor`, which classifies run health from durable evidence and
+  applies only the remedies `autoHeal` names.
+- Added `Lineage` and `Steering` projections, so a client reading the journal
+  directly reaches the same conclusions the server does.
+- Added `ControlSchema.defaultPageSize`, `ControlSchema.maxPageSize`, and
+  `ControlSchema.PageLimit`, so a listing has a documented bound the wire
+  enforces.
+- Added `ControlError.ControlErrorSchema` as the single membership list for the
+  `ControlError` union, and added `CredentialConflict` to it.
+- Added `SystemFlows.plannable` and a `plannable` marker on every catalog entry,
+  so a verb the release policy removed cannot be planned as a flow.
+- Added the namespaced `Migrations` module for every control and credential
+  table, while standalone adapters reuse the same idempotent schema source.
+
+### Changed
+
+- `Control.run({_tag: "Resume"})` is the same operation as `Control.resume`.
+  It used to be a second path that claimed without `scope: "launched"` (which
+  overwrote an engine-created run's continuation state), replayed a recorded
+  receipt for a run that had since settled, and journaled `control.run.resumed`,
+  which the agent bridge reads as an approval delegation.
+- `Control.resume` records the authenticated principal and the stated reason on
+  `control.run.resume`, and the `Resume` RPC payload carries `reason` so a local
+  and a remote resume no longer differ.
+- `Control.plan` journals `control.plan.created` only when it created a plan.
+  `ControlRuntime.plan` returns `{ card, created }` to say which happened.
+- `Control.list` reads one run through `getRun` when `filters.runId` names one,
+  instead of projecting every row in the database.
+- `Control.list` refuses `filters.principalId`. It was accepted and applied
+  nowhere, so a caller using it as a tenant restriction received every run.
+- `Control.list` refuses a page size that cannot make progress and a cursor it
+  did not issue, and applies `defaultPageSize` when the caller names none. A
+  zero-sized page used to answer with a cursor a client loops on forever.
+- `Control.steer` refuses a message whose `message.runId` disagrees with the
+  run the call names, and records the message's stated `createdAt` on
+  `control.steer.enqueued`.
+- `Control.watch` refuses `afterSequence` without `runId`. Journal sequences are
+  partition-local, so one scalar cursor applied to every partition skipped
+  unseen entries in all of them but its own.
+- Unscoped follow mode now subscribes before pinning one high-water mark per
+  partition, then joins the finite snapshot to the buffered tail at those
+  marks. The former 1,024-key cache could re-emit old overlap after eviction.
+- A cancel that learns the engine row already settled reconciles the control row
+  onto the engine's own status instead of leaving it non-terminal forever.
+- Mutations now snapshot at an inert, schema-decoded 4 MiB boundary before
+  their first wait. Durable identity is a fixed-size canonical SHA-256 digest
+  scoped to the authenticated actor's stable id and kind; accessors and
+  `toJSON` never participate, server timestamps do not split retries, and a
+  nested `principal` remains caller intent.
+- `ControlClient` classifies a transport failure by what actually happened. A
+  request it could not encode, a response it could not decode, an unusable URL
+  and an HTTP 4xx are final; a connection it could not open and an HTTP 5xx are
+  retryable. Every failure used to be reported as retryable, carrying the
+  transport's own message, so a keyless call was retried after a refusal that
+  repeating could not fix. An interrupted call stays interrupted.
+- `Monitor` records `control.monitor.healed` only for an `Accepted` or
+  `AlreadyApplied` receipt, stops on a `Terminal` one, and no longer resets its
+  stall evidence for a remedy that was refused.
+- `SqlControlRuntime.listRuns` omits a row deleted between reading the id index
+  and reading the row, instead of collapsing the whole listing to `[]`.
+- Separately constructed `SqlControlRuntime` instances now mint distinct valid
+  default owner identities, so one runtime cannot write through another's
+  process fence when a host omits an explicit owner.
+- Channel ingestion snapshots caller-owned bytes and headers before
+  verification, and adapters declare the non-secret semantic headers included
+  in durable idempotency fingerprints.
+- `SqlControlRuntime.make` is the only exported constructor; the duplicate
+  `make_` and the re-exported `FlowId` are gone.
+- Approval tokens and bulk grants use the complete plan or node identity in
+  memory and SQL. The SQL storage format now records target kind, run, target
+  id, and the authenticated principal that resolved each token.
+- Credential ciphertext authenticates a versioned canonical encoding of its
+  stored id, name, and credential version, so blob moves, renames, and version
+  rollbacks fail closed.
+- The memory control runtime and credential store copy values at their storage
+  boundaries, matching SQL serialization when callers mutate inputs or results.
+- Public control JSDoc points only to documentation paths present in this
+  repository.
+
+### Removed
+
+- Removed `Control.pause`. The frozen 1.0.0-rc.0 contract has no pause verb; an
+  operator park is written through
+  `ControlRuntime.writeStatus(runId, fence, "parked")`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Cory and the Smithers Flows contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,169 @@
-# Temporary Holding Version
+# @smthrs/control
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Release candidate scope, host requirements and compatibility review are defined in the [library support policy](https://github.com/smithersai/smithers/blob/main/RELEASE_SUPPORT.md).
+
+This package declares `effect` as an exact
+`4.0.0-rc.115` peer dependency. Keep the application on that version so
+all Smithers packages share one Effect runtime.
+
+**Documentation:** https://control.smithers.sh
+
+Control services and RPC projections for flows. It defines the
+transport-independent Control service, its runtime and execution ports, local
+and RPC implementations, verified ingress channels, credentials, and the shared
+wire schemas both halves decode.
+
+Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+
+The package
+requires Node.js 26.4.0 or later and ships as both ESM and CommonJS with
+TypeScript declarations.
+
+It imports no `node:*` module, so the same modules run in Node.js and in a
+browser that supplies a SQL driver. That is a statement about the imports, not
+a tested guarantee: verify your own bundle before you depend on it.
+
+The `smthrs` command line, [`@smthrs/cli`](https://cli.smithers.sh), is a host
+over this package: its verbs call the `Control` service defined here and
+nothing else. Install the CLI to drive runs from a shell; install this package
+to build a host of your own, such as a gateway, an MCP server, or a dashboard.
+
+## Public API
+
+The root entry point exports these namespaces; each is also importable from
+`@smthrs/control/<Module>`. Every export of every namespace, with its
+signature, is on the [API reference](https://control.smithers.sh/reference/api/).
+
+| Namespace                                           | What it is                                                                                             |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `Control`                                           | The service: `plan`, `run`, `approve`, `deny`, `steer`, `signal`, `cancel`, `resume`, `list`, `watch`. |
+| `ControlSchema`                                     | The serializable values both halves of the wire decode, and the RPC request schemas.                   |
+| `ControlError`                                      | Every stable failure, as classes and as one membership schema.                                         |
+| `ControlLive`                                       | The in-process implementation over the runtime, the journal, the notification queue, and the registry. |
+| `ControlRuntime`                                    | The persistence port, plus `layerMemory`.                                                              |
+| `SqlControlRuntime`                                 | The durable persistence adapter over a SQL database and the fenced run store.                          |
+| `ControlExecutor`                                   | The execution port: launch, cancel, signal, resume, and the park settlement a cancel needs.            |
+| `DispatchReader`                                    | The trigger read port: registered triggers and the fire ledger `list` pages; `layerNone` refuses.      |
+| `ControlRpcs`, `ControlServer`, `ControlClient`     | The RPC contract, the HTTP and WebSocket mount, and the client projected back into `Control`.          |
+| `ScopedToken`                                       | Scoped, expiring tokens minted under a bearer credential and verified with it.                         |
+| `Lineage`, `Cancellation`, `Steering`               | Pure projections: how a run came to exist, who cancelled it, and when a steer was delivered.           |
+| `Monitor`                                           | Run health as a pure classification, and the beat loop that acts on it.                                |
+| `Health`                                            | Configurable Effect checks, bounded observation policies, provenance, and the shared status rollup.    |
+| `JevSessionChecker`                                 | The registered `jev.session` checker: does this session's own output show it waiting on a person?      |
+| `Channels`, `WebhookChannel`                        | Verified ingress: an external request becomes a control mutation, once.                                |
+| `Credential`, `CredentialStore`, `CredentialCipher` | The credential boundary and its two ports.                                                             |
+| `SqlCredentialStore`, `WebCryptoCipher`             | Their durable and AES-256-GCM adapters.                                                                |
+| `Migrations`                                        | The package's namespaced migration set and the layer that runs it.                                     |
+| `SystemFlows`                                       | The reserved CLI verb to flow-id catalog.                                                              |
+
+A host that binds `jev.session` supplies its existing evaluator through
+`Health.makeRegistry(config, kind, evaluator)`. Native hosts use a subscription
+seat. Missing configuration, unavailable seats and invalid judgments produce
+`probe-error`, never a healthy result. No gateway key or separate auth path is
+used.
+
+```ts
+import { Control } from "@smthrs/control"
+import { Effect } from "effect"
+
+const program = Effect.gen(function*() {
+  const control = yield* Control.Control
+  return yield* control.list({ _tag: "runs" })
+}).pipe(Effect.provide(Control.layerNoop))
+```
+
+Use `ControlLive.layer` for in-process operation, `ControlClient.layer({ url, credential })`
+for authenticated RPC, or `ControlRuntime.layerMemory()` when assembling a
+deterministic runtime. `@smthrs/control/package.json` is also exported;
+`internal/*` and nested `*/index` subpaths are blocked.
+
+## Receipts and failures
+
+Every mutation answers a `ControlSchema.Receipt` rather than throwing on a
+second ask. `Accepted` means this call did the work, `AlreadyApplied` means an
+earlier call under the same idempotency key did, `Conflict` means the key names
+a different intent, `Parked` means the plan is waiting for an approval, and
+`Terminal` means the run had already settled and reports the status it settled
+with.
+
+For `signal`, `Accepted` means durable admission. The command and its receipt
+commit before execution observes the payload. Delivery is tracked separately
+by `ControlRuntime.signalCommand`: `pending`, `delivered`, `rejected`, or
+`terminal`. A definite incompatible wait still raises `NoMatchingWait`, and
+that rejected disposition survives retries. Admission emits
+`control.signal.admitted`; queued commands are never announced as delivered.
+
+Before its first wait, each mutation copies only bounded JSON own data fields
+and schema-decodes that detached value. Its durable fingerprint is a canonical
+SHA-256 digest, and an authenticated request namespaces its idempotency key by
+the principal's stable `kind` and `id`, not the changing server timestamp.
+Accessors, `toJSON`, sparse arrays, cycles, and non-JSON objects are refused
+with `InvalidInput` before any collaborator sees them.
+
+`Channels.ingest` copies inbound bytes and own string header fields before
+verification. A channel lists only the non-secret headers that change its
+decoded command in `fingerprintHeaders`; those names are normalized
+case-insensitively and joined with the body digest. Signature, authorization,
+cookie, token, and credential headers stay outside durable identity. Reusing a
+key with different declared semantics returns `Conflict`, while rotating an
+excluded credential header remains the same delivery.
+
+| Verb                       | Receipts                                             | Typed failures                                                                                                                                         |
+| -------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `plan`                     | returns a `PlanCard`, not a receipt                  | `FlowNotFound`, `InvalidInput`, `PersistenceError`, `Unavailable`                                                                                      |
+| `run` (`Plan`)             | `Accepted`, `AlreadyApplied`, `Conflict`, `Parked`   | `PlanNotFound`, `PlanDenied`, `PlanDigestMismatch`, `EnvelopeMismatch`, `ClaimLost`, `InvalidInput`, `LaunchFailed`, `PersistenceError`, `Unavailable` |
+| `run` (`Resume`), `resume` | `Accepted`, `AlreadyApplied`, `Conflict`, `Terminal` | `RunNotFound`, `ClaimLost`, `CodeDrift`, `InvalidInput`, `PersistenceError`, `Unavailable`                                                             |
+| `approve`, `deny`          | `Accepted`, `AlreadyApplied`, `Conflict`, `Terminal` | `PlanDigestMismatch`, `EnvelopeMismatch`, `AlreadyResolved`, `PlanNotFound`, `RunNotFound`, `InvalidInput`, `PersistenceError`, `Unavailable`          |
+| `steer`                    | `Accepted`, `AlreadyApplied`, `Conflict`, `Terminal` | `RunNotFound`, `InvalidInput`, `PersistenceError`, `Unavailable`                                                                                       |
+| `signal`                   | `Accepted`, `AlreadyApplied`, `Conflict`, `Terminal` | `RunNotFound`, `NoMatchingWait`, `InvalidInput`, `PersistenceError`, `Unavailable`                                                                     |
+| `cancel`                   | `Accepted`, `Terminal`                               | `RunNotFound`, `ClaimLost`, `InvalidInput`, `PersistenceError`, `Unavailable`                                                                          |
+| `list`, `watch`            | a page or a stream                                   | every member of `ControlError`                                                                                                                         |
+
+`ControlError.ControlErrorSchema` is the single membership list for the union,
+including `CredentialConflict`, and `ControlClient.isControlError` is derived
+from it. Each class carries a stable `code` (`plan_not_found`, `plan_denied`,
+`run_not_found`, `claim_lost`, `no_matching_wait`, `invalid_input`, and so on)
+that clients may branch on.
+
+## Deployment requirements
+
+`SqlControlRuntime` reads the engine's own columns for the projections it
+reports: `flows_runs.waiting_reason`, the `flows_run_parents` spawn edges, fork
+markers and `flows.engine.interrupted` entries in `flows_journal_events`, and
+`cancel_requested_at_ms`. It reads them through the `SqlClient` it was built
+over, so a composition that wants `RunSummary.waitingReason`, engine-created
+children and forks in `list`, or `source: "engine"` cancel attribution must give
+the control runtime and the engine ONE database.
+
+The shipped `smthrs` CLI does not: it keeps `.flows/control.db` and
+`.flows/engine.db` as two files, so one run has two rows. Cancellation still
+converges, because the request is recorded on the engine row through the
+`ControlExecutor` port and the owning driver settles from it. The projections
+above are empty there.
+
+## Limits
+
+| Bound                       | Value                                                                                                | Refusal                                                                                        |
+| --------------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `list` page size            | `ControlSchema.defaultPageSize` (100) by default, `ControlSchema.maxPageSize` (500) maximum          | `InvalidInput` with code `invalid_input`, naming `limit`                                       |
+| `list` cursor               | only a cursor a previous page returned                                                               | `InvalidInput`, naming `cursor`                                                                |
+| `list` run filters          | `runId`, `flowId`, `status`, `parentRunId`, `lineageId`                                              | `InvalidInput` for `principalId`, which rc.0 records nothing to evaluate                       |
+| `list` trigger listings     | `triggers` filters `triggerId`, `flowId`, `enabled`; `fires` filters `triggerId`, `runId`, `outcome` | `InvalidInput` naming `this host serves no trigger store` when no `DispatchReader` is provided |
+| `watch` cursor              | `afterSequence` requires `runId`                                                                     | `InvalidInput`, naming `afterSequence`                                                         |
+| `watch` follow-mode handoff | one high-water mark per partition present when the watch starts                                      | snapshot rows at or below the mark; buffered tail rows above it                                |
+| `watch` partition reads     | 8 partition snapshots at a time, plus one reserved slot for the live tail                            | queued, never refused                                                                          |
+| webhook request body        | `WebhookChannel.maximumBodyBytes` (1 MiB), lowered per mount by `handler`'s third argument           | `InvalidInput` naming both byte counts, before the read when `content-length` declares it      |
+| mutation identity           | 4 MiB, 128 levels, 100,000 values and members; idempotency keys are 1 to 1,024 characters            | `InvalidInput` before the first wait                                                           |
+
+A `steer` whose `message.runId` disagrees with the run the call names is
+refused with `InvalidInput` before anything is admitted to the queue.
+
+Approval and denial default to the exact identity `local/operator`, for both
+plan and node targets and all grant scopes. The memory adapter's own default
+also delegates its `memory/test` identity. Authentication
+and approval authority are independent: a custom operator identity has no
+authority until the host explicitly delegates it. Hosts may delegate exact
+identity tuples, including agents, with specific target kinds and approval
+scopes. Denial requires a delegated target kind and installs no grant. Callers
+without authority receive `Unauthorized` (`code: "unauthorized"`) before target
+reads or receipt replay. See [who may decide](docs/guides/approvals.md#who-may-decide).

package/dist/cjs/ApprovalAuthority.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Host-owned approval authority, separate from principal attribution and from
+ * the permissions a workflow receives after approval.
+ *
+ * @since 1.0.0
+ */
+import { Effect, Schema } from "effect";
+import { InvalidInput, type PersistenceError, Unauthorized } from "./ControlError.ts";
+import { type ApprovalTarget, GrantScope, type Principal } from "./ControlSchema.ts";
+/**
+ * An approval decision whose caller has already been authenticated by its host.
+ * @category models
+ * @since 1.0.0
+ */
+export interface Request {
+    readonly principal: Principal;
+    readonly target: ApprovalTarget;
+    readonly decision: "approved" | "denied";
+    readonly scope: GrantScope;
+}
+/**
+ * A trusted host policy. Both refusals and unavailable policy storage fail
+ * closed. Implementations must be bounded and safe inside a write transaction;
+ * they must not recursively invoke Control or perform the gated work.
+ * @category services
+ * @since 1.0.0
+ */
+export interface Service {
+    readonly authorize: (request: Request) => Effect.Effect<void, Unauthorized | PersistenceError>;
+}
+/**
+ * An explicit delegation to one authenticated identity, not everyone whose
+ * kind resembles a role. Scopes are exact, not implicitly hierarchical. A
+ * delegation may approve only its listed scopes and may deny either target
+ * kind it names (denial installs no grant).
+ * Delegation is reusable: `scopes: ["once"]` permits once-scoped grants, not
+ * one lifetime decision. Use a host policy for expiry or one-use delegation.
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Delegation: Schema.Struct<{
+    readonly principal: Schema.Struct<{
+        readonly id: Schema.String;
+        readonly kind: Schema.String;
+    }>;
+    readonly scopes: Schema.$Array<Schema.Literals<readonly ["once", "run", "remembered"]>>;
+    readonly targets: Schema.$Array<Schema.Literals<readonly ["Plan", "Node"]>>;
+}>;
+/**
+ * One explicit host-owned approval delegation.
+ * @category models
+ * @since 1.0.0
+ */
+export type Delegation = typeof Delegation.Type;
+/**
+ * Builds an immutable policy from explicit host configuration. Invalid
+ * configuration is refused without including its contents in the error.
+ * The caller's arrays and objects are not retained after acquisition.
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const make: (delegations: ReadonlyArray<Delegation>) => Effect.Effect<Service, InvalidInput>;
+/**
+ * Default trusted-local policy. Only the local operator identity is an
+ * approver. A custom actor, gateway identity, or agent needs explicit host
+ * delegation; setting Principal.kind is not itself an authorization. The
+ * in-memory test adapter's `memory`/`test` identity is delegated only by that
+ * adapter's own default policy, never here.
+ * @category policies
+ * @since 1.0.0
+ */
+export declare const local: Service;
+//# sourceMappingURL=ApprovalAuthority.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ApprovalAuthority.d.ts","sourceRoot":"","sources":["../../src/ApprovalAuthority.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AACvC,OAAO,EAAE,YAAY,EAAE,KAAK,gBAAgB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AACrF,OAAO,EAAE,KAAK,cAAc,EAAE,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAEpF;;;;GAIG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;IAC/B,QAAQ,CAAC,QAAQ,EAAE,UAAU,GAAG,QAAQ,CAAA;IACxC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,GAAG,gBAAgB,CAAC,CAAA;CAC/F;AAID;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU;;;;;;;EAIrB,CAAA;AAEF;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAC,IAAI,CAAA;AA4B/C;;;;;;GAMG;AACH,eAAO,MAAM,IAAI,GACf,aAAa,aAAa,CAAC,UAAU,CAAC,KACrC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,YAAY,CAMnC,CAAA;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,KAAK,EAAE,OAElB,CAAA"}

package/dist/cjs/ApprovalAuthority.js

@@ -0,0 +1,62 @@
+"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 ApprovalAuthority_exports = {};
+__export(ApprovalAuthority_exports, {
+  Delegation: () => Delegation,
+  local: () => local,
+  make: () => make
+});
+module.exports = __toCommonJS(ApprovalAuthority_exports);
+var import_effect = require("effect");
+var import_ControlError = require("./ControlError.js");
+var import_ControlSchema = require("./ControlSchema.js");
+const IdentityPart = import_effect.Schema.String.check(import_effect.Schema.isMinLength(1), import_effect.Schema.isMaxLength(1024));
+const Delegation = import_effect.Schema.Struct({
+  principal: import_effect.Schema.Struct({ id: IdentityPart, kind: IdentityPart }),
+  scopes: import_effect.Schema.Array(import_ControlSchema.GrantScope).check(import_effect.Schema.isMinLength(1), import_effect.Schema.isMaxLength(3)),
+  targets: import_effect.Schema.Array(import_effect.Schema.Literals(["Plan", "Node"])).check(import_effect.Schema.isMinLength(1), import_effect.Schema.isMaxLength(2))
+});
+const identity = (principal) => JSON.stringify([principal.id, principal.kind]);
+const compile = (delegations) => {
+  const permissions = /* @__PURE__ */ new Map();
+  for (const delegation of delegations) {
+    for (const target of delegation.targets) {
+      const key = JSON.stringify([identity(delegation.principal), target]);
+      const scopes = permissions.get(key) ?? /* @__PURE__ */ new Set();
+      for (const scope of delegation.scopes) scopes.add(scope);
+      permissions.set(key, scopes);
+    }
+  }
+  return Object.freeze({
+    authorize: (request) => import_effect.Effect.suspend(() => {
+      const scopes = permissions.get(JSON.stringify([identity(request.principal), request.target._tag]));
+      return scopes !== void 0 && (request.decision === "denied" || request.decision === "approved" && scopes.has(request.scope)) ? import_effect.Effect.void : import_effect.Effect.fail(new import_ControlError.Unauthorized({ message: "This caller has no authority to make this approval decision" }));
+    })
+  });
+};
+const make = (delegations) => import_effect.Schema.decodeUnknownEffect(import_effect.Schema.Array(Delegation).check(import_effect.Schema.isMaxLength(1024)))(delegations, {
+  onExcessProperty: "error"
+}).pipe(
+  import_effect.Effect.mapError(() => new import_ControlError.InvalidInput({ issue: "Invalid approval-authority delegation configuration" })),
+  import_effect.Effect.map(compile)
+);
+const local = compile([
+  { principal: { id: "local", kind: "operator" }, scopes: ["once", "run", "remembered"], targets: ["Plan", "Node"] }
+]);
+//# sourceMappingURL=ApprovalAuthority.js.map

package/dist/cjs/ApprovalAuthority.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/ApprovalAuthority.ts"],
+  "sourcesContent": ["/**\n * Host-owned approval authority, separate from principal attribution and from\n * the permissions a workflow receives after approval.\n *\n * @since 1.0.0\n */\n\nimport { Effect, Schema } from \"effect\"\nimport { InvalidInput, type PersistenceError, Unauthorized } from \"./ControlError.ts\"\nimport { type ApprovalTarget, GrantScope, type Principal } from \"./ControlSchema.ts\"\n\n/**\n * An approval decision whose caller has already been authenticated by its host.\n * @category models\n * @since 1.0.0\n */\nexport interface Request {\n  readonly principal: Principal\n  readonly target: ApprovalTarget\n  readonly decision: \"approved\" | \"denied\"\n  readonly scope: GrantScope\n}\n\n/**\n * A trusted host policy. Both refusals and unavailable policy storage fail\n * closed. Implementations must be bounded and safe inside a write transaction;\n * they must not recursively invoke Control or perform the gated work.\n * @category services\n * @since 1.0.0\n */\nexport interface Service {\n  readonly authorize: (request: Request) => Effect.Effect<void, Unauthorized | PersistenceError>\n}\n\nconst IdentityPart = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(1024))\n\n/**\n * An explicit delegation to one authenticated identity, not everyone whose\n * kind resembles a role. Scopes are exact, not implicitly hierarchical. A\n * delegation may approve only its listed scopes and may deny either target\n * kind it names (denial installs no grant).\n * Delegation is reusable: `scopes: [\"once\"]` permits once-scoped grants, not\n * one lifetime decision. Use a host policy for expiry or one-use delegation.\n * @category schemas\n * @since 1.0.0\n */\nexport const Delegation = Schema.Struct({\n  principal: Schema.Struct({ id: IdentityPart, kind: IdentityPart }),\n  scopes: Schema.Array(GrantScope).check(Schema.isMinLength(1), Schema.isMaxLength(3)),\n  targets: Schema.Array(Schema.Literals([\"Plan\", \"Node\"])).check(Schema.isMinLength(1), Schema.isMaxLength(2))\n})\n\n/**\n * One explicit host-owned approval delegation.\n * @category models\n * @since 1.0.0\n */\nexport type Delegation = typeof Delegation.Type\n\nconst identity = (principal: Pick<Principal, \"id\" | \"kind\">): string => JSON.stringify([principal.id, principal.kind])\n\nconst compile = (delegations: ReadonlyArray<Delegation>): Service => {\n  // Separate target keys preserve each delegation's target/scope pairing;\n  // unioning both dimensions independently would grant a cross product.\n  const permissions = new Map<string, Set<GrantScope>>()\n  for (const delegation of delegations) {\n    for (const target of delegation.targets) {\n      const key = JSON.stringify([identity(delegation.principal), target])\n      const scopes = permissions.get(key) ?? new Set<GrantScope>()\n      for (const scope of delegation.scopes) scopes.add(scope)\n      permissions.set(key, scopes)\n    }\n  }\n  return Object.freeze({\n    authorize: (request: Request) =>\n      Effect.suspend(() => {\n        const scopes = permissions.get(JSON.stringify([identity(request.principal), request.target._tag]))\n        return scopes !== undefined &&\n            (request.decision === \"denied\" || (request.decision === \"approved\" && scopes.has(request.scope)))\n          ? Effect.void\n          : Effect.fail(new Unauthorized({ message: \"This caller has no authority to make this approval decision\" }))\n      })\n  })\n}\n\n/**\n * Builds an immutable policy from explicit host configuration. Invalid\n * configuration is refused without including its contents in the error.\n * The caller's arrays and objects are not retained after acquisition.\n * @category constructors\n * @since 1.0.0\n */\nexport const make = (\n  delegations: ReadonlyArray<Delegation>\n): Effect.Effect<Service, InvalidInput> =>\n  Schema.decodeUnknownEffect(Schema.Array(Delegation).check(Schema.isMaxLength(1024)))(delegations, {\n    onExcessProperty: \"error\"\n  }).pipe(\n    Effect.mapError(() => new InvalidInput({ issue: \"Invalid approval-authority delegation configuration\" })),\n    Effect.map(compile)\n  )\n\n/**\n * Default trusted-local policy. Only the local operator identity is an\n * approver. A custom actor, gateway identity, or agent needs explicit host\n * delegation; setting Principal.kind is not itself an authorization. The\n * in-memory test adapter's `memory`/`test` identity is delegated only by that\n * adapter's own default policy, never here.\n * @category policies\n * @since 1.0.0\n */\nexport const local: Service = compile([\n  { principal: { id: \"local\", kind: \"operator\" }, scopes: [\"once\", \"run\", \"remembered\"], targets: [\"Plan\", \"Node\"] }\n])\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAOA,oBAA+B;AAC/B,0BAAkE;AAClE,2BAAgE;AAyBhE,MAAM,eAAe,qBAAO,OAAO,MAAM,qBAAO,YAAY,CAAC,GAAG,qBAAO,YAAY,IAAI,CAAC;AAYjF,MAAM,aAAa,qBAAO,OAAO;AAAA,EACtC,WAAW,qBAAO,OAAO,EAAE,IAAI,cAAc,MAAM,aAAa,CAAC;AAAA,EACjE,QAAQ,qBAAO,MAAM,+BAAU,EAAE,MAAM,qBAAO,YAAY,CAAC,GAAG,qBAAO,YAAY,CAAC,CAAC;AAAA,EACnF,SAAS,qBAAO,MAAM,qBAAO,SAAS,CAAC,QAAQ,MAAM,CAAC,CAAC,EAAE,MAAM,qBAAO,YAAY,CAAC,GAAG,qBAAO,YAAY,CAAC,CAAC;AAC7G,CAAC;AASD,MAAM,WAAW,CAAC,cAAsD,KAAK,UAAU,CAAC,UAAU,IAAI,UAAU,IAAI,CAAC;AAErH,MAAM,UAAU,CAAC,gBAAoD;AAGnE,QAAM,cAAc,oBAAI,IAA6B;AACrD,aAAW,cAAc,aAAa;AACpC,eAAW,UAAU,WAAW,SAAS;AACvC,YAAM,MAAM,KAAK,UAAU,CAAC,SAAS,WAAW,SAAS,GAAG,MAAM,CAAC;AACnE,YAAM,SAAS,YAAY,IAAI,GAAG,KAAK,oBAAI,IAAgB;AAC3D,iBAAW,SAAS,WAAW,OAAQ,QAAO,IAAI,KAAK;AACvD,kBAAY,IAAI,KAAK,MAAM;AAAA,IAC7B;AAAA,EACF;AACA,SAAO,OAAO,OAAO;AAAA,IACnB,WAAW,CAAC,YACV,qBAAO,QAAQ,MAAM;AACnB,YAAM,SAAS,YAAY,IAAI,KAAK,UAAU,CAAC,SAAS,QAAQ,SAAS,GAAG,QAAQ,OAAO,IAAI,CAAC,CAAC;AACjG,aAAO,WAAW,WACb,QAAQ,aAAa,YAAa,QAAQ,aAAa,cAAc,OAAO,IAAI,QAAQ,KAAK,KAC9F,qBAAO,OACP,qBAAO,KAAK,IAAI,iCAAa,EAAE,SAAS,8DAA8D,CAAC,CAAC;AAAA,IAC9G,CAAC;AAAA,EACL,CAAC;AACH;AASO,MAAM,OAAO,CAClB,gBAEA,qBAAO,oBAAoB,qBAAO,MAAM,UAAU,EAAE,MAAM,qBAAO,YAAY,IAAI,CAAC,CAAC,EAAE,aAAa;AAAA,EAChG,kBAAkB;AACpB,CAAC,EAAE;AAAA,EACD,qBAAO,SAAS,MAAM,IAAI,iCAAa,EAAE,OAAO,sDAAsD,CAAC,CAAC;AAAA,EACxG,qBAAO,IAAI,OAAO;AACpB;AAWK,MAAM,QAAiB,QAAQ;AAAA,EACpC,EAAE,WAAW,EAAE,IAAI,SAAS,MAAM,WAAW,GAAG,QAAQ,CAAC,QAAQ,OAAO,YAAY,GAAG,SAAS,CAAC,QAAQ,MAAM,EAAE;AACnH,CAAC;",
+  "names": []
+}