@1agh/maude 0.47.0 → 0.49.0

package/README.md

@@ -82,7 +82,7 @@ maude doctor --json   # machine-readable envelope
 
 ### Sidecar cache — `maude cache`
 
-Flow + design commands reuse expensive cross-session work through a small sidecar cache at `.ai/cache/` ([DDR-061](.ai/decisions/DDR-061-sidecar-cache-monitor-background-orchestration.md)): domain research (skips 30–90 s of WebSearch on a same-domain brief), codebase-intelligence scans (skips rescan when the tree is unchanged), parsed design-system vocabulary, and security-review reuse (one shared 1-hour window across `/flow:validate`, `/flow:done`, `/flow:validate-security`). Correctness comes first — most layers are content-addressed (a changed input changes the key → guaranteed miss), and a stale entry is never served speculatively.
+Flow + design commands reuse expensive cross-session work through a small sidecar cache at `.ai/cache/` ([DDR-061](.ai/archive/decisions/DDR-061-sidecar-cache-monitor-background-orchestration.md)): domain research (skips 30–90 s of WebSearch on a same-domain brief), codebase-intelligence scans (skips rescan when the tree is unchanged), parsed design-system vocabulary, and security-review reuse (one shared 1-hour window across `/flow:validate`, `/flow:done`, `/flow:validate-security`). Correctness comes first — most layers are content-addressed (a changed input changes the key → guaranteed miss), and a stale entry is never served speculatively.
 
 ```sh
 maude cache list              # layers, entry counts, sizes, last-write time
@@ -95,7 +95,7 @@ The `research/domain` and `codebase-intelligence` layers are **committed** (dete
 
 ### Plugins call `maude` for executable logic
 
-Plugin slash-commands reach all executable logic through the on-PATH `maude` binary — never a relative `cli/lib/*.mjs` path or a raw `$CLAUDE_PLUGIN_ROOT/dev-server/bin/*.sh` invocation ([DDR-062](.ai/decisions/DDR-062-plugins-reach-executable-logic-via-maude.md)). The marketplace copies each plugin alone (no sibling `cli/`, no `dev-server/`), and a flow command's `$CLAUDE_PLUGIN_ROOT` points at the flow plugin (which has no dev-server at all) — so the only contract that holds across every install shape is `maude`, which resolves bundled helpers from its own package root. Cache/preflight go via `maude cache …` / `maude preflight …`; the design dev-server's bash helpers go via **`maude design <verb>`** (`screenshot`, `server-up`, `prep`, `slug`, `smoke`, `runtime-health`, …) — see `maude design help`. Keep the global `maude` current; a stale binary means stale helpers.
+Plugin slash-commands reach all executable logic through the on-PATH `maude` binary — never a relative `cli/lib/*.mjs` path or a raw `$CLAUDE_PLUGIN_ROOT/dev-server/bin/*.sh` invocation ([DDR-062](.ai/archive/decisions/DDR-062-plugins-reach-executable-logic-via-maude.md)). The marketplace copies each plugin alone (no sibling `cli/`, no `dev-server/`), and a flow command's `$CLAUDE_PLUGIN_ROOT` points at the flow plugin (which has no dev-server at all) — so the only contract that holds across every install shape is `maude`, which resolves bundled helpers from its own package root. Cache/preflight go via `maude cache …` / `maude preflight …`; the design dev-server's bash helpers go via **`maude design <verb>`** (`screenshot`, `server-up`, `prep`, `slug`, `smoke`, `runtime-health`, …) — see `maude design help`. Keep the global `maude` current; a stale binary means stale helpers.
 
 ## Runtime requirements
 
@@ -105,10 +105,10 @@ Plugin slash-commands reach all executable logic through the on-PATH `maude` bin
 
 ## Collaboration model
 
-Two clean paths, no middle ground ([DDR-047](.ai/decisions/DDR-047-collab-scope-cut-no-lan-mode-hub-admin-ui.md)):
+Two clean paths, no middle ground ([DDR-047](.ai/archive/decisions/DDR-047-collab-scope-cut-no-lan-mode-hub-admin-ui.md)):
 
 - **v1.0 — git handoff OR loopback multi-tab.** Push / pull is the cross-machine story. On a single machine, two browser tabs (or two Claude Code instances editing the same repo) sync cursors, comments, and annotations live over loopback WebSocket. The dev server refuses any non-loopback `host` header on the collab WS endpoint.
-- **v1.1 — deploy a hub** (Phase 9, in-flight). Cross-machine live collab needs a hub binary you deploy yourself. No tunnel mode; no shared cloud. **Boot order can't eat your work** ([DDR-102](.ai/decisions/DDR-102-cold-start-divergence-resolution.md)): a per-machine journal tells clean catch-ups apart from genuine divergence; diverged canvases snapshot **both** versions to `_history/` before the newer one wins, so the loser is one `/design:rollback` away — and `maude design status` reports per-canvas sync state honestly (synced / pending / auth-rejected).
+- **v1.1 — deploy a hub** (Phase 9, in-flight). Cross-machine live collab needs a hub binary you deploy yourself. No tunnel mode; no shared cloud. **Boot order can't eat your work** ([DDR-102](.ai/archive/decisions/DDR-102-cold-start-divergence-resolution.md)): a per-machine journal tells clean catch-ups apart from genuine divergence; diverged canvases snapshot **both** versions to `_history/` before the newer one wins, so the loser is one `/design:rollback` away — and `maude design status` reports per-canvas sync state honestly (synced / pending / auth-rejected).
 
 ## Security
 
@@ -118,7 +118,8 @@ Solo mode (the default) is fully local — no accounts, no telemetry, no network
 
 User-facing docs live in two places — the README points you the right way:
 
-- **Reference** (every command, every config key, recipes for Next.js / Expo / monorepo) → [`site/content/docs/`](./site/content/docs/) (served at https://maude.sh once Vercel is wired — see [DDR-005](.ai/decisions/DDR-005-docs-site-stack-and-hosting.md)).
+- **Reference** (every command, every config key, recipes for Next.js / Expo / monorepo) → [`site/content/docs/`](./site/content/docs/) (served at https://maude.sh once Vercel is wired — see [DDR-005](.ai/archive/decisions/DDR-005-docs-site-stack-and-hosting.md)).
+- **kgai knowledge-graph backend** (opt-in shared decision memory across repos) → [`docs/kgai-onboarding.md`](./docs/kgai-onboarding.md) (per user) + [`docs/kgai-company-setup.md`](./docs/kgai-company-setup.md) (one-time admin). Off by default — absent `kg`, every command runs its classic `.ai/` path.
 - **Quickstart** + **contributor info** → this README.
 
 The docs site auto-generates per-command pages from `plugins/{flow,design}/commands/*.md` frontmatter and a typed schema reference from `plugins/flow/.claude-plugin/config.schema.json`. Adding a new command → docs update on next build.
@@ -130,7 +131,7 @@ The repo is a **pnpm workspace monorepo** with one published npm package (`@1agh
 | Workspace | Purpose |
 | --------- | ------- |
 | `.` (root) | The single npm publisher — CLI, dev-server entry, plugin templates that ship to npm. |
-| `site/` | Docs site — Fumadocs + Next.js, deployed to Vercel ([DDR-005](.ai/decisions/DDR-005-docs-site-stack-and-hosting.md)). |
+| `site/` | Docs site — Fumadocs + Next.js, deployed to Vercel ([DDR-005](.ai/archive/decisions/DDR-005-docs-site-stack-and-hosting.md)). |
 | `apps/studio/` | Zero-dep Node dev server + browser client. Bundled output (`dist/`) is the only thing in the npm tarball. |
 | `apps/hub/` | Reserved for the v1.1 federated hub (Phase 9). |
 

package/apps/studio/acp/bridge.ts

@@ -396,7 +396,14 @@ export function newSessionParams(
     // gets it double-loaded with zero suppression (the exact double-
     // registration risk this override exists to close). No test currently
     // catches this drift.
-    options.settings = { enabledPlugins: { 'design@maude': false } };
+    // `kgai` is the third-party autonomous-capture plugin the desktop bundle
+    // injects (plugin-bootstrap.ts). Suppressing its natively-installed copy is
+    // MORE load-bearing than for our own plugins: a user-installed kgai would
+    // run its own SessionStart `install.sh` (Go/network) and point at a
+    // different engine version than the pinned, signed sidecar we ship. Its id
+    // has no `@marketplace` suffix — it's injected as a bare local plugin dir
+    // whose manifest `name` is `kgai`.
+    options.settings = { enabledPlugins: { 'design@maude': false, kgai: false } };
   }
   meta.claudeCode = { options };
   return {

package/apps/studio/acp/plugin-bootstrap.ts

@@ -38,7 +38,7 @@
 // id via the SDK's documented `flag > user` settings precedence — so the
 // bundled copy injected here is the ONLY one that ever loads.
 
-import { DESIGN_PLUGIN_DIR, FLOW_PLUGIN_DIR } from '../paths.ts';
+import { DESIGN_PLUGIN_DIR, FLOW_PLUGIN_DIR, KGAI_PLUGIN_DIR } from '../paths.ts';
 
 /**
  * SDK plugin-load config (`@anthropic-ai/claude-agent-sdk` `SdkPluginConfig`).
@@ -61,6 +61,8 @@ export interface SessionPluginDeps {
   designDir: string | null;
   /** Bundled `flow` plugin dir, or null (npm/web layout). */
   flowDir: string | null;
