stitchkit 0.74.0 → 0.75.0

package/dist/internal/sqlite.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The minimal synchronous SQLite boundary the framework types against.
+ *
+ * Deliberately three methods and nothing else: it is satisfied structurally by
+ * `bun:sqlite`'s `Database` and by a thin wrapper over `node:sqlite`, so a
+ * caller passes the handle it already holds instead of adopting a driver of
+ * ours. → ADR 0142.
+ *
+ * One name for one thing. This was `AgentRuntimeSqliteDatabase` while the agent
+ * runtime was its only user; a second user made the name wrong rather than
+ * merely long — a keyspace typed against an `AgentRuntime*` boundary reads as
+ * a dependency on the agent runtime, which it is not.
+ */
+export type SqliteValue = string | number | bigint | null | Uint8Array;
+export interface SqliteStatement {
+    get(...parameters: SqliteValue[]): unknown;
+    all(...parameters: SqliteValue[]): readonly unknown[];
+    run(...parameters: SqliteValue[]): {
+        changes: number;
+    };
+}
+export interface SqliteDatabase {
+    exec(sql: string): void;
+    prepare(sql: string): SqliteStatement;
+    close(): void;
+}
+//# sourceMappingURL=sqlite.d.ts.map

package/dist/internal/sqlite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite.d.ts","sourceRoot":"","sources":["../../src/internal/sqlite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,UAAU,CAAC;AAEvE,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,GAAG,UAAU,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC;IAC3C,GAAG,CAAC,GAAG,UAAU,EAAE,WAAW,EAAE,GAAG,SAAS,OAAO,EAAE,CAAC;IACtD,GAAG,CAAC,GAAG,UAAU,EAAE,WAAW,EAAE,GAAG;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACxD;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAAC;IACtC,KAAK,IAAI,IAAI,CAAC;CACf"}

package/dist/internal/stable-digest.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The value with every object's keys sorted, recursively — arrays keep their
+ * order, because in an array order *is* the value.
+ *
+ * `Object.keys` returns own enumerable keys only, so nothing from a prototype
+ * reaches the digest.
+ */
+export declare function stableValue(value: unknown): unknown;
+/**
+ * A bounded, order-independent digest of a call's arguments.
+ *
+ * SHA-256 over the key-sorted JSON, base64url without padding. Bounded because
+ * the key travels on the wire and arguments do not have a bounded size; a hash
+ * rather than the JSON itself so a large argument object does not become a
+ * large subscription key repeated in every frame.
+ *
+ * What it cannot do, stated because the limit is easy to walk into: values
+ * `JSON.stringify` drops or transforms — `undefined` members, a `Date`, a `Map`,
+ * a `BigInt` (which throws) — are not distinguished, or not survivable, here.
+ * Contract arguments are parsed JSON, so this is the argument shape by
+ * construction; a caller digesting something else has to say what it means.
+ */
+export declare function argumentsDigest(args: Record<string, unknown>): Promise<string>;
+//# sourceMappingURL=stable-digest.d.ts.map

package/dist/internal/stable-digest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stable-digest.d.ts","sourceRoot":"","sources":["../../src/internal/stable-digest.ts"],"names":[],"mappings":"AAkBA;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAQnD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAGpF"}

package/dist/live/events.d.ts

