@synap-core/workspace-templates 0.11.0 → 0.23.0

package/src/apify-social-reader.test.ts

@@ -0,0 +1,317 @@
+/**
+ * Apify's `capture_social_post` is a PURE URL READER ("Any link → data",
+ * 2026-10-15): same verb id, intent `read_webpage`, `metadata.readOnly`,
+ * declared `urls`, and it returns the UrlRead shape (`@synap-core/types/url-read`).
+ * It writes nothing: the Library item is the one home of a kept post.
+ *
+ * SEAM: the verb's REAL `code` body, run the way the pod's executor wraps it
+ * (`async (args, context) => { <code> }` with `callProvider` / `propose` in
+ * scope), against Apify dataset payloads shaped like the actors' documented
+ * output, and its answer passed through the REAL parse door `normalizeUrlRead`.
+ * The URL table runs the declared `urls` through the REAL `matchUrlPattern`, so
+ * the declaration and the code cannot drift apart.
+ *
+ * NOT covered: the live actors' output (the payloads are hand-written from the
+ * actors' documented fields), the isolate's polyfilled `URL` (Node's is used),
+ * and how the pod routes or stores a read (backend's url-readers tests).
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { matchUrlPattern, normalizeUrlRead, type ReaderStamp } from "@synap-core/types/url-read";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const manifest = JSON.parse(readFileSync(join(HERE, "../capabilities/apify.capability.json"), "utf8"));
+type Skill = { name: string; intent?: string; code?: string; urls?: string[]; metadata?: { readOnly?: boolean } };
+const skills = manifest.spec.skills as Skill[];
+const reader = skills.find((s) => s.name === "capture_social_post")!;
+
+const AsyncFunction = Object.getPrototypeOf(async () => {}).constructor as new (
+  ...args: string[]
+) => (...a: unknown[]) => Promise<unknown>;
+const body = new AsyncFunction("args", "context", "callProvider", "propose", reader.code!);
+
+type Call = { tool: string; method: string; path: string; input: unknown };
+async function run(url: string, answer: unknown | (() => never), extra: Record<string, unknown> = {}) {
+  const calls: Call[] = [];
+  const writes: unknown[] = [];
+  const callProvider = async (tool: string, method: string, path: string, input: unknown) => {
+    calls.push({ tool, method, path, input });
+    if (typeof answer === "function") return (answer as () => never)();
+    return { status: 201, headers: {}, body: answer };
+  };
+  const propose = { entity: async (x: unknown) => (writes.push(x), { status: "proposed" }) };
+  const raw = (await body({ url, ...extra }, {}, callProvider, propose)) as Record<string, any>;
+  return { raw, calls, writes };
+}
+const VIA: ReaderStamp = { id: "apify.capture_social_post", name: "Apify", billed: true, readAt: "2026-10-15T00:00:00.000Z" };
+
+const IG_CAROUSEL = {
+  url: "https://www.instagram.com/p/CAROUSEL1/",
+  type: "Sidecar",
+  caption: "Three looks for autumn\nswipe for the third",
+  ownerUsername: "studio.x",
+  ownerFullName: "Studio X",
+  timestamp: "2026-10-01T09:30:00.000Z",
+  displayUrl: "https://cdn.example/ig/slide1.jpg",
+  dimensionsWidth: 1080,
+  dimensionsHeight: 1350,
+  likesCount: 812,
+  commentsCount: 41,
+  images: ["https://cdn.example/ig/slide1.jpg", "https://cdn.example/ig/slide2.jpg", "https://cdn.example/ig/slide3.jpg"],
+  childPosts: [
+    { type: "Image", displayUrl: "https://cdn.example/ig/slide1.jpg", dimensionsWidth: 1080, dimensionsHeight: 1350 },
+    { type: "Image", displayUrl: "https://cdn.example/ig/slide2.jpg" },
+    { type: "Video", displayUrl: "https://cdn.example/ig/slide3.jpg", videoUrl: "https://cdn.example/ig/slide3.mp4", videoDuration: 7.5 },
+  ],
+};
+const IG_REEL = {
+  url: "https://www.instagram.com/reel/REEL1/",
+  type: "Video",
+  caption: "Behind the scenes",
+  ownerUsername: "studio.x",
+  timestamp: "2026-10-02T10:00:00.000Z",
+  displayUrl: "https://cdn.example/ig/reel-cover.jpg",
+  videoUrl: "https://cdn.example/ig/reel.mp4",
+  videoDuration: 31.2,
+  likesCount: 90,
+  commentsCount: 3,
+  videoViewCount: 4200,
+};
+const TIKTOK = {
+  webVideoUrl: "https://www.tiktok.com/@maker/video/7400000000000000001",
+  text: "How we pack an order",
+  createTimeISO: "2026-09-30T18:00:00.000Z",
+  authorMeta: { name: "maker", profileUrl: "https://www.tiktok.com/@maker" },
+  videoMeta: { coverUrl: "https://cdn.example/tt/cover.jpg", downloadAddr: "https://cdn.example/tt/dl.mp4", width: 720, height: 1280, duration: 22 },
+  mediaUrls: ["https://api.apify.com/v2/key-value-stores/s/records/video-1.mp4"],
+  diggCount: 1500,
+  commentCount: 12,
+  playCount: 99000,
+};
+
+describe("capture_social_post — declared as a pure reader", () => {
+  it("is a read_webpage, read-only verb that takes a url and declares the links it reads", () => {
+    expect(reader.intent).toBe("read_webpage");
+    expect(reader.metadata?.readOnly).toBe(true);
+    expect((reader as any).parameters).toEqual({ url: "string", withVideo: "boolean?" });
+    expect(reader.urls).toEqual([
+      "instagram.com/p/*",
+      "instagram.com/reel/*",
+      "instagram.com/reels/*",
+      "instagram.com/tv/*",
+      "tiktok.com/@*/video/*",
+      "vm.tiktok.com/*",
+      "vt.tiktok.com/*",
+    ]);
+  });
+
+  it("the Apify verbs that only read are read-only; the generic actor run is not", () => {
+    const ro = Object.fromEntries(skills.map((s) => [s.name, s.metadata?.readOnly === true]));
+    expect(ro).toMatchObject({
+      apify_search_actors: true,
+      apify_get_actor_schema: true,
+      apify_list_actor_runs: true,
+      apify_get_dataset_items: true,
+      capture_social_post: true,
+      apify_run_actor: false,
+    });
+  });
+
+  it("the code proposes nothing and hands no media-urls over (the Library item is the one home)", () => {
+    expect(reader.code).not.toMatch(/propose\.entity|media-urls|bookmark/);
+  });
+});
+
+describe("capture_social_post — its answer through the real parse door", () => {
+  it("the vendor receives the URL as PARSED, never the raw string (a tab inside is dropped by WHATWG)", async () => {
+    const { calls } = await run("https://www.instagram.com/p/CAR\tOUSEL1/", [IG_CAROUSEL]);
+    expect(calls.map((c) => c.input)).toEqual([
+      { directUrls: ["https://www.instagram.com/p/CAROUSEL1/"], resultsType: "posts" },
+    ]);
+    const tt = await run("https://www.tiktok.com/@ada/video/1\n23", []);
+    expect(tt.calls.map((c) => c.input)).toEqual([
+      { postURLs: ["https://www.tiktok.com/@ada/video/123"], shouldDownloadVideos: false },
+    ]);
+  });
+
+  it("withVideo: declared as an optional boolean; TikTok downloads the video ONLY when it is true; Instagram is unaffected", async () => {
+    expect((reader as Skill & { parameters?: Record<string, string> }).parameters).toEqual({
+      url: "string",
+      withVideo: "boolean?",
+    });
+    const TT = "https://www.tiktok.com/@ada/video/123";
+    for (const [extra, expected] of [
+      [{}, false],
+      [{ withVideo: false }, false],
+      [{ withVideo: "yes" }, false],
+      [{ withVideo: true }, true],
+    ] as const) {
+      const { calls } = await run(TT, [], extra);
+      expect(calls.map((c) => c.input)).toEqual([{ postURLs: [TT], shouldDownloadVideos: expected }]);
+    }
+    const ig = await run("https://www.instagram.com/p/CAROUSEL1/", [IG_CAROUSEL], { withVideo: true });
+    expect(ig.calls.map((c) => c.input)).toEqual([
+      { directUrls: ["https://www.instagram.com/p/CAROUSEL1/"], resultsType: "posts" },
+    ]);
+  });
+
+  it("an Instagram carousel: every slide as an image, a video slide's file too, in order, with its counts", async () => {
+    const { raw, calls, writes } = await run("https://www.instagram.com/p/CAROUSEL1/", [IG_CAROUSEL]);
+    expect(writes).toEqual([]);
+    expect(calls).toEqual([
+      {
+        tool: "apify_api",
+        method: "POST",
+        path: "/actors/apify~instagram-scraper/run-sync-get-dataset-items",
+        input: { directUrls: ["https://www.instagram.com/p/CAROUSEL1/"], resultsType: "posts" },
+      },
+    ]);
+    const read = normalizeUrlRead(raw, "https://www.instagram.com/p/CAROUSEL1/", VIA);
+    expect(read).toMatchObject({
+      status: "ok",
+      canonicalUrl: "https://www.instagram.com/p/CAROUSEL1/",
+      title: "Three looks for autumn",
+      author: "studio.x",
+      authorUrl: "https://www.instagram.com/studio.x/",
+      text: IG_CAROUSEL.caption,
+      publishedAt: "2026-10-01T09:30:00.000Z",
+      fields: { platform: "instagram", likes: 812, comments: 41 },
+    });
+    expect(read.media?.map((m) => [m.order, m.kind, m.role, m.url])).toEqual([
+      [0, "image", "slide", "https://cdn.example/ig/slide1.jpg"],
+      [1, "image", "slide", "https://cdn.example/ig/slide2.jpg"],
+      [2, "image", "slide", "https://cdn.example/ig/slide3.jpg"],
+      [3, "video", "slide", "https://cdn.example/ig/slide3.mp4"],
+    ]);
+    expect(read.media?.[3].durationSec).toBe(7.5);
+  });
+
+  it("an Instagram reel: the cover still, then the video file, with views", async () => {
+    const { raw } = await run("https://instagram.com/reel/REEL1/?igsh=abc", [IG_REEL]);
+    const read = normalizeUrlRead(raw, "https://instagram.com/reel/REEL1/?igsh=abc", VIA);
+    expect(read.status).toBe("ok");
+    expect(read.media?.map((m) => [m.kind, m.role ?? null, m.url])).toEqual([
+      ["image", "cover", "https://cdn.example/ig/reel-cover.jpg"],
+      ["video", null, "https://cdn.example/ig/reel.mp4"],
+    ]);
+    expect(read.media?.[1].durationSec).toBe(31.2);
+    expect(read.fields).toEqual({ platform: "instagram", likes: 90, comments: 3, views: 4200 });
+  });
+
+  it("an Instagram carousel known only by `images`: each one a slide", async () => {
+    const { childPosts: _drop, ...noChildren } = IG_CAROUSEL;
+    const { raw } = await run("https://www.instagram.com/p/CAROUSEL1/", [noChildren]);
+    const read = normalizeUrlRead(raw, "https://www.instagram.com/p/CAROUSEL1/", VIA);
+    expect(read.media?.map((m) => m.url)).toEqual(IG_CAROUSEL.images);
+    expect(read.media?.every((m) => m.kind === "image" && m.role === "slide")).toBe(true);
+  });
+
+  it("a TikTok video: the cover, then the stored video file (the post page is never a media file)", async () => {
+    const { raw, calls } = await run("https://www.tiktok.com/@maker/video/7400000000000000001", [TIKTOK]);
+    expect(calls[0].path).toBe("/actors/clockworks~tiktok-scraper/run-sync-get-dataset-items");
+    const read = normalizeUrlRead(raw, "https://www.tiktok.com/@maker/video/7400000000000000001", VIA);
+    expect(read).toMatchObject({
+      status: "ok",
+      canonicalUrl: TIKTOK.webVideoUrl,
+      author: "maker",
+      authorUrl: "https://www.tiktok.com/@maker",
+      text: "How we pack an order",
+      publishedAt: "2026-09-30T18:00:00.000Z",
+      fields: { platform: "tiktok", likes: 1500, comments: 12, views: 99000 },
+    });
+    expect(read.media?.map((m) => [m.kind, m.role ?? null, m.url])).toEqual([
+      ["image", "cover", "https://cdn.example/tt/cover.jpg"],
+      ["video", null, TIKTOK.mediaUrls[0]],
+    ]);
+    expect(read.media?.some((m) => m.url === TIKTOK.webVideoUrl)).toBe(false);
+  });
+
+  it("a TikTok the actor did not store: its download address is the video", async () => {
+    const { mediaUrls: _drop, ...noStored } = TIKTOK;
+    const { raw } = await run("https://vm.tiktok.com/ZMabc123/", [noStored]);
+    const read = normalizeUrlRead(raw, "https://vm.tiktok.com/ZMabc123/", VIA);
+    expect(read.media?.find((m) => m.kind === "video")?.url).toBe("https://cdn.example/tt/dl.mp4");
+  });
+
+  it("not there / not public is BLOCKED with the reason, never an empty ok", async () => {
+    const cases: Array<[unknown, string]> = [
+      [[], "not_found"],
+      [[{ url: "https://www.instagram.com/p/GONE/", error: "not_found", errorDescription: "Page not found" }], "not_found"],
+      [[{ inputUrl: "https://www.instagram.com/p/GONE/", error: "no_items", errorDescription: "Empty or private data for provided input" }], "not_found"],
+      [[{ url: "https://www.instagram.com/p/LOCK/", error: "restricted_page", errorDescription: "This account is private" }], "private"],
+    ];
+    for (const [answer, reason] of cases) {
+      const { raw } = await run("https://www.instagram.com/p/X1/", answer);
+      const read = normalizeUrlRead(raw, "https://www.instagram.com/p/X1/", VIA);
+      expect(read.status, JSON.stringify(answer)).toBe("blocked");
+      expect(read.blocked?.reason, JSON.stringify(answer)).toBe(reason);
+    }
+  });
+
+  it("an Apify run failure PROPAGATES (the executor keeps its failure class); it is never folded into a read", async () => {
+    // HTTP / auth / quota / run failure: callProvider throws, and so does the verb.
+    await expect(
+      run("https://www.instagram.com/p/X1/", () => {
+        throw new Error("callProvider failed: Apify 402 Payment Required");
+      }),
+    ).rejects.toThrow(/402 Payment Required/);
+    // An actor error that says nothing about the post is a run failure too.
+    await expect(run("https://www.instagram.com/p/X1/", [{ error: "rate_limited", errorDescription: "Try later" }])).rejects.toThrow(
+      /rate_limited: Try later/,
+    );
+  });
+
+  it("parity: the code reads EXACTLY the links its `urls` declare (the real matcher), and calls Apify for nothing else", async () => {
+    const table = [
+      "https://www.instagram.com/p/ABC123/",
+      "https://instagram.com/p/ABC123",
+      "http://instagram.com/reel/R1/",
+      "https://www.instagram.com/reels/R1/",
+      "https://www.instagram.com/tv/T1/",
+      "https://www.tiktok.com/@maker/video/7400000000000000001",
+      "https://tiktok.com/@maker/video/1?lang=en",
+      "https://vm.tiktok.com/ZMabc123/",
+      "https://vt.tiktok.com/ZSxyz/",
+      // not declared: a profile, a story, another host, a lookalike, a bare TikTok profile
+      "https://www.instagram.com/studio.x/",
+      "https://www.instagram.com/stories/studio.x/1/",
+      "https://m.instagram.com/p/ABC123/",
+      "https://notinstagram.com/p/ABC123/",
+      "https://www.tiktok.com/@maker",
+      "https://www.tiktok.com/@maker/photo/1",
+      "https://example.com/p/ABC123/",
+      "ftp://instagram.com/p/ABC123/",
+    ];
+    const declaredHits = table.filter((u) => reader.urls!.some((p) => matchUrlPattern(p, u)));
+    // non-vacuity: the table holds both answers
+    expect(declaredHits.length).toBe(9);
+    for (const u of table) {
+      const { raw, calls } = await run(u, [IG_REEL]);
+      const declared = declaredHits.includes(u);
+      expect(raw.status === "blocked" && raw.blocked?.reason === "unsupported", u).toBe(!declared);
+      expect(calls.length, u).toBe(declared ? 1 : 0);
+    }
+  });
+});
+
+describe("apify_run_actor — a billed run always hands its items back", () => {
+  const runner = skills.find((s) => s.name === "apify_run_actor")!;
+  const runBody = new AsyncFunction("args", "context", "callProvider", "propose", runner.code!);
+
+  it("writes nothing (a bookmark without a url failed the verb AFTER the credit was spent)", async () => {
+    const writes: unknown[] = [];
+    // Any write-back fails the way the approval did: the run must not depend on one.
+    const propose = { entity: async (x: unknown) => (writes.push(x), Promise.reject(new Error("missing_field: url"))) };
+    const items = [{ id: 1 }, { id: 2 }];
+    const callProvider = async () => ({ status: 201, headers: {}, body: items });
+    const out = (await runBody({ actorId: "owner/actor", input: {} }, {}, callProvider, propose)) as Record<string, any>;
+    expect(writes).toEqual([]);
+    expect(out).toMatchObject({ success: true, actorId: "owner/actor", itemCount: 2, items });
+  });
+
+  it("the code has no propose.entity at all", () => {
+    expect(runner.code).not.toMatch(/propose\.entity|bookmark/);
+  });
+});

package/src/base.template.test.ts

@@ -8,14 +8,14 @@
  * seeders be deleted (Wave 4) without silently changing what every workspace
  * gets.
  *
- * FIDELITY MECHANISM. The report prompts are the product — a single altered
- * character is a regression. Importing `REPORT_AUTOMATION_FLOW` from
- * `@synap/database` into this frontend package would be an upward layering
- * violation, so instead the byte-for-byte guardrail is a COMMITTED, GENERATED
- * fixture (`__fixtures__/report-automation-flow.json`) snapshotted from the
- * backend const at authoring time, never hand-typed. The chain the test proves:
- *     compiled base flow  ===  fixture  (=== REPORT_AUTOMATION_FLOW at capture).
- * Same for the 23-ish relation defs via `__fixtures__/default-relation-defs.json`.
+ * FIDELITY MECHANISM. base.yaml is now the SINGLE source of the report flow —
+ * the backend `REPORT_AUTOMATION_FLOW` const it was once snapshotted against was
+ * retired, and with it the `__fixtures__/report-automation-flow.json` copy-pin
+ * (a copy pinned to a copy caught no upstream drift). The report flow is guarded
+ * here directly instead: the prompt-fragment smoke check below proves the product
+ * content survived, and `templates-freshness.test.ts` pins templates.ts == the
+ * YAML source. The 23-ish relation defs KEEP their byte-for-byte fixture
+ * guardrail (`__fixtures__/default-relation-defs.json`).
  */
 
 import { readFileSync } from "fs";
