@sigrun/sigrun 0.1.4 → 0.1.5

package/dist/server/routes/surfaces.js

@@ -0,0 +1,387 @@
+/**
+ * Extension surface routes (UI-blocks U3 Task 2, spec §7.2): the render
+ * and data GETs plus the actions POST, mounted at core's reserved
+ * `surfaces/` prefix under `/v1/ext/<slug>/`, behind the W1 auth
+ * pipeline like every `/v1` route.
+ *
+ * - `GET /v1/ext/<slug>/surfaces/<id>?params=<json>` → `{tree, data,
+ *   rev, treeRev, access}`; `params` is a JSON object capped at 4 KiB
+ *   (spec §15) — anything else is `400 invalid_field params`.
+ * - `GET …/data?params=<json>&since=<rev>` → `{rev, treeRev, data}` or
+ *   `{rev, treeRev, ops}` when the server holds the ops since `since`
+ *   (sharedData surfaces, §7.3).
+ * - `POST …/actions` `{action, payload, actionId, params}` → the
+ *   handler's `ActionResult` wrapped per §6.3 (an accept carries the
+ *   assigned `rev`, plus the `ops` echoed back when it came with an
+ *   `update`), deduped per actionId per instance (10-minute window),
+ *   rate-limited per principal per surface (20/s burst 40 → 429), and
+ *   timed out at 10 s (`{ok:false, error:{message:"timed out"}}`).
+ *   Access (§6.5) gates BEFORE the handler runs: `read` → 403, `none`
+ *   → 404 `surface_not_found` (indistinguishable from an unknown id).
+ * - `PUT …/uploads/<field>/<name>?params` → raw octet-stream body,
+ *   capped at the field's `maxBytes` (clamped by
+ *   `server.maxUploadBytes`) — over the cap is a 413 answered from the
+ *   FIRST chunks, without buffering the rest (the parser destroys the
+ *   request stream, so the socket never sees the remainder). The
+ *   `onUpload` handler receives `{field, name, mime, bytes}` with the
+ *   MIME sniffed from the bytes (never the client name).
+ *
+ * Errors: a render/data throw or an invalid tree is
+ * `500 surface_failed` (logged here; the response body carries the
+ * validation `errors` only when `server.dev` is true, spec §14.2). The
+ * extension stays loaded.
+ */
+import { PassThrough } from "node:stream";
+import { instanceKey } from "../surfaces/instance.js";
+import { ActionRateLimitedError, SurfaceFailedError, UnknownActionError, } from "../surfaces/service.js";
+/**
+ * The one upload-name rule, shared with core's conversation upload
+ * route (files.ts §6.2 — kept in sync by hand): no `/` or `\\`, not
+ * `.` or `..`, non-empty. Fastify has already percent-DECODED the
+ * `:name` param, so `%2e%2e` arrives as `..` and is rejected.
+ */
+function validUploadName(name) {
+    return (name.length > 0 &&
+        !name.includes("/") &&
+        !name.includes("\\") &&
+        name !== "." &&
+        name !== "..");
+}
+/** The params cap (spec §15): 4 KiB of JSON text. */
+export const PARAMS_MAX_BYTES = 4096;
+/** The not-found body — shared by unknown ids and `access: "none"`. */
+const NOT_FOUND = { error: "surface_not_found" };
+/**
+ * Parse the `?params=` query value: absent → `{}`; present must decode
+ * as a JSON OBJECT within the 4 KiB cap. Returns the object or the
+ * error body (`invalid_field params`).
+ */
+function parseParams(raw) {
+    if (raw === undefined)
+        return { ok: true, params: {} };
+    if (typeof raw !== "string")
+        return { ok: false };
+    if (Buffer.byteLength(raw, "utf8") > PARAMS_MAX_BYTES)
+        return { ok: false };
+    let decoded;
+    try {
+        decoded = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false };
+    }
+    if (typeof decoded !== "object" || decoded === null || Array.isArray(decoded)) {
+        return { ok: false };
+    }
+    return { ok: true, params: decoded };
+}
+/** Parse `?since=`: absent → undefined; a non-negative integer else. */
+function parseSince(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw !== "string" || !/^\d+$/.test(raw))
+        return null;
+    return Number.parseInt(raw, 10);
+}
+/** Register the surface routes over the shared context's service. */
+export function registerSurfaceRoutes(app, ctx) {
+    const { surfaces } = ctx;
+    const uploadCaps = new WeakMap();
+    /** The shared failure mapping (logged; errors only under server.dev). */
+    const failureReply = async (reply, slug, id, cause) => {
+        const failed = cause instanceof SurfaceFailedError
+            ? cause
+            : new SurfaceFailedError(cause instanceof Error ? cause.message : String(cause));
+        console.warn(`surface failed: ${slug}/${id}: ${failed.message}${failed.errors === undefined
+            ? ""
+            : ` (${failed.errors.map((e) => `${e.path}: ${e.message}`).join("; ")})`}`);
+        return reply.code(500).send({
+            error: "surface_failed",
+            ...(ctx.config.dev && failed.errors !== undefined
+                ? { errors: failed.errors }
+                : {}),
+        });
+    };
+    app.get("/v1/ext/:slug/surfaces/:id", async (request, reply) => {
+        const { slug, id } = request.params;
+        const parsed = parseParams(request.query.params);
+        if (!parsed.ok) {
+            return await reply
+                .code(400)
+                .send({ error: "invalid_field", field: "params" });
+        }
+        try {
+            const result = await surfaces.render(request.params.slug, id, parsed.params, request.principal, request.headers["x-sigrun-stream"]);
+            if (result === undefined) {
+                return await reply.code(404).send(NOT_FOUND);
+            }
+            return await reply.send(result);
+        }
+        catch (cause) {
+            return await failureReply(reply, slug, id, cause);
+        }
+    });
+    app.get("/v1/ext/:slug/surfaces/:id/data", async (request, reply) => {
+        const { slug, id } = request.params;
+        const parsed = parseParams(request.query.params);
+        if (!parsed.ok) {
+            return await reply
+                .code(400)
+                .send({ error: "invalid_field", field: "params" });
+        }
+        const since = parseSince(request.query.since);
+        if (since === null) {
+            return await reply
+                .code(400)
+                .send({ error: "invalid_field", field: "since" });
+        }
+        try {
+            const result = await surfaces.data(slug, id, parsed.params, request.principal, since, request.headers["x-sigrun-stream"]);
+            if (result === undefined) {
+                return await reply.code(404).send(NOT_FOUND);
+            }
+            return await reply.send(result);
+        }
+        catch (cause) {
+            return await failureReply(reply, slug, id, cause);
+        }
+    });
+    app.post("/v1/ext/:slug/surfaces/:id/actions", async (request, reply) => {
+        const { slug, id } = request.params;
+        const body = request.body ?? {};
+        if (typeof body.action !== "string") {
+            return await reply
+                .code(400)
+                .send({ error: "invalid_field", field: "action" });
+        }
+        let params = {};
+        if (body.params !== undefined) {
+            const encoded = JSON.stringify(body.params);
+            if (typeof body.params !== "object" ||
+                body.params === null ||
+                Array.isArray(body.params) ||
+                Buffer.byteLength(encoded, "utf8") > PARAMS_MAX_BYTES) {
+                return await reply
+                    .code(400)
+                    .send({ error: "invalid_field", field: "params" });
+            }
+            params = body.params;
+        }
+        // The §6.5 access gate: cache or re-render decides BEFORE the
+        // handler runs. A located-check first keeps unknown slugs/ids on
+        // the same 404 body without a render.
+        const binding = ctx.opened.extensionSurfaces.find((entry) => entry.extension === slug);
+        const def = binding?.defs.find((entry) => entry.id === id);
+        if (def === undefined) {
+            return await reply.code(404).send(NOT_FOUND);
+        }
+        // A throwing `instanceKey` is an extension fault: 500
+        // surface_failed, the extension stays loaded (deferred minor from
+        // Task 2 — this ran outside the try before).
+        let key;
+        try {
+            key =
+                def.instanceKey !== undefined
+                    ? def.instanceKey(params)
+                    : instanceKey(params);
+        }
+        catch (cause) {
+            return await failureReply(reply, slug, id, cause);
+        }
+        let access;
+        try {
+            access = await surfaces.accessFor(slug, id, key, params, request.principal);
+        }
+        catch (cause) {
+            return await failureReply(reply, slug, id, cause);
+        }
+        if (access === "none") {
+            return await reply.code(404).send(NOT_FOUND);
+        }
+        if (access === "read") {
+            return await reply.code(403).send({ error: "forbidden" });
+        }
+        try {
+            const result = await surfaces.act(slug, id, key, params, request.principal, body.action, body.payload, typeof body.actionId === "string" ? body.actionId : undefined, request.signal);
+            return await reply.send(result);
+        }
+        catch (cause) {
+            if (cause instanceof UnknownActionError) {
+                return await reply.code(400).send({ error: "unknown_action" });
+            }
+            if (cause instanceof ActionRateLimitedError) {
+                return await reply.code(429).send({ error: "rate_limited" });
+            }
+            return await failureReply(reply, slug, id, cause);
+        }
+    });
+    /**
+     * The upload route (spec §7.2). The gate + cap resolution run in
+     * `preParsing` — AFTER the headers, BEFORE the body is read. The cap
+     * is enforced by the route itself, not Fastify's bodyLimit: the hook
+     * wraps the payload in a PassThrough counter that forwards chunks up
+     * to the resolved field cap (`maxBytes` from the last rendered tree,
+     * clamped by `server.maxUploadBytes`); the first over-cap chunk sends
+     * `413 {error:"too_large", maxBytes}` DIRECTLY from the hook and
+     * then destroys the request socket (the reply is sent first —
+     * destroying the socket before the reply lands makes Node drop the
+     * response), so the sender's remaining bytes are never written
+     * (Review Focus 5). The handler itself only validates the name and
+     * dispatches to `onUpload`.
+     */
+    app.put("/v1/ext/:slug/surfaces/:id/uploads/:field/:name", {
+        // Untyped non-empty bodies would 415 (files.ts' identical
+        // default): uploads arrive raw.
+        onRequest: async (request) => {
+            if (request.headers["content-type"] === undefined) {
+                request.headers["content-type"] = "application/octet-stream";
+            }
+        },
+        preParsing: async (request, reply, payload) => {
+            const { slug, id, field } = request.params;
+            const parsed = parseParams(request.query.params);
+            if (!parsed.ok) {
+                return await reply
+                    .code(400)
+                    .send({ error: "invalid_field", field: "params" });
+            }
+            const binding = ctx.opened.extensionSurfaces.find((entry) => entry.extension === slug);
+            const def = binding?.defs.find((entry) => entry.id === id);
+            if (def === undefined) {
+                return await reply.code(404).send(NOT_FOUND);
+            }
+            let key;
+            try {
+                key =
+                    def.instanceKey !== undefined
+                        ? def.instanceKey(parsed.params)
+                        : instanceKey(parsed.params);
+            }
+            catch (cause) {
+                return await failureReply(reply, slug, id, cause);
+            }
+            // The §6.5 access gate, BEFORE the body is consumed.
+            let access;
+            try {
+                access = await surfaces.accessFor(slug, id, key, parsed.params, request.principal);
+            }
+            catch (cause) {
+                return await failureReply(reply, slug, id, cause);
+            }
+            if (access === "none") {
+                return await reply.code(404).send(NOT_FOUND);
+            }
+            if (access === "read") {
+                return await reply.code(403).send({ error: "forbidden" });
+            }
+            // The cap: the field's declared maxBytes (from the last
+            // rendered tree) clamped by server.maxUploadBytes. An
+            // instance that was never rendered has no recorded caps —
+            // re-render to fill them. Unknown field → 400.
+            let cap = surfaces.uploadCapBytes(slug, id, key, field);
+            if (cap === undefined) {
+                try {
+                    await surfaces.render(slug, id, parsed.params, request.principal);
+                }
+                catch (cause) {
+                    return await failureReply(reply, slug, id, cause);
+                }
+                cap = surfaces.uploadCapBytes(slug, id, key, field);
+            }
+            if (cap === undefined) {
+                return await reply.code(400).send({ error: "unknown_field" });
+            }
+            // A declared content-length already over the cap: answer
+            // 413 without touching the body (Fastify never reads it;
+            // the connection-close header drops the socket).
+            const declared = Number(request.headers["content-length"]);
+            if (Number.isFinite(declared) && declared > cap) {
+                reply.header("connection", "close");
+                return await reply
+                    .code(413)
+                    .send({ error: "too_large", maxBytes: cap });
+            }
+            uploadCaps.set(request, { cap, key, params: parsed.params, tripped: false });
+            // The chunked cut-off (Review Focus 5): wrap the payload in a
+            // counter whose first over-cap chunk destroys the request
+            // socket (the client's remaining chunks are never written) and
+            // sends the 413 DIRECTLY — answering from the hook, not the
+            // handler, because the handler only runs after the (destroyed)
+            // body finishes. The handler's `gate.tripped` check below
+            // stays as the in-process belt (an inject path never trips the
+            // stream).
+            const gate = uploadCaps.get(request);
+            if (gate === undefined) {
+                return payload;
+            }
+            let received = 0;
+            const capped = new PassThrough();
+            payload.on("data", (chunk) => {
+                if (gate.tripped)
+                    return;
+                received += chunk.byteLength;
+                if (received > gate.cap) {
+                    gate.tripped = true;
+                    // The reply first, then the socket: destroying the
+                    // request stream before the reply lands makes Node drop
+                    // the response entirely.
+                    void reply
+                        .code(413)
+                        .send({ error: "too_large", maxBytes: gate.cap });
+                    // Destroy the counter too: the parser keeps buffering the
+                    // already-forwarded prefix while it believes the stream is
+                    // still live.
+                    setImmediate(() => {
+                        payload.destroy();
+                        capped.destroy();
+                    });
+                    return;
+                }
+                capped.write(chunk);
+            });
+            payload.on("end", () => capped.end());
+            payload.on("error", () => capped.end());
+            return capped;
+        },
+    }, async (request, reply) => {
+        const { slug, id, field, name } = request.params;
+        const gate = uploadCaps.get(request);
+        uploadCaps.delete(request);
+        if (gate === undefined) {
+            // unreachable (the preParsing hook short-circuits every
+            // failure); defend anyway.
+            return await reply.code(404).send(NOT_FOUND);
+        }
+        // The one upload-name rule, shared with core's conversation
+        // uploads (files.ts §6.2): no separators, not `.`/`..`, on the
+        // DECODED param.
+        if (!validUploadName(name)) {
+            return await reply.code(400).send({ error: "invalid_body" });
+        }
+        const binding = ctx.opened.extensionSurfaces.find((entry) => entry.extension === slug);
+        const def = binding?.defs.find((entry) => entry.id === id);
+        if (def === undefined) {
+            return await reply.code(404).send(NOT_FOUND);
+        }
+        const bytes = request.body === undefined
+            ? new Uint8Array(0)
+            : new Uint8Array(request.body);
+        // The stream-side cap tripped (a chunked body cut off mid-way):
+        // the body never arrived intact — answer the 413.
+        if (gate.tripped) {
+            return await reply
+                .code(413)
+                .send({ error: "too_large", maxBytes: gate.cap });
+        }
+        try {
+            const result = await surfaces.upload(slug, id, gate.key, gate.params, request.principal, field, name, bytes, request.signal);
+            return await reply.send(result);
+        }
+        catch (cause) {
+            if (cause instanceof UnknownActionError) {
+                return await reply.code(400).send({ error: "unknown_action" });
+            }
+            return await failureReply(reply, slug, id, cause);
+        }
+    });
+}