+  /** Bundled third-party `kgai` plugin dir, or null (only staged in the .app). */
+  kgaiDir?: string | null;
 }
 
 /**
@@ -81,6 +83,17 @@ export function computeSessionPlugins(deps: SessionPluginDeps): SdkPluginConfig[
   // `/flow` auto-load is intentionally OFF for now (2026-07-03) — the chat ships
   // design-only. `deps.flowDir` stays resolved (harmless) so restoring it is a
   // one-liner: re-add `add(deps.flowDir)`.
+  //
+  // kgai (third-party, MIT) — injected so its `Stop` hook loads and autonomous
+  // decision capture actually fires in the ACP panel. Without this the packaged
+  // app captures NOTHING: the session is built with settingSources:['user']
+  // (DDR-144) and a terminal-less DDR-177 user never marketplace-installs it.
+  // Non-null only in the desktop bundle (sync-kg.mjs stages a pinned release).
+  //
+  // ⚠ DRIFT TRAP — adding an id here REQUIRES a matching `'<id>': false` entry in
+  // bridge.ts's hand-maintained `enabledPlugins` suppression literal, or a user
+  // who ALSO has it natively enabled gets it double-loaded (see that comment).
+  add(deps.kgaiDir ?? null);
   return out;
 }
 
@@ -117,5 +130,6 @@ export function resolveSessionPlugins(): SdkPluginConfig[] {
     native: isNativePluginContext(),
     designDir: DESIGN_PLUGIN_DIR,
     flowDir: FLOW_PLUGIN_DIR,
+    kgaiDir: KGAI_PLUGIN_DIR,
   });
 }

package/apps/studio/api.ts

@@ -5,7 +5,7 @@ import crypto from 'node:crypto';
 import type { Dirent } from 'node:fs';
 import { lstat, mkdir, readdir, readFile, rename, rm, stat as statp } from 'node:fs/promises';
 import path from 'node:path';
-
+import { createAssetMirror, s3ConfigFromEnv } from './assets-s3.ts';
 import { renderBriefBoard, validateCanvasName } from './canvas-create.ts';
 import {
   type AssembleClip,
@@ -1646,6 +1646,12 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
   //     user input, but a poisoned designRoot must still not escape).
   // Running total of bytes this server instance has actually written (post-dedupe).
   let assetBytesWritten = 0;
+  // S3/R2 asset lane (Cloud Phase 3 Task 2). Unconfigured by default — a local
+  // project and a single-box self-hoster both work with no bucket at all.
+  const assetMirror = createAssetMirror(s3ConfigFromEnv());
+  if (assetMirror.configured) {
+    console.log(`[assets] mirroring new assets to ${assetMirror.describe}`);
+  }
 
   /**
    * DDR-148 — the streaming write path behind `POST /_api/asset`. Reads the
@@ -1777,7 +1783,17 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
       }
       await rename(tmpAbs, fileAbs);
       assetBytesWritten += total;
-      return { ok: true, path: `assets/${name}` };
+      const rel = `assets/${name}`;
+      // S3/R2 lane (Cloud Phase 3) — mirror the bytes so a second machine can
+      // resolve them without the file riding git. Deliberately awaited but
+      // never able to fail the save: the asset is already on disk, the mirror
+      // is the redundant copy, and `maude hub asset-check` reconciles a miss.
+      // Only a genuinely NEW file reaches here, so this is not re-uploading on
+      // every dedupe hit.
+      if (assetMirror.configured) {
+        void assetMirror.push(rel, new Uint8Array(await Bun.file(fileAbs).arrayBuffer()));
+      }
+      return { ok: true, path: rel };
     } catch (err) {
       await cleanup();
       return { ok: false, status: 500, error: err instanceof Error ? err.message : 'write failed' };

package/apps/studio/assets-s3.ts

@@ -0,0 +1,291 @@
+// S3/R2 asset lane — Cloud Phase 3 Task 2.
+//
+// THE PROBLEM. Binary media currently rides git. A 60 MB video in a design repo
+// is 60 MB in every clone, forever, and git's delta compression does nothing for
+// it. DDR-148's line that "video rides git and hub sync" describes an intent the
+// code never made true cross-machine; this lane is what makes heavy media
+// actually reach a second machine without bloating history.
+//
+// THE SHAPE. Assets stay CONTENT-ADDRESSED exactly as they are today —
+// `assets/<sha8>.<ext>`. That single property is what makes every operation
+// here safe:
+//
+//   • push is idempotent — the same bytes produce the same key, so a re-upload
+//     is a no-op rather than a duplicate;
+//   • there is no invalidation problem — a key's content never changes, so a
+//     cached copy is never stale;
+//   • pull is verifiable — the bytes must hash back to the key they came from,
+//     which is what lets us accept them from a semi-trusted hub (DDR-054).
+//
+// NEVER GARBAGE-COLLECTED. A canvas in git history can reference an asset that
+// no current canvas does, so "unreferenced" never means "unreachable". Bucket
+// lifecycle/expiry rules MUST be off for the `assets/` prefix — an expired
+// object is a permanently broken canvas with no recovery path.
+//
+// NO PRESIGNED URLS IN A CANVAS. The canvas origin's CSP is `img-src 'self'`
+// (DDR-063/DDR-054) and stays that way: media is fetched through the hub's
+// authenticated proxy and served same-origin. A presigned URL would also be a
+// bearer credential embedded in tenant-authored content — exactly the thing the
+// canvas must never hold.
+
+import { createHash, createHmac } from 'node:crypto';
+
+// ---------------------------------------------------------------- SigV4
+
+const sha256Hex = (data: string | Uint8Array): string =>
+  createHash('sha256').update(data).digest('hex');
+const hmac = (key: string | Buffer, data: string): Buffer =>
+  createHmac('sha256', key).update(data).digest();
+
+export interface S3Config {
+  endpoint: string;
+  bucket: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  region: string;
+  sessionToken?: string;
+}
+
+/**
+ * Resolve an S3 target from environment. Returns null when not configured —
+ * an unconfigured asset lane is the DEFAULT, not an error: a local project and
+ * a self-hoster on a single box both work without a bucket.
+ */
+export function s3ConfigFromEnv(env: NodeJS.ProcessEnv = process.env): S3Config | null {
+  const endpoint = env.MAUDE_S3_ENDPOINT;
+  const bucket = env.MAUDE_S3_BUCKET;
+  const accessKeyId = env.MAUDE_S3_ACCESS_KEY_ID;
+  const secretAccessKey = env.MAUDE_S3_SECRET_ACCESS_KEY;
+  if (!endpoint || !bucket || !accessKeyId || !secretAccessKey) return null;
+  return {
+    endpoint: endpoint.replace(/\/+$/, ''),
+    bucket,
+    accessKeyId,
+    secretAccessKey,
+    region: env.MAUDE_S3_REGION || 'auto',
+    ...(env.MAUDE_S3_SESSION_TOKEN ? { sessionToken: env.MAUDE_S3_SESSION_TOKEN } : {}),
+  };
+}
+
+function encodeSegment(segment: string): string {
+  return encodeURIComponent(segment).replace(
+    /[!'()*]/g,
+    (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`
+  );
+}
+
+function encodeKey(key: string): string {
+  return key.split('/').map(encodeSegment).join('/');
+}
+
+export interface SignedRequest {
+  url: string;
+  headers: Record<string, string>;
+}
+
+/**
+ * AWS Signature Version 4 for one request.
+ *
+ * Hand-rolled for the same reason the hub's is (DDR-194 §7): `@aws-sdk/client-s3`
+ * is ~20 MB and several hundred packages to perform three HTTP verbs, and this
+ * code ships inside a compiled binary users install. Deliberately mirrors
+ * `apps/hub/src/s3.mjs` rather than sharing it — the two packages build
+ * independently — and `test/assets-s3.test.ts` pins them to the same signature
+ * for the same input so they cannot drift.
+ */
+export function signRequest(
+  cfg: S3Config,
+  {
+    method,
+    key,
+    body = null,
+    now = new Date(),
+  }: { method: string; key: string; body?: Uint8Array | null; now?: Date }
+): SignedRequest {
+  const url = new URL(`${cfg.endpoint}/${cfg.bucket}${key ? `/${encodeKey(key)}` : ''}`);
+  const iso = now
+    .toISOString()
+    .replace(/[-:]/g, '')
+    .replace(/\.\d{3}/, '');
+  const dateStamp = iso.slice(0, 8);
+  const payloadHash = body === null ? sha256Hex('') : sha256Hex(body);
+
+  const headers: Record<string, string> = {
+    host: url.host,
+    'x-amz-content-sha256': payloadHash,
+    'x-amz-date': iso,
+    ...(cfg.sessionToken ? { 'x-amz-security-token': cfg.sessionToken } : {}),
+  };
+  const names = Object.keys(headers).sort();
+  const canonicalHeaders = names.map((h) => `${h}:${headers[h]}\n`).join('');
+  const signedHeaders = names.join(';');
+  const canonicalRequest = [
+    method,
+    url.pathname,
+    '',
+    canonicalHeaders,
+    signedHeaders,
+    payloadHash,
+  ].join('\n');
+
+  const scope = `${dateStamp}/${cfg.region}/s3/aws4_request`;
+  const stringToSign = ['AWS4-HMAC-SHA256', iso, scope, sha256Hex(canonicalRequest)].join('\n');
+
+  let signingKey = hmac(`AWS4${cfg.secretAccessKey}`, dateStamp);
+  signingKey = hmac(signingKey, cfg.region);
+  signingKey = hmac(signingKey, 's3');
+  signingKey = hmac(signingKey, 'aws4_request');
+  const signature = createHmac('sha256', signingKey).update(stringToSign).digest('hex');
+
+  headers.authorization =
+    `AWS4-HMAC-SHA256 Credential=${cfg.accessKeyId}/${scope}, ` +
+    `SignedHeaders=${signedHeaders}, Signature=${signature}`;
+
+  return { url: url.toString(), headers };
+}
+
+// ------------------------------------------------------------ content address
+
+/** The `sha8` in `assets/<sha8>.<ext>` — first 8 hex chars of sha256. */
+export function sha8(bytes: Uint8Array): string {
+  return createHash('sha256').update(bytes).digest('hex').slice(0, 8);
+}
+
+/**
+ * Extract the sha8 from a designRoot-relative asset path, or null when the path
+ * is not a content-addressed asset (a legacy or hand-placed file).
+ *
+ * The suffix after the hash is deliberately permissive, because the real corpus
+ * is more varied than `<sha8>.<ext>`:
+ *
+ *   assets/deadbeef.png            saveAsset's own output
+ *   assets/deadbeef.photo.json     a sidecar (dotted, multi-part)
+ *   assets/deadbeef-cloud.mp4      ingested footage, hash + human label
+ *
+ * A stricter pattern silently classified the last two as "not content
+ * addressed", which made `verifyAssetBytes` refuse them — so the mirror would
+ * have rejected legitimate assets as unverifiable. Found by running
+ * `maude hub asset-check` against this repo's own design root, not by a test:
+ * the fixtures all had the tidy shape.
+ *
+ * What must NOT match is anything where the 8 hex chars are not a complete
+ * token — `deadbeef1.png` is a different name, not this asset.
+ */
+export function sha8FromAssetPath(rel: string): string | null {
+  const m = rel.match(/^assets\/([0-9a-f]{8})(?:[-.][^/]*)?$/);
+  return m?.[1] ?? null;
+}
+
+/**
+ * Verify bytes against the sha8 embedded in the path they were fetched under.
+ *
+ * This is what makes accepting an asset from a SEMI-TRUSTED hub (DDR-054) safe:
+ * the hub can refuse to serve, but it cannot substitute different bytes without
+ * the mismatch being detectable. A path with no sha8 (legacy) can't be verified
+ * and is treated as unverifiable rather than valid.
+ */
+export function verifyAssetBytes(rel: string, bytes: Uint8Array): boolean {
+  const expected = sha8FromAssetPath(rel);
+  if (!expected) return false;
+  return sha8(bytes) === expected;
+}
+
+// ------------------------------------------------------------------ the lane
+
+export interface AssetMirror {
+  readonly configured: boolean;
+  readonly describe: string;
+  /**
+   * Upload one asset. Content-addressed ⇒ idempotent, so a re-push of identical
+   * bytes is harmless. Returns false on failure rather than throwing: a failed
+   * mirror must NEVER fail the local save (the file is on disk and in git; the
+   * bucket is the redundant copy, not the authority).
+   */
+  push(rel: string, bytes: Uint8Array): Promise<boolean>;
+  /** Download one asset, or null when absent. Verifies the content address. */
+  pull(rel: string): Promise<Uint8Array | null>;
+  /** True when the object exists. Used by the dangling-pointer check. */
+  has(rel: string): Promise<boolean>;
+}
+
+const NOOP_MIRROR: AssetMirror = {
+  configured: false,
+  describe: 'none',
+  async push() {
+    return false;
+  },
+  async pull() {
+    return null;
+  },
+  async has() {
+    return false;
+  },
+};
+
+export function createAssetMirror(
+  cfg: S3Config | null,
+  { log = console }: { log?: Pick<Console, 'warn'> } = {}
+): AssetMirror {
+  if (!cfg) return NOOP_MIRROR;
+
+  const send = (method: string, key: string, body: Uint8Array | null = null) => {
+    const { url, headers } = signRequest(cfg, { method, key, body });
+    return fetch(url, { method, headers, ...(body === null ? {} : { body }) });
+  };
+
+  return {
+    configured: true,
+    describe: `s3://${cfg.bucket} @ ${cfg.endpoint}`,
+
+    async push(rel, bytes) {
+      try {
+        const res = await send('PUT', rel, bytes);
+        if (!res.ok) {
+          log.warn(`[assets] mirror PUT ${rel} failed: ${res.status}`);
+          return false;
+        }
+        return true;
+      } catch (err) {
+        // Offline, DNS, a bad key — all the same answer. The asset is safely on
+        // local disk; a later push (or `maude hub asset-check`) reconciles.
+        log.warn(`[assets] mirror PUT ${rel} failed: ${(err as Error).message}`);
+        return false;
+      }
+    },
+
+    async pull(rel) {
+      try {
+        const res = await send('GET', rel);
+        if (res.status === 404) return null;
+        if (!res.ok) {
+          log.warn(`[assets] mirror GET ${rel} failed: ${res.status}`);
+          return null;
+        }
+        const bytes = new Uint8Array(await res.arrayBuffer());
+        if (!verifyAssetBytes(rel, bytes)) {
+          // Content address mismatch: either corruption or substitution. Refuse
+          // either way — writing these bytes to disk under this name would
+          // poison every peer that later mirrors from us.
+          log.warn(
+            `[assets] REFUSING ${rel}: content does not hash to its own name ` +
+              '(corruption or substitution — see DDR-054)'
+          );
+          return null;
+        }
+        return bytes;
+      } catch (err) {
+        log.warn(`[assets] mirror GET ${rel} failed: ${(err as Error).message}`);
+        return null;
+      }
+    },
+
+    async has(rel) {
+      try {
+        const res = await send('HEAD', rel);
+        return res.ok;
+      } catch {
+        return false;
+      }
+    },
+  };
+}

package/apps/studio/build.ts

@@ -317,7 +317,7 @@ export function writeCompileEntry(target: PlatformTarget): string {
   const bindingSpec = `@oxc-parser/binding-${oxcSlug}/parser.${oxcSlug}.node`;
   const initContent = `// AUTO-GENERATED by build.ts — do not edit by hand.
 // Per-target oxc-parser binding embed (Bun 1.3.4+ --compile NAPI regression
-// workaround — see .ai/decisions/DDR-042-oxc-parser-bun-compile-workaround.md).
+// workaround — see .ai/archive/decisions/DDR-042-oxc-parser-bun-compile-workaround.md).
 // Side-effect module: must be imported BEFORE any oxc-parser usage.
 import bindingPath from ${JSON.stringify(bindingSpec)} with { type: 'file' };
 process.env.NAPI_RS_NATIVE_LIBRARY_PATH = bindingPath;

package/apps/studio/client/export-center.jsx

@@ -56,12 +56,13 @@ async function autoDownloadBlob(id, fallbackName) {
   URL.revokeObjectURL(url);
 }
 
-async function saveNative(id, fallbackName) {
-  const got = await fetchJobBytes(id);
-  if (!got) return null;
-  const filename = got.filename || fallbackName || 'export';
-  const bytes = Array.from(new Uint8Array(await got.blob.arrayBuffer()));
-  return saveExport(filename, bytes);
+// Native "Save…" — unlike the web `download()` path, this does NOT fetch the
+// job's bytes into the renderer first. `save_export` fetches them itself
+// (RCA issue-desktop-print-pdf-save-as-hang-large-payload: routing a
+// hundreds-of-MB export through a JS Uint8Array + Tauri's JSON IPC froze the
+// app), so all this needs is the filename already carried on the job record.
+async function saveNative(id, filename) {
+  return saveExport(filename || 'export', id);
 }
 
 export function useExportCenter() {

package/apps/studio/client/github.js

@@ -93,11 +93,18 @@ export const pickDirectory = () => invoke('pick_directory');
 export const openLocalProject = (path) => invoke('open_local_project', { path });
 /**
  * Native "Save As…" for an export — opens an OS save dialog seeded with
- * `filename`, writes `bytes` (a plain number array from a Uint8Array) to the
- * chosen path, and resolves to that path (or null if cancelled). Only callable in
- * the native app; the browser build uses the `<a download>` blob instead.
+ * `filename`, then has the Rust side fetch the finished `jobId`'s bytes
+ * directly from the local dev-server and stream them to the chosen path, and
+ * resolves to that path (or null if cancelled). Only callable in the native
+ * app; the browser build uses the `<a download>` blob instead.
+ *
+ * Deliberately does NOT take the bytes as an argument (it used to — RCA
+ * issue-desktop-print-pdf-save-as-hang-large-payload): shipping a large export
+ * (a print-ready PDF can be hundreds of MB) through Tauri's JSON-serialized
+ * IPC as `Array.from(new Uint8Array(...))` froze the renderer. Rust fetches
+ * the bytes itself now; the webview never sees the payload.
  */
-export const saveExport = (filename, bytes) => invoke('save_export', { filename, bytes });
+export const saveExport = (filename, jobId) => invoke('save_export', { filename, jobId });
 
 /**
  * Native "open file" for media upload — the read counterpart to saveExport.

package/apps/studio/collab/origins.ts

@@ -0,0 +1,150 @@
+// Origin gate for canvas-realm Y.Doc ops — the named-but-undone DDR-122
+// follow-up ("Origin-gate canvas-injected doc ops"), landed by Cloud Phase 1
+// Task 3.
+//
+// THE THREAT (DDR-054 F1/F3, restated by DDR-122's security residual): the
+// canvas iframe is untrusted, and same-realm canvas script can reach the live
+// collab Y.Doc via `useCollab().doc`. Nothing stopped it from writing the BODY
+// lanes — `html` / `css` / `meta` / `syncMeta`, i.e. the canvas's own `.tsx`,
+// its sibling `.css`, and the shared `.meta.json` — which the sync agent then
+// materializes to **every peer's disk**. That is "untrusted canvas writes
+// source code to all peers" (stored-XSS + Claude-Code-context-poisoning).
+//
+// THE GATE, dual-lock (DDR-063's canvas-origin split is the seam that makes
+// lock 2 expressible at all):
+//
+//   Lock 1 — CLIENT (`use-collab.tsx`): a local doc update that touches a body
+//            lane is not broadcast to the server unless its transaction origin
+//            is a *trusted sentinel* registered here. Closes the honest path
+//            (`useCollab().doc.getText('html').insert(...)`).
+//   Lock 2 — SERVER (`collab/room.ts`): an update arriving on a collab socket
+//            that was upgraded on the CANVAS origin is validated against a
+//            mirror doc before it is allowed to touch the real room doc; a
+//            body-lane write is refused outright and never broadcast. Closes
+//            the bypass where canvas script skips `use-collab` and opens its
+//            own WebSocket to `/_ws/collab/:slug`.
+//
+// Lock 1 alone is defense-in-depth; lock 2 is the actual boundary. Both exist
+// because lock 1 is where the intent is legible and lock 2 is where it is
+// enforceable.
+//
+// WHY A MIRROR DOC AND NOT UPDATE INSPECTION (load-bearing, don't "simplify"):
+// `Y.decodeUpdate` only reveals a struct's parent when the struct has neither a
+// left nor a right origin (yjs writes the parent key *only* in that case). An
+// insert into existing text carries an origin ID instead, so the lane it targets
+// is simply not in the bytes — it is only resolvable against a doc that already
+// holds the referenced items. Hence: apply to a mirror of the room doc, read
+// `transaction.changed`, decide, and only then touch the real doc.
+
+import * as Y from 'yjs';
+
+/**
+ * Lanes that carry the canvas SOURCE (and its sync bookkeeping). Written only
+ * by server-side code — `sync/agent.ts`, `sync/codec.ts`, `sync/projection.ts`.
+ * No browser-realm code writes these today; the gate keeps it that way.
+ */
+const BODY_LANES = new Set<string>(['html', 'css', 'meta', 'syncMeta']);
+
+/**
+ * Lanes the canvas realm legitimately co-authors — annotations (draw layer),
+ * comments, and the presentation channel. Deliberately NOT used as an allowlist
+ * for the gate (a new lane must be reasoned about, not silently permitted); it
+ * documents intent and backs `isCanvasAuthorableLane` for callers that want the
+ * positive form.
+ */
+const CANVAS_AUTHORABLE_LANES = new Set<string>(['comments', 'annotations', 'presentation']);
+
+/** True when `name` is a source-carrying lane the canvas realm may never write. */
+export function isBodyLane(name: string): boolean {
+  return BODY_LANES.has(name);
+}
+
+/** True when `name` is a lane the canvas realm co-authors by design. */
+export function isCanvasAuthorableLane(name: string): boolean {
+  return CANVAS_AUTHORABLE_LANES.has(name);
+}
+
+/** Test/introspection — the frozen lane vocabulary as plain arrays. */
+export function laneVocabulary(): { body: string[]; canvasAuthorable: string[] } {
+  return { body: [...BODY_LANES].sort(), canvasAuthorable: [...CANVAS_AUTHORABLE_LANES].sort() };
+}
+
+// ---------------------------------------------------------------------------
+// Trusted origin sentinels
+// ---------------------------------------------------------------------------
+
+// A WeakSet, not a marker property: a marker property is forgeable by any
+// same-realm script (`{ maudeTrusted: true }`), a WeakSet membership is not —
+// an attacker would need the sentinel *object itself*, which is only reachable
+// from module scope of the modules that legitimately hold it.
+const TRUSTED_ORIGINS = new WeakSet<object>();
+
+/**
+ * Register `origin` as a trusted doc-update origin. Returns it, so a sentinel
+ * can be declared and marked in one expression. Frozen objects are fine —
+ * freezing does not affect WeakSet membership.
+ */
+export function markTrustedOrigin<T extends object>(origin: T): T {
+  TRUSTED_ORIGINS.add(origin);
+  return origin;
+}
+
+/** True when a Y transaction origin was registered via `markTrustedOrigin`. */
+export function isTrustedOrigin(origin: unknown): boolean {
+  return typeof origin === 'object' && origin !== null && TRUSTED_ORIGINS.has(origin as object);
+}
+
+/**
+ * The shell's sanctioned edit path — the inspector / shell UI mutating a body
+ * lane on behalf of an explicit user gesture. Nothing in the canvas realm can
+ * obtain this object; it is exported for the shell modules that need it.
+ */
+export const SHELL_EDIT_ORIGIN: object = markTrustedOrigin(
+  Object.freeze({ maudeOrigin: 'shell-edit' })
+);
+
+/**
+ * The local sync agent applying a disk-authoritative body into the doc. Used by
+ * server-side code that runs outside the canvas realm entirely; marked here so
+ * the client-side lock stays correct if a future build ever colocates them.
+ */
+export const SYNC_AGENT_ORIGIN: object = markTrustedOrigin(
+  Object.freeze({ maudeOrigin: 'sync-agent' })
+);
+
+// ---------------------------------------------------------------------------
+// Transaction inspection
+// ---------------------------------------------------------------------------
+
+/**
+ * Root shared-type names a transaction touched.
+ *
+ * `transaction.changed` is keyed by the *concrete* type that changed, which for
+ * a nested structure is not the root — so walk `_item.parent` up to the root and
+ * resolve its registered name via `Y.findRootTypeKey`. A type that cannot be
+ * resolved (detached / mid-destroy) yields the sentinel `'<unresolved>'`, which
+ * is deliberately NOT a body lane but also not an authorable one — callers that
+ * fail closed should treat an unresolved root as untrusted.
+ */
+export function rootTypesTouched(transaction: Y.Transaction): Set<string> {
+  const roots = new Set<string>();
+  for (const type of transaction.changed.keys()) {
+    let t: Y.AbstractType<unknown> = type;
+    // biome-ignore lint/suspicious/noExplicitAny: `_item` is yjs-internal but stable API surface for parent walks.
+    while ((t as any)._item != null) t = (t as any)._item.parent;
+    try {
+      roots.add(Y.findRootTypeKey(t));
+    } catch {
+      roots.add('<unresolved>');
+    }
+  }
+  return roots;
+}
+
+/** True when a transaction wrote any source-carrying lane. */
+export function touchesBodyLane(transaction: Y.Transaction): boolean {
+  for (const name of rootTypesTouched(transaction)) {
+    if (isBodyLane(name)) return true;
+  }
+  return false;
+}