@zackbart/connecta 0.26.3 → 0.28.0

package/AGENTS.md

@@ -4,13 +4,13 @@ This is the canonical instruction file for coding agents. `CLAUDE.md` is a
 symlink to this file so every agent works from the same conventions.
 
 A single MCP endpoint aggregating downstream connectors (remote MCP servers and
-plain HTTP APIs) behind eight meta-tools, `execute_code` among them. Every
+plain HTTP APIs) behind seven meta-tools, `execute_code` among them. Every
 deployment configures an executor, and agents reach connectors by writing
 JavaScript against it. One fetch-native core on Effect behind a Promise API,
-running on both Node and Cloudflare Workers. A program's write pauses until
-`resume_execution` repeats it. One `planned` decision changes that picture — an
-artifacts module — and until it ships, the code and the guides describe what
-exists.
+running on both Node and Cloudflare Workers. A program runs read-only and
+config-exempt tools; every other write is its own `call_destructive_tool` call,
+so the host's permission prompt is the only approval. The code and the guides
+describe what exists.
 
 - **[`ethos.md`](./ethos.md) is the constitution.** It states what connecta is
   and isn't, and its decisions table carries a verdict for every shape already
@@ -74,7 +74,7 @@ pins the generated deployment to the CLI package's exact version, restores the
 template `.gitignore` and the `CLAUDE.md` symlink, and refuses to merge into an
 existing path.
 `connecta doctor` verifies a running deployment's health, executor, and exact
-eight-tool surface. The template carries its own `Dockerfile` and
+seven-tool surface. The template carries its own `Dockerfile` and
 `docker-compose.yml`, so the generated project is the container: setup changes
 must keep the root README, the template (source, container files, and README),
 and the `scripts/check-package.mjs` smoke — which builds and runs that
@@ -141,14 +141,14 @@ an unclassified, double-classified, stale, or reasonless entry.
   Promise-based and name no Effect type: a deployment author should never need
   a second async paradigm to write a connector, so convert at the boundary,
   not in the caller. Effect is a hard dependency pinned to one exact version,
-  never a range, and it is the version Alchemy pins, so a deployment that uses
-  both resolves one Effect rather than two. `effect/unstable/*` modules are
-  allowed, which is exactly why the pin is exact: they break in minor releases,
+  never a range, and compatible with Alchemy's peer requirement, so a deployment
+  that uses both resolves one Effect rather than two. Modules tagged
+  `@stability unstable` are allowed behind subpaths: they can break in minor releases,
   so an upgrade is its own deliberate pull request, never a drive-by in another
   change. `effect/testing` stays out of `src/` (see import-graph purity). The
   MCP edges do not move with the core — `@modelcontextprotocol/server` upward,
-  the SDK client downstream; Effect's `McpServer` is parked until the Effect
-  core is stable and those edges are re-proven.
+  the SDK client downstream. Replacing either requires separate proof of the
+  wire contracts and request lifetimes; the stable core release is not that proof.
 - **Style.** There is no formatter. Match the surrounding code. The docs voice
   is precise, occasionally wry, and always explains *why* — don't flatten it
   into boilerplate.

package/CHANGELOG.md

@@ -2,7 +2,134 @@
 
 All notable changes to this package are documented here.
 