@@ -0,0 +1,155 @@
+/**
+ * An event declaration beside the operation contract.
+ *
+ * `defineContract` says what a caller may *ask*. This says what the server may
+ * *announce*: a topic, the schema of its one payload, and how it is delivered
+ * to listeners in this process. One declaration, so a topic cannot be published
+ * in one shape and parsed in another — the failure `defineContract` exists to
+ * make impossible for requests, made impossible for announcements too.
+ *
+ * **This is a declaration, not a transport.** The wire is the Socket.IO realtime
+ * contract stitchkit already ships: {@link toRealtimeContract} projects this
+ * declaration onto `RealtimeContract`, and `bindRealtimeServer` /
+ * `bindRealtimeClient` carry it with the validation, rejection reporting and
+ * room semantics they already have. There is no second socket, no second
+ * validator and no second `on()`. That is deliberate and it is the whole point:
+ * ADR 0009 records a hand-rolled event stack in this repository that reached
+ * about 700 lines, was never adopted by a single consumer, and was deleted —
+ * with the lesson written into ADR 0008 as *wrap the transport the consumers
+ * already run on*. This declaration does not reopen that decision.
+ *
+ * → ADR 0150.
+ */
+import { z } from 'zod';
+import type { RealtimeContract, RealtimeEventRegistry } from '../realtime/contract.js';
+/**
+ * How a topic reaches the listeners registered for it **in this process**.
+ *
+ * Delivery to remote subscribers is always observation: a browser cannot delay
+ * or veto a server's announcement, so the mode says nothing about the wire. It
+ * says what the *server's own* listeners may do.
+ *
+ * - `emit` — announce and continue. Listeners run concurrently, a failing one
+ *   is isolated from the others, and the caller does not wait.
+ * - `serial` — listeners run one at a time, in registration order, and the
+ *   caller waits for all of them. For work whose order is the point.
+ * - `decision` — listeners vote. Each returns `allow`, `deny` with a reason, or
+ *   `defer`; the first `deny` wins and the rest are not consulted.
+ */
+export type EventDeliveryMode = 'emit' | 'serial' | 'decision';
+/**
+ * One listener's vote on a `decision` topic.
+ *
+ * `defer` is a real answer — "not my call" — and it is distinct from `allow` on
+ * purpose: an event where every listener defers is one nobody claimed, and what
+ * should happen then is a policy the topic has to state rather than a default
+ * somebody guesses. See `whenAllDefer`.
+ */
+export type EventDecision = {
+    readonly outcome: 'allow';
+} | {
+    readonly outcome: 'deny';
+    readonly reason: string;
+} | {
+    readonly outcome: 'defer';
+};
+/** What a `decision` topic concludes when every listener deferred, or there were none. */
+export type EventUndecided = 'allow' | 'deny';
+export interface EventTopicDeclaration<TSchema extends z.ZodType = z.ZodType> {
+    /** The payload schema. One payload per topic — a topic is not a function call. */
+    readonly schema: TSchema;
+    readonly mode: EventDeliveryMode;
+    /**
+     * Required on a `decision` topic, refused on any other.
+     *
+     * There is no default, and that is the point: whichever value were chosen as
+     * the default would be a standing `allow` or a standing `deny` applied to
+     * every topic whose author never thought about it. Both are decisions; a
+     * default makes them silently.
+     */
+    readonly whenAllDefer?: EventUndecided;
+    /**
+     * How long one listener may take on a `serial` or `decision` topic before the
+     * dispatcher stops waiting for it, in milliseconds.
+     *
+     * Required on those two modes, refused on `emit` (which never waits). A
+     * listener that never settles would otherwise hang the caller forever, and a
+     * caller hanging forever is indistinguishable from a caller doing work.
+     * A `decision` listener that runs out of time votes `deny` — a vote that
+     * never arrived cannot be read as consent.
+     */
+    readonly listenerTimeoutMs?: number;
+}
+export type EventTopicRegistry = Record<string, EventTopicDeclaration>;
+export interface EventsConfig {
+    /**
+     * Prefixed onto every topic name, separated by a dot.
+     *
+     * The prefixed form is the **only** name the topic has: it is the key of the
+     * declaration's `topics`, the event name on the wire, and the string passed to
+     * `on`. The short key in the literal is where the full name is built, not a
+     * second name for the same topic — a topic addressable two ways is a topic
+     * that will be published one way and subscribed the other.
+     */
+    readonly prefix?: string;
+}
+/** The wire name of a topic: `prefix.name`, or just `name` when no prefix is declared. */
+export type WireTopic<TPrefix, TName extends string> = TPrefix extends string ? `${TPrefix}.${TName}` : TName;
+export interface EventsDeclaration<TPrefix extends string | undefined, TTopics extends EventTopicRegistry> {
+    readonly prefix: TPrefix;
+    /** Keyed by wire topic — see {@link EventsConfig.prefix}. */
+    readonly topics: {
+        readonly [TName in keyof TTopics & string as WireTopic<TPrefix, TName>]: TTopics[TName];
+    };
+}
+/** The payload type of each topic, keyed by its wire name. */
+export type EventPayloads<TDeclaration> = TDeclaration extends EventsDeclaration<infer _TPrefix, infer _TTopics> ? {
+    [TTopic in keyof TDeclaration['topics']]: TDeclaration['topics'][TTopic] extends {
+        schema: infer TSchema extends z.ZodType;
+    } ? z.output<TSchema> : never;
+} : never;
+/** Topics of one declaration whose declared mode is `TMode`. */
+export type EventTopicsOfMode<TDeclaration, TMode extends EventDeliveryMode> = TDeclaration extends EventsDeclaration<infer _TPrefix, infer _TTopics> ? {
+    [TTopic in keyof TDeclaration['topics']]: TDeclaration['topics'][TTopic] extends {
+        mode: TMode;
+    } ? TTopic : never;
+}[keyof TDeclaration['topics']] & string : never;
+/**
+ * Declare a set of topics.
+ *
+ * ```ts
+ * const events = defineEvents(
+ *   { prefix: 'notes' },
+ *   {
+ *     'changed': { schema: z.object({ folder: z.string() }), mode: 'emit' },
+ *     'archiving': {
+ *       schema: z.object({ folder: z.string() }),
+ *       mode: 'decision',
+ *       whenAllDefer: 'allow',
+ *       listenerTimeoutMs: 2_000,
+ *     },
+ *   },
+ * );
+ * // events.topics has the keys 'notes.changed' and 'notes.archiving'
+ * ```
+ */
+export declare function defineEvents<const TConfig extends EventsConfig, const TTopics extends EventTopicRegistry>(config: TConfig, topics: TTopics): EventsDeclaration<TConfig extends {
+    prefix: infer TPrefix extends string;
+} ? TPrefix : undefined, TTopics>;
+/**
+ * Project a declaration onto the realtime contract, so the existing validated
+ * socket carries it.
+ *
+ * A realtime event's `args` is the **tuple of wire arguments**, not a payload,
+ * so a one-payload topic becomes a one-element tuple. That single mapping is the
+ * only place the two shapes meet, and it is why a test that binds one
+ * declaration to both ends proves less than it looks: both ends would project
+ * identically, so a wrong projection stays invisible. The test that measures it
+ * injects a raw frame past the validating wrapper.
+ *
+ * Announcements travel server → client. `clientToServer` is empty by
+ * construction: a client that could publish a server's topic would make the
+ * declared publisher a suggestion.
+ */
+export declare function toRealtimeContract<TPrefix extends string | undefined, TTopics extends EventTopicRegistry>(declaration: EventsDeclaration<TPrefix, TTopics>): RealtimeContract<RealtimeEventRegistry, Record<string, never>>;
+//# sourceMappingURL=events.d.ts.map

