@swirls/looms 0.4.0 → 0.5.0

package/dist/core/run-context.d.ts

@@ -0,0 +1,33 @@
+import { Schema, type Effect } from 'effect';
+import type { JsonValue } from './types';
+/**
+ * Immutable labels for a run, such as tenant, project, or org.
+ * They are safe for every reader of the run: events, snapshots, summaries, and authorization.
+ */
+export type RunAttributes = {
+    readonly [key: string]: string;
+};
+/**
+ * Bearer material for a run, such as an attenuated macaroon.
+ * It is stored beside the log and is never written to an event, snapshot, or HTTP response.
+ */
+export type SecretContext = {
+    readonly [key: string]: string;
+};
+export declare const RunAttributesSchema: Schema.$Record<Schema.String, Schema.String>;
+export declare const SecretContextSchema: Schema.$Record<Schema.String, Schema.String>;
+export interface RunSecretStore {
+    readonly get: (runId: string) => Effect.Effect<SecretContext, Error>;
+    readonly put: (runId: string, secrets: SecretContext) => Effect.Effect<void, Error>;
+}
+export declare function hasEntries(record: {
+    readonly [key: string]: string;
+}): boolean;
+export declare function sameStringRecord(left: {
+    readonly [key: string]: string;
+}, right: {
+    readonly [key: string]: string;
+}): boolean;
+/** Reads a string map from an event payload. Anything else becomes an empty map. */
+export declare function readAttributes(value: JsonValue | undefined): RunAttributes;
+export declare function readSecretContext(value: JsonValue): SecretContext;

package/dist/core/run-context.js

@@ -0,0 +1,23 @@
+import { Option, Schema } from 'effect';
+export const RunAttributesSchema = Schema.Record(Schema.String, Schema.String);
+export const SecretContextSchema = Schema.Record(Schema.String, Schema.String);
+const decodeAttributes = Schema.decodeUnknownOption(RunAttributesSchema);
+const decodeSecretContext = Schema.decodeUnknownOption(SecretContextSchema);
+export function hasEntries(record) {
+    return Object.keys(record).length > 0;
+}
+export function sameStringRecord(left, right) {
+    const leftKeys = Object.keys(left).toSorted();
+    const rightKeys = Object.keys(right).toSorted();
+    if (leftKeys.length !== rightKeys.length) {
+        return false;
+    }
+    return leftKeys.every((key, index) => key === rightKeys[index] && left[key] === right[key]);
+}
+/** Reads a string map from an event payload. Anything else becomes an empty map. */
+export function readAttributes(value) {
+    return value === undefined ? {} : Option.getOrElse(decodeAttributes(value), () => ({}));
+}
+export function readSecretContext(value) {
+    return Option.getOrElse(decodeSecretContext(value), () => ({}));
+}

package/dist/core/sqlite-store.js

@@ -1,6 +1,7 @@
 import { Effect, Option, Queue, Schema, Stream } from 'effect';
 import { EventEnvelopeSchema, fromWireEvent, withAssignedSeq } from './envelope.js';
 import { assertEventByteLimits, assertSnapshotByteLimit, EventPayloadTooLargeError, SnapshotPayloadTooLargeError, } from './limits.js';
+import { RunAttributesSchema } from './run-context.js';
 import { SnapshotStoreError, withSnapshotStore, } from './snapshot-store.js';
 import { RunStateSchema } from './state.js';
 import { EventStoreConflictError, EventStoreError, EventStoreFencedError, } from './store.js';