@@ -55,18 +55,13 @@ describe("Task A — report automation, byte-faithful", () => {
     expect(automation?.description).toMatch(/Gather this workspace's state/);
   });
 
-  it("flow BYTE-MATCHES the REPORT_AUTOMATION_FLOW snapshot", () => {
-    const fixture = readFixture("report-automation-flow.json");
-    // deep-equal: the compiled template's flow is JSON.stringify(parsed YAML), so
-    // a deep-equal against the JSON snapshot of the source const proves the
-    // transcription is lossless (nodes, edges, and every prompt string).
-    expect(automation?.flow).toEqual(fixture);
-  });
-
   it("preserves the load-bearing hardened prompt fragments (v13)", () => {
-    // A coarse smoke check that the specific product content survived — the
-    // deep-equal above is authoritative, but these named fragments make a
-    // regression legible if the fixture is ever regenerated wrongly.
+    // The primary guardrail that the report flow's product content survived in
+    // base.yaml. (A byte-for-byte fixture pin used to sit above this, snapshotting
+    // the retired backend `REPORT_AUTOMATION_FLOW` const; with that const gone
+    // base.yaml is the single source, so a copy-pinned-to-a-copy proved nothing
+    // and was dropped. `templates-freshness.test.ts` pins templates.ts == the
+    // YAML source.)
     const flowStr = JSON.stringify(automation?.flow);
     for (const marker of [
       "COUNTS — the exact number of records gathered",
@@ -77,6 +72,17 @@ describe("Task A — report automation, byte-faithful", () => {
       expect(flowStr).toContain(marker);
     }
   });
+
+  it("carries the v15 retry policy on all four AI rounds (regression guard)", () => {
+    // v15's fix for the 2026-08-03 finishReason=length incident: each of the four
+    // ai.generate rounds (analyze/relate/assemble/summarize) gets ONE retry with a
+    // 5s delay. This field dropped SILENTLY once — the 700→2000 fix ported maxTokens
+    // into base.yaml but not the retry policy, so it went missing on the reconcile-
+    // winning path. Assert it here (base.yaml is the SSOT now) so it can't drift again.
+    const flowStr = JSON.stringify(automation?.flow);
+    expect((flowStr.match(/"retryDelay":5000/g) ?? []).length).toBe(4);
+    expect((flowStr.match(/"maxRetries":1(?=[,}])/g) ?? []).length).toBe(4);
+  });
 });
 
 describe("Task B — relation defs, full coverage", () => {

package/src/base.yaml

@@ -458,6 +458,8 @@ automations:
               maxTokens: "2000"
             errorHandling:
               continueOnError: true
+              maxRetries: 1
+              retryDelay: 5000
         - id: relate
           type: capability
           position:
@@ -540,6 +542,8 @@ automations:
               maxTokens: "2000"
             errorHandling:
               continueOnError: true
+              maxRetries: 1
+              retryDelay: 5000
         - id: assemble
           type: capability
           position:
@@ -581,15 +585,17 @@ automations:
                 3. The outer container must always have STRICTLY MORE colons than anything nested
                    inside it. Four outside, three inside. If you ever nest a four-colon block in a
                    four-colon block the section closes early and the rest of the report leaks out.
-                4. ATTRIBUTE VALUES MUST BE QUOTED. An UNQUOTED value ends at the first } it
-                   contains, which silently truncates the attribute — so always quote. Use
-                   DOUBLE quotes for a plain value, and SINGLE quotes when the value is itself
-                   a JSON object, so the JSON's own double quotes survive:
-                   :::synap-cell{cellKey="chart-pie" cellProps='{"profileSlug":"task","groupBy":"status"}'}
+                4. ATTRIBUTES ARE REFERENCES ONLY, ALWAYS DOUBLE-QUOTED: cellKey="…", id="…".
+                   A cell's settings NEVER go in an attribute. They go in a ```json block,
+                   the first thing inside the embed, compact on one line, a JSON object:
+                   :::synap-cell{cellKey="chart-pie"}
+                   ```json
+                   {"profileSlug":"task","groupBy":"status","label":"Open tasks by status"}
+                   ```
                    :::
-                   A single-quoted value may contain both " and } — those are only special to
-                   an unquoted value. Write the JSON compact, on one line, with no trailing
-                   comma; malformed JSON renders the cell with empty config.
+                   Inside that block ordinary JSON rules apply (an apostrophe is fine).
+                   Malformed JSON is shown to the reader as a broken cell. Never write the
+                   old cellProps='…' attribute form.
                 5. The ONLY section attributes that survive are: id, agent, round, skills,
                    confidence, stepRunId, nodeId, status. Anything else is silently dropped.
                 6. confidence is a 0-1 ratio written as a decimal string, e.g. confidence="0.8".
@@ -607,12 +613,13 @@ automations:
                 8. NEVER EMIT :::synap-view, AND NEVER EMIT :::synap-cell WITH AN instanceId.
                    Both need an id you have not been given and cannot obtain, and a made-up
                    reference produces a permanent broken block in a document a human reads.
-                9. YOU MAY EMIT A CHART :::synap-cell — from this allowlist ONLY, configured
-                   through cellProps. These cells fetch their own data at render time, so they
-                   need no id, and they make the report a live surface instead of a text file:
-                   - :::synap-cell{cellKey="stat-card" cellProps='{"profileSlug":"<kind>","aggregation":"count","timePeriod":"week","label":"<Kind> created this week"}'}
-                   - :::synap-cell{cellKey="chart-pie" cellProps='{"profileSlug":"<kind>","groupBy":"<property>","label":"<the finding this shows>"}'}
-                   - :::synap-cell{cellKey="chart-bar" cellProps='{"profileSlug":"<kind>","mode":"category","groupBy":"<property>","label":"<the finding this shows>"}'}
+                9. YOU MAY EMIT A CHART :::synap-cell — from this allowlist ONLY, each with its
+                   settings in the ```json block of rule 4. These cells need no id: their data
+                   is read from the settings in the json block, never written by you. The three
+                   cells and their json blocks:
+                   - cellKey="stat-card" with {"profileSlug":"<kind>","aggregation":"count","timePeriod":"week","label":"<Kind> created this week"}
+                   - cellKey="chart-pie" with {"profileSlug":"<kind>","groupBy":"<property>","label":"<Kind> by <property>"}
+                   - cellKey="chart-bar" with {"profileSlug":"<kind>","mode":"category","groupBy":"<property>","label":"<Kind> by <property>"}
                    Rules, all mandatory:
                    (a) profileSlug must be one of the kinds gathered for THIS report: task,
                        note, person, company. A chart over any other kind is a claim this
@@ -633,28 +640,29 @@ automations:
                        nothing here. If no gathered kind has a distribution worth showing,
                        emit no cells at all — that is a correct report, not a lesser one.
                    (e) AT MOST ONE cell per section, and NEVER at the top of a section.
-                       Place it immediately AFTER the sentence making the claim it evidences,
-                       so the reader has the claim before the picture. A chart that opens a
-                       section makes the reader decode a graphic to find out what the section
-                       is about, which is the delay the ## heading and the claim sentence
-                       exist to remove.
-                   (f) The label must state the FINDING, not the dimension. Write
-                       label:"Half the open tasks are blocked", never label:"Distribution",
-                       "Status" or "Tasks by status". Always set label explicitly: with none,
-                       a pie chart titles itself "Distribution" and a bar chart "Breakdown" —
-                       words true of every such chart ever drawn, which tell the reader
-                       nothing they cannot already see in the shapes.
-                   (g) A CHART IS A LIVE VIEW, THE PROSE IS A SNAPSHOT. These cells run
-                       their own query when the report is OPENED, which may be long after
-                       this text was written — so a sentence quoting a count and a chart
-                       measuring the same thing WILL eventually disagree, and the reader
-                       cannot tell which is stale. Never write a specific number in a
-                       sentence that sits beside a chart of the same data: let the chart
-                       carry the number and let the sentence carry the claim
-                       ("most open tasks are stalled at review", not "12 of 19 are stalled").
-                       And if the sentence already gives the number the chart would show,
-                       DROP THE CHART — one of them is redundant, and the sentence is the one
-                       that cannot go stale against itself.
+                       The ## claim heading and at least one sentence of context come first.
+                       Then the cell. Then, IMMEDIATELY AFTER the cell's closing ::: line,
+                       one prose sentence stating the FINDING the chart shows
+                       ("Review is where open tasks accumulate."). The finding lives in
+                       prose, where it can be read, quoted and edited — never inside the
+                       cell.
+                   (f) The json block carries STRUCTURE ONLY: profileSlug, aggregation,
+                       timePeriod, mode, groupBy, field, and a SHORT label naming what is
+                       measured ("Open tasks by status", "Notes created this week"). The
+                       label is a name, not a sentence: no verb, no finding. Always set the
+                       label: with none, a pie chart titles itself "Distribution" and a bar
+                       chart "Breakdown".
+                   (g) YOU WRITE THE CHART'S QUESTION, NEVER ITS NUMBERS. Never put a
+                       "data" or "capturedAt" key in a json block. After you finish, the
+                       pipeline runs each chart's own query and stores the result in the
+                       embed as a dated snapshot, so the chart shows the workspace as it
+                       was when this report was generated. You never see those numbers,
+                       so never write a specific number in a sentence that sits beside a
+                       chart of the same data: let the chart carry the number and let the
+                       sentence carry the claim ("most open tasks are stalled at review",
+                       not "12 of 19 are stalled"). And if the sentence already gives the
+                       number the chart would show, DROP THE CHART — one of them is
+                       redundant.
                    Everything else this report needs is ::::synap-section containers plus
                    [[entity:…]] chips inline.
 
@@ -671,6 +679,11 @@ automations:
                     section whose heading merely names the round tells the reader nothing
                     they cannot already see.
 
+                LAYOUT: put ONE blank line between blocks (paragraphs, headings, embeds) and
+                none directly after a section's opening line or before its closing ::::, as
+                in the worked example — that is the layout the document editor writes back,
+                so the report opens in it for editing.
+
                 STRUCTURE: one ::::synap-section per round, in order — analyze, then relate.
                 Open with a single "# " title line ABOVE the first section, and open each
                 section with its own ## claim heading per rule 10.
@@ -698,8 +711,14 @@ automations:
                 majority are sitting in one status — the oldest is
                 [[entity:3f2a91c4-7b10-4e55-9c02-8ad1f6e4b2d7|Migrate the billing worker]].
                 Notes are thin.
-                :::synap-cell{cellKey="chart-pie" cellProps='{"profileSlug":"task","groupBy":"status","label":"Review is where open tasks accumulate"}'}
+
+                :::synap-cell{cellKey="chart-pie"}
+                ```json
+                {"profileSlug":"task","groupBy":"status","label":"Open tasks by status"}
+                ```
                 :::
+
+                Review is where open tasks accumulate.
                 ::::
 
                 ::::synap-section{agent="analyst" round="relate" status="failed" confidence="0.2"}
@@ -724,6 +743,9 @@ automations:
                 RELATE ROUND MATERIAL:
                 {{steps.relate.output}}
               maxTokens: "2000"
+            errorHandling:
+              maxRetries: 1
+              retryDelay: 5000
         - id: summarize
           type: capability
           position:
@@ -742,6 +764,9 @@ automations:
                 Material to summarize (may be an error object if the round failed):
                 {{steps.analyze.output}}
               maxTokens: "500"
+            errorHandling:
+              maxRetries: 1
+              retryDelay: 5000
         - id: guard-assembled
           type: guard
           position:
@@ -756,6 +781,17 @@ automations:
               - path: steps.assemble.output.error
                 exists: false
                 message: The assembler round failed — refusing to write a report without a body.
+        - id: freeze-charts
+          type: capability
+          position:
+            x: 1740
+            "y": 320
+          data:
+            label: Freeze charts
+            verbId: document.freeze_charts
+            verbKind: read
+            inputMapping:
+              markdown: "{{steps.assemble.output}}"
         - id: create-report
           type: output
           position:
@@ -777,11 +813,25 @@ automations:
                   - Notes
                   - People
                   - Companies
-              body: "{{steps.assemble.output}}"
+              body: "{{steps.freeze-charts.output.markdown}}"
               systemData:
                 renderer:
                   kind: cell
                   cellKey: "{{trigger.payload.renderer}}"
+        - id: stamp-chart-diagnostics
+          type: capability
+          position:
+            x: 2100
+            "y": 320
+          data:
+            label: Record charts left live
+            verbId: document.stamp_diagnostics
+            verbKind: write
+            inputMapping:
+              documentId: "{{steps.create-report.output.documentId}}"
+              items: "{{steps.freeze-charts.output.diagnostics}}"
+            errorHandling:
+              continueOnError: true
       edges:
         - id: e-trigger-now
           source: trigger
@@ -834,6 +884,12 @@ automations:
         - id: e-summarize-guard
           source: summarize
           target: guard-assembled
-        - id: e-guard-create
+        - id: e-guard-freeze
           source: guard-assembled
+          target: freeze-charts
+        - id: e-freeze-create
+          source: freeze-charts
           target: create-report
+        - id: e-create-stamp
+          source: create-report
+          target: stamp-chart-diagnostics

package/src/blockchain-ecosystem.yaml

@@ -433,6 +433,7 @@ onboarding:
       who's providing liquidity, who's auditing, who's building, and who's amplifying.
   collect:
     - profileSlug: market-maker
+      min: 1
       what: The market-makers / liquidity providers you work with, tagged onto the real company.
       cardinality: few
       keyFields: [status, exchanges]