package/dist/live/events.d.ts.map

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

package/dist/live/watch-client.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The client half of a watched read.
+ *
+ * `watch.notes.list({ folder: 'a' })` returns a handle. Subscribe to it and the
+ * values arrive; unsubscribe and, once nobody is left, the server is told to
+ * stop reading. Two components asking the same question share one subscription
+ * and one server-side read, which is the arrangement the hub exists for and
+ * which a per-component `useEffect` cannot reach.
+ *
+ * ## Why it is built from the contract, not from a method
+ *
+ * `watch(api.notes.list, args)` is the shape one would write first, and it
+ * cannot work: a client method is a bare closure with a `withOptions` property
+ * and no identity on it, deliberately — it has to survive being handed to a
+ * `map`. Passing one here gives an anonymous function, and the server needs to
+ * know *what* to re-read. So the watch client is built from the contract, like
+ * `createUrlBuilder`, and the identity is the contract's own
+ * `(prefix, endpoint key)` — the same pair the server labels every request with.
+ *
+ * ## Retention
+ *
+ * The last value of a key is kept while anyone holds it, and for `holdMs` after
+ * the last subscriber leaves. A component that unmounts and remounts inside that
+ * window paints immediately from memory. The key digest is cached too, so the
+ * second subscription resolves synchronously — computing it is a promise, and a
+ * value that arrives on a later microtask is not "before the network" in any
+ * sense a rendering component can use.
+ */
+import type { ContractDef, EndpointDef } from '../contract/define.js';
+import { type WatchKey, type WatchStateFrame } from './watch-contract.js';
+export interface WatchListeners<TValue> {
+    value(value: TValue): void;
+    /** Phase and, when unhealthy, the read's own code and message. */
+    state?(state: WatchStateFrame): void;
+}
+export interface WatchHandle<TValue> {
+    /** Returns the unsubscribe. The retained value, if any, arrives before it returns. */
+    subscribe(listeners: WatchListeners<TValue>): () => void;
+    /** Drops every listener this handle registered and releases the key. */
+    close(): void;
+}
+/** The transport half a watch client needs — a bound realtime client for `watchContract`. */
+export interface WatchTransport {
+    on(event: string, handler: (payload: never) => void): () => void;
+    emit(event: string, payload: unknown): void;
+    request(event: string, payload: unknown, options: {
+        timeoutMs: number;
+    }): Promise<{
+        accepted: boolean;
+        reason?: string;
+    }>;
+}
+export interface WatchClientConfig {
+    readonly transport: WatchTransport;
+    /** How long a key's value is retained after its last subscriber. Default 0. */
+    readonly holdMs?: number;
+    /** Deadline for the `open` acknowledgement. Default 10000. */
+    readonly openTimeoutMs?: number;
+    /** Called when the server refuses to open a watch, in its own words. */
+    readonly onRefused?: (key: WatchKey, reason: string) => void;
+}
+export type TypedWatchClient<T extends Record<string, EndpointDef>> = {
+    [K in keyof T]: (args?: Record<string, unknown>) => WatchHandle<unknown>;
+};
+export declare function createWatchClient<T extends Record<string, EndpointDef>>(contract: ContractDef<T, string>, config: WatchClientConfig): TypedWatchClient<T>;
+//# sourceMappingURL=watch-client.d.ts.map

