@sigrun/sigrun 0.1.3 → 0.1.5

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");
+}

package/dist/server/surfaces/mime.js

@@ -0,0 +1,73 @@
+/**
+ * Magic-byte MIME sniffing (UI-blocks U3 Task 3, spec §7.1): the upload
+ * and asset routes report the type sniffed from the BYTES, never a
+ * client-supplied filename or content-type. Covers the image types the
+ * spec admits (§11.1: PNG, JPEG, GIF, WebP) plus the generic text and
+ * JSON an extension form field accepts; anything unrecognized is
+ * `application/octet-stream`.
+ */
+/** Sniff one buffer's MIME type from its leading bytes. */
+export function sniffMime(bytes) {
+    if (bytes.length >= 8 &&
+        bytes[0] === 0x89 &&
+        bytes[1] === 0x50 && // P
+        bytes[2] === 0x4e && // N
+        bytes[3] === 0x47 // G
+    ) {
+        return "image/png";
+    }
+    if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
+        return "image/jpeg";
+    }
+    if (bytes.length >= 6 &&
+        bytes[0] === 0x47 && // G
+        bytes[1] === 0x49 && // I
+        bytes[2] === 0x46 // F
+    ) {
+        return "image/gif";
+    }
+    if (bytes.length >= 12 &&
+        bytes[0] === 0x52 && // R
+        bytes[1] === 0x49 && // I
+        bytes[2] === 0x46 && // F
+        bytes[3] === 0x46 && // F
+        bytes[8] === 0x57 && // W
+        bytes[9] === 0x45 && // E
+        bytes[10] === 0x42 && // B
+        bytes[11] === 0x50 // P
+    ) {
+        return "image/webp";
+    }
+    if (bytes.length >= 4 &&
+        bytes[0] === 0x25 && // %
+        bytes[1] === 0x50 && // P
+        bytes[2] === 0x44 && // D
+        bytes[3] === 0x46 // F
+    ) {
+        return "application/pdf";
+    }
+    // Strictly valid UTF-8 text (no NUL) reads as text; a JSON-shaped
+    // text body reports as JSON.
+    if (bytes.length > 0 && isUtf8Text(bytes)) {
+        const trimmed = new TextDecoder().decode(bytes).trimStart();
+        if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+            return "application/json";
+        }
+        return "text/plain";
+    }
+    return "application/octet-stream";
+}
+/** True when the bytes are valid UTF-8 with no NULs (a text file). */
+function isUtf8Text(bytes) {
+    for (const byte of bytes) {
+        if (byte === 0)
+            return false;
+    }
+    try {
+        new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/server/surfaces/rate-limit.js

@@ -0,0 +1,63 @@
+/**
+ * Action rate limiting (UI-blocks U3 Task 3, spec §15): 20 actions per
+ * second per principal per surface, burst 40, over → 429. A token
+ * bucket keyed `(slug, id, principal.user)`; memory-only, buckets
+ * lazily refilled on read and swept when the table grows.
+ */
+/** The refill rate (spec §15): 20 tokens per second. */
+export const RATE_PER_SECOND = 20;
+/** The burst capacity (spec §15): 40 tokens. */
+export const BURST_CAPACITY = 40;
+/** The per-principal-per-surface token bucket table. */
+export class ActionRateLimit {
+    buckets = new Map();
+    clock;
+    disabled = false;
+    constructor(clock) {
+        // Resolve Date.now at CALL time (see ActionDedup's note).
+        this.clock = clock ?? (() => Date.now());
+    }
+    /**
+     * Test seam: disable (or re-enable) the limiter. The actions tests
+     * disable it for the non-rate tests so per-test state isolation is
+     * not required (the service is a per-server singleton).
+     */
+    setDisabled(disabled) {
+        this.disabled = disabled;
+    }
+    /**
+     * Take one token: `true` when the action may proceed, `false` when
+     * the bucket is empty (→ 429). Refills lazily from the wall clock.
+     */
+    take(slug, id, user) {
+        if (this.disabled)
+            return true;
+        const now = this.clock();
+        const key = `${slug}
${id}
${user}`;
+        let bucket = this.buckets.get(key);
+        if (bucket === undefined) {
+            bucket = { tokens: BURST_CAPACITY - 1, lastRefill: now };
+            this.buckets.set(key, bucket);
+            if (this.buckets.size > 4096)
+                this.sweep(now);
+            return true;
+        }
+        const refill = ((now - bucket.lastRefill) / 1000) * RATE_PER_SECOND;
+        const tokens = Math.min(BURST_CAPACITY, bucket.tokens + refill);
+        bucket.lastRefill = now;
+        if (tokens < 1) {
+            bucket.tokens = tokens;
+            return false;
+        }
+        bucket.tokens = tokens - 1;
+        return true;
+    }
+    /** Drop stale full buckets (nothing a refill would change). */
+    sweep(now) {
+        const fullAfterMs = (BURST_CAPACITY / RATE_PER_SECOND) * 1000;
+        for (const [key, bucket] of this.buckets) {
+            if (now - bucket.lastRefill > fullAfterMs)
+                this.buckets.delete(key);
+        }
+    }
+}

package/dist/server/surfaces/service.js

@@ -0,0 +1,493 @@
+/**
+ * The surface service (UI-blocks U3 Task 2, spec §7.1–§7.3): renders
+ * and refetches extension surfaces over the loader's flattened
+ * `ExtensionSurfaceBinding` list, enforcing the per-principal access
+ * contract (§6.5) server-side:
+ *
+ * - `render` validates the extension's tree against its placement with
+ *   `handlers` = the surface's action keys, caches the verdict per
+ *   `(slug, id, key, principal.user)` for 60 s, and keeps per-instance
+ *   revision state (`rev`, `treeRev`, and the shared-data op log);
+ * - `data` refetches principal-specific surfaces by calling the
+ *   extension's `data()` on EVERY fetch; for a surface without `data()`
+ *   (and without `refreshMs`) the fetch re-runs `render` (the brief's
+ *   ruling; spec §7.1's "data refetch would re-run render");
+ * - `sharedData` surfaces keep the last {@link SHARED_OPS_WINDOW} ops
+ *   passed to `changed`/`bumpRev` per instance; a `since` inside the
+ *   window answers `{rev, treeRev, ops}`, a stale `since` falls back to
+ *   a full `data()` call;
+ * - `none` is indistinguishable from an unknown id (the routes map both
+ *   to the same 404 body).
+ *
+ * Errors: a render/data throw, or an invalid tree, throws
+ * {@link SurfaceFailedError} carrying the validation errors; the route
+ * maps it to `500 surface_failed` (bodies carry `errors` only when
+ * `server.dev`). The extension stays loaded.
+ */
+import { validateTree } from "../../blocks/validate.js";
+import { AccessCache } from "./access-cache.js";
+import { ActionDedup } from "./dedup.js";
+import { eventKey, instanceKey as defaultInstanceKey } from "./instance.js";
+import { sniffMime } from "./mime.js";
+import { ActionRateLimit } from "./rate-limit.js";
+import { WatcherRegistry } from "./watchers.js";
+/** The shared-data op-log window (spec §7.3): the last 100 updates. */
+export const SHARED_OPS_WINDOW = 100;
+/** The action timeout (spec §6.3): 10 s, then the action is a reject. */
+export const ACTION_TIMEOUT_MS = 10 * 1000;
+/** The body sent for a timed-out handler (spec §6.3 step 4). */
+const TIMED_OUT_RESULT = {
+    ok: false,
+    error: { message: "timed out" },
+};
+/** Errors `act` reports without calling the handler. */
+export class ActionRateLimitedError extends Error {
+    constructor() {
+        super("rate limited");
+        this.name = "ActionRateLimitedError";
+    }
+}
+export class UnknownActionError extends Error {
+    constructor(action) {
+        super(`unknown action: ${action}`);
+        this.name = "UnknownActionError";
+    }
+}
+function isRec(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Yield every node of a block tree, structurally (the walk only reads
+ * `children`, `fields`, `item`, and each field's own props — a tree
+ * validated at render time is the expected input, but an unvalidated
+ * def tree walks the same way).
+ */
+function* walkNodes(root) {
+    yield root;
+    // The tree record itself: descend its `root`. Blocks descend their
+    // `children` (stack/section/form/columns…), a page's `main`, a
+    // collection's `item` template, and a form's field lists; a `list`
+    // field's `item` field recurses the same way.
+    const childLists = [
+        root.root,
+        root.children,
+        root.fields,
+        root.main,
+        root.sidebar,
+        root.detail,
+    ];
+    for (const list of childLists) {
+        if (Array.isArray(list)) {
+            for (const child of list) {
+                if (isRec(child)) {
+                    if (isRec(child.block)) {
+                        // columns/grid wrappers: `{weight?, block}`
+                        yield* walkNodes(child.block);
+                    }
+                    else {
+                        yield* walkNodes(child);
+                    }
+                }
+            }
+        }
+        else if (isRec(list)) {
+            yield* walkNodes(list);
+        }
+    }
+    if (isRec(root.item))
+        yield* walkNodes(root.item);
+}
+/** A render/data failure (throw or invalid tree) → 500 surface_failed. */
+export class SurfaceFailedError extends Error {
+    errors;
+    constructor(message, errors) {
+        super(message);
+        this.name = "SurfaceFailedError";
+        this.errors = errors;
+    }
+}
+/**
+ * The render/data service over `opened.extensionSurfaces`. Holds the
+ * access cache and the per-instance revision state.
+ */
+export class SurfaceService {
+    bindings;
+    cache;
+    instances = new Map();
+    dedup = new ActionDedup();
+    rateLimit = new ActionRateLimit();
+    maxUploadBytes;
+    watchers;
+    publishChanged;
+    constructor(bindings, options) {
+        this.bindings = bindings;
+        this.cache = new AccessCache();
+        this.maxUploadBytes = options?.maxUploadBytes ?? Number.MAX_SAFE_INTEGER;
+        this.watchers = options?.watchers ?? new WatcherRegistry();
+        this.publishChanged = options?.publishChanged;
+    }
+    /** The watcher registry (the events route reads it per event). */
+    get watcherRegistry() {
+        return this.watchers;
+    }
+    /** Find one surface def by slug + id. */
+    locate(slug, id) {
+        for (const binding of this.bindings) {
+            if (binding.extension !== slug)
+                continue;
+            const def = binding.defs.find((entry) => entry.id === id);
+            if (def !== undefined)
+                return { slug, def };
+        }
+        return undefined;
+    }
+    /** The instance key: the surface's own `instanceKey` or the default. */
+    keyFor(def, params) {
+        if (def.instanceKey !== undefined)
+            return def.instanceKey(params);
+        return defaultInstanceKey(params);
+    }
+    /** The per-instance state, created on first touch (revs start at 0). */
+    stateFor(slug, id, key) {
+        const composite = `${slug}\u0001${id}\u0001${key}`;
+        let state = this.instances.get(composite);
+        if (state === undefined) {
+            state = { rev: 0, treeRev: 0, ops: [], fileFields: new Map() };
+            this.instances.set(composite, state);
+        }
+        return state;
+    }
+    /**
+     * Render one surface instance for one principal. Throws
+     * SurfaceFailedError on an extension throw or an invalid tree; returns
+     * `undefined` when the surface id is unknown or access is `none`.
+     */
+    async render(slug, id, params, principal, _stream) {
+        const located = this.locate(slug, id);
+        if (located === undefined)
+            return undefined;
+        const key = this.keyFor(located.def, params);
+        const result = await this.callRender(located, key, params, principal);
+        const validation = validateTree(result.tree, {
+            placement: located.def.placement,
+            handlers: new Set(Object.keys(located.def.actions ?? {})),
+        });
+        if (!validation.ok) {
+            throw new SurfaceFailedError(`surface ${slug}/${id} returned an invalid tree`, validation.errors);
+        }
+        this.cache.set(slug, id, key, principal.user, result.access);
+        if (result.access === "none")
+            return undefined;
+        // The watcher registration (Task 4, spec §7.3): a fetch carrying
+        // `X-Sigrun-Stream` creates/refreshes the entry with the access the
+        // fetch resolved — the events route reads the STORED access, never
+        // re-rendering per event.
+        if (_stream !== undefined) {
+            this.watchers.touch(_stream, principal.user ?? "", slug, id, key, result.access);
+        }
+        const state = this.stateFor(slug, id, key);
+        // Record the tree's file-field caps for the upload route (spec
+        // §7.1: the field's maxBytes, clamped by server.maxUploadBytes).
+        state.fileFields.clear();
+        for (const node of walkNodes(validation.tree)) {
+            if (node.type === "file" && typeof node.name === "string") {
+                if (typeof node.maxBytes === "number") {
+                    state.fileFields.set(node.name, node.maxBytes);
+                }
+            }
+        }
+        return {
+            tree: validation.tree,
+            data: result.data,
+            rev: state.rev,
+            treeRev: state.treeRev,
+            access: result.access,
+        };
+    }
+    /**
+     * Fetch one instance's data. Principal-specific surfaces call
+     * `data()` on every fetch (or re-run `render` when no `data()` exists
+     * — the data-less fallback ruling). `sharedData` surfaces answer from
+     * the op log when `since` is inside the window. Returns `undefined`
+     * for unknown ids and `none` access alike.
+     */
+    async data(slug, id, params, principal, since, _stream) {
+        const located = this.locate(slug, id);
+        if (located === undefined)
+            return undefined;
+        const key = this.keyFor(located.def, params);
+        const state = this.stateFor(slug, id, key);
+        const access = await this.accessFor(slug, id, key, params, principal);
+        if (access === "none")
+            return undefined;
+        // The since window (spec §7.3): contiguous iff every rev increment
+        // corresponds to one logged op (the full-fetch path below never
+        // bumps a sharedData rev, preserving this). `since == rev` answers
+        // an empty op list — the client is current.
+        if (located.def.sharedData === true &&
+            since !== undefined &&
+            since >= state.rev - state.ops.length &&
+            since <= state.rev) {
+            const ops = state.ops
+                .filter((entry) => entry.rev > since)
+                .flatMap((entry) => entry.ops);
+            return { rev: state.rev, treeRev: state.treeRev, ops };
+        }
+        let data;
+        let access2;
+        if (located.def.data !== undefined) {
+            let result;
+            try {
+                result = await located.def.data({
+                    principal,
+                    params,
+                    key,
+                    signal: new AbortController().signal,
+                });
+            }
+            catch (cause) {
+                throw new SurfaceFailedError(`surface ${slug}/${id} data() threw: ${cause instanceof Error ? cause.message : String(cause)}`);
+            }
+            data = result.data;
+            access2 = result.access;
+        }
+        else {
+            // No data(): the refetch re-runs render (the fallback ruling).
+            const rendered = await this.callRender(located, key, params, principal);
+            data = rendered.data;
+            access2 = rendered.access;
+        }
+        this.cache.set(slug, id, key, principal.user, access2);
+        if (_stream !== undefined) {
+            this.watchers.touch(_stream, principal.user ?? "", slug, id, key, access2);
+        }
+        if (access2 === "none")
+            return undefined;
+        // Rev advances only via bumpRev for sharedData surfaces (spec §7.3):
+        // the server-assigned rev reflects STORED changes, and a full data()
+        // refetch returns data consistent with the stored rev — bumping here
+        // would break the since-window invariant (every rev must correspond
+        // to one logged op) and strand clients at an unobservable revision.
+        // Principal-specific surfaces keep no ops contract; their bump is a
+        // per-fetch freshness marker only (gap detection, never consumed for
+        // ops).
+        if (located.def.sharedData !== true) {
+            state.rev += 1;
+        }
+        return { rev: state.rev, treeRev: state.treeRev, data };
+    }
+    /**
+     * One principal's access to one instance (spec §6.5): the cached
+     * verdict when fresh, else a re-render whose answer is cached.
+     */
+    async accessFor(slug, id, key, params, principal) {
+        const cached = this.cache.get(slug, id, key, principal.user);
+        if (cached !== undefined)
+            return cached;
+        const located = this.locate(slug, id);
+        if (located === undefined)
+            return "none";
+        const result = await this.callRender(located, key, params, principal);
+        this.cache.set(slug, id, key, principal.user, result.access);
+        return result.access;
+    }
+    /** The composite instance key (`slug
id
key`) for one def + params. */
+    compositeFor(slug, def, params) {
+        return `${slug}
${def.id}
${this.keyFor(def, params)}`;
+    }
+    /**
+     * The effective upload cap for one field (spec §7.1): the field's
+     * own `maxBytes` clamped by the server-wide `server.maxUploadBytes`.
+     * A field absent from the last rendered tree answers `undefined`.
+     */
+    uploadCapBytes(slug, id, key, field) {
+        const state = this.instances.get(`${slug}
${id}
${key}`);
+        if (state === undefined)
+            return undefined;
+        if (!state.fileFields.has(field))
+            return undefined;
+        const fieldMax = state.fileFields.get(field);
+        return Math.min(fieldMax ?? Number.MAX_SAFE_INTEGER, this.maxUploadBytes);
+    }
+    /** Test seam: enable or disable the action rate limiter. */
+    setRateLimitDisabled(disabled) {
+        this.rateLimit.setDisabled(disabled);
+    }
+    /**
+     * Invoke one action handler (spec §6.1/§6.3/§15): rate-limited per
+     * principal per surface, deduped per actionId per instance for 10
+     * minutes (a duplicate returns the FIRST stored result), timed out
+     * at 10 s (the handler is abandoned; its late settlement is dropped
+     * — the dedup entry still records the timeout body), and wrapped per
+     * §6.3: an accept WITH `update.ops` answers `{ok, rev, ops}` (ops
+     * logged for sharedData), an accept WITHOUT ops answers `{ok, rev}`
+     * with nothing recorded (extension surfaces own their data), and
+     * `navigate`/`toast` pass through.
+     *
+     * Ordering note (a decision, not an accident): the rate limiter
+     * takes its token BEFORE the dedup check, so a legitimate retry of
+     * an already-processed actionId still costs a token — replayed
+     * actionIds can never probe the service rate-free; the trade-off is
+     * that a client hammering one actionId can 429 itself.
+     *
+     * The caller (the route) has ALREADY enforced access; a miss/throw
+     * inside the handler maps to {@link SurfaceFailedError}.
+     */
+    async act(slug, id, key, params, principal, action, payload, actionId, signal) {
+        const located = this.locate(slug, id);
+        if (located === undefined)
+            return { ok: false, error: { message: "unknown surface" } };
+        const handler = located.def.actions?.[action];
+        if (handler === undefined)
+            throw new UnknownActionError(action);
+        if (!this.rateLimit.take(slug, id, principal.user ?? "")) {
+            throw new ActionRateLimitedError();
+        }
+        const composite = `${slug}
${id}
${key}`;
+        if (actionId !== undefined) {
+            const hit = this.dedup.check(actionId, composite);
+            if (hit !== undefined && hit !== null)
+                return hit.result;
+        }
+        const result = await this.invokeWithTimeout(() => handler({ principal, params, key, signal }, payload));
+        const wrapped = this.wrapResult(slug, id, key, result);
+        if (actionId !== undefined) {
+            this.dedup.record(actionId, composite, wrapped);
+        }
+        return wrapped;
+    }
+    /**
+     * Deliver one upload (spec §7.1/§7.2): the bytes were capped at the
+     * route (field `maxBytes` clamped by `server.maxUploadBytes`); the
+     * MIME is sniffed from the bytes, never the client name. The
+     * handler's result is wrapped like an action's.
+     */
+    async upload(slug, id, key, params, principal, field, name, bytes, signal) {
+        const located = this.locate(slug, id);
+        if (located === undefined)
+            return { ok: false, error: { message: "unknown surface" } };
+        const handler = located.def.actions?.[field];
+        if (handler === undefined)
+            throw new UnknownActionError(field);
+        const file = {
+            field,
+            name,
+            mime: sniffMime(bytes),
+            bytes,
+        };
+        let result;
+        try {
+            result = await handler({ principal, params, key, signal }, file);
+        }
+        catch (cause) {
+            throw new SurfaceFailedError(`surface ${slug}/${id} upload handler "${field}" threw: ${cause instanceof Error ? cause.message : String(cause)}`);
+        }
+        return this.wrapResult(slug, id, key, result);
+    }
+    /**
+     * The §6.3 accept rules: WITH `update.ops` the ops log (sharedData)
+     * and the answer carries `{ok, rev, ops}`; WITHOUT ops nothing is
+     * recorded and the answer is `{ok, rev}` (extension surfaces own
+     * their data — the rev bump announces the change). A reject and the
+     * `navigate`/`toast` fields pass through unchanged.
+     */
+    wrapResult(slug, id, key, result) {
+        if (!result.ok)
+            return result;
+        if (result.update !== undefined) {
+            const rev = this.bumpRev(slug, id, key, result.update);
+            return {
+                ok: true,
+                rev,
+                ops: result.update.ops,
+                ...(result.navigate === undefined ? {} : { navigate: result.navigate }),
+                ...(result.toast === undefined ? {} : { toast: result.toast }),
+            };
+        }
+        const rev = this.bumpRev(slug, id, key);
+        return {
+            ok: true,
+            rev,
+            ...(result.navigate === undefined ? {} : { navigate: result.navigate }),
+            ...(result.toast === undefined ? {} : { toast: result.toast }),
+        };
+    }
+    /**
+     * Race the handler against the 10 s timeout (spec §6.3 step 4): on a
+     * timeout the handler is abandoned (its late settlement is dropped)
+     * and the action answers the `timed out` reject body.
+     */
+    async invokeWithTimeout(invoke) {
+        let timer;
+        try {
+            const outcome = await Promise.race([
+                invoke().then((result) => ({
+                    kind: "done",
+                    result,
+                }), (cause) => ({
+                    kind: "threw",
+                    cause,
+                })),
+                new Promise((resolvePromise) => {
+                    timer = setTimeout(() => resolvePromise({ kind: "timedout" }), ACTION_TIMEOUT_MS);
+                }),
+            ]);
+            if (outcome.kind === "timedout")
+                return TIMED_OUT_RESULT;
+            if (outcome.kind === "threw") {
+                throw outcome.cause instanceof Error
+                    ? outcome.cause
+                    : new Error(String(outcome.cause));
+            }
+            return outcome.result;
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
+    /**
+     * Record a change for one instance (spec §7.3): advances `rev`;
+     * `ops` are kept only for `sharedData` surfaces (the window above).
+     * Returns the new `rev`.
+     */
+    bumpRev(slug, id, key, ops) {
+        const state = this.stateFor(slug, id, key);
+        state.rev += 1;
+        const located = this.locate(slug, id);
+        if (located?.def.sharedData === true && ops !== undefined) {
+            state.ops.push({ rev: state.rev, ops: ops.ops });
+            while (state.ops.length > SHARED_OPS_WINDOW)
+                state.ops.shift();
+        }
+        // The surface.changed nudge (Task 4, spec §7.3): the hashed
+        // instance key, the new rev, NO params and NO data; the events
+        // route's visibility case delivers it to watching streams only.
+        // The watching-stream list resolves HERE — the registry keys on
+        // the plain `key`; the wire's hashed `k` can never be reversed.
+        this.publishChanged?.({
+            type: "surface.changed",
+            slug,
+            id,
+            k: eventKey(slug, id, key),
+            rev: state.rev,
+            treeRev: state.treeRev,
+            streams: this.watchers.streamsFor(slug, id, key),
+        });
+        return state.rev;
+    }
+    /** Call the surface's `render`, mapping throws to SurfaceFailedError. */
+    async callRender(located, key, params, principal) {
+        try {
+            return await located.def.render({
+                principal,
+                params,
+                key,
+                signal: new AbortController().signal,
+            });
+        }
+        catch (cause) {
+            throw new SurfaceFailedError(`surface ${located.slug}/${located.def.id} render() threw: ${cause instanceof Error ? cause.message : String(cause)}`);
+        }
+    }
+}