@loopbacktools/server 0.0.0-stage → 0.4.1

package/dist/src/space/operations.js

@@ -0,0 +1,568 @@
+import { answerEntries, answersProblem, foldBriefing, } from "@loopbacktools/protocol";
+import { Clock, Duration, Effect, Option, PubSub } from "effect";
+import { briefingPrompt, checkReply, checkSize, fingerprint, imagesIn, questionPrompt, REATTACH_WINDOW_MS, reviewPrompt, sha256, statusAfter, toAsk, } from "../domain/ask.js";
+import { AskClosed, AskNotFound, ContentInvalid, NotYourTurn, TicketInvalid, UploadExpired, UploadNotFound, UploadRejected, } from "../domain/errors.js";
+import { Host, MAX_WAIT_MS, Presence, Replies } from "./services.js";
+import { AskStore, TicketStore, UploadStore } from "./store.js";
+/** How many closed asks a snapshot carries. */
+export const RECENT_LIMIT = 50;
+/** How long an upload ticket stays usable. */
+export const UPLOAD_TTL_MS = 15 * 60 * 1000;
+/** How long an event ticket stays usable: long enough to open a socket, too short to be worth stealing. */
+export const TICKET_TTL_MS = 60 * 1000;
+/** The largest image an upload ticket accepts. */
+export const UPLOAD_MAX_BYTES = 10 * 1024 * 1024;
+const now = Effect.map(Clock.currentTimeMillis, (ms) => new Date(ms).toISOString());
+/** A fresh 256-bit secret, URL- and subprotocol-safe. */
+const secret = () => btoa(String.fromCharCode(...crypto.getRandomValues(new Uint8Array(32))))
+    .replaceAll("+", "-")
+    .replaceAll("/", "_")
+    .replace(/=+$/, "");
+const findAsk = Effect.fnUntraced(function* (askId) {
+    const store = yield* AskStore;
+    const found = yield* store.find(askId);
+    if (Option.isNone(found))
+        return yield* new AskNotFound({ askId });
+    return found.value;
+});
+/** How often an agent's waiting is written down: often enough for the reattach window, no more. */
+const NOTE_WAITING_EVERY_MS = 60_000;
+/** Writes down that an agent is waiting on the ask, unless that was done within the last minute. */
+const noteWaiting = Effect.fnUntraced(function* (record, at) {
+    const since = record.lastWaitedAt === null ? Infinity : Date.parse(at) - Date.parse(record.lastWaitedAt);
+    if (since < NOTE_WAITING_EVERY_MS)
+        return;
+    const store = yield* AskStore;
+    yield* store.touchWaited(record.id, at);
+});
+/** The ask in its wire shape, with its thread and whether an agent is waiting on it. */
+const view = Effect.fnUntraced(function* (record) {
+    const store = yield* AskStore;
+    const presence = yield* Presence;
+    return toAsk(record, yield* store.thread(record.id), presence.isWaiting(record.id));
+});
+/** The asks in their wire shape, leaving out any whose thread can't be read. */
+const views = Effect.fnUntraced(function* (records) {
+    const store = yield* AskStore;
+    const presence = yield* Presence;
+    const threads = yield* store.threads(records.map((record) => record.id));
+    return records.flatMap((record) => {
+        const thread = threads.get(record.id);
+        return thread === undefined ? [] : [toAsk(record, thread, presence.isWaiting(record.id))];
+    });
+});
+const announce = Effect.fnUntraced(function* (type, ask) {
+    const host = yield* Host;
+    yield* host.broadcast({ type, ask });
+});
+/** Every inbox hears the ask as it now stands, since an agent started or stopped following it. */
+const announceFollowing = (askId) => Effect.flatMap(findAsk(askId), view).pipe(Effect.flatMap((ask) => announce("ask.updated", ask)), Effect.ignoreCause({ log: true }));
+/** A lap or poll begins on the ask; inboxes hear it when that starts the ask being followed. */
+const follow = Effect.fnUntraced(function* (askId) {
+    const presence = yield* Presence;
+    if (yield* presence.begin(askId))
+        yield* announceFollowing(askId);
+});
+/** A lap or poll ends; inboxes hear it if no other begins within the grace. */
+const unfollow = Effect.fnUntraced(function* (askId) {
+    const presence = yield* Presence;
+    yield* presence.end(askId, announceFollowing(askId));
+});
+/** Every image the blocks show must be an upload this space holds. */
+const checkImages = Effect.fnUntraced(function* (blocks) {
+    const uploads = yield* UploadStore;
+    for (const uploadId of imagesIn(blocks)) {
+        const upload = yield* uploads.find(uploadId);
+        if (Option.isNone(upload) || upload.value.status !== "stored") {
+            return yield* new ContentInvalid({
+                reason: `No uploaded image "${uploadId}". Upload it with create_image_upload first.`,
+            });
+        }
+    }
+});
+/** Everything a set of briefing points shows. */
+const blocksOf = (points) => points.flatMap((point) => point.content ?? []);
+/**
+ * Opens an ask, or rejoins the one a retried call opened. A retry is the same question or review,
+ * from the same client and project, while the ask is still open or holds a reply that never
+ * reached the agent, and only if an agent waited on it within the reattach window.
+ */
+export const open = Effect.fn("Space.open")(function* (request) {
+    const store = yield* AskStore;
+    yield* checkSize(request.input, `Show the part that matters, or split it into several ${request.kind}s.`);
+    const at = yield* now;
+    const key = yield* fingerprint({
+        kind: request.kind,
+        client: request.client ?? null,
+        actor: request.actor.id,
+        input: request.input,
+    });
+    const since = new Date(Date.parse(at) - REATTACH_WINDOW_MS).toISOString();
+    const retried = yield* store.findRetry(key, since);
+    if (Option.isSome(retried)) {
+        yield* noteWaiting(retried.value, at);
+        return yield* view(retried.value);
+    }
+    if (request.kind === "review") {
+        yield* checkImages(request.input.content);
+        if (request.input.revises !== undefined) {
+            const revised = yield* store.find(request.input.revises);
+            if (Option.isNone(revised) || revised.value.kind !== "review") {
+                return yield* new ContentInvalid({
+                    reason: `"revises" names no review: "${request.input.revises}".`,
+                });
+            }
+        }
+    }
+    const head = {
+        id: crypto.randomUUID(),
+        key,
+        status: "awaiting_human",
+        project: request.input.project ?? null,
+        client: request.client ?? null,
+        raisedBy: request.actor,
+        createdAt: at,
+        updatedAt: at,
+        closedAt: null,
+        lastWaitedAt: at,
+    };
+    let record;
+    switch (request.kind) {
+        case "question":
+            record = { ...head, kind: "question", prompt: questionPrompt(request.input) };
+            break;
+        case "review":
+            record = {
+                ...head,
+                kind: "review",
+                prompt: reviewPrompt(request.input),
+                revises: request.input.revises ?? null,
+            };
+            break;
+        case "briefing": {
+            const prompt = yield* briefingPrompt(request.input);
+            yield* checkImages(blocksOf(request.input.sections.flatMap((section) => section.points)));
+            record = { ...head, kind: "briefing", prompt };
+            break;
+        }
+    }
+    yield* store.insert(record);
+    const ask = yield* view(record);
+    yield* announce("ask.opened", ask);
+    return ask;
+});
+/**
+ * Records the agent's answer to a question the person asked back, and hands the move back to them.
+ * Sending the same answer again while it is already their move is a retry, and changes nothing.
+ */
+export const answerFollowUp = Effect.fn("Space.answerFollowUp")(function* (input) {
+    const store = yield* AskStore;
+    const presence = yield* Presence;
+    const record = yield* findAsk(input.askId);
+    if (record.kind === "briefing") {
+        return yield* new ContentInvalid({
+            reason: "This is a briefing: answer it with answer_briefing, on each point.",
+        });
+    }
+    if (record.status === "closed")
+        return yield* new AskClosed({ askId: record.id });
+    if (record.status === "awaiting_human") {
+        const thread = yield* store.thread(record.id);
+        const last = thread.at(-1)?.entry;
+        const same = last?.author === "agent" &&
+            last.answer === input.answer &&
+            JSON.stringify(last.content ?? []) === JSON.stringify(input.content ?? []);
+        if (same)
+            return toAsk(record, thread, presence.isWaiting(record.id));
+        return yield* new NotYourTurn({ askId: record.id, turn: "human" });
+    }
+    yield* checkSize({ answer: input.answer, content: input.content });
+    yield* checkImages(input.content ?? []);
+    const at = yield* now;
+    yield* store.transaction(Effect.gen(function* () {
+        // Answering the person's question shows the agent had it.
+        yield* store.markAllDelivered(record.id, at);
+        yield* store.append(record.id, {
+            author: "agent",
+            answer: input.answer,
+            ...(input.content === undefined ? {} : { content: input.content }),
+            at,
+        });
+        yield* store.setStatus(record.id, "awaiting_human", at);
+        yield* store.touchWaited(record.id, at);
+    }));
+    const ask = yield* view({ ...record, status: "awaiting_human", updatedAt: at });
+    yield* announce("ask.updated", ask);
+    return ask;
+});
+/** Whether a recorded agent entry is this answer, as a retried move would send it again. */
+const sameAnswer = (entry, answer) => entry.point === answer.point &&
+    entry.answer === answer.answer &&
+    JSON.stringify(entry.content ?? []) === JSON.stringify(answer.content ?? []) &&
+    JSON.stringify((entry.points ?? []).map(({ id: _, ...point }) => point)) ===
+        JSON.stringify(answer.points ?? []);
+/**
+ * The turn a retried move rejoins, if it is one: the agent's latest move is this same move, and
+ * nothing the person sent since has reached the agent. Once any reply after the move has reached it,
+ * the agent has seen past the move, so the same words again are a new move, never a retry.
+ */
+const rejoins = (thread, answers) => {
+    const last = thread.findLastIndex((row) => row.entry.author === "agent");
+    if (last + 1 < answers.length)
+        return undefined;
+    const move = thread.slice(last + 1 - answers.length, last + 1);
+    const same = move.every((row, n) => {
+        const answer = answers[n];
+        return row.entry.author === "agent" && answer !== undefined && sameAnswer(row.entry, answer);
+    });
+    if (!same)
+        return undefined;
+    const since = thread.slice(last + 1);
+    return since.every((row) => row.deliveredAt === null) ? thread[last]?.seq : undefined;
+};
+/**
+ * Records the agent's answers on a briefing, one thread entry per point, numbering any sub-points,
+ * and hands the move back to the person. A move sent again before its reply reached the agent is a
+ * retry: it rejoins the move it repeats, and changes nothing.
+ */
+export const answerBriefing = Effect.fn("Space.answerBriefing")(function* (input) {
+    const store = yield* AskStore;
+    const at = yield* now;
+    const { record, turn, made } = yield* store.transaction(Effect.gen(function* () {
+        const found = yield* findAsk(input.askId);
+        if (found.kind !== "briefing") {
+            return yield* new ContentInvalid({
+                reason: `This is a ${found.kind}, not a briefing: answer_briefing answers only briefings.`,
+            });
+        }
+        const thread = yield* store.thread(found.id);
+        const rejoined = rejoins(thread, input.answers);
+        if (rejoined !== undefined)
+            return { record: found, turn: rejoined, made: false };
+        if (found.status === "closed")
+            return yield* new AskClosed({ askId: found.id });
+        if (found.status === "awaiting_human") {
+            return yield* new NotYourTurn({ askId: found.id, turn: "human" });
+        }
+        yield* checkSize(input.answers);
+        yield* checkImages(input.answers.flatMap((answer) => [
+            ...(answer.content ?? []),
+            ...blocksOf(answer.points ?? []),
+        ]));
+        const tree = foldBriefing(found.prompt, thread.map((row) => row.entry));
+        const problem = answersProblem(tree, input.answers);
+        if (problem !== null)
+            return yield* new ContentInvalid({ reason: problem });
+        // Answering the person's replies shows the agent had them.
+        yield* store.markAllDelivered(found.id, at);
+        let last = 0;
+        for (const entry of answerEntries(tree, input.answers, at)) {
+            last = (yield* store.append(found.id, entry)).seq;
+        }
+        yield* store.setStatus(found.id, "awaiting_human", at);
+        yield* store.touchWaited(found.id, at);
+        const updated = { ...found, status: "awaiting_human", updatedAt: at };
+        return { record: updated, turn: last, made: true };
+    }));
+    const ask = yield* view(record);
+    if (made)
+        yield* announce("ask.updated", ask);
+    const move = { ask, turn };
+    return move;
+});
+/**
+ * Waits up to `waitMs` for a reply the agent has not yet taken, and shows it. `null` means none
+ * came: the caller waits again. The reply stays the agent's to take until `markDelivered` says it
+ * reached them, so a wait whose caller has gone loses nothing. While a wait is held the ask shows
+ * as waiting.
+ */
+export const awaitReply = Effect.fn("Space.awaitReply")(function* (askId, waitMs) {
+    const store = yield* AskStore;
+    const replies = yield* Replies;
+    const record = yield* findAsk(askId);
+    const take = Effect.gen(function* () {
+        const entry = yield* store.undelivered(askId);
+        if (Option.isNone(entry) || entry.value.entry.author !== "human")
+            return null;
+        const delivery = { askId, reply: entry.value.entry.reply, seq: entry.value.seq };
+        return delivery;
+    });
+    const wait = Effect.gen(function* () {
+        // Subscribed before the first look, so a reply landing in between still wakes this wait.
+        const woken = yield* PubSub.subscribe(replies);
+        const ready = yield* take;
+        if (ready !== null || waitMs <= 0)
+            return ready;
+        const later = Effect.gen(function* () {
+            for (;;) {
+                yield* PubSub.take(woken);
+                const delivery = yield* take;
+                if (delivery !== null)
+                    return delivery;
+            }
+        });
+        const held = Duration.millis(Math.min(waitMs, MAX_WAIT_MS));
+        return Option.getOrNull(yield* Effect.timeoutOption(later, held));
+    });
+    return yield* Effect.acquireUseRelease(Effect.gen(function* () {
+        yield* follow(askId);
+        yield* noteWaiting(record, yield* now);
+    }), () => Effect.scoped(wait), () => unfollow(askId));
+});
+/** Records that the agent was handed the reply at `seq`: a retry no longer collects it. */
+export const markDelivered = Effect.fn("Space.markDelivered")(function* (askId, seq) {
+    const store = yield* AskStore;
+    yield* store.markDelivered(askId, seq, yield* now);
+    return null;
+});
+/** The task for turn `afterSeq` of an ask: when it started, and the reply that ends it, if given. */
+const locateTask = Effect.fnUntraced(function* (askId, afterSeq) {
+    const store = yield* AskStore;
+    const record = yield* findAsk(askId);
+    const thread = yield* store.thread(askId);
+    let startedAt = afterSeq === 0 ? record.createdAt : undefined;
+    let answer;
+    for (const row of thread) {
+        if (row.seq === afterSeq && row.entry.author === "agent")
+            startedAt = row.entry.at;
+        if (answer === undefined && row.seq > afterSeq && row.entry.author === "human") {
+            answer = {
+                seq: row.seq,
+                at: row.entry.at,
+                reply: { askId, reply: row.entry.reply, seq: row.seq },
+                delivered: row.deliveredAt !== null,
+            };
+        }
+    }
+    // A turn this ask never had names no task.
+    if (startedAt === undefined)
+        return yield* new AskNotFound({ askId });
+    return { record, startedAt, answer };
+});
+/**
+ * One poll of an agent's background task. While it is working, each poll keeps the ask showing an
+ * agent following it; once the person replies, it completes with that reply, every time it is asked.
+ */
+export const followTask = Effect.fn("Space.followTask")(function* (askId, afterSeq) {
+    const store = yield* AskStore;
+    const { record, startedAt, answer } = yield* locateTask(askId, afterSeq);
+    if (answer !== undefined) {
+        if (!answer.delivered)
+            yield* store.markDelivered(askId, answer.seq, yield* now);
+        const state = {
+            status: "completed",
+            createdAt: startedAt,
+            lastUpdatedAt: answer.at,
+            reply: answer.reply,
+        };
+        return state;
+    }
+    const cancelledAt = yield* store.taskCancelledAt(askId, afterSeq);
+    if (Option.isSome(cancelledAt)) {
+        const state = {
+            status: "cancelled",
+            createdAt: startedAt,
+            lastUpdatedAt: cancelledAt.value,
+            reply: null,
+        };
+        return state;
+    }
+    yield* follow(askId);
+    yield* unfollow(askId);
+    yield* noteWaiting(record, yield* now);
+    const state = {
+        status: "working",
+        createdAt: startedAt,
+        lastUpdatedAt: startedAt,
+        reply: null,
+    };
+    return state;
+});
+/**
+ * The agent stops following a background task. The ask stays open, and the person can still
+ * answer it; the inbox stops showing anyone waiting. A task that already completed stays completed.
+ */
+export const cancelTask = Effect.fn("Space.cancelTask")(function* (askId, afterSeq) {
+    const store = yield* AskStore;
+    const presence = yield* Presence;
+    const { startedAt, answer } = yield* locateTask(askId, afterSeq);
+    if (answer !== undefined) {
+        const state = {
+            status: "completed",
+            createdAt: startedAt,
+            lastUpdatedAt: answer.at,
+            reply: answer.reply,
+        };
+        return state;
+    }
+    const at = yield* now;
+    yield* store.cancelTask(askId, afterSeq, at);
+    if (yield* presence.drop(askId))
+        yield* announceFollowing(askId);
+    const state = {
+        status: "cancelled",
+        createdAt: startedAt,
+        lastUpdatedAt: at,
+        reply: null,
+    };
+    return state;
+});
+/** Records a person's reply, wakes the agent waiting for it, and tells every inbox. */
+export const reply = Effect.fn("Space.reply")(function* (askId, answer, by) {
+    const store = yield* AskStore;
+    const replies = yield* Replies;
+    const at = yield* now;
+    const { record, status } = yield* store.transaction(Effect.gen(function* () {
+        const found = yield* findAsk(askId);
+        const thread = (yield* store.thread(askId)).map((row) => row.entry);
+        yield* checkReply(found, thread, answer);
+        const next = statusAfter(found, thread, answer);
+        yield* store.append(askId, { author: "human", reply: answer, by, at });
+        yield* store.setStatus(askId, next, at);
+        return { record: found, status: next };
+    }));
+    yield* PubSub.publish(replies, undefined);
+    const ask = yield* view({
+        ...record,
+        status,
+        updatedAt: at,
+        closedAt: status === "closed" ? at : null,
+    });
+    yield* announce("ask.updated", ask);
+    return ask;
+});
+export const get = (askId) => Effect.flatMap(findAsk(askId), view);
+/** Every open ask and the most recently closed. */
+export const snapshot = Effect.gen(function* () {
+    const store = yield* AskStore;
+    const current = {
+        open: yield* views(yield* store.open),
+        recent: yield* views((yield* store.closed(undefined, RECENT_LIMIT)).records),
+    };
+    return current;
+});
+/** A page of closed asks, newest first. */
+export const history = Effect.fn("Space.history")(function* (before, limit) {
+    const store = yield* AskStore;
+    const { records, nextBefore } = yield* store.closed(before, limit);
+    const items = yield* views(records);
+    const page = { items, ...(nextBefore === null ? {} : { nextBefore }) };
+    return page;
+});
+/** Issues a single-use ticket to upload one image. */
+export const createUpload = Effect.fn("Space.createUpload")(function* (contentType) {
+    const uploads = yield* UploadStore;
+    const host = yield* Host;
+    const at = yield* now;
+    const token = secret();
+    const issued = {
+        uploadId: crypto.randomUUID(),
+        spaceId: host.spaceId,
+        token,
+        contentType,
+        expiresAt: new Date(Date.parse(at) + UPLOAD_TTL_MS).toISOString(),
+        maxBytes: UPLOAD_MAX_BYTES,
+    };
+    yield* uploads.insert({
+        id: issued.uploadId,
+        tokenHash: yield* sha256(token),
+        contentType,
+        maxBytes: issued.maxBytes,
+        status: "pending",
+        size: null,
+        createdAt: at,
+        expiresAt: issued.expiresAt,
+    });
+    return issued;
+});
+/** Uses up an upload ticket. Once claimed it is spent, whether or not the upload then succeeds. */
+export const claimUpload = Effect.fn("Space.claimUpload")(function* (token, contentType) {
+    const uploads = yield* UploadStore;
+    const found = yield* uploads.findByToken(yield* sha256(token));
+    if (Option.isNone(found))
+        return yield* new UploadNotFound();
+    const upload = found.value;
+    if (upload.status !== "pending" ||
+        Date.parse(upload.expiresAt) <= (yield* Clock.currentTimeMillis)) {
+        return yield* new UploadExpired();
+    }
+    const declared = contentType.split(";")[0]?.trim().toLowerCase();
+    if (declared !== upload.contentType) {
+        return yield* new UploadRejected({
+            reason: `This ticket is for ${upload.contentType}, not ${declared || "an unnamed type"}.`,
+        });
+    }
+    yield* uploads.setStatus(upload.id, "claimed", null);
+    const claimed = {
+        uploadId: upload.id,
+        contentType: upload.contentType,
+        maxBytes: upload.maxBytes,
+    };
+    return claimed;
+});
+/** Records that a claimed upload's bytes are stored. */
+export const completeUpload = Effect.fn("Space.completeUpload")(function* (uploadId, size) {
+    const uploads = yield* UploadStore;
+    const found = yield* uploads.find(uploadId);
+    if (Option.isNone(found) || found.value.status !== "claimed")
+        return yield* new UploadNotFound();
+    yield* uploads.setStatus(uploadId, "stored", size);
+    const receipt = { uploadId, contentType: found.value.contentType, size };
+    return receipt;
+});
+/** A stored upload's type and size. */
+export const findUpload = Effect.fn("Space.findUpload")(function* (uploadId) {
+    const uploads = yield* UploadStore;
+    const found = yield* uploads.find(uploadId);
+    if (Option.isNone(found) || found.value.status !== "stored")
+        return yield* new UploadNotFound();
+    const receipt = {
+        uploadId,
+        contentType: found.value.contentType,
+        size: found.value.size ?? 0,
+    };
+    return receipt;
+});
+/** Issues a one-time pass onto the event socket, held only as its hash. */
+export const issueTicket = Effect.fn("Space.issueTicket")(function* (actorId) {
+    const tickets = yield* TicketStore;
+    const host = yield* Host;
+    const at = yield* now;
+    yield* tickets.purge(at);
+    const issued = {
+        spaceId: host.spaceId,
+        secret: secret(),
+        expiresAt: new Date(Date.parse(at) + TICKET_TTL_MS).toISOString(),
+    };
+    yield* tickets.insert(yield* sha256(issued.secret), actorId, issued.expiresAt);
+    return issued;
+});
+/** Spends an event ticket: who it was issued to, or `TicketInvalid` when it is unknown, used or expired. */
+export const redeemTicket = Effect.fn("Space.redeemTicket")(function* (ticketSecret) {
+    const tickets = yield* TicketStore;
+    const at = yield* now;
+    const taken = yield* tickets.take(yield* sha256(ticketSecret));
+    if (Option.isNone(taken) || taken.value.expiresAt <= at)
+        return yield* new TicketInvalid();
+    return { actorId: taken.value.actorId };
+});
+/** Everything a space does, by name: what its object serves over RPC. */
+export const operations = {
+    open,
+    answerFollowUp,
+    answerBriefing,
+    awaitReply,
+    markDelivered,
+    followTask,
+    cancelTask,
+    reply,
+    get,
+    snapshot: () => snapshot,
+    history,
+    createUpload,
+    claimUpload,
+    completeUpload,
+    findUpload,
+    issueTicket,
+    redeemTicket,
+};