package/dist/live/watch-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-client.d.ts","sourceRoot":"","sources":["../../src/live/watch-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEnE,OAAO,EAKL,KAAK,QAAQ,EACb,KAAK,eAAe,EAGrB,MAAM,kBAAkB,CAAC;AAE1B,MAAM,WAAW,cAAc,CAAC,MAAM;IACpC,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,kEAAkE;IAClE,KAAK,CAAC,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,WAAW,CAAC,MAAM;IACjC,sFAAsF;IACtF,SAAS,CAAC,SAAS,EAAE,cAAc,CAAC,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC;IACzD,wEAAwE;IACxE,KAAK,IAAI,IAAI,CAAC;CACf;AAED,6FAA6F;AAC7F,MAAM,WAAW,cAAc;IAC7B,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,KAAK,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACjE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5C,OAAO,CACL,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAC7B,OAAO,CAAC;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACpD;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,wEAAwE;IACxE,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9D;AAcD,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,IAAI;KACnE,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,WAAW,CAAC,OAAO,CAAC;CACzE,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACrE,QAAQ,EAAE,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,EAChC,MAAM,EAAE,iBAAiB,GACxB,gBAAgB,CAAC,CAAC,CAAC,CAqKrB"}

package/dist/live/watch-contract.d.ts

