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

package/dist/esm/Steering.d.ts

@@ -0,0 +1,464 @@
+/**
+ * Turn-boundary steering values and their source contract.
+ *
+ * Governing design: `../docs/concepts.md#notification-queue`.
+ *
+ * @since 0.1.0
+ */
+import * as ModelRequest from "@smthrs/model/ModelRequest";
+import { Context, Effect, Layer, Schema } from "effect";
+import type { HarnessError } from "./HarnessError.ts";
+/**
+ * The boundary at which a transcript insertion may be promoted.
+ *
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export type Delivery = "steer" | "queue";
+/**
+ * A transcript insertion promoted at the next turn boundary.
+ *
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export interface SteerInsert {
+    readonly _tag: "Insert";
+    readonly delivery: "steer";
+    readonly admittedAt: number;
+    readonly message: ModelRequest.Message;
+}
+/**
+ * A transcript insertion promoted only when the run would otherwise go idle.
+ *
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export interface QueueInsert {
+    readonly _tag: "Insert";
+    readonly delivery: "queue";
+    readonly admittedAt: number;
+    readonly message: ModelRequest.Message;
+}
+/**
+ * A transcript insertion admitted for a future turn.
+ *
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export type Insert = SteerInsert | QueueInsert;
+/**
+ * A model-seat change that applies only after the current turn closes.
+ *
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export interface SeatChange {
+    readonly _tag: "SeatChange";
+    readonly delivery: "steer";
+    readonly admittedAt: number;
+    readonly seat: string;
+}
+/**
+ * A thinking-level change that applies only after the current turn closes.
+ *
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export interface ThinkingChange {
+    readonly _tag: "ThinkingChange";
+    readonly delivery: "steer";
+    readonly admittedAt: number;
+    readonly thinking: ModelRequest.ReasoningEffort;
+}
+/**
+ * A serializable steering event.
+ *
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export type Item = Insert | SeatChange | ThinkingChange;
+/**
+ * An immutable, FIFO queue of steering events.
+ *
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export interface Queue {
+    readonly items: ReadonlyArray<Item>;
+}
+/**
+ * The values promoted when a turn reaches its close boundary.
+ *
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export interface Drain {
+    readonly inserts: ReadonlyArray<ModelRequest.Message>;
+    readonly seatChanges: ReadonlyArray<SeatChange | ThinkingChange>;
+    readonly remaining: Queue;
+    readonly queued: boolean;
+    /**
+     * Whether this boundary had already drained, so the answer is the one it gave
+     * the first time.
+     *
+     * This is what makes a parked run answerable. A park resumes by re-executing
+     * its own frames, so it reaches the same boundary again and must be told the
+     * same thing — and it must also be able to find out that a NEWER boundary is
+     * the one an operator's answer is waiting at. A run walks its park's
+     * boundaries until one reports `false`, which is the first one this run has
+     * not consulted before.
+     *
+     * Host queue bookkeeping, like {@link Drain.remaining}, and deliberately not
+     * part of {@link DrainRecord}: it says which attempt asked, not what the
+     * boundary holds, and freezing it in a journaled value would tell every later
+     * attempt it was the first.
+     */
+    readonly duplicate: boolean;
+}
+/**
+ * The boundary a drain is being attempted at, and whether the run would go
+ * idle if nothing were delivered. Followups are held back until it would.
+ *
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export interface BoundaryInput {
+    readonly boundary: string;
+    readonly wouldIdle: boolean;
+    /**
+     * Set only at an honored park's boundary: why the run parked and what it
+     * asked. A source that can reach a person may show them the question and
+     * answer the drain with their reply; one that cannot ignores it.
+     */
+    readonly park?: {
+        readonly reason: "waiting-input" | "waiting-event" | "waiting-quota";
+        readonly message: string;
+    } | undefined;
+}
+/**
+ * The journaled record of one turn-boundary drain.
+ *
+ * A drain consumes host queue state, so it is a nondeterministic read: the
+ * controller journals exactly this projection through `EngineLike.record`,
+ * keyed on the frame and boundary, and a re-executed frame replays the record
+ * instead of draining an already-drained queue. Everything the controller
+ * folds into durable state is here; `remaining` is host queue bookkeeping and
+ * deliberately is not.
+ *
+ * @category schemas
+ * @since 0.1.0
+ * @slop
+ */
+export declare const DrainRecord: Schema.Struct<{
+    readonly inserts: Schema.$Array<Schema.Union<readonly [typeof ModelRequest.UserMessage, typeof ModelRequest.AssistantMessage, typeof ModelRequest.ToolMessage]> & {
+        readonly discriminants: readonly ["user", "assistant", "tool"];
+        readonly cases: {
+            user: typeof ModelRequest.UserMessage;
+            assistant: typeof ModelRequest.AssistantMessage;
+            tool: typeof ModelRequest.ToolMessage;
+        };
+        readonly isAnyOf: <const Keys>(keys: readonly Keys[]) => (value: ModelRequest.UserMessage | ModelRequest.AssistantMessage | ModelRequest.ToolMessage) => value is Extract<ModelRequest.UserMessage, {
+            readonly role: Keys;
+        }> | Extract<ModelRequest.AssistantMessage, {
+            readonly role: Keys;
+        }> | Extract<ModelRequest.ToolMessage, {
+            readonly role: Keys;
+        }>;
+        readonly guards: {
+            user: (u: unknown) => u is ModelRequest.UserMessage;
+            assistant: (u: unknown) => u is ModelRequest.AssistantMessage;
+            tool: (u: unknown) => u is ModelRequest.ToolMessage;
+        };
+        readonly match: {
+            <Cases extends {
+                user: (value: ModelRequest.UserMessage) => any;
+                assistant: (value: ModelRequest.AssistantMessage) => any;
+                tool: (value: ModelRequest.ToolMessage) => any;
+            }>(value: ModelRequest.UserMessage | ModelRequest.AssistantMessage | ModelRequest.ToolMessage, cases: Cases): Cases[keyof Cases] extends (value: any) => infer R ? import("effect/Unify").Unify<R> : never;
+            <Cases extends {
+                user: (value: ModelRequest.UserMessage) => any;
+                assistant: (value: ModelRequest.AssistantMessage) => any;
+                tool: (value: ModelRequest.ToolMessage) => any;
+            }>(cases: Cases): (value: ModelRequest.UserMessage | ModelRequest.AssistantMessage | ModelRequest.ToolMessage) => Cases[keyof Cases] extends (value: any) => infer R ? import("effect/Unify").Unify<R> : never;
+        };
+        readonly matchOrElse: {
+            <Cases extends {
+                user?: (value: ModelRequest.UserMessage) => any;
+                assistant?: (value: ModelRequest.AssistantMessage) => any;
+                tool?: (value: ModelRequest.ToolMessage) => any;
+            } & { [K in Exclude<keyof Cases, "user" | "assistant" | "tool">]: never; }, OrElse extends (value: Exclude<ModelRequest.UserMessage, {
+                readonly role: keyof Cases;
+            }> | Exclude<ModelRequest.AssistantMessage, {
+                readonly role: keyof Cases;
+            }> | Exclude<ModelRequest.ToolMessage, {
+                readonly role: keyof Cases;
+            }>) => any>(value: ModelRequest.UserMessage | ModelRequest.AssistantMessage | ModelRequest.ToolMessage, cases: Cases, orElse: OrElse): import("effect/Unify").Unify<{ [K_1 in keyof Cases]-?: NonNullable<Cases[K_1]> extends (...args: Array<any>) => infer R ? R : never; }[keyof Cases] | ReturnType<OrElse>>;
+            <Cases extends {
+                user?: (value: ModelRequest.UserMessage) => any;
+                assistant?: (value: ModelRequest.AssistantMessage) => any;
+                tool?: (value: ModelRequest.ToolMessage) => any;
+            } & { [K in Exclude<keyof Cases, "user" | "assistant" | "tool">]: never; }, OrElse extends (value: Exclude<ModelRequest.UserMessage, {
+                readonly role: keyof Cases;
+            }> | Exclude<ModelRequest.AssistantMessage, {
+                readonly role: keyof Cases;
+            }> | Exclude<ModelRequest.ToolMessage, {
+                readonly role: keyof Cases;
+            }>) => any>(cases: Cases, orElse: OrElse): (value: ModelRequest.UserMessage | ModelRequest.AssistantMessage | ModelRequest.ToolMessage) => import("effect/Unify").Unify<{ [K_1 in keyof Cases]-?: NonNullable<Cases[K_1]> extends (...args: Array<any>) => infer R ? R : never; }[keyof Cases] | ReturnType<OrElse>>;
+        };
+    } & {
+        make: (message: ModelRequest.Message) => ModelRequest.Message;
+        user: (content: string | ModelRequest.TextPart | ReadonlyArray<ModelRequest.TextPart>) => ModelRequest.UserMessage;
+        assistant: (content: string | ModelRequest.AssistantContentPart | ReadonlyArray<ModelRequest.AssistantContentPart>, options?: {
+            readonly stopReason?: ModelRequest.StopReason | undefined;
+            readonly responseId?: string | undefined;
+            readonly itemIds?: ReadonlyArray<string> | undefined;
+        }) => ModelRequest.AssistantMessage;
+        tool: (content: ModelRequest.ToolResultPart | ReadonlyArray<ModelRequest.ToolResultPart>) => ModelRequest.ToolMessage;
+    }>;
+    readonly seatChanges: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+        readonly _tag: Schema.Literal<"SeatChange">;
+        readonly delivery: Schema.Literal<"steer">;
+        readonly admittedAt: Schema.Number;
+        readonly seat: Schema.String;
+    }>, Schema.Struct<{
+        readonly _tag: Schema.Literal<"ThinkingChange">;
+        readonly delivery: Schema.Literal<"steer">;
+        readonly admittedAt: Schema.Number;
+        readonly thinking: Schema.Literals<readonly ["none", "minimal", "low", "medium", "high", "xhigh", "max"]>;
+    }>]>>;
+    readonly queued: Schema.Boolean;
+    /**
+     * Messages the run's supervisor delivers at this boundary, kept apart from
+     * `inserts` because they are not the person's words: the model reads them,
+     * and the completion brake's task never does. Absent from records written
+     * before the supervisor had a field of its own, and from boundaries it
+     * delivered nothing at.
+     */
+    readonly supervisor: Schema.optional<Schema.$Array<Schema.Union<readonly [typeof ModelRequest.UserMessage, typeof ModelRequest.AssistantMessage, typeof ModelRequest.ToolMessage]> & {
+        readonly discriminants: readonly ["user", "assistant", "tool"];
+        readonly cases: {
+            user: typeof ModelRequest.UserMessage;
+            assistant: typeof ModelRequest.AssistantMessage;
+            tool: typeof ModelRequest.ToolMessage;
+        };
+        readonly isAnyOf: <const Keys>(keys: readonly Keys[]) => (value: ModelRequest.UserMessage | ModelRequest.AssistantMessage | ModelRequest.ToolMessage) => value is Extract<ModelRequest.UserMessage, {
+            readonly role: Keys;
+        }> | Extract<ModelRequest.AssistantMessage, {
+            readonly role: Keys;
+        }> | Extract<ModelRequest.ToolMessage, {
+            readonly role: Keys;
+        }>;
+        readonly guards: {
+            user: (u: unknown) => u is ModelRequest.UserMessage;
+            assistant: (u: unknown) => u is ModelRequest.AssistantMessage;
+            tool: (u: unknown) => u is ModelRequest.ToolMessage;
+        };
+        readonly match: {
+            <Cases extends {
+                user: (value: ModelRequest.UserMessage) => any;
+                assistant: (value: ModelRequest.AssistantMessage) => any;
+                tool: (value: ModelRequest.ToolMessage) => any;
+            }>(value: ModelRequest.UserMessage | ModelRequest.AssistantMessage | ModelRequest.ToolMessage, cases: Cases): Cases[keyof Cases] extends (value: any) => infer R ? import("effect/Unify").Unify<R> : never;
+            <Cases extends {
+                user: (value: ModelRequest.UserMessage) => any;
+                assistant: (value: ModelRequest.AssistantMessage) => any;
+                tool: (value: ModelRequest.ToolMessage) => any;
+            }>(cases: Cases): (value: ModelRequest.UserMessage | ModelRequest.AssistantMessage | ModelRequest.ToolMessage) => Cases[keyof Cases] extends (value: any) => infer R ? import("effect/Unify").Unify<R> : never;
+        };
+        readonly matchOrElse: {
+            <Cases extends {
+                user?: (value: ModelRequest.UserMessage) => any;
+                assistant?: (value: ModelRequest.AssistantMessage) => any;
+                tool?: (value: ModelRequest.ToolMessage) => any;
+            } & { [K in Exclude<keyof Cases, "user" | "assistant" | "tool">]: never; }, OrElse extends (value: Exclude<ModelRequest.UserMessage, {
+                readonly role: keyof Cases;
+            }> | Exclude<ModelRequest.AssistantMessage, {
+                readonly role: keyof Cases;
+            }> | Exclude<ModelRequest.ToolMessage, {
+                readonly role: keyof Cases;
+            }>) => any>(value: ModelRequest.UserMessage | ModelRequest.AssistantMessage | ModelRequest.ToolMessage, cases: Cases, orElse: OrElse): import("effect/Unify").Unify<{ [K_1 in keyof Cases]-?: NonNullable<Cases[K_1]> extends (...args: Array<any>) => infer R ? R : never; }[keyof Cases] | ReturnType<OrElse>>;
+            <Cases extends {
+                user?: (value: ModelRequest.UserMessage) => any;
+                assistant?: (value: ModelRequest.AssistantMessage) => any;
+                tool?: (value: ModelRequest.ToolMessage) => any;
+            } & { [K in Exclude<keyof Cases, "user" | "assistant" | "tool">]: never; }, OrElse extends (value: Exclude<ModelRequest.UserMessage, {
+                readonly role: keyof Cases;
+            }> | Exclude<ModelRequest.AssistantMessage, {
+                readonly role: keyof Cases;
+            }> | Exclude<ModelRequest.ToolMessage, {
+                readonly role: keyof Cases;
+            }>) => any>(cases: Cases, orElse: OrElse): (value: ModelRequest.UserMessage | ModelRequest.AssistantMessage | ModelRequest.ToolMessage) => import("effect/Unify").Unify<{ [K_1 in keyof Cases]-?: NonNullable<Cases[K_1]> extends (...args: Array<any>) => infer R ? R : never; }[keyof Cases] | ReturnType<OrElse>>;
+        };
+    } & {
+        make: (message: ModelRequest.Message) => ModelRequest.Message;
+        user: (content: string | ModelRequest.TextPart | ReadonlyArray<ModelRequest.TextPart>) => ModelRequest.UserMessage;
+        assistant: (content: string | ModelRequest.AssistantContentPart | ReadonlyArray<ModelRequest.AssistantContentPart>, options?: {
+            readonly stopReason?: ModelRequest.StopReason | undefined;
+            readonly responseId?: string | undefined;
+            readonly itemIds?: ReadonlyArray<string> | undefined;
+        }) => ModelRequest.AssistantMessage;
+        tool: (content: ModelRequest.ToolResultPart | ReadonlyArray<ModelRequest.ToolResultPart>) => ModelRequest.ToolMessage;
+    }>>;
+    /**
+     * Keys of the memory rows among `supervisor`, which the run has now been
+     * shown. Absent from boundaries that delivered none.
+     */
+    readonly memory: Schema.optional<Schema.$Array<Schema.String>>;
+    /** The monitor whose message leads `supervisor`, when one was delivered. */
+    readonly monitor: Schema.optional<Schema.String>;
+    /** Crossed monitors this boundary withheld, and why. Absent when none was. */
+    readonly suppressed: Schema.optional<Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly reason: Schema.Literals<readonly ["streak", "cooldown", "limit", "slot"]>;
+    }>>>;
+    /**
+     * The monitor ledger after this boundary gated a reading, which the run
+     * carries into its next frame. Absent from boundaries that gated none.
+     */
+    readonly monitorLedger: Schema.optional<Schema.$Record<Schema.String, Schema.Struct<{
+        readonly streak: Schema.Int;
+        readonly delivered: Schema.Int;
+        readonly lastFrame: Schema.Int;
+    }>>>;
+    /**
+     * Jev's answers about transcript segments, by digest, which the run stores
+     * for its next compaction. The model is not sent them. Absent from
+     * boundaries that took none.
+     */
+    readonly marks: Schema.optional<Schema.$Array<Schema.Struct<{
+        readonly remove: Schema.Number;
+        readonly keep: Schema.Number;
+        readonly digest: Schema.String;
+    }>>>;
+    /**
+     * The context triggers the delivered supervisor reading fired, which
+     * compact the run at its next frame. Absent from boundaries that took none.
+     */
+    readonly compact: Schema.optional<Schema.$Array<Schema.Literals<readonly ["budget", "outdated_context", "irrelevant_context"]>>>;
+}>;
+/**
+ * The journaled record of one turn-boundary drain.
+ *
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export type DrainRecord = typeof DrainRecord.Type;
+/**
+ * Projects a {@link Drain} into its journaled record.
+ *
+ * @category conversions
+ * @since 0.1.0
+ * @slop
+ */
+export declare const drainRecord: (drain: Drain) => DrainRecord;
+/**
+ * Creates an empty immutable steering queue.
+ *
+ * @category constructors
+ * @since 0.1.0
+ * @slop
+ */
+export declare const empty: () => Queue;
+/**
+ * Appends an item without mutating the prior queue.
+ *
+ * @category operations
+ * @since 0.1.0
+ * @slop
+ */
+export declare const enqueue: (queue: Queue, item: Item) => Queue;
+/**
+ * Drains only items admitted at or before the turn's fixed cutoff.
+ *
+ * @category operations
+ * @since 0.1.0
+ * @slop
+ */
+export declare const drainAtClose: (queue: Queue, cutoff: number) => Drain;
+/**
+ * Source of a serializable steering-queue snapshot. Storage and persistence
+ * promotion are deliberately supplied by the host.
+ *
+ * @category services
+ * @since 0.1.0
+ * @slop
+ */
+export interface Source {
+    readonly read: () => Effect.Effect<Queue, HarnessError>;
+    /**
+     * Promotes what one boundary may deliver.
+     *
+     * A drain is IDEMPOTENT in its boundary string: a second drain at one
+     * boundary promotes nothing and hands back exactly what the first one
+     * promoted, with {@link Drain.duplicate} set. That is not an optimization, it
+     * is the contract a resumed run depends on — a re-executed frame drains the
+     * boundaries it already drained and must be told the same thing, or it
+     * rebuilds a different context and re-keys every later sealed step. A source
+     * that promotes afresh each time cannot answer a parked run and will deliver
+     * one message many times.
+     */
+    readonly drain: (input: BoundaryInput) => Effect.Effect<Drain, HarnessError>;
+}
+/**
+ * The methods {@link make} needs to build a {@link Source}.
+ *
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export interface SourceInput {
+    readonly read: () => Effect.Effect<Queue, HarnessError>;
+    readonly drain: (input: BoundaryInput) => Effect.Effect<Drain, HarnessError>;
+}
+/**
+ * Service tag for the external steering queue source.
+ *
+ * @category services
+ * @since 0.1.0
+ * @slop
+ */
+export declare const Source: Context.Service<Source, Source>;
+/**
+ * Constructs a steering source service.
+ *
+ * @category constructors
+ * @since 0.1.0
+ * @slop
+ */
+export declare const make: (implementation: SourceInput) => Source;
+/**
+ * Creates a source that always returns an empty queue.
+ *
+ * @category constructors
+ * @since 0.1.0
+ * @slop
+ */
+export declare const makeNoop: (overrides?: Partial<Source>) => Source;
+/**
+ * Provides a steering source as a layer.
+ *
+ * @category layers
+ * @since 0.1.0
+ * @slop
+ */
+export declare const layer: (implementation: SourceInput) => Layer.Layer<Source>;
+/**
+ * Provides an empty steering source as a layer.
+ *
+ * @category layers
+ * @since 0.1.0
+ * @slop
+ */
+export declare const layerNoop: (overrides?: Partial<Source>) => Layer.Layer<Source>;
+//# sourceMappingURL=Steering.d.ts.map

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

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