@@ -40,7 +41,13 @@ CREATE TABLE IF NOT EXISTS looms_run_headers (
   run_id TEXT PRIMARY KEY,
   status TEXT NOT NULL,
   kind TEXT,
-  definition_name TEXT
+  definition_name TEXT,
+  attributes TEXT NOT NULL DEFAULT '{}'
+);
+
+CREATE TABLE IF NOT EXISTS looms_run_secrets (
+  run_id TEXT PRIMARY KEY,
+  body TEXT NOT NULL
 );
 `.trim();
 const StreamRowSchema = Schema.Struct({
@@ -117,6 +124,13 @@ function initSchema(exec) {
             exec.run(sql);
         }
     }
+    // Databases created before attributes were indexed already have the headers table.
+    try {
+        exec.run(`ALTER TABLE looms_run_headers ADD COLUMN attributes TEXT NOT NULL DEFAULT '{}'`);
+    }
+    catch {
+        // The column is already present.
+    }
 }
 function parseEvent(body) {
     return fromWireEvent(decodeEventBody(body));
@@ -136,14 +150,20 @@ const HeaderRowSchema = Schema.Struct({
     status: RunStateSchema.fields.status,
     kind: Schema.NullOr(Schema.String),
     definition_name: Schema.NullOr(Schema.String),
+    attributes: Schema.String,
 });
 const decodeHeaderRow = Schema.decodeUnknownSync(HeaderRowSchema);
+const encodeAttributes = Schema.encodeSync(Schema.fromJsonString(RunAttributesSchema));
+const encodeSecrets = Schema.encodeSync(Schema.fromJsonString(Schema.Record(Schema.String, Schema.String)));
+const decodeAttributesColumn = Schema.decodeUnknownOption(Schema.fromJsonString(RunAttributesSchema));
+const decodeSecretsColumn = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Record(Schema.String, Schema.String)));
 function headerFromRow(row) {
     return {
         runId: row.run_id,
         status: row.status,
         kind: row.kind,
         definitionName: row.definition_name,
+        attributes: Option.getOrElse(decodeAttributesColumn(row.attributes), () => ({})),
     };
 }
 function createSqliteSnapshotStore(exec) {
@@ -199,23 +219,54 @@ function createSqliteSnapshotStore(exec) {
         }),
         saveHeader: (header) => Effect.try({
             try: () => {
-                exec.run(`INSERT INTO looms_run_headers (run_id, status, kind, definition_name)
-             VALUES (?, ?, ?, ?)
+                exec.run(`INSERT INTO looms_run_headers (run_id, status, kind, definition_name, attributes)
+             VALUES (?, ?, ?, ?, ?)
              ON CONFLICT (run_id) DO UPDATE SET
                status = excluded.status,
                kind = excluded.kind,
-               definition_name = excluded.definition_name`, [header.runId, header.status, header.kind, header.definitionName]);
+               definition_name = excluded.definition_name,
+               attributes = excluded.attributes`, [
+                    header.runId,
+                    header.status,
+                    header.kind,
+                    header.definitionName,
+                    encodeAttributes(header.attributes),
+                ]);
             },
             catch: (cause) => new SnapshotStoreError(`Failed to save run header for ${header.runId}`, cause),
         }),
         listHeaders: Effect.try({
             try: () => exec
-                .rows('SELECT run_id, status, kind, definition_name FROM looms_run_headers')
+                .rows('SELECT run_id, status, kind, definition_name, attributes FROM looms_run_headers')
                 .map((row) => headerFromRow(decodeHeaderRow(row))),
             catch: (cause) => new SnapshotStoreError('Failed to list run headers', cause),
         }),
     };
 }
+const SecretRowSchema = Schema.Struct({ body: Schema.String });
+const decodeSecretRow = Schema.decodeUnknownSync(SecretRowSchema);
+function createSqliteSecrets(exec) {
+    return {
+        get: (runId) => Effect.try({
+            try: () => {
+                const [row] = exec.rows('SELECT body FROM looms_run_secrets WHERE run_id = ?', [runId]);
+                if (row === undefined) {
+                    return {};
+                }
+                return Option.getOrElse(decodeSecretsColumn(decodeSecretRow(row).body), () => ({}));
+            },
+            catch: (cause) => new EventStoreError(`Failed to read secret context for ${runId}`, cause),
+        }),
+        put: (runId, secrets) => Effect.try({
+            try: () => {
+                exec.run(`INSERT INTO looms_run_secrets (run_id, body)
+             VALUES (?, ?)
+             ON CONFLICT (run_id) DO UPDATE SET body = excluded.body`, [runId, encodeSecrets(secrets)]);
+            },
+            catch: (cause) => new EventStoreError(`Failed to store secret context for ${runId}`, cause),
+        }),
+    };
+}
 function createSqliteEventStore(exec) {
     const waiters = new Map();
     const getStream = (runId) => {
@@ -398,6 +449,7 @@ function createSqliteEventStore(exec) {
                 .map((row) => decodeRunIdRow(row).run_id),
             catch: (cause) => new EventStoreError('listRuns failed', cause),
         }),
+        runSecrets: createSqliteSecrets(exec),
     };
     return service;
 }

package/dist/core/state.d.ts

@@ -1,5 +1,8 @@
 import { Schema } from 'effect';
 import { type RuntimeEffect, type WaitCondition } from './effects';
+import { type ChildClose, type RunLaunchSource } from './launcher';
+import { type RunAttributes } from './run-context';
+import { type TraceContext } from './trace';
 import type { JsonValue, ThreadStatus, RunStatus } from './types';
 export interface ThreadRecord {
     threadId: string;
@@ -35,6 +38,8 @@ export interface EffectExecutionRecord {
     /** When the current attempt started executing, locally or on a worker. */
     startedAt: number | null;
     lastHeartbeatAt: number | null;
+    /** Progress reported by the latest heartbeat. Survives retries so the next attempt can resume. */
+    heartbeatDetails: JsonValue | null;
     lastError: string | null;
 }
 export interface RunStartIdentity {
@@ -45,18 +50,29 @@ export interface RunStartIdentity {
     requestedThreadId: string | null;
     idempotencyKey: string | null;
     rootThreadId: string;
+    launchedBy: RunLaunchSource | null;
+    correlationId: string | null;
+    attributes: RunAttributes;
+    /** The caller's W3C trace context. Effects, workers, and launched runs inherit it. */
+    trace: TraceContext | null;
 }
 /** The run and last sequence a fork copied its history from. */
 export interface RunForkSource {
     runId: string;
     seq: number;
 }
+export interface LaunchedRun {
+    runId: string;
+    close: ChildClose;
+}
 export interface RunState {
     runId: string;
     status: RunStatus;
     rootThreadId: string | null;
     startIdentity: RunStartIdentity | null;
     forkedFrom: RunForkSource | null;
+    /** Immutable labels copied from `runtime.run.started`. Safe for every reader of the run. */
+    attributes: RunAttributes;
     threads: {
         [threadId: string]: ThreadRecord;
     };
@@ -69,6 +85,12 @@ export interface RunState {
     };
     completedEffectIds: readonly string[];
     processedIdempotencyKeys: readonly string[];
+    /** Child runs this run launched and has not yet seen settle. */
+    launchedRuns: readonly LaunchedRun[];
+    /** The run is cancelling and will not finish until `wait` children settle. */
+    closeWaiting: boolean;
+    /** Child runs were already asked to stop because this run closed. */
+    childCloseSent: boolean;
 }
 export declare const RunStateSchema: Schema.Struct<{
     readonly runId: Schema.String;
@@ -82,7 +104,21 @@ export declare const RunStateSchema: Schema.Struct<{
         readonly requestedThreadId: Schema.NullOr<Schema.String>;
         readonly idempotencyKey: Schema.NullOr<Schema.String>;
         readonly rootThreadId: Schema.String;
+        readonly launchedBy: Schema.withDecodingDefaultKey<Schema.NullOr<Schema.Struct<{
+            readonly runId: Schema.String;
+            readonly threadId: Schema.String;
+            readonly effectId: Schema.String;
+            readonly causationId: Schema.String;
+            readonly causationSeq: Schema.Finite;
+        }>>, never>;
+        readonly correlationId: Schema.withDecodingDefaultKey<Schema.NullOr<Schema.String>, never>;
+        readonly attributes: Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.String>, never>;
+        readonly trace: Schema.withDecodingDefaultKey<Schema.NullOr<Schema.Struct<{
+            readonly traceparent: Schema.String;
+            readonly tracestate: Schema.optional<Schema.String>;
+        }>>, never>;
     }>>, never>;
+    readonly attributes: Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.String>, never>;
     readonly forkedFrom: Schema.withDecodingDefaultKey<Schema.NullOr<Schema.Struct<{
         readonly runId: Schema.String;
         readonly seq: Schema.Finite;
@@ -150,6 +186,9 @@ export declare const RunStateSchema: Schema.Struct<{
                     readonly actorId: Schema.optional<Schema.String>;
                 }>, Schema.Struct<{
                     readonly type: Schema.Literal<"system">;
+                }>, Schema.Struct<{
+                    readonly type: Schema.Literal<"run">;
+                    readonly runId: Schema.String;
                 }>]>>;
                 readonly ephemeral: Schema.optional<Schema.Boolean>;
                 readonly id: Schema.optional<Schema.String>;
@@ -167,10 +206,24 @@ export declare const RunStateSchema: Schema.Struct<{
             readonly type: Schema.Literal<"runtime.cancel">;
             readonly threadId: Schema.String;
             readonly tag: Schema.optional<Schema.String>;
+        }>, Schema.Struct<{
+            readonly type: Schema.Literal<"runtime.launch">;
+            readonly runId: Schema.String;
+            readonly kind: Schema.String;
+            readonly definitionName: Schema.String;
+            readonly definitionVersion: Schema.withDecodingDefaultKey<Schema.String, never>;
+            readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+            readonly close: Schema.withDecodingDefaultKey<Schema.Union<readonly [Schema.Literal<"terminate">, Schema.Literal<"wait">]>, never>;
+            readonly tag: Schema.optional<Schema.String>;
+        }>, Schema.Struct<{
+            readonly type: Schema.Literal<"runtime.cancelRun">;
+            readonly runId: Schema.String;
+            readonly tag: Schema.optional<Schema.String>;
         }>, Schema.Struct<{
             readonly type: Schema.String;
             readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
             readonly tag: Schema.optional<Schema.String>;
+            readonly at: Schema.optional<Schema.Finite>;
         }>]>;
     }>>;
     readonly effectExecutions: Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.Struct<{
@@ -181,10 +234,17 @@ export declare const RunStateSchema: Schema.Struct<{
         readonly deadlineAt: Schema.withDecodingDefaultKey<Schema.NullOr<Schema.Finite>, never>;
         readonly startedAt: Schema.withDecodingDefaultKey<Schema.NullOr<Schema.Finite>, never>;
         readonly lastHeartbeatAt: Schema.withDecodingDefaultKey<Schema.NullOr<Schema.Finite>, never>;
+        readonly heartbeatDetails: Schema.withDecodingDefaultKey<Schema.NullOr<Schema.Codec<Schema.Json, Schema.Json, never, never>>, never>;
         readonly lastError: Schema.NullOr<Schema.String>;
     }>>, never>;
     readonly completedEffectIds: Schema.withDecodingDefaultKey<Schema.$Array<Schema.String>, never>;
     readonly processedIdempotencyKeys: Schema.withDecodingDefaultKey<Schema.$Array<Schema.String>, never>;
+    readonly launchedRuns: Schema.withDecodingDefaultKey<Schema.$Array<Schema.Struct<{
+        readonly runId: Schema.String;
+        readonly close: Schema.Union<readonly [Schema.Literal<"terminate">, Schema.Literal<"wait">]>;
+    }>>, never>;
+    readonly closeWaiting: Schema.withDecodingDefaultKey<Schema.Boolean, never>;
+    readonly childCloseSent: Schema.withDecodingDefaultKey<Schema.Boolean, never>;
 }>;
 export declare function emptyRunState(runId: string): RunState;
 export declare function isRunTerminal(state: RunState): boolean;

package/dist/core/state.js

@@ -1,8 +1,11 @@
 import { Effect, Predicate, Schema } from 'effect';
 import { RuntimeEffectSchema, WaitConditionSchema, } from './effects.js';
 import { JsonValueSchema } from './envelope.js';
+import { RunLaunchSourceSchema } from './launcher.js';
 import { DEFAULT_DEFINITION_VERSION } from './module.js';
+import { RunAttributesSchema } from './run-context.js';
 import { isTerminalStatus } from './thread.js';
+import { TraceContextSchema } from './trace.js';
 export const RunStateSchema = Schema.Struct({
     runId: Schema.String,
     status: Schema.Union([
@@ -20,7 +23,12 @@ export const RunStateSchema = Schema.Struct({
         requestedThreadId: Schema.NullOr(Schema.String),
         idempotencyKey: Schema.NullOr(Schema.String),
         rootThreadId: Schema.String,
+        launchedBy: Schema.NullOr(RunLaunchSourceSchema).pipe(Schema.withDecodingDefaultKey(Effect.succeed(null))),
+        correlationId: Schema.NullOr(Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed(null))),
+        attributes: RunAttributesSchema.pipe(Schema.withDecodingDefaultKey(Effect.succeed({}))),
+        trace: Schema.NullOr(TraceContextSchema).pipe(Schema.withDecodingDefaultKey(Effect.succeed(null))),
     })).pipe(Schema.withDecodingDefaultKey(Effect.succeed(null))),
+    attributes: RunAttributesSchema.pipe(Schema.withDecodingDefaultKey(Effect.succeed({}))),
     forkedFrom: Schema.NullOr(Schema.Struct({ runId: Schema.String, seq: Schema.Finite })).pipe(Schema.withDecodingDefaultKey(Effect.succeed(null))),
     threads: Schema.Record(Schema.String, Schema.Struct({
         threadId: Schema.String,
@@ -71,10 +79,17 @@ export const RunStateSchema = Schema.Struct({
         deadlineAt: Schema.NullOr(Schema.Finite).pipe(Schema.withDecodingDefaultKey(Effect.succeed(null))),
         startedAt: Schema.NullOr(Schema.Finite).pipe(Schema.withDecodingDefaultKey(Effect.succeed(null))),
         lastHeartbeatAt: Schema.NullOr(Schema.Finite).pipe(Schema.withDecodingDefaultKey(Effect.succeed(null))),
+        heartbeatDetails: Schema.NullOr(JsonValueSchema).pipe(Schema.withDecodingDefaultKey(Effect.succeed(null))),
         lastError: Schema.NullOr(Schema.String),
     })).pipe(Schema.withDecodingDefaultKey(Effect.succeed({}))),
     completedEffectIds: Schema.Array(Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed([]))),
     processedIdempotencyKeys: Schema.Array(Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed([]))),
+    launchedRuns: Schema.Array(Schema.Struct({
+        runId: Schema.String,
+        close: Schema.Union([Schema.Literal('terminate'), Schema.Literal('wait')]),
+    })).pipe(Schema.withDecodingDefaultKey(Effect.succeed([]))),
+    closeWaiting: Schema.Boolean.pipe(Schema.withDecodingDefaultKey(Effect.succeed(false))),
+    childCloseSent: Schema.Boolean.pipe(Schema.withDecodingDefaultKey(Effect.succeed(false))),
 });
 export function emptyRunState(runId) {
     return {
@@ -83,12 +98,16 @@ export function emptyRunState(runId) {
         rootThreadId: null,
         startIdentity: null,
         forkedFrom: null,
+        attributes: {},
         threads: {},
         waits: {},
         outstandingEffects: [],
         effectExecutions: {},
         completedEffectIds: [],
         processedIdempotencyKeys: [],
+        launchedRuns: [],
+        closeWaiting: false,
+        childCloseSent: false,
     };
 }
 export function isRunTerminal(state) {

package/dist/core/store.d.ts

@@ -1,6 +1,7 @@
 import { Context, Effect, Layer, Stream } from 'effect';
 import { type AppendableEvent, type EventEnvelope } from './envelope';
 import { EventPayloadTooLargeError } from './limits';
+import { type RunSecretStore } from './run-context';
 declare const EventStoreError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
     readonly _tag: "EventStoreError";
 } & Readonly<A>;
@@ -165,6 +166,11 @@ export interface EventStore {
         fromSeq?: number;
     }) => Stream.Stream<EventEnvelope, EventStoreError>;
     readonly listRuns: Effect.Effect<string[], EventStoreError>;
+    /**
+     * Run-scoped bearer material. Absent on stores that cannot keep it out of the event log.
+     * A start that supplies secrets fails closed when this is missing.
+     */
+    readonly runSecrets?: RunSecretStore;
 }
 /**
  * Utility to read an EventStore as a Stream.Stream, using `store.readStream` if implemented

package/dist/core/store.js

@@ -1,6 +1,7 @@
 import { Context, Data, Effect, Layer, Option, Queue, Ref, Stream } from 'effect';
 import { withAssignedSeq } from './envelope.js';
 import { assertEventByteLimits, EventPayloadTooLargeError } from './limits.js';
+import { readSecretContext } from './run-context.js';
 export class EventStoreError extends Data.TaggedError('EventStoreError') {
     conflict;
     cause;
@@ -117,6 +118,11 @@ export class EventStoreTag extends Context.Service()('looms/EventStore') {
 }
 export const makeMemoryEventStore = Effect.gen(function* () {
     const logs = yield* Ref.make(new Map());
+    const secrets = yield* Ref.make(new Map());
+    const runSecrets = {
+        get: (runId) => Ref.get(secrets).pipe(Effect.map((map) => readSecretContext(map.get(runId) ?? {}))),
+        put: (runId, value) => Ref.update(secrets, (map) => new Map(map).set(runId, value)),
+    };
     const getOrCreate = (map, runId) => {
         const existing = map.get(runId);
         if (existing) {
@@ -278,6 +284,7 @@ export const makeMemoryEventStore = Effect.gen(function* () {
             }));
         })),
         listRuns: Ref.get(logs).pipe(Effect.map((map) => [...map.keys()])),
+        runSecrets,
     };
     return service;
 });

package/dist/core/subscription.d.ts

@@ -0,0 +1,97 @@
+import type { EventEnvelope } from './envelope';
+import { type JsonValue } from './types';
+/** A socket is closed with this code when the client must resume from `head`. */
+export declare const SUBSCRIPTION_RESYNC_CODE = 4000;
+/** Close a socket that has fallen this far behind instead of buffering without bound. */
+export declare const SUBSCRIPTION_BACKPRESSURE_BYTES: number;
+export type SubscriptionTransport = 'websocket' | 'sse' | 'auto';
+export type SubscriptionResyncReason = 'trimmed' | 'backpressure';
+export interface SubscriptionHello {
+    readonly type: 'hello';
+    readonly head: number;
+    readonly tail: number;
+}
+export interface SubscriptionBatch {
+    readonly type: 'batch';
+    readonly batch: readonly JsonValue[];
+}
+export interface SubscriptionResync {
+    readonly type: 'resync';
+    readonly head: number;
+    readonly reason: SubscriptionResyncReason;
+}
+export type SubscriptionFrame = SubscriptionHello | SubscriptionBatch | SubscriptionResync;
+export interface SubscriptionFilter {
+    readonly threadId: string | null;
+    readonly includeEphemeral: boolean;
+}
+/** State hibernated with a Durable Object WebSocket. Writes stay on HTTP. */
+export interface SubscriptionAttachment {
+    readonly principal: string | null;
+    readonly cursor: number;
+    readonly threadId: string | null;
+    readonly includeEphemeral: boolean;
+}
+export interface SubscriptionSender {
+    send(data: string): void;
+    close(code: number, reason: string): void;
+    readonly bufferedAmount: number;
+}
+export interface AttachedSubscriptionSocket extends SubscriptionSender {
+    attachment(): SubscriptionAttachment | undefined;
+    setAttachment(attachment: SubscriptionAttachment): void;
+}
+export interface SubscriptionPushOptions {
+    readonly bufferLimitBytes?: number;
+    readonly head?: number;
+}
+export type SubscriptionOpening = {
+    readonly kind: 'resync';
+    readonly head: number;
+} | {
+    readonly kind: 'open';
+    readonly hello: SubscriptionHello;
+    readonly events: readonly EventEnvelope[];
+};
+export type SubscriptionRead = {
+    readonly kind: 'events';
+    readonly events: readonly EventEnvelope[];
+} | {
+    readonly kind: 'hello';
+    readonly head: number;
+    readonly tail: number;
+} | {
+    readonly kind: 'resync';
+    readonly head: number;
+    readonly reason: SubscriptionResyncReason;
+} | {
+    readonly kind: 'ignore';
+};
+export declare function encodeSubscriptionFrame(frame: SubscriptionFrame): string;
+export declare function decodeSubscriptionFrame(data: string): SubscriptionFrame | undefined;
+/** One cursor for SSE and WebSocket. `Last-Event-ID` is the last seen seq. */
+export declare function subscriptionFromSeq(url: URL, lastEventId: string | null): {
+    readonly ok: true;
+    readonly fromSeq: number;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+export declare function subscriptionFilter(url: URL): SubscriptionFilter;
+export declare function subscriptionReplay(head: number, fromSeq: number): {
+    readonly kind: 'resync';
+    readonly head: number;
+} | {
+    readonly kind: 'play';
+    readonly fromSeq: number;
+};
+export declare function eventMatchesSubscription(event: EventEnvelope, filter: SubscriptionFilter): boolean;
+export declare function attachmentFromFilter(filter: SubscriptionFilter, fromSeq: number, principal: string | null): SubscriptionAttachment;
+export declare function readSubscriptionData(data: string, runId: string): SubscriptionRead;
+/**
+ * Sends the events this attachment still needs. Returns the advanced attachment,
+ * or `undefined` after the socket is closed for resync.
+ */
+export declare function pushSubscriptionEvents(socket: SubscriptionSender, events: readonly EventEnvelope[], attachment: SubscriptionAttachment, options?: SubscriptionPushOptions): SubscriptionAttachment | undefined;
+export declare function openSubscription(socket: SubscriptionSender, attachment: SubscriptionAttachment, opening: SubscriptionOpening, options?: SubscriptionPushOptions): SubscriptionAttachment | undefined;
+export declare function fanoutSubscription(sockets: readonly AttachedSubscriptionSocket[], events: readonly EventEnvelope[], options?: SubscriptionPushOptions): void;