@smthrs/gateway 0.35.0 → 1.0.0-rc.3

package/CHANGELOG.md

@@ -0,0 +1,198 @@
+# @smthrs/gateway
+
+## [Unreleased]
+
+### Added
+
+- `RuntimeBridge.LifecycleCommand` accepts `complete`;
+  `RuntimeBridge.Config.requestComplete` supplies the host completion port.
+
+- `Diagnosis.digest` takes an optional `runId`. A `control.run.*` verdict
+  stamped with another run's id, such as a child's, no longer sets the digested
+  run's status or failure cause, so a run summary no longer reports a child's
+  failure as the parent's.
+
+- Approval RPC failures include `CodeDrift`; gateway envelopes and projections
+  carry the optional budget `onExceeded` policy. Clients with exhaustive error
+  handling must handle the new refusal (#1807, #1843).
+
+- Added `GatewaySchema.SnapshotOf`, `FrameOf`, and `RowOf`, and made
+  `Projections.Service.snapshot`, `subscribe`, and `GatewaySchema.rowSchemaFor`
+  generic in their selector, so a literal selector keeps its own row type and a
+  caller reads `requestId` or `nodeId` without an assertion. A selector chosen
+  at runtime still maps to the `ProjectionSnapshot` and `GatewayFrame` unions.
+
+### Changed
+
+- The runtime monitor omits the raw journal (paged from `run-events` when its
+  tab opens; a replay frame keeps its prefix) and adds the run's `extent`.
+  Plan structure and child-flow calls are no longer steps, and a check phase
+  is titled by the failures its receipts report (#3514).
+
+- The runtime monitor no longer refuses runs with model tokens. Settled native
+  steps carry their metered dispatches (`meter`), journaled model calls
+  (`model_calls`) and tokens (`tokens`), and their agent transcript as phase
+  cells; a run with tokens returns no `cost_usd` and the install prices it from
+  metered proxy rows (#3514).
+
+- Monitor graphs collapse Engine bookkeeping nodes while retaining visible
+  dependency order through nested boundaries.
+
+- The `workspace-runs` and `approvals` projections fold the newest 500 runs
+  instead of the oldest 500, and a followed workspace admits a run created
+  after its oldest followed run by displacing that run. Before, a workspace
+  past 500 runs never showed a newly launched run.
+- The runtime bridge logs the full cause of every failure the caller did not
+  cause, and runs each handler in a `runtime-bridge.command` or
+  `runtime-bridge.observe` span. The wire response is unchanged.
+- A gateway that enables the runtime bridge without a bearer credential now
+  refuses to bind with `bind_failed`, including on loopback. It used to start
+  and answer 401 to every bridge request.
+- The Bun host keeps the operating-system errno on its bind refusal, so the
+  operator log names `EADDRINUSE`, `EACCES`, or `EADDRNOTAVAIL` as the Node
+  host's does. The wire refusal still omits it.
+- `GatewaySchema` derives `ProjectionSelector`, `ProjectionName`,
+  `rowSchemaFor`, `ProjectionSnapshot`, `RowFrame`, and `DeltaFrame` from one
+  selector-to-row table instead of five hand-kept lists. The wire format is
+  unchanged.
+- Renamed the `GatewayError`, `ResumeError`, and `SuperviseRuntime` tags from
+  the retired `flows/gateway/` namespace to `@smthrs/gateway/`, the namespace
+  `Projections` already used. A refusal body now carries
+  `"_tag": "@smthrs/gateway/GatewayError"`.
+- `@smthrs/run-store` is no longer a runtime dependency. `SuperviseRuntime`
+  spells its two ownership shapes structurally.
+
+### Removed
+
+- Removed `sleepWaits` from `EngineTrace.EngineExecutionEvidence`; it is now `waits`,
+  whose entries carry `kind: "sleep" | "signal"` beside `id`, `since` and
+  `settledAt` (6a995431/5847ca8c, #3514). Migration: read
+  `waits.filter((wait) => wait.kind === "sleep")` where `sleepWaits` was read.
+  This RC change follows
+  [RELEASE_SUPPORT.md](https://github.com/smithersai/smithers/blob/main/RELEASE_SUPPORT.md),
+  whose opening RC policy states that the candidate is not a stable 1.0
+  compatibility or long-term support commitment.
+
+- Removed `"forks"` from `RunTrace.TraceFilter` and `TRACE_FILTER_IDS`.
+  Migration: replace stored or supplied `"forks"` filters with `"all"` and
+  remove exhaustive branches for the old value. This RC change follows
+  [RELEASE_SUPPORT.md](https://github.com/smithersai/smithers/blob/main/RELEASE_SUPPORT.md),
+  whose opening RC policy states that the candidate is not a stable 1.0
+  compatibility or long-term support commitment.
+
+- Removed `SuperviseRuntime` and `test/TestSuperviseRuntime`. No host
+  implemented the port, so it shipped as a stub that scanned nothing and
+  resumed nothing. Recovery remains the heartbeat reclaim.
+- Removed `GatewaySchema.Workspace`, `GatewayConfig`, `GatewayStatus`,
+  `SingletonRecord`, `TokenScope`, and `TokenRecord`, and the API and
+  trust-boundary passages that had to disclaim them: nothing minted, read,
+  persisted, or served one, and a first release has nothing to be compatible
+  with. A singleton handshake lands with its route and its tests.
+
+## [1.0.0-rc.0] - 2026-09-01
+
+### Added
+
+- Added the assembled workspace gateway: `POST /rpc`, `/rpc/ws`,
+  `POST /projections`, `/projections/ws`, `POST /sync`, `/sync/ws`, and an
+  unauthenticated `GET /health`, as one application layer with
+  `node/NodeGateway` as its Node host.
+- Added the served read path: `workspace-runs`, `run-summary`, `run-events`,
+  `transcript`, `run-tree`, `approvals`, and `node-output`, folded from the
+  control events `Control.watch` publishes and served as snapshots, replacement
+  deltas, and keepalive frames.
+- Added `Approval.Submit`, the one composite mutation a product client cannot
+  assemble safely on its own, journaled under the operator the shared bearer
+  middleware authenticated rather than the composition's default.
+- Added keepalives on `/rpc/ws` and `/projections/ws` at a cadence well inside
+  the 600-second idle cut a relay applies, and an ingress guard that answers
+  401, 400, and 413 with a typed body instead of an empty 500.
+- Added `Diagnosis`, which computes what happened to a run from that run's own
+  events and renders it as the `run-summary` row's verdict and diagnosis card.
+- Added `NodeGateway.bindRefusal`, `GatewayError.settingRefusal`, and
+  `GatewayServer.exceededBodyLimit`, so a start-time refusal is a typed
+  `bind_failed` value and a body-read failure is told apart from a body that
+  was too big.
+- Added `GatewaySchema.rowSchemaFor`, a resume cursor on
+  `Projection.Subscribe`, and same-named type aliases for every public selector
+  and frame schema, so a client decodes rows and resumes a subscription instead
+  of casting and re-reading.
+- Added package-owned documentation under `docs/`, built and drift-checked by
+  the `PACKAGE.ts` `docs` and `docsFiles` targets.
+
+### Changed
+
+- A workspace subscription now reports new runs, status changes, and new gates
+  instead of emitting a snapshot and then keepalives forever.
+- A subscription now reads the control plane exactly once. The rows, the cursor
+  the snapshot advertises, and the sequence its deltas start after all come
+  from that read, so an event landing mid-read is no longer delivered as both a
+  row and a delta.
+- A delta now folds the events accumulated on the stream instead of re-reading
+  the whole journal per event, so following a run costs one read whatever its
+  length.
+- `GatewayError.cause` now carries a redacted `{_tag, code}` summary rather than
+  the whole internal `ControlError`, and the full cause is logged server-side.
+- Projection histories and encoded row sets are bounded. A limit breach now
+  fails as `resource_limit` rather than retaining an unbounded journal or wire
+  payload.
+- Projection cursors now bind the full selector and a sequence-local offset,
+  preserving every derived event when several share one journal sequence.
+- Startup policy and operating-system bind failures now travel through typed
+  effect and layer channels as sanitized `bind_failed` values; constructors no
+  longer throw synchronously.
+- The workspace approvals follower counts only runs with pending gates toward
+  its run ceiling, so irrelevant completed histories cannot starve a later
+  request.
+- An unknown run now fails `run_not_found` identically for every run-scoped
+  selector, rather than failing for two of them and answering an empty snapshot
+  for the other four.
+- `Diagnosis.clip` now cuts on code points, never emitting a lone surrogate,
+  and honours widths of 0 and 1; `firstLine` no longer leaves a carriage return
+  on a CRLF cause.
+- `Diagnosis.digest` now measures a run's span from the kinds it handles, so
+  the keepalive merged into a followed `Watch` no longer reports a run as
+  having lasted as long as it was watched.
+- `nodeOutput` now keys its rows exactly as `runTree` does, even when an event
+  names no run, so the two folds cannot disagree about which node produced
+  which output.
+- `GatewayServer.layer` now takes an options object rather than two positional
+  optionals.
+- `Approval.Submit` now declares exactly the failures `Control.approve` and
+  `Control.deny` raise. It gained `PlanNotFound`, which a decision naming a plan
+  the control plane does not have answers with, and lost `ClaimLost`, which
+  neither command raises: a declared tag no command produces is a recovery
+  branch no client's code can reach.
+- The ingress guard now classifies a request target the way the router resolves
+  it rather than by its literal spelling. `HttpRouter` reaches `/rpc` from
+  `/%72pc`, `/rpc;transport-parameter`, `/rpc/`, `//rpc`, `/rpc//`, `/RPC`, and
+  `/foo/../rpc`, and the guard recognised none of them, so on a credentialed
+  bind those spellings reached the mount with neither the bearer check nor the
+  body limit applied. `ControlClient`'s HTTP protocol posts every call to
+  `/rpc/`, so this was the ordinary client path and not only a crafted alias.
+  An uncredentialed call is now refused 401 at the edge before its body is
+  read, which an Effect RPC client reports as a transport failure rather than
+  as the mount's own `Unauthorized`.
+- A transcript row now carries one display line per event: a seat, flow name,
+  failure message, resolved output, or approval question containing a newline
+  no longer splits one row into several.
+- The published runtime dependency set no longer includes
+  `@effect/platform-node-shared`, `@smthrs/journal`, or
+  `@smthrs/notifications`. Journal and notifications remain development-only
+  fixtures for the real SQLite gateway tests.
+
+### Removed
+
+- Removed `plan-cards` from `ProjectionName`, `PlanCardsSelector`, and the read
+  path: the declared projection set equals the served set (release requirements), and
+  a plan card is what `Control.plan` returns rather than something projected.
+- Removed the never-produced `GatewayErrorCode` members `already_running`,
+  `not_running`, `token_expired`, `unsupported_projection`,
+  `subscription_expired`, `overflow`, and `sweep_failed`.
+- Removed the never-emitted `OverflowFrame`, `ExpiredFrame`, `TerminalFrame`,
+  and `UnauthorizedFrame`, and the unreferenced `SubscriptionTick` and
+  `SubscriptionWatch` schemas.
+- Removed `SubmitApprovalOutput.resume` and the `layerRefuseMalformedRpc`
+  alias: a first release has nothing to be compatible with.
+- The 0.x gateway protocol is replaced rather than adapted. No 0.x method name
+  or path is served and there is no compatibility projection.

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 William Cory
+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

package/README.md

@@ -0,0 +1,92 @@
+# @smthrs/gateway
+
+The gateway requires `effect` at `4.0.0-rc.115` as its only peer. Node and Bun adapters are bundled privately at the same version; hosts need no separate adapter install.
+
+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).
+
+**Documentation:** https://gateway.smithers.sh
+
+The assembled workspace gateway: one HTTP surface carrying the control plane, the sync read path, the served projections, and a health probe. It also defines the gateway wire schemas and re-exports the durable journal synchronization package gateway hosts use.
+
+The mounts, the bind and credential policy, the projections and their rows, the subscription and cursor semantics, every failure code with the status it answers, and the resource limits are documented once, on [the API page](https://gateway.smithers.sh/reference/api/). This file lists what the package exports and shows how a host composes it.
+
+`smthrs serve`, from [`@smthrs/cli`](https://cli.smithers.sh), is a host over this package: it resolves a project on disk, builds the control plane and the journal over that project's database, and hands the assembly here to bind and serve. Install the CLI when you want a gateway without writing code; install this package when you are writing a client against the wire, or embedding the surface in a process of your own.
+
+## Install
+
+Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+
+Node 26.4.0 or later is required. `effect@4.0.0-rc.115` is a required peer.
+
+```bash
+pnpm add @smthrs/gateway effect@4.0.0-rc.115
+```
+
+## Public API
+
+The root entry point exports these namespaces; local modules are also importable from `@smthrs/gateway/<Module>`.
+
+| Module              | Public exports                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Description                                                                                                  |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `GatewayError`      | `GatewayErrorCode`, `GatewayError`, `settingRefusal`                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Defines the stable failure codes, including local Host/Origin refusals, and the refusal a bad setting earns. |
+| `GatewaySchema`     | `GatewayHealth`, `ProjectionName`, `WorkspaceRunsSelector`, `RunSummarySelector`, `RunEventsSelector`, `TranscriptSelector`, `RunTreeSelector`, `ApprovalsSelector`, `NodeOutputSelector`, `FlowDurationsSelector`, `ProjectionSelector`, `rowSchemaFor`, `RowOf`, `ProjectionCursor`, `ProjectionSnapshot`, `SnapshotOf`, `SnapshotStartFrame`, `RowFrame`, `SnapshotEndFrame`, `DeltaFrame`, `HeartbeatFrame`, `GatewayFrame`, `FrameOf`                                                                 | Supplies the wire schemas for projections, cursors, snapshots, and frames.                                   |
+| `Diagnosis`         | `RunStatus`, `Refusal`, `Digest`, `asRecord`, `asString`, `asNumber`, `timeOf`, `firstLine`, `clip`, `digest`, `emptyDigest`, `handlerReach`, `combine`, `duration`, `usd`, `resolvedOutput`, `verdict`, `Subject`, `render`, `callEventKey`, `callScope`, `nativeCallEvent`, `nativeStepEvent`, `openCallIndex`, `uniqueCallEvents`, `foreignVerdict`                                                                                                                                                     | Computes and renders what happened to a run, from that run's own control events.                             |
+| `GatewayProjection` | `RunSummaryRow`, `RunTreeRow`, `ApprovalRow`, `NodeOutputRow`, `FlowDurationRow`, `NodeDuration`, `TranscriptRow`, `runSummary`, `statusRollup`, `runTree`, `approvals`, `nodeOutput`, `nodeDurations`, `flowDurations`, `transcript`                                                                                                                                                                                                                                                                      | Defines the served wire rows and the pure folds that compute them.                                           |
+| `GatewayRpcs`       | `Decision`, `SubmitApprovalInput`, `SubmitApprovalOutput`, `GatewayRpcs`                                                                                                                                                                                                                                                                                                                                                                                                                                   | Declares the served read path, the composite approval mutation, and run fork and verify.                     |
+| `GatewayServer`     | `Health`, `layerHealth`, `layerHandlers`, `watchHeartbeatKind`, `layerKeepAlive`, `layerProjectionsKeepAlive`, `layerControlHttp`, `layerProjectionsHttp`, `layerSyncHttp`, `rpcPaths`, `boundedPostPaths`, `protectedPaths`, `routedPath`, `defaultMaxRequestBodyBytes`, `loopbackHostNames`, `loopbackHostHeaderNames`, `IngressOptions`, `exceededBodyLimit`, `bodyRefusal`, `carriesRpcRequest`, `ticketPath`, `ticketPaths`, `defaultTicketMillis`, `Ticket`, `layerIngress`, `LayerOptions`, `layer` | Assembles the whole HTTP surface as one application layer a host serves.                                     |
+| `Projections`       | `heartbeatIntervalMillis`, `maxWorkspaceRuns`, `maxEventsPerRun`, `maxEventsScanned`, `maxEventsPerPage`, `maxDurationRuns`, `maxProjectionBytes`, `maxEventBytes`, `Service`, `Projections`, `make`, `layer`, `layerWith`                                                                                                                                                                                                                                                                                 | Serves the bounded read path as snapshots and followed deltas.                                               |
+| `RunHistory`        | `Step`, `VerifyInput`, `VerifyReport`, `StepEdit`, `ForkInput`, `ForkOutput`, `HistoryRefused`, `Service`, `RunHistory`                                                                                                                                                                                                                                                                                                                                                                                    | Declares the run fork and verify wire shapes and the host service that serves them.                          |
+| `RuntimeBridge`     | `protocol`, `Identity`, `LaunchCommand`, `DecisionCommand`, `SignalCommand`, `SteerCommand`, `LifecycleCommand`, `Command`, `ObserveRequest`, `CommandReceipt`, `Config`, `BridgeError`, `execute`, `observe`, `monitor`, `CommandResponse`, `ObserveResponse`, `ErrorResponse`, `layer`                                                                                                                                                                                                                                     | Adapts authenticated versioned JSON commands to the canonical Control service.                               |
+| `Sync`              | `RunCatalog`, `SyncClient`, `SyncError`, `SyncProtocol`, `SyncRpcs`, `SyncServer`                                                                                                                                                                                                                                                                                                                                                                                                                          | Re-exports `@smthrs/sync`, the read-only journal replication protocol.                                       |
+| `node/NodeGateway`  | `ServerOptions`, `defaultServerOptions`, `isLoopbackHost`, `bindRefusal`, `listenOptions`, `ingressOptions`, `layerAuth`, `bearerPrincipal`, `scopedPrincipal`, `scopedTokenPaths`, `layer`                                                                                                                                                                                                                                                                                                                | Binds the assembled gateway to a Node HTTP server under the bind and credential policy.                      |
+| `bun/BunGateway`    | `ServerOptions`, `layer`, `bearerPrincipal`, `scopedPrincipal`                                                                                                                                                                                                                                                                                                                                                                                                                                             | Bun HTTP/WebSocket adapter using the same bind, bearer, ingress and RPC policies.                            |
+
+## Hosting it
+
+```ts
+import * as NodeGateway from "@smthrs/gateway/node/NodeGateway"
+
+// The composition `smthrs serve` hosts. The caller supplies
+// `Control`, `Projections`, `SyncServer`, and the `SyncAuth` middleware.
+const gateway = NodeGateway.layer(
+  { workspaceHash: "…", gatewayId: "…", protocolVersion: "1", version: "1.0.0-rc.0" },
+  { host: "0.0.0.0", port: 7331, listen: true, credential: process.env.SMITHERS_TOKEN }
+)
+```
+
+A bind the policy or operating system refuses fails the layer with a sanitized `bind_failed` `GatewayError`. A host can inspect policy before composing the layer:
+
+```ts
+const refusal = NodeGateway.bindRefusal({ host: "0.0.0.0", port: 7331 })
+// => GatewayError { code: "bind_failed", message: "Refusing non-loopback gateway bind 0.0.0.0 without an explicit --listen opt-in" }
+```
+
+A credential-less loopback host also requires a loopback `Host`. On every
+host, a supplied browser `Origin` must be a canonical HTTP(S) origin whose host
+and port equal the request's `Host`, so a browser client is served from the
+gateway's own origin or through a same-origin proxy. Origin-less CLI requests
+remain accepted. Refusals
+are typed `GatewayError` bodies with stable `invalid_host` or `invalid_origin`
+codes, and the same rule runs on HTTP and WebSocket upgrades.
+
+## Recovery at 1.0.0-rc.0
+
+The gateway does not supervise runs. Nothing here watches for a run whose owner died, so a run abandoned through the gateway is not automatically discovered, reclaimed, or resumed.
+
+Recovery is a reclaim rather than a supervisor. A run becomes reclaimable once the heartbeat its owner stopped renewing is older than 30 seconds, and any running `smthrs` process with the flow registered takes it over. Bring up a host composition running the durable engine driver with the relevant flows registered, or recover the run explicitly.
+
+`@smthrs/gateway/package.json` is also exported. `internal/*` and nested `*/index` subpaths are not public.
+
+The concrete Bun adapter serves the same protocol without a Node sidecar:
+
+```ts
+import * as BunGateway from "@smthrs/gateway/bun/BunGateway"
+
+const server = BunGateway.layer(health, { host: "127.0.0.1", port: 7331 })
+// Supply the same Control, Projections, SyncServer and SyncAuth layers.
+```
+
+`bun/BunGateway` supports TCP host/port binds. Platform adapters share one private
+policy/router implementation; neither adapter automatically advertises coding
+capabilities. Those belong to a configured host after its catalog and workspace
+binding have been validated.

package/dist/cjs/Diagnosis.d.ts

@@ -0,0 +1,275 @@
+/**
+ * The run diagnosis: what happened to a run, computed from its own control
+ * events.
+ *
+ * The old gateway answered this question with a `whatHappened` RPC that read
+ * run rows, node-iteration rows, and attempt rows out of the engine database
+ * and optionally asked an agent to narrate them. The rc.0 gateway serves the
+ * same answer as a field of the `run-summary` projection, computed from the
+ * ordered `ControlEvent` deltas `Control.watch` already publishes. Nothing
+ * here opens a database, so a diagnosis read through a relay is the same
+ * diagnosis a local reader computes.
+ *
+ * This is the one fold both surfaces read. `@smthrs/cli` `Forensics` calls
+ * `digest` and adds what a terminal card needs on top of it: duplicate calls,
+ * per-flow counts, the parked approval payload, and the declined-launch state
+ * the wire vocabulary does not carry. The counts, the refusal aggregation, and
+ * the clipping are therefore one implementation, not two that drift.
+ *
+ * @since 1.0.0
+ */
+import { ControlSchema } from "@smthrs/control";
+import * as Fault from "@smthrs/flow/Fault";
+import { uniqueCallEvents } from "./internal/callEvents.ts";
+import * as NativeResolution from "./internal/nativeResolution.ts";
+/**
+ * Keeps one start and settlement per durable call identity, preferring a
+ * committed native fact over telemetry at the first observation's position.
+ * Unidentified legacy events remain distinct because their identity cannot
+ * be recovered from flow names and inputs. Shared with CLI call counts.
+ *
+ * @since 1.0.0
+ * @category projections
+ */
+export { uniqueCallEvents };
+/**
+ * Native fact normalization and stable call/checkpoint identities.
+ * Incremental readers retain these keys to match the full history fold.
+ *
+ * @since 1.0.0
+ * @category projections
+ */
+export { callEventKey, callScope, nativeCallEvent, nativeStepEvent } from "./internal/callEvents.ts";
+/**
+ * Finds an open call by ID, with name/FIFO fallback only for legacy starts.
+ * Shared by gateway node output and the CLI's compatible flow/ordinal IDs.
+ *
+ * @since 1.0.0
+ * @category projections
+ */
+export { openCallIndex } from "./internal/callEvents.ts";
+/**
+ * The run statuses a digest may report.
+ *
+ * `@smthrs/control` `ControlSchema.RunStatus` is the vocabulary; this is the
+ * runtime set the fold checks a journaled kind against.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export type RunStatus = ControlSchema.RunStatus;
+/**
+ * One refused flow call, aggregated by its refusal message.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface Refusal {
+    readonly message: string;
+    readonly count: number;
+}
+/**
+ * Everything the diagnosis computes from one run's events.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface Digest {
+    /** The last run status seen, or undefined before launch. */
+    readonly status: RunStatus | undefined;
+    /** The journaled failure cause, when the run failed and recorded one. */
+    readonly cause: string | undefined;
+    /** The typed fault stamped beside {@link cause}; it is written and cleared with it. */
+    readonly fault?: Fault.Fault | undefined;
+    /** The model seat the last opened turn ran on. */
+    readonly seat: string | undefined;
+    readonly turns: number;
+    readonly calls: number;
+    readonly callsFailed: number;
+    readonly editsAttempted: number;
+    readonly editsSucceeded: number;
+    /** Refusal messages, descending by count. */
+    readonly refusals: ReadonlyArray<Refusal>;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    /** USD the run's priced model calls cost; zero when none was priced. */
+    readonly costUsd: number;
+    /** The final assistant output, when the run resolved. */
+    readonly finalOutput: string | undefined;
+    /** Root binding and committed native result, retained across bounded windows. */
+    readonly nativeResolution?: NativeResolution.NativeResolution | undefined;
+    /** The pending ask's question, when the run parked for approval. */
+    readonly parkedQuestion: string | undefined;
+    /** The earliest time a kind this fold handles occurred at. */
+    readonly startedAt: number | undefined;
+    /** The latest time a kind this fold handles occurred at. */
+    readonly endedAt: number | undefined;
+}
+/**
+ * Reads a payload as a record. Wire payloads are `Json`, so every field read
+ * tolerates absence and the digest of a malformed journal is a sparse digest,
+ * never a throw.
+ *
+ * @param value the payload to read
+ * @since 1.0.0
+ * @category conversions
+ */
+export declare const asRecord: (value: unknown) => Record<string, unknown>;
+/**
+ * Reads a payload field as a string, or nothing when it is not one.
+ *
+ * @param value the field to read
+ * @since 1.0.0
+ * @category conversions
+ */
+export declare const asString: (value: unknown) => string | undefined;
+/**
+ * Reads a payload field as a number, or nothing when it is not one.
+ *
+ * @param value the field to read
+ * @since 1.0.0
+ * @category conversions
+ */
+export declare const asNumber: (value: unknown) => number | undefined;
+/**
+ * Occurrence time: the payload's own stamp, else journal admission time.
+ *
+ * @param event the event to time
+ * @since 1.0.0
+ * @category conversions
+ */
+export declare const timeOf: (event: ControlSchema.ControlEvent) => number;
+/**
+ * The first line, whichever line ending produced it. Splitting on `\n` alone
+ * left the `\r` of a CRLF cause on the wire, and every reader of a one-line
+ * field, here and in `@smthrs/cli` `Forensics`, wants the same answer.
+ *
+ * @param text the text to read one line of
+ * @since 1.0.0
+ * @category conversions
+ */
+export declare const firstLine: (text: string) => string;
+/**
+ * Truncates to a display width, marking the cut.
+ *
+ * The cut is made on code points, never on UTF-16 code units. Slicing code
+ * units splits an astral character in half and puts a lone surrogate on the
+ * wire, where a Go decoder silently replaces it with U+FFFD and a strict
+ * decoder rejects the whole frame; the result of this function is always well
+ * formed. A clipped result is exactly `width` code points, so `width` 1 is the
+ * ellipsis alone and `width` 0, or any negative width, is the empty string.
+ *
+ * @param text the text to clip
+ * @param width the greatest number of code points to keep
+ * @since 1.0.0
+ * @category rendering
+ */
+export declare const clip: (text: string, width: number) => string;
+/**
+ * The kinds this fold handles, with the class each one's fields belong to.
+ *
+ * Exported so a test can hold the table above against the map rather than
+ * trusting a comment, and so a new handler that names no class fails both the
+ * compiler and that test.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export declare const handlerReach: Readonly<Record<string, "aggregate" | "root">>;
+/**
+ * A `control.run.*` verdict stamped with a run id other than `runId`, such as
+ * a child's riding in the parent's events. It must not set the digested run's
+ * status or failure cause. An unstamped verdict is the run's own.
+ *
+ * @param event the event to classify
+ * @param runId the run being digested; omitted, no verdict is foreign
+ * @category predicates
+ * @since 1.0.0
+ */
+export declare const foreignVerdict: (event: ControlSchema.ControlEvent, runId: string | undefined) => boolean;
+/**
+ * Folds one event range, retaining compact identities for later combination.
+ * Native facts supersede telemetry at its first position across ranges too.
+ *
+ * @param events the range to fold
+ * @param runId the run being digested; a `control.run.*` verdict stamped with
+ *   another run's id is skipped. Omitted, every verdict folds.
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const digest: (events: ReadonlyArray<ControlSchema.ControlEvent>, runId?: string) => Digest;
+/**
+ * The wall-clock span the events cover, rendered for a reader.
+ *
+ * Only the span is read, so a caller carrying a wider digest of its own, as
+ * `@smthrs/cli` `Forensics` does, measures it with this rather than a copy.
+ *
+ * @param value the span to measure
+ * @since 1.0.0
+ * @category rendering
+ */
+export declare const duration: (value: Pick<Digest, "startedAt" | "endedAt">) => string;
+/**
+ * A USD amount for a reader: cents from one dollar, four places below it, so
+ * a cheap run never reads as `$0.00`.
+ *
+ * @param value dollars, finite and non-negative
+ * @since 1.0.0
+ * @category rendering
+ */
+export declare const usd: (value: number) => string;
+/**
+ * Assistant text, or a typed module's committed result under its bound root.
+ * @category projections
+ * @since 1.0.0
+ */
+export declare const resolvedOutput: (value: Pick<Digest, "finalOutput" | "nativeResolution">) => string | undefined;
+/**
+ * The one-line verdict: the status plus the reason that most explains it.
+ *
+ * Priority order mirrors what a reader needs first: a recorded failure cause,
+ * then a park's question, then the "worked but never edited" pathology a green
+ * status would otherwise hide, then the resolved output.
+ *
+ * @param value the digest to judge
+ * @since 1.0.0
+ * @category rendering
+ */
+export declare const verdict: (value: Digest) => string;
+/**
+ * Identity a diagnosis is rendered for.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface Subject {
+    readonly runId: string;
+    readonly flowId?: string | undefined;
+}
+/**
+ * Renders the diagnosis card for one run: verdict, activity evidence, tokens,
+ * cost when any call was priced, refusals, cause, and output.
+ *
+ * @param subject the run being diagnosed
+ * @param value the digest computed from its events
+ * @since 1.0.0
+ * @category rendering
+ */
+export declare const render: (subject: Subject, value: Digest) => string;
+/**
+ * A digest of no events at all: the identity {@link combine} folds onto.
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export declare const emptyDigest: () => Digest;
+/**
+ * Combines adjacent digests without counting an identified call or checkpoint
+ * twice. A later native fact replaces the earlier telemetry contribution.
+ * Identity state is private and must stay with the in-memory digest; a plain
+ * reconstructed Digest is treated as an already aggregated, unkeyed value.
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const combine: (earlier: Digest, later: Digest) => Digest;
+//# sourceMappingURL=Diagnosis.d.ts.map

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

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