package/dist/src/space/read.d.ts

@@ -0,0 +1,8 @@
+import { Result, Schema } from "effect";
+/**
+ * Reading what a space is handed or holds: decoded with the schemas generated from the contract,
+ * never cast. A message holding something from a newer revision of the contract, a member of a union
+ * those schemas decode as `unknown`, can't be read either: this code would only guess at it. See
+ * docs/design/versioned-messages.md.
+ */
+export declare const read: <A>(schema: Schema.Codec<A, unknown>, value: unknown) => Result.Result<A, string>;

package/dist/src/space/read.js

@@ -0,0 +1,33 @@
+import { Result, Schema } from "effect";
+/**
+ * Reading what a space is handed or holds: decoded with the schemas generated from the contract,
+ * never cast. A message holding something from a newer revision of the contract, a member of a union
+ * those schemas decode as `unknown`, can't be read either: this code would only guess at it. See
+ * docs/design/versioned-messages.md.
+ */
+export const read = (schema, value) => {
+    const decoded = Schema.decodeUnknownResult(schema)(value);
+    if (Result.isFailure(decoded))
+        return Result.fail(decoded.failure.message);
+    const found = unreadable(decoded.success);
+    return found === undefined
+        ? Result.succeed(decoded.success)
+        : Result.fail(`it holds ${found}, from a newer revision of the contract`);
+};
+/** What a decoded message holds that this code can't read, if anything. */
+const unreadable = (value) => {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const record = value;
+    for (const tag of ["kind", "type", "outcome"]) {
+        if (record[tag] === "unknown" && typeof record["was"] === "string") {
+            return `the ${tag} "${record["was"]}"`;
+        }
+    }
+    for (const inner of Object.values(record)) {
+        const found = unreadable(inner);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+};

package/dist/src/space/rpc.d.ts

@@ -0,0 +1,61 @@
+import { Effect, type Exit, Schema } from "effect";
+import { AskClosed, AskNotFound, ContentInvalid, type Declined, NotYourTurn, ReplyInvalid, TicketInvalid, UploadExpired, UploadNotFound, UploadRejected } from "../domain/errors.ts";
+import { type Operations } from "./operations.ts";
+/**
+ * The version of the code making a call: the contract revision it writes, and the deploy it is part
+ * of. A space compares them with its own, since for a while after a deploy the Worker and a space can
+ * run different code. `build` is the version's creation time, from Cloudflare's version metadata, and
+ * absent where there is none (local tests): then nothing is compared.
+ */
+export interface Caller {
+    readonly revision: number;
+    readonly build?: string | undefined;
+}
+/** A deployment's build, from its version metadata binding, if it has one. */
+export declare const buildOf: (env: unknown) => string | undefined;
+/** Whether a build is from a later deploy than another; unknown when either is. */
+export declare const isLater: (build: string | undefined, than: string | undefined) => boolean;
+declare const Outdated_base: Schema.Class<Outdated, Schema.TaggedStruct<"Outdated", {}>, import("effect/Cause").YieldableError>;
+/**
+ * A space's refusal of a call from newer code than its own: it ran nothing, and restarts onto the new
+ * code a moment later. The client tries the call again, whatever it is, and never hands this on.
+ */
+export declare class Outdated extends Outdated_base {
+}
+/** Every error a space operation fails with. */
+export declare const SpaceFailure: Schema.Union<readonly [typeof AskNotFound, typeof AskClosed, typeof NotYourTurn, typeof ReplyInvalid, typeof ContentInvalid, typeof TicketInvalid, typeof UploadNotFound, typeof UploadExpired, typeof UploadRejected]>;
+export type SpaceFailure = typeof SpaceFailure.Type;
+/**
+ * An operation's outcome as it crosses the RPC boundary. Errors do not survive structured clone
+ * with their tags, so every answer is its Exit encoded as JSON; a defect crosses as its name and
+ * message. Success values are the contract's own JSON shapes and pass through unchanged.
+ */
+export type ExitJson = Schema.Json;
+/** What a call can fail with across the boundary: an operation's errors, or the space's refusal. */
+declare const CallFailure: Schema.Union<readonly [typeof AskNotFound, typeof AskClosed, typeof NotYourTurn, typeof ReplyInvalid, typeof ContentInvalid, typeof TicketInvalid, typeof UploadNotFound, typeof UploadExpired, typeof UploadRejected, typeof Outdated]>;
+type CallFailure = typeof CallFailure.Type;
+export declare const encodeExit: (exit: Exit.Exit<unknown, CallFailure>) => ExitJson;
+/** A space operation by name, as the object serves it. */
+export type OperationName = keyof Operations;
+/** What the Worker holds to reach a space: its object's single RPC entry point. */
+export interface SpaceStub {
+    call(method: OperationName, args: readonly unknown[], caller: Caller): Promise<ExitJson>;
+}
+/** The operations a deployment may decline, wrapping the client: the ones that open something new. */
+export type Declinable = "open" | "createUpload";
+/**
+ * A space's operations as seen from the Worker: the same signatures, with no services required. A
+ * client a deployment wraps may also decline what it lets open; the space's own never does.
+ */
+export type SpaceClient = {
+    readonly [K in OperationName]: (...args: Parameters<Operations[K]>) => Effect.Effect<Effect.Success<ReturnType<Operations[K]>>, Effect.Error<ReturnType<Operations[K]>> | (K extends Declinable ? Declined : never)>;
+};
+/**
+ * The typed client for one space, for code of the version `caller` names. Each call is decoded back
+ * into the operation's own success value or tagged error. A call the object refused is tried again on
+ * a fresh stub when it is safe to, as Cloudflare advises; otherwise it is a defect. A call a space
+ * refused as `Outdated` ran nothing, so it is tried again whatever it is, until the space is on the
+ * new code.
+ */
+export declare const spaceClient: (stub: () => SpaceStub, caller: Caller) => SpaceClient;
+export {};