@@ -0,0 +1,157 @@
+/**
+ * The wire protocol of a watched read — one contract, shared by both ends.
+ *
+ * A watched read is a GET that the server re-runs when something it depends on
+ * changes, pushing the new answer to everyone watching. The protocol is four
+ * events on the realtime contract the application already runs, and it is
+ * declared once here so the hub and the client cannot drift: a second copy of
+ * these shapes on the client is exactly the hand-written frame parsing that
+ * `defineContract` exists to end.
+ *
+ * The state vocabulary is `LiveStatePhase` and `LiveStateStopReason` — the ones
+ * the live-state controller already publishes — and not a second, poorer pair.
+ * A reader with one component on a controller's phase and another on a watch's
+ * state must be able to compare them, and `live | unavailable` beside
+ * `idle | opening | live | resync-required | unavailable | closed` cannot be
+ * compared at all. It also supplies the third answer a two-word vocabulary
+ * loses: `opening` — subscribed, nothing read yet — which is neither healthy nor
+ * broken, and rendering it as "unavailable" tells a user something is wrong when
+ * the truth is that it is early.
+ */
+import { z } from 'zod';
+/** The identity of one watched read: an operation plus the arguments it was asked with. */
+export declare const WatchKeySchema: z.ZodReadonly<z.ZodObject<{
+    service: z.ZodString;
+    action: z.ZodString;
+    digest: z.ZodString;
+}, z.core.$strict>>;
+export type WatchKey = z.infer<typeof WatchKeySchema>;
+export declare const WatchOpenSchema: z.ZodReadonly<z.ZodObject<{
+    key: z.ZodReadonly<z.ZodObject<{
+        service: z.ZodString;
+        action: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>>;
+    args: z.ZodUnknown;
+}, z.core.$strip>>;
+export declare const WatchAcceptedSchema: z.ZodReadonly<z.ZodObject<{
+    accepted: z.ZodBoolean;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
+export declare const WatchValueSchema: z.ZodReadonly<z.ZodObject<{
+    key: z.ZodReadonly<z.ZodObject<{
+        service: z.ZodString;
+        action: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>>;
+    revision: z.ZodNumber;
+    value: z.ZodUnknown;
+}, z.core.$strip>>;
+export declare const WatchStateSchema: z.ZodReadonly<z.ZodObject<{
+    key: z.ZodReadonly<z.ZodObject<{
+        service: z.ZodString;
+        action: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>>;
+    phase: z.ZodEnum<{
+        closed: "closed";
+        idle: "idle";
+        live: "live";
+        opening: "opening";
+        "resync-required": "resync-required";
+        unavailable: "unavailable";
+    }>;
+    reason: z.ZodOptional<z.ZodEnum<{
+        "buffer-overflow": "buffer-overflow";
+        "controller-capacity": "controller-capacity";
+        "controller-error": "controller-error";
+        gap: "gap";
+        "source-error": "source-error";
+        "source-unavailable": "source-unavailable";
+    }>>;
+    code: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+export type WatchValueFrame = z.infer<typeof WatchValueSchema>;
+export type WatchStateFrame = z.infer<typeof WatchStateSchema>;
+export declare const WATCH_OPEN = "stitchkit.watch.open";
+export declare const WATCH_CLOSE = "stitchkit.watch.close";
+export declare const WATCH_VALUE = "stitchkit.watch.value";
+export declare const WATCH_STATE = "stitchkit.watch.state";
+/**
+ * The realtime contract a watched read travels on.
+ *
+ * Merge it into the application's own contract — `{ serverToClient: {...app,
+ * ...watchContract.serverToClient}, … }` — or bind it on its own. Event names
+ * are namespaced so a merge cannot collide with an application's topics.
+ */
+export declare const watchContract: {
+    readonly serverToClient: {
+        readonly "stitchkit.watch.value": {
+            readonly args: z.ZodTuple<[z.ZodReadonly<z.ZodObject<{
+                key: z.ZodReadonly<z.ZodObject<{
+                    service: z.ZodString;
+                    action: z.ZodString;
+                    digest: z.ZodString;
+                }, z.core.$strict>>;
+                revision: z.ZodNumber;
+                value: z.ZodUnknown;
+            }, z.core.$strip>>], null>;
+        };
+        readonly "stitchkit.watch.state": {
+            readonly args: z.ZodTuple<[z.ZodReadonly<z.ZodObject<{
+                key: z.ZodReadonly<z.ZodObject<{
+                    service: z.ZodString;
+                    action: z.ZodString;
+                    digest: z.ZodString;
+                }, z.core.$strict>>;
+                phase: z.ZodEnum<{
+                    closed: "closed";
+                    idle: "idle";
+                    live: "live";
+                    opening: "opening";
+                    "resync-required": "resync-required";
+                    unavailable: "unavailable";
+                }>;
+                reason: z.ZodOptional<z.ZodEnum<{
+                    "buffer-overflow": "buffer-overflow";
+                    "controller-capacity": "controller-capacity";
+                    "controller-error": "controller-error";
+                    gap: "gap";
+                    "source-error": "source-error";
+                    "source-unavailable": "source-unavailable";
+                }>>;
+                code: z.ZodOptional<z.ZodString>;
+                message: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>], null>;
+        };
+    };
+    readonly clientToServer: {
+        readonly "stitchkit.watch.open": {
+            readonly args: z.ZodTuple<[z.ZodReadonly<z.ZodObject<{
+                key: z.ZodReadonly<z.ZodObject<{
+                    service: z.ZodString;
+                    action: z.ZodString;
+                    digest: z.ZodString;
+                }, z.core.$strict>>;
+                args: z.ZodUnknown;
+            }, z.core.$strip>>], null>;
+            readonly ack: z.ZodReadonly<z.ZodObject<{
+                accepted: z.ZodBoolean;
+                reason: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+        };
+        readonly "stitchkit.watch.close": {
+            readonly args: z.ZodTuple<[z.ZodReadonly<z.ZodObject<{
+                key: z.ZodReadonly<z.ZodObject<{
+                    service: z.ZodString;
+                    action: z.ZodString;
+                    digest: z.ZodString;
+                }, z.core.$strict>>;
+            }, z.core.$strip>>], null>;
+        };
+    };
+};
+/** The wire key as one string — what a map is keyed by on both ends. */
+export declare function watchKeyString(key: WatchKey): string;
+//# sourceMappingURL=watch-contract.d.ts.map

package/dist/live/watch-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-contract.d.ts","sourceRoot":"","sources":["../../src/live/watch-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,2FAA2F;AAC3F,eAAO,MAAM,cAAc;;;;mBAkBd,CAAC;AACd,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD,eAAO,MAAM,eAAe;;;;;;;kBAAkE,CAAC;AAE/F,eAAO,MAAM,mBAAmB;;;mBAOnB,CAAC;AAEd,eAAO,MAAM,gBAAgB;;;;;;;;kBAUhB,CAAC;AAEd,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;kBAShB,CAAC;AAEd,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC/D,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE/D,eAAO,MAAM,UAAU,yBAAyB,CAAC;AACjD,eAAO,MAAM,WAAW,0BAA0B,CAAC;AACnD,eAAO,MAAM,WAAW,0BAA0B,CAAC;AACnD,eAAO,MAAM,WAAW,0BAA0B,CAAC;AAEnD;;;;;;GAMG;AACH,eAAO,MAAM,aAAa;;;qBAEL,IAAI;;;;;;;;;;;qBACJ,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAGL,IAAI;;;;;;;;qBAA8B,GAAG;;;;;;qBACpC,IAAI;;;;;;;;;CAKxB,CAAC;AAEF,wEAAwE;AACxE,wBAAgB,cAAc,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,CAEpD"}

package/dist/live.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `stitchkit/live` — declarations for the things that change while a caller is
+ * watching: announcements and watched reads.
+ *
+ * Browser-safe and evolving. Browser-safe because both halves are declarations
+ * plus a client, and a client that cannot run in a browser is not a client.
+ * Evolving because the shape here is being found with its first consumers — the
+ * entrypoint says so rather than leaving a reader to discover it in a minor.
+ *
+ * What lives here is deliberately small: this entrypoint owns no transport. The
+ * wire is the Socket.IO realtime contract from `stitchkit`, the in-process
+ * delivery is `createEventBus` from `stitchkit/server`, and the server halves of
+ * a watched read live in `stitchkit/application`. → ADR 0150.
+ */
+export { defineEvents, type EventDecision, type EventDeliveryMode, type EventPayloads, type EventsConfig, type EventsDeclaration, type EventTopicDeclaration, type EventTopicRegistry, type EventTopicsOfMode, type EventUndecided, toRealtimeContract, type WireTopic, } from './live/events.js';
+export { createWatchClient, type TypedWatchClient, type WatchClientConfig, type WatchHandle, type WatchListeners, type WatchTransport, } from './live/watch-client.js';
+export { WATCH_CLOSE, WATCH_OPEN, WATCH_STATE, WATCH_VALUE, type WatchKey, WatchKeySchema, type WatchStateFrame, WatchStateSchema, type WatchValueFrame, WatchValueSchema, watchContract, watchKeyString, } from './live/watch-contract.js';
+//# sourceMappingURL=live.d.ts.map

package/dist/live.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live.d.ts","sourceRoot":"","sources":["../src/live.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EACL,YAAY,EACZ,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,kBAAkB,EAClB,KAAK,SAAS,GACf,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,iBAAiB,EACjB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,WAAW,EACX,UAAU,EACV,WAAW,EACX,WAAW,EACX,KAAK,QAAQ,EACb,cAAc,EACd,KAAK,eAAe,EACpB,gBAAgB,EAChB,KAAK,eAAe,EACpB,gBAAgB,EAChB,aAAa,EACb,cAAc,GACf,MAAM,uBAAuB,CAAC"}