package/dist/esm/Steering.js

@@ -0,0 +1,193 @@
+/**
+ * Turn-boundary steering values and their source contract.
+ *
+ * Governing design: `../docs/concepts.md#notification-queue`.
+ *
+ * @since 0.1.0
+ */
+import * as ModelRequest from "@smthrs/model/ModelRequest";
+import { Context, Effect, Layer, Schema } from "effect";
+import * as AgentEvent from "./AgentEvent.js";
+import * as compactionMarks from "./internal/compactionMarks.js";
+import * as Monitor from "./Monitor.js";
+const SeatChangeRecord = Schema.Struct({
+    _tag: Schema.Literal("SeatChange"),
+    delivery: Schema.Literal("steer"),
+    admittedAt: Schema.Number,
+    seat: Schema.String
+});
+const ThinkingChangeRecord = Schema.Struct({
+    _tag: Schema.Literal("ThinkingChange"),
+    delivery: Schema.Literal("steer"),
+    admittedAt: Schema.Number,
+    thinking: ModelRequest.ReasoningEffort
+});
+/**
+ * The journaled record of one turn-boundary drain.
+ *
+ * A drain consumes host queue state, so it is a nondeterministic read: the
+ * controller journals exactly this projection through `EngineLike.record`,
+ * keyed on the frame and boundary, and a re-executed frame replays the record
+ * instead of draining an already-drained queue. Everything the controller
+ * folds into durable state is here; `remaining` is host queue bookkeeping and
+ * deliberately is not.
+ *
+ * @category schemas
+ * @since 0.1.0
+ * @slop
+ */
+export const DrainRecord = Schema.Struct({
+    inserts: Schema.Array(ModelRequest.Message),
+    seatChanges: Schema.Array(Schema.Union([SeatChangeRecord, ThinkingChangeRecord])),
+    queued: Schema.Boolean,
+    /**
+     * Messages the run's supervisor delivers at this boundary, kept apart from
+     * `inserts` because they are not the person's words: the model reads them,
+     * and the completion brake's task never does. Absent from records written
+     * before the supervisor had a field of its own, and from boundaries it
+     * delivered nothing at.
+     */
+    supervisor: Schema.optional(Schema.Array(ModelRequest.Message)),
+    /**
+     * Keys of the memory rows among `supervisor`, which the run has now been
+     * shown. Absent from boundaries that delivered none.
+     */
+    memory: Schema.optional(Schema.Array(Schema.String)),
+    /** The monitor whose message leads `supervisor`, when one was delivered. */
+    monitor: Schema.optional(Schema.String),
+    /** Crossed monitors this boundary withheld, and why. Absent when none was. */
+    suppressed: Schema.optional(Schema.Array(Schema.Struct({ id: Schema.String, reason: AgentEvent.Suppression }))),
+    /**
+     * The monitor ledger after this boundary gated a reading, which the run
+     * carries into its next frame. Absent from boundaries that gated none.
+     */
+    monitorLedger: Schema.optional(Monitor.Ledger),
+    /**
+     * Jev's answers about transcript segments, by digest, which the run stores
+     * for its next compaction. The model is not sent them. Absent from
+     * boundaries that took none.
+     */
+    marks: Schema.optional(Schema.Array(compactionMarks.Marking)),
+    /**
+     * The context triggers the delivered supervisor reading fired, which
+     * compact the run at its next frame. Absent from boundaries that took none.
+     */
+    compact: Schema.optional(Schema.Array(AgentEvent.CompactionCause))
+});
+/**
+ * Projects a {@link Drain} into its journaled record.
+ *
+ * @category conversions
+ * @since 0.1.0
+ * @slop
+ */
+export const drainRecord = (drain) => ({
+    inserts: drain.inserts,
+    seatChanges: drain.seatChanges,
+    queued: drain.queued
+});
+const immutable = (items) => Object.freeze({ items: Object.freeze([...items]) });
+const immutableItem = (item) => Object.freeze({ ...item });
+/**
+ * Creates an empty immutable steering queue.
+ *
+ * @category constructors
+ * @since 0.1.0
+ * @slop
+ */
+export const empty = () => immutable([]);
+/**
+ * Appends an item without mutating the prior queue.
+ *
+ * @category operations
+ * @since 0.1.0
+ * @slop
+ */
+export const enqueue = (queue, item) => immutable([...queue.items, immutableItem(item)]);
+/**
+ * Drains only items admitted at or before the turn's fixed cutoff.
+ *
+ * @category operations
+ * @since 0.1.0
+ * @slop
+ */
+export const drainAtClose = (queue, cutoff) => {
+    const inserts = [];
+    const seatChanges = [];
+    const remaining = [];
+    for (const item of queue.items) {
+        if (item.delivery === "queue" || item.admittedAt > cutoff) {
+            remaining.push(item);
+            continue;
+        }
+        switch (item._tag) {
+            case "Insert":
+                inserts.push(item.message);
+                break;
+            case "SeatChange":
+            case "ThinkingChange":
+                seatChanges.push(item);
+                break;
+        }
+    }
+    return {
+        inserts: Object.freeze(inserts),
+        seatChanges: Object.freeze(seatChanges),
+        remaining: immutable(remaining),
+        queued: false,
+        // An in-memory cutoff drain keeps no boundary ledger, so it can never say
+        // it has answered this boundary before.
+        duplicate: false
+    };
+};
+/**
+ * Service tag for the external steering queue source.
+ *
+ * @category services
+ * @since 0.1.0
+ * @slop
+ */
+export const Source = Context.Service("@smthrs/harness/Steering/Source");
+/**
+ * Constructs a steering source service.
+ *
+ * @category constructors
+ * @since 0.1.0
+ * @slop
+ */
+export const make = (implementation) => Source.of(implementation);
+/**
+ * Creates a source that always returns an empty queue.
+ *
+ * @category constructors
+ * @since 0.1.0
+ * @slop
+ */
+export const makeNoop = (overrides = {}) => make({
+    read: Effect.fn("Steering.Source.read")(() => Effect.succeed(empty())),
+    drain: Effect.fn("Steering.Source.drain")(() => Effect.succeed({
+        inserts: [],
+        seatChanges: [],
+        remaining: empty(),
+        queued: false,
+        duplicate: false
+    })),
+    ...overrides
+});
+/**
+ * Provides a steering source as a layer.
+ *
+ * @category layers
+ * @since 0.1.0
+ * @slop
+ */
+export const layer = (implementation) => Layer.succeed(Source)(make(implementation));
+/**
+ * Provides an empty steering source as a layer.
+ *
+ * @category layers
+ * @since 0.1.0
+ * @slop
+ */
+export const layerNoop = (overrides = {}) => Layer.succeed(Source)(makeNoop(overrides));
+//# sourceMappingURL=Steering.js.map