-## Unreleased
+## 0.28.0 — 2026-10-04
+
+This minor release removes program pauses ([#672](https://github.com/zackbart/connecta/issues/672)).
+`execute_code` programs run explicitly read-only tools and the writes
+`execute.approval` exempts, and every other write is its own
+`call_destructive_tool` call, so the host's permission prompt on that call is
+the only approval there is. Hosts approve one tool call at a time, and under
+always-allow or bypass modes the agent called `resume_execution` itself: each
+pause cost a round trip and a full replay and protected nothing. What breaks:
+`resume_execution` is gone, so the surface is seven tools again, and a host
+allow-list or cached tool list naming it should drop it.
+`execute.resumableWrites` and `execute.pausedRunTtlSeconds` now refuse to
+construct with an error naming
+the removal — delete them, including the Worker example's
+`execute: { resumableWrites: false }` line. A program's non-exempt write now
+fails `destructive_tool_requires_approval` with a `nextAction` for
+`call_destructive_tool`, exactly as it did on deployments without resumable
+writes, and a run never returns `{ paused: … }`. `Date.now()` and
+`Math.random()` inside a program are the runtime's own again rather than pinned
+per run. A deployment that sets neither option and whose programs only read
+can ignore all of this: approval exemptions, `execute.maxWrites`, storage
+contracts, and the D1 activity schema are unchanged, and any paused runs left
+in storage expire on their own TTL. The Node template now pins 0.28.0.
+
+### Removed
+
+- `resume_execution`, the run journal, deterministic replay, compare-and-set
+  run claims, and the pinned clock and randomness (code-mode `P6`) that
+  existed only so a replay could match. `W1`–`W8`, `W11`, `P6`, and `X12` are
+  retired clause ids.
+- The pause-only error codes: `execution_paused`, `pending_write_too_large`,
+  `journal_too_large`, `execution_interrupted`, `execution_diverged`,
+  `execution_claim_lost`, `approval_mismatch`, `execution_token_stale`,
+  `execution_in_progress`, `execution_expired`, `execution_not_found`, and
+  `resumable_writes_unavailable`. `write_outcome_unknown` stays, for an exempt
+  write that was sent and never answered.
+- `resumableWrites` from `/health`, and the "resumable writes off" note from
+  `connecta doctor`, which now verifies the exact seven-tool surface.
+- The pause and resume agent eval tasks.
+
+### Changed
+
+- The MCP instructions, the `execute_code` description, and the `usage` skill
+  describe the read-only program route: reads and config-exempt writes in a
+  program, every other write through `call_destructive_tool`. The description
+  states the exempt-write budget.
+- `execute.maxWrites` now bounds only config-exempt writes, the one kind a
+  program can still send. Its default stays 10.
+- Activity no longer emits `paused` or `approved` outcomes, the
+  `resume_execution` source, or an `approval` scope. The types keep them as
+  read-only history, the operator UI still renders older rows (a historical
+  pause now reads "Paused for approval"), and the D1 example still stores and
+  reads the `approval` column.
+- QuickJS still runs its child with `TZ=UTC`, now for parity with a Dynamic
+  Worker's local time rather than for replay.
+
+## 0.27.0 — 2026-10-01
+
+This minor release moves the runtime to stable Effect v4 and fixes execution,
+OAuth, storage, and operator recovery. Deployment APIs and the eight MCP tools
+keep their existing contracts, and the Node template now pins 0.27.0.
+Development requires TypeScript 5.9.3 or newer within 5.x.
+
+Duplicate API tool names now fail at construction. Memory, file, and D1 storage
+refuse TTLs that cannot produce finite expirations. Artifact quotas reserve 8 KiB
+for frame metadata, reducing the available content allowance by 4 KiB, and apply
+to historical snapshots too. Artifact render checks use the deployment's viewer
+theme.
+
+### Changed
+
+- Pin Effect to `4.0.0`, replacing `4.0.0-rc.117`, and align the optional
+  Alchemy setup instructions with the stable pin.
+- Require TypeScript 5.9.3 or newer within 5.x for repository and Node-template
+  development, matching Effect v4's TypeScript 5.9 minimum.
+
+### Fixed
+
+- Refuse already-aborted deadline operations and preserve explicit `null`
+  cancellation reasons (#660) (#661).
+- Return structured failures for malformed executor replies (#662).
+- Close callback and credential-test connector scopes after their final use,
+  keeping cleanup bounded and best-effort (#663) (#664).
+- Prevent concurrent OAuth state handoffs from replacing another owner on
+  storage that supports atomic claims (#665).
+- Show retryable Activity errors for unreadable pages and discard superseded
+  pagination responses (#666) (#667).
+- Reject invalid TTLs in memory and D1 storage before mutation, and match NUL
+  bytes literally in D1 list prefixes (#668) (#669).
+- Enforce catalog count and byte ceilings even when discovery is invalidated
+  while the listing is in flight (#644).
+- Retain OAuth cleanup lineage after uncertain storage commits, preserve
+  concurrent token rotation and revocation during issuer migration, and isolate
+  refresh coordination by credential owner (#645) (#646) (#648).
+- Return `null` for absent prototype-named credential fields (#647).
+- Reserve enough artifact frame metadata for valid document names and titles,
+  enforce current quotas on historical snapshots, and reject refresh scan
+  cursors that fail to advance (#649) (#658) (#650).
+- Reconcile connector state after failed operator mutations, ignore older data
+  reloads, and keep malformed collection responses recoverable (#651) (#652)
+  (#653).
+- Keep committed file snapshots consistent after rename, quarantine malformed
+  entries, and reject TTLs that cannot produce finite expirations (#654) (#655)
+  (#656).
+- Reject unreadable successful responses and malformed build-log streams from
+  named Vercel tools, preserving raw API response bodies and no-content
+  mutations (#657).
+- Keep queued catalog mutations alive across Worker requests while preserving
+  cancellation and storage ordering (#623).
+- Release failed access-token reservations before lookup publication, close
+  failed OAuth callback transports, and persist accepted rotating refresh tokens
+  after owner cancellation without reviving disconnected generations (#624)
+  (#625) (#626).
+- Count historical writes across divergent resumptions and bound resumed write
+  answers by the journal limit, retaining truthful outcomes for writes already
+  sent (#627) (#628).
+- Roll back rejected file-storage mutations, preserve prototype-named keys,
+  expire entries at their TTL boundary, and quarantine invalid snapshot roots
+  without losing their original bytes (#629) (#630) (#631) (#632).
+- Ignore superseded artifact-list responses, preserve newly created tokens when
+  an older list finishes, and reload a confined artifact shell when signing in
+  again (#633) (#634) (#635).
+- Advance artifact listings through empty continuation pages, refuse already
+  cancelled render checks, and validate Markdown with the viewer's theme across
+  writes and refreshes (#636) (#637) (#638).
+- Prevent doctor redirects from forwarding Cloudflare Access credentials,
+  reject unreadable successful Notion responses, and reject duplicate API tool
+  names before classification and dispatch can disagree (#639) (#640) (#641).
 
 ## 0.26.3 — 2026-09-28
 

package/README.md

@@ -10,19 +10,18 @@ writing code instead of loading a thousand tool definitions.
 You ask your agent a question that touches a service — Linear, Stripe, an
 internal API, anything you have connected. Here is what happens:
 
-1. The agent talks to one endpoint, yours, and sees eight tools. Always eight,
+1. The agent talks to one endpoint, yours, and sees seven tools. Always seven,
    no matter how many services sit behind it.
 2. It writes a short JavaScript program. Connecta runs it in a sandbox next to
    your integrations. The program can search for tools, call them, chain the
    calls, and shape the result.
 3. Only the answer comes back into the agent's context — not raw pages of
    API output.
-4. If the program wants to change something — create, update, delete — it
-   stops right there, before anything is sent, and hands the agent the exact
-   write. The agent repeats it through `resume_execution`, which your MCP
-   client can put in front of you first. Approve it and the program picks up
-   where it stopped, without re-reading what it already read. A single write
-   can also go straight through `call_destructive_tool`.
+4. If the agent wants to change something — create, update, delete — it
+   cannot do that from a program, unless your config exempts that tool. The
+   program refuses the write before anything is sent and hands back the exact
+   call; the agent makes it through `call_destructive_tool`, one visible call
+   your MCP client can put in front of you first.
 
 Credentials never leave the server. The program never sees them, and neither
 does the agent.
@@ -31,9 +30,9 @@ does the agent.
 flowchart TB
     Client["Your MCP client<br/>Claude, Cursor, …"]
 
-    subgraph Connecta["Connecta — one endpoint, eight tools, your credentials"]
-        Sandbox["execute_code<br/>the agent's program runs here<br/>reads run, writes pause"]
-        Explicit["resume_execution · call_destructive_tool<br/>the exact write, visible<br/>your client can ask you first"]
+    subgraph Connecta["Connecta — one endpoint, seven tools, your credentials"]
+        Sandbox["execute_code<br/>the agent's program runs here<br/>read-only tools, plus writes<br/>your config exempts"]
+        Explicit["call_destructive_tool<br/>one visible call per write<br/>your client can ask you first"]
     end
 
     Integrations["The integrations you chose<br/>Linear · Stripe · Notion · Vercel · your HTTP API · any MCP server"]
@@ -41,7 +40,6 @@ flowchart TB
     Client -->|"one connection"| Sandbox
     Client --> Explicit
     Sandbox -->|"reads"| Integrations
-    Sandbox -.->|"paused write"| Explicit
     Explicit -->|"writes"| Integrations
 ```
 
@@ -82,13 +80,11 @@ Fifty issues in, one small object out. Your context window notices.
   notice also points the agent to reduce or search the result inside a
   program. Discovery can show compact schemas, exact JSON Schema, or a
   TypeScript signature to read while writing JavaScript.
-- **Keep writes deliberate.** Only tools marked read-only run in a program
-  unasked. Any other call pauses the program with the exact write, and it
-  runs only once `resume_execution` repeats it — a visible call your client
-  can gate. A paused run is a journal in storage, not a held program, so it
-  survives a restart; it expires, and a write whose outcome is unknown is
-  never sent twice. Config — and only config — can exempt a cheap,
-  reversible write from asking, per tool or per connector.
+- **Keep writes deliberate.** Only tools marked read-only run in a program.
+  Every other write is a separate, visible `call_destructive_tool` call your
+  client can gate, so the host's permission prompt is the one approval there
+  is. Config — and only config — can exempt a cheap, reversible write from
+  asking, per tool or per connector, and then a program may make it.
 - **Run it on Node or Cloudflare Workers.** The core is shared; each deployment
   supplies its platform's executor and storage. The Node template also runs
   unchanged in Docker.
@@ -122,7 +118,7 @@ and why.
 
 Setup is written for an agent. Point yours at [`AGENTS.md`](./AGENTS.md) and
 ask it to set up a Connecta deployment; the
-[documentation](./documentation/) covers the architecture, the eight tools,
+[documentation](./documentation/) covers the architecture, the seven tools,
 code mode, and inbound auth if you want to go deeper. When upgrading an
 existing deployment, each [changelog](./CHANGELOG.md) release opens with what
 breaks and what a deployment can ignore.

package/bin/connecta.mjs

@@ -132,10 +132,18 @@ const DOCTOR_TIMEOUT_MS = 10_000;
 
 async function doctorFetch(url, init = {}) {
   try {
-    return await fetch(url, {
+    const response = await fetch(url, {
       ...init,
+      redirect: "manual",
       signal: AbortSignal.timeout(DOCTOR_TIMEOUT_MS),
     });
+    if ([301, 302, 303, 307, 308].includes(response.status)) {
+      await response.body?.cancel().catch(() => {});
+      throw new Error(
+        `HTTP ${response.status} redirect refused: doctor sends authentication only to the configured deployment URL.`,
+      );
+    }
+    return response;
   } catch (error) {
     if (
       error instanceof Error &&
@@ -249,7 +257,6 @@ async function doctor() {
     "call_tool",
     "execute_code",
     "get_result",
-    "resume_execution",
     "search_tools",
     "skills",
   ];
@@ -302,10 +309,7 @@ async function doctor() {
   console.log(
     `Connecta doctor passed: ${health.connectors} connector(s), ` +
       `${executorName ? `${executorName} executed` : "code executed"}, ` +
-      "prescribed eight-tool surface" +
-      // resume_execution is listed either way; whether programs can write is
-      // what an operator cannot tell from the tool list, so say when not.
-      (health.resumableWrites === false ? ", resumable writes off" : "") +
+      "prescribed seven-tool surface" +
       (drifted.length > 0
         ? `, catalog drift on ${drifted.length} connector(s).`
         : "."),

package/dist/access-tokens.js

@@ -191,8 +191,19 @@ export class AccessTokenManager {
                 ? {}
                 : { principal: { ...createdBy } }),
         };
-        await this.updateActive(record.id, true);
-        await this.storage.set(recordKey(record.id), JSON.stringify(record));
+        try {
+            await this.updateActive(record.id, true);
+            await this.storage.set(recordKey(record.id), JSON.stringify(record));
+        }
+        catch (error) {
+            // No lookup write has started, so this secret can never authenticate.
+            // A failed record or reservation write may still have committed: revoke
+            // whatever metadata exists and release the reservation even on a miss.
+            const revoked = await this.revoke(record.id, record.createdBy);
+            if (!revoked)
+                await this.updateActive(record.id, false);
+            throw error;
+        }
         // A failed lookup write may have committed. Keep its reservation and
         // metadata, so a manager can revoke it without ever returning the secret.
         await this.storage.set(lookupKey(hash), JSON.stringify({ version: 1, id: record.id }));

package/dist/activity.d.ts

@@ -2,7 +2,7 @@ import type { ActivityModule } from "./module-contracts.js";
 import type { CatalogDriftCounts, Logger } from "./types.js";
 export type ActivityCallSource = "call_tool" | "call_destructive_tool" | "batch_call" | "execute_code" | "resume_execution";
 export type ActivityOutcome = "success" | "error" | "timeout" | "cancelled" | "paused" | "approved";
-/** How much one `resume_execution` approved: this call, or this tool for the run. */
+/** Read-only history: how much one `resume_execution` approved (#672). */
 export type ActivityApproval = "call" | "tool";
 export type AgentFriction = "tool_not_found" | "schema_retry" | "destructive_reroute" | "auth_required" | "result_too_large";
 export { agentFrictionForCode } from "./activity-friction.js";
@@ -50,8 +50,9 @@ export interface ToolCallActivityEvent {
      */
     friction?: AgentFriction;
     /**
-     * Set only on an `approved` event: the scope the approval covered. An enum,
-     * like everything else here — the approved arguments are never recorded.
+     * Read-only history: set only on an `approved` event written before issue
+     * #672, the scope the approval covered. An enum, like everything else
+     * here — the approved arguments were never recorded.
      */
     approval?: ActivityApproval;
     serverName: string;
@@ -149,7 +150,7 @@ export interface ActivityRequestContext {
     defer?: (promise: Promise<unknown>) => void;
     logger: Logger;
 }
-export type ActivityEventInput = Pick<ToolCallActivityEvent, "connectorId" | "toolName" | "address" | "source" | "outcome" | "durationMs" | "attempts" | "errorCode" | "friction" | "approval">;
+export type ActivityEventInput = Pick<ToolCallActivityEvent, "connectorId" | "toolName" | "address" | "source" | "outcome" | "durationMs" | "attempts" | "errorCode" | "friction">;
 /**
  * Best-effort by design: activity storage can never change a tool result.
  * Workers attach async sinks to waitUntil; synchronous sinks such as Analytics

package/dist/activity.js

@@ -49,18 +49,9 @@ export function recordToolActivity(context, input) {
         source: input.source,
         outcome: input.outcome,
         durationMs: Math.max(0, Math.trunc(input.durationMs)),
-        // A pause and an approval reach nothing downstream, so they are the two
-        // events that honestly carry zero attempts. Every other outcome keeps its
-        // floor of one, as it always has.
-        attempts: input.outcome === "paused" || input.outcome === "approved"
-            ? 0
-            : Math.max(1, Math.trunc(input.attempts)),
+        attempts: Math.max(1, Math.trunc(input.attempts)),
         ...(input.errorCode ? { errorCode: input.errorCode } : {}),
         ...(friction ? { friction } : {}),
-        ...(input.outcome === "approved" &&
-            (input.approval === "call" || input.approval === "tool")
-            ? { approval: input.approval }
-            : {}),
         serverName: context.serverInfo.name,
         serverVersion: context.serverInfo.version,
         ...(context.deploymentId

package/dist/artifacts/connector.d.ts

@@ -1,3 +1,4 @@
+import { type ResolvedTheme } from "../branding.js";
 import type { Connector } from "../types.js";
 import { type ArtifactOperations } from "./operations.js";
 import { type ArtifactRefreshService } from "./refresh.js";
@@ -50,6 +51,8 @@ export interface ArtifactsConnectorOptions {
     renderCheck?: ArtifactRenderCheck;
     /** Where pages are served, when not the deployment's own origin. */
     origin?: string;
+    /** Resolved deployment theme, available after the module binds to core. */
+    theme?: () => ResolvedTheme | undefined;
 }
 export declare function artifactsConnector(options: ArtifactsConnectorOptions): Connector;
 export {};

package/dist/artifacts/connector.js

@@ -9,6 +9,7 @@
 import { api } from "../connectors/api.js";
 import { callerOf } from "../connector-caller.js";
 import { ConnectorCallError } from "../errors.js";
+import { resolveTheme } from "../branding.js";
 import { buildFrameDocument, frameCsp } from "./document.js";
 import { buildGuide, GUIDE_SUMMARY } from "./guide.js";
 import { invalidContent, } from "./operations.js";
@@ -56,6 +57,9 @@ function renderFindings(values) {
 }
 /** Run a hook under its 20-second deadline and the call's own signal. Never throws. */
 export async function runRenderCheck(hook, input, callSignal) {
+    if (callSignal?.aborted) {
+        return { ok: false, unavailable: "The render check's call was cancelled; nothing was saved." };
+    }
     const controller = new AbortController();
     let timer;
     const onAbort = () => controller.abort(callSignal?.reason);
@@ -162,6 +166,7 @@ export function artifactsConnector(options) {
                 document: buildFrameDocument({
                     kind: head.kind,
                     source,
+                    theme: options.theme?.() ?? resolveTheme(),
                     global: globalFor(artifactId, head, head.view, liveOf(head), false),
                     data,
                 }),
@@ -450,6 +455,7 @@ export function artifactsConnector(options) {
                         document: buildFrameDocument({
                             kind: args.kind,
                             source: args.source,
+                            theme: options.theme?.() ?? resolveTheme(),
                             global: {
                                 id: "preview",
                                 title: "Preview",

package/dist/artifacts/document.js

@@ -8,6 +8,12 @@
 import { scanHtml } from "./html-scan.js";
 import { scriptSafeJson } from "./json.js";
 import { markdownPage, MarkdownNestingError } from "./markdown.js";
+/**
+ * Reserve for the injected global and Markdown theme beyond source and data.
+ * Sixteen 64-character document names appear twice, alongside timestamps and
+ * versions, and a 160-character title can expand sixfold when script-escaped.
+ */
+export const FRAME_OVERHEAD_BYTES = 8192;
 /**
  * The frame's Content-Security-Policy. `sandbox allow-scripts` without
  * `allow-same-origin` gives the page an opaque origin — no cookies, no

package/dist/artifacts/json.js

@@ -66,3 +66,13 @@ export function jsonProblem(value, maxDepth) {
     }
     return undefined;
 }
+const encoder = new TextEncoder();
+/** A string's size in UTF-8 bytes: what every artifact limit counts. */
+export function utf8Bytes(text) {
+    return encoder.encode(text).byteLength;
+}
+/** SHA-256 as lowercase hex: the content address of a stored body. */
+export async function sha256Hex(text) {
+    const digest = await crypto.subtle.digest("SHA-256", encoder.encode(text));
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}

package/dist/artifacts/module.js

@@ -1,4 +1,5 @@
 // artifacts(): the typed module a deployment passes as `ConnectaConfig.artifacts`.
+import { resolveBranding } from "../branding.js";
 import { artifactsConnector } from "./connector.js";
 import { ArtifactOperations } from "./operations.js";
 import { artifactRoutes } from "./routes.js";
@@ -43,17 +44,22 @@ export function artifacts(options) {
         limits,
     });
     const refresh = new ArtifactRefreshService(operations);
+    let theme;
     const connector = artifactsConnector({
         operations,
         refresh,
         allowlist,
         limits,
+        theme: () => theme,
         ...(options.renderCheck ? { renderCheck: options.renderCheck } : {}),
     });
     return Object.freeze({
         connector,
         handle: artifactRoutes({ operations, allowlist }),
-        bindRefresh: (runtime) => refresh.bind(runtime),
+        bindRefresh: (runtime) => {
+            refresh.bind(runtime);
+            theme = resolveBranding(runtime.branding).theme;
+        },
         refresh: (id, by) => refresh.run(id, { manual: by }),
         runDue: () => refresh.runDue(),
     });

package/dist/artifacts/operations.d.ts

@@ -1,3 +1,4 @@
+import type { ResolvedTheme } from "../branding.js";
 import { type CheckContext } from "./validate.js";
 import type { ArtifactActor, ArtifactHeadRecord, ArtifactIssue, ArtifactKind, ArtifactStore, ArtifactValidation, ArtifactVersionRecord, ArtifactRefreshSchedule, ArtifactRunRecord } from "./types.js";
 type ArtifactFailureCode = "conflict" | "invalid_args" | "not_found" | "unavailable";
@@ -164,10 +165,11 @@ export declare class ArtifactOperations {
     page(id: string, pin?: {
         view?: number;
         documents?: Record<string, number>;
-    }): Promise<Result<{
+    }, theme?: ResolvedTheme): Promise<Result<{
         head: ArtifactHeadRecord;
         view: ArtifactVersionRecord;
         source: string;
+        document: string;
         documents: Record<string, {
             record: ArtifactVersionRecord;
             value: unknown;

package/dist/artifacts/operations.js

@@ -14,7 +14,8 @@
 // Nothing here throws for a caller's mistake. Operations answer
 // `{ ok: false, code, message }`, and the connector turns that into its typed
 // error; a throw means storage failed.
-import { sha256Hex, utf8Bytes } from "../run-journal.js";
+import { buildFrameDocument, FRAME_OVERHEAD_BYTES } from "./document.js";
+import { sha256Hex, utf8Bytes } from "./json.js";
 import { markdownPage, MarkdownNestingError } from "./markdown.js";
 import { ARTIFACT_ID, checkDocument, checkDocumentTotals, checkView, finish, validDocumentName, } from "./validate.js";
 /** Physical head moves a write absorbs before giving up as busy. */
@@ -23,8 +24,6 @@ const MAX_SWAP_ATTEMPTS = 8;
 const HISTORY_LIMIT = 20;
 /** Heads one listing call may examine while searching. */
 const LIST_SCAN_LIMIT = 1000;
-/** What the viewer adds around a page beyond its source and documents. */
-const FRAME_OVERHEAD_BYTES = 4096;
 /** Tombstones keep version numbers, so distinct names need their own bound. */
 const DOCUMENT_NAMES_LIMIT = 64;
 const fail = (code, message, extra = {}) => ({ ok: false, code, message, ...extra });
@@ -827,7 +826,7 @@ export class ArtifactOperations {
         return { ok: true, head: current.head, record, value, history };
     }
     /** The page a viewer renders: a view version and exactly the documents asked for (all current ones by default). */
-    async page(id, pin = {}) {
+    async page(id, pin = {}, theme) {
         const badId = this.#checkId(id);
         if (badId)
             return badId;
@@ -841,7 +840,10 @@ export class ArtifactOperations {
         const wanted = pin.documents
             ? Object.entries(pin.documents)
             : liveDocuments(head).map(([name, record]) => [name, record.version]);
-        const documents = {};
+        // Historical streams were each valid when written, but their selected
+        // versions may never have coexisted. Bound the selection before loading
+        // its bodies, then check the actual bodies against today's configuration.
+        const selected = [];
         for (const [name, version] of wanted) {
             const badName = this.#checkDocumentName(name);
             if (badName)
@@ -849,11 +851,58 @@ export class ArtifactOperations {
             const record = await this.#version(id, `doc:${name}`, head.documents[name], version);
             if (!record)
                 return this.#notFound(id);
-            if (record.removed)
-                continue;
-            documents[name] = { record, value: JSON.parse(await this.#body(record.body)) };
+            if (!record.removed)
+                selected.push([name, record]);
+        }
+        const { limits } = this.#context;
+        const tooMany = checkDocumentTotals(selected.length, 0, limits);
+        if (tooMany)
+            return invalidContent("The snapshot", finish({ errors: [tooMany], warnings: [] }));
+        const source = await this.#body(view.body);
+        const sourceBytes = utf8Bytes(source);
+        if (sourceBytes > limits.sourceBytes) {
+            return invalidContent("The snapshot", finish({ errors: [{
+                        code: "E_TOO_LARGE", severity: "error",
+                        message: `The view is ${sourceBytes} bytes; the limit is ${limits.sourceBytes}.`,
+                    }], warnings: [] }));
         }
-        return { ok: true, head, view, source: await this.#body(view.body), documents };
+        const documents = {};
+        const data = {};
+        let dataBytes = 0;
+        for (const [name, record] of selected) {
+            const value = JSON.parse(await this.#body(record.body));
+            const checked = checkDocument(name, value, limits);
+            if (checked.error)
+                return invalidContent("The snapshot", finish({ errors: [checked.error], warnings: [] }));
+            dataBytes += checked.bytes;
+            const totals = checkDocumentTotals(selected.length, dataBytes, limits);
+            if (totals)
+                return invalidContent("The snapshot", finish({ errors: [totals], warnings: [] }));
+            documents[name] = { record, value };
+            data[name] = checked.text;
+        }
+        const tooLarge = () => invalidContent("The snapshot", finish({ errors: [{
+                    code: "E_TOO_LARGE", severity: "error",
+                    message: `The rendered page exceeds the current limit of ${limits.renderedBytes} bytes.`,
+                }], warnings: [] }));
+        // For HTML, source plus data is a lower bound before frame construction.
+        // Markdown can shrink or expand, so its final document decides the bound.
+        if (dataBytes + (head.kind === "html" ? sourceBytes : 0) > limits.renderedBytes)
+            return tooLarge();
+        const rendered = buildFrameDocument({
+            kind: head.kind, source, ...(theme ? { theme } : {}),
+            global: {
+                id, title: head.title, view: { version: view.version },
+                documents: Object.fromEntries(selected.map(([name, record]) => [name, {
+                        version: record.version, updatedAt: record.at,
+                    }])),
+                snapshot: pin.view !== undefined || pin.documents !== undefined,
+            },
+            data,
+        });
+        if (utf8Bytes(rendered) > limits.renderedBytes)
+            return tooLarge();
+        return { ok: true, head, view, source, document: rendered, documents };
     }
     async list(options) {
         if (options.cursor !== undefined && !ARTIFACT_ID.test(options.cursor)) {
@@ -864,9 +913,11 @@ export class ArtifactOperations {
         let after = options.cursor;
         let scanned = 0;
         for (;;) {
+            const limit = Math.min(100, LIST_SCAN_LIMIT - scanned);
+            const previous = after;
             const page = await this.#store.heads({
                 ...(after === undefined ? {} : { after }),
-                limit: Math.min(100, LIST_SCAN_LIMIT - scanned),
+                limit,
             });
             for (const item of page.heads) {
                 scanned++;
@@ -885,8 +936,15 @@ export class ArtifactOperations {
             }
             if (page.next === undefined)
                 return { ok: true, items };
+            if (previous !== undefined && page.next <= previous) {
+                return fail("unavailable", "Artifact head scan did not advance; retry the listing.");
+            }
+            // Listed keys can disappear before the store reads them. Its cursor
+            // still consumed the whole page, including those missing head records.
+            after = page.next;
+            scanned += Math.max(0, limit - page.heads.length);
             if (scanned >= LIST_SCAN_LIMIT) {
-                return after === undefined ? { ok: true, items } : { ok: true, items, nextCursor: after };
+                return { ok: true, items, nextCursor: after };
             }
         }
     }

package/dist/artifacts/refresh.d.ts

@@ -28,6 +28,8 @@ export interface ArtifactRefreshRuntime {
         isError?: boolean;
     }>;
     claimMs: number;
+    /** UI branding shared by the viewer and every render check. */
+    branding?: import("../types.js").ConnectaBranding;
 }
 export type RefreshOutcome = {
     status: "skipped";