package/dist/server/routes/users.js

@@ -14,13 +14,18 @@ import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
 import { withClaimLock } from "../auth/claim-lock.js";
 import { transferOwnership } from "../ownership.js";
 /** The wire form of one directory user (the record minus nothing — the
- * routes serving it are admin-gated, and emails are admin material). */
+ * routes serving it are admin-gated, and emails are admin material).
+ * `admin` stays the STORED flag; `groupAdmin` (gateway C8) is the
+ * persisted proxy-group grant alongside it. */
 function userWire(record) {
     return {
         user: record.user,
         ...(record.name === undefined ? {} : { name: record.name }),
         ...(record.email === undefined ? {} : { email: record.email }),
         admin: record.admin,
+        ...(record.groupAdmin === undefined
+            ? {}
+            : { groupAdmin: record.groupAdmin }),
         createdAt: record.createdAt,
         source: record.source,
     };

package/dist/server/session-meta.js

@@ -28,9 +28,10 @@
  * `Conversation.commit` callback, so concurrent patches cannot lose each
  * other's fields (the mutation line serializes commits).
  *
- * Server-owned fields (`autoName`, `autoNameAttempts`, `lastActivityAt`)
- * are written by host code only (activity.ts, the A2 auto-namer); they
- * are NOT patch surface — the strict validator keeps rejecting them as
+ * Server-owned fields (`autoName`, `autoNameAttempts`,
+ * `lastActivityAt`, `jobId`, `deliver`) are written by host code only
+ * (activity.ts, the A2 auto-namer, fire.ts's job stamp); they are NOT
+ * patch surface — the strict validator keeps rejecting them as
  * `invalid_field`.
  */
 import { defineDoc } from "@earendil-works/pi-durable";
@@ -154,9 +155,14 @@ export function validateSessionMetaPatch(body) {
                 break;
             }
             case "source":
-            case "owner": {
-                // Server-only (spec §5.9): the KEY itself is the client error,
-                // whatever the value — even a `null` clear.
+            case "owner":
+            case "jobId":
+            case "deliver": {
+                // Server-only (spec §5.9 + gateway C7): the KEY itself is the
+                // client error, whatever the value — even a `null` clear. The
+                // job stamp fields move with the fire (fire.ts's creating
+                // commit) and the delivery targets ride the job spec, never a
+                // meta patch.
                 return { error: "invalid_field", field: key };
             }
             case "sharing": {

package/dist/server/shutdown.js

@@ -0,0 +1,85 @@
+/**
+ * The ordered shutdown (gateway C2's extraction of serve.ts's inline
+ * `shutdown`): seven steps, each in its own try/catch so a failure never
+ * skips the remaining steps, with every failure collected into one
+ * `AggregateError("sigrun shutdown failed")` after ALL steps ran (the
+ * pre-extraction semantics, byte-for-byte).
+ *
+ * The order (spec §8.0 — the gateway lifecycle slots between the server
+ * drain and the event-bus flush):
+ *
+ * 1. `endStreams` — SSE streams FIRST (hijacked event streams never end
+ *    on their own, and `closeApp`'s drain waits for in-flight requests —
+ *    with any webui tab open, shutdown hung forever on its /v1/events
+ *    connection);
+ * 2. `closeApp` — the server drain (in-flight requests finish);
+ * 3. `gateway.stopIntake` — the engine closes inbound intake BEFORE the
+ *    bus drain: the drain is the last admission window, so no chat
+ *    message admitted mid-drain can outrun it;
+ * 4. `eventBusShutdown` — the bus's shutdown sequence (drain pending
+ *    settles, then deliver `harnessShutdown` — handlers may commit);
+ * 5. `gateway.stop` — the engine stops only once every settle has been
+ *    delivered (its adapters' outbound side saw the final answers);
+ * 6. `stopProviderRefresh` — the interval scheduler + the bounded
+ *    boot-refresh join (no catalog fetch outlives the shutdown);
+ * 7. `closeHarness` — the seal (joins tasks, seals storage).
+ *
+ * Does NOT exit the process — the caller owns exit policy (the deploy
+ * entry exits 0/1; the CLI's `run` returns to its exit code).
+ */
+/**
+ * Build the ordered shutdown over the seven steps. Failures from ANY step
+ * are collected (the remaining steps still run) and thrown together as
+ * `AggregateError(failures, "sigrun shutdown failed")` at the end; a clean
+ * run resolves.
+ */
+export function createShutdown(steps) {
+    return async () => {
+        const failures = [];
+        try {
+            steps.endStreams();
+        }
+        catch (error) {
+            failures.push(error);
+        }
+        try {
+            await steps.closeApp();
+        }
+        catch (error) {
+            failures.push(error);
+        }
+        try {
+            await steps.gateway.stopIntake();
+        }
+        catch (error) {
+            failures.push(error);
+        }
+        try {
+            await steps.eventBusShutdown();
+        }
+        catch (error) {
+            failures.push(error);
+        }
+        try {
+            await steps.gateway.stop();
+        }
+        catch (error) {
+            failures.push(error);
+        }
+        try {
+            await steps.stopProviderRefresh();
+        }
+        catch (error) {
+            failures.push(error);
+        }
+        try {
+            await steps.closeHarness();
+        }
+        catch (error) {
+            failures.push(error);
+        }
+        if (failures.length > 0) {
+            throw new AggregateError(failures, "sigrun shutdown failed");
+        }
+    };
+}

package/dist/server/surfaces/access-cache.js

@@ -0,0 +1,43 @@
+/**
+ * The per-principal access cache (UI-blocks U3 Task 2, spec §6.5): the
+ * server caches the access verdict of each render, keyed by
+ * `(slug, id, key, principal.user)`, for 60 seconds. An action checks
+ * the cached verdict first; a miss (expired or never rendered) is not
+ * an allow — the caller re-renders for that principal and caches its
+ * answer before deciding. One principal's entry never answers for
+ * another (`principal.user` is part of the key).
+ */
+/** The cache TTL (spec §6.5): 60 seconds. */
+export const ACCESS_CACHE_TTL_MS = 60_000;
+/** The cache store: composite-key → verdict, expiring lazily on read. */
+export class AccessCache {
+    entries = new Map();
+    now;
+    /** @param now the clock (tests inject a fake; production passes Date.now). */
+    constructor(now = () => Date.now()) {
+        this.now = now;
+    }
+    static composite(slug, id, key, user) {
+        // The unit separator keeps segments unambiguous (no escaping needed).
+        return [slug, id, key, user ?? ""].join("\u0001");
+    }
+    /** The cached verdict for this principal, or undefined on a miss/expiry. */
+    get(slug, id, key, user) {
+        const composite = AccessCache.composite(slug, id, key, user);
+        const entry = this.entries.get(composite);
+        if (entry === undefined)
+            return undefined;
+        if (entry.expiresAt <= this.now()) {
+            this.entries.delete(composite);
+            return undefined;
+        }
+        return entry.access;
+    }
+    /** Cache one principal's verdict for the TTL. */
+    set(slug, id, key, user, access) {
+        this.entries.set(AccessCache.composite(slug, id, key, user), {
+            access,
+            expiresAt: this.now() + ACCESS_CACHE_TTL_MS,
+        });
+    }
+}

package/dist/server/surfaces/dedup.js

@@ -0,0 +1,67 @@
+/**
+ * Action dedup (UI-blocks U3 Task 3, spec §6.1): the server invokes a
+ * surface action handler at most once per `actionId` per surface
+ * instance within a 10-minute window; a duplicate POST returns the
+ * FIRST invocation's stored result (retries are safe). Entries are
+ * keyed by actionId alone — actionIds are channel-generated UUIDs —
+ * with the instance composite (`slug
id
key`) stored on the entry so a
+ * collision across instances is treated as a distinct action, not a
+ * replay of another instance's result.
+ *
+ * Process-memory only, like the service's rev state (§7.3). Entries
+ * expire lazily on read; a bounded sweep caps memory between reads.
+ */
+/** The dedup window (spec §6.1): 10 minutes. */
+export const DEDUP_WINDOW_MS = 10 * 60 * 1000;
+/**
+ * The actionId → result table. `check` returns the stored result on a
+ * same-instance duplicate (and `null` when a different instance already
+ * holds the actionId — the caller treats that as a fresh action);
+ * `record` stores the first result.
+ */
+export class ActionDedup {
+    entries = new Map();
+    clock;
+    sweepCounter = 0;
+    constructor(clock) {
+        // Resolve Date.now at CALL time, not construction: a default
+        // parameter (`clock = Date.now`) would capture the Date.now of
+        // whichever fake-timer install was active at construction and
+        // freeze this table to that install's clock.
+        this.clock = clock ?? (() => Date.now());
+    }
+    /**
+     * Look one actionId up for one instance: the stored result on a
+     * duplicate, `undefined` when never seen, `null` when the actionId
+     * belongs to a different instance (treated as fresh by the caller).
+     */
+    check(actionId, composite) {
+        const entry = this.entries.get(actionId);
+        if (entry === undefined)
+            return undefined;
+        if (entry.expiresAt <= this.clock()) {
+            this.entries.delete(actionId);
+            return undefined;
+        }
+        if (entry.composite !== composite)
+            return null;
+        return { result: entry.result };
+    }
+    /** Record the first result of one actionId for one instance. */
+    record(actionId, composite, result) {
+        this.entries.set(actionId, {
+            composite,
+            result,
+            expiresAt: this.clock() + DEDUP_WINDOW_MS,
+        });
+        this.sweepCounter += 1;
+        if (this.sweepCounter >= 64) {
+            this.sweepCounter = 0;
+            const now = this.clock();
+            for (const [id, entry] of this.entries) {
+                if (entry.expiresAt <= now)
+                    this.entries.delete(id);
+            }
+        }
+    }
+}

package/dist/server/surfaces/instance.js

@@ -0,0 +1,42 @@
+/**
+ * Instance keys (UI-blocks U3 Task 2, spec §7.3): a surface instance is
+ * addressed by `(slug, id, key)` where `key` is `instanceKey(params)` —
+ * by default the CANONICAL JSON of the params object, with every
+ * object's keys sorted recursively, so `{a:1,b:2}` and `{b:2,a:1}`
+ * address the same instance. An extension may override `instanceKey`
+ * per surface; the spec's hash form (`eventKey`, sha256 over
+ * `slug \0 id \0 key`) is what events name instances by — params never
+ * appear on the wire (computed here so Task 4's events share it).
+ */
+import { createHash } from "node:crypto";
+/**
+ * Canonical JSON: every object serializes with keys SORTED (recursive);
+ * primitives and arrays serialize as usual. Two params objects equal up
+ * to key order produce byte-identical strings.
+ */
+export function canonicalJson(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => canonicalJson(entry)).join(",")}]`;
+    }
+    if (typeof value === "object" && value !== null) {
+        const keys = Object.keys(value).sort();
+        const parts = keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`);
+        return `{${parts.join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+/**
+ * The default instance key (spec §7.3): canonical JSON of the params.
+ * A surface's own `instanceKey` overrides this; the service applies the
+ * override, this is the fallback.
+ */
+export function instanceKey(params) {
+    return canonicalJson(params);
+}
+/**
+ * The wire name of an instance (spec §7.3): `sha256(slug + "\0" + id +
+ * "\0" + key)` hex. Events carry `k`, never the key or the params.
+ */
+export function eventKey(slug, id, key) {
+    return createHash("sha256").update([slug, id, key].join("\u0000")).digest("hex");
+}