@oneie/sdk 0.14.13 → 0.15.0

package/dist/receivers.js

@@ -159,6 +159,12 @@ export const RECEIVERS = {
         summary: "Agency mints a scoped invite; on accept the invitee owns a new workspace parented under the agency",
         request: z.object({
             slug: z.string(),
+            // The invitee's slug. Prefer this over `slug`: a trusted service caller
+            // nominates its OWN workspace with `slug` (the ask route reads payload.slug
+            // as the caller identity), so naming the invitee there self-parents the
+            // invite and mints credits against no sponsor. Refused server-side when the
+            // resolved child equals the sponsor.
+            child: z.string().optional(),
             name: z.string().optional(),
             email: z.string().email().optional(),
             plan: z.enum(["free", "pro", "studio", "agency", "enterprise"]).optional(),
@@ -170,7 +176,7 @@ export const RECEIVERS = {
         }),
         response: z.object({ token: z.string(), id: z.string(), child: z.string(), expiresAt: z.number() }),
         effect: "ask", auth: "manage_clients", reversible: false,
-        examples: [{ slug: "beta", email: "owner@beta.com", plan: "studio", credits: 50000, markup: 20 }],
+        examples: [{ slug: "one", child: "beta", email: "owner@beta.com", plan: "studio", credits: 50000, markup: 20 }],
     }),
     "world:accept-client-invite": receiver({
         receiver: "world:accept-client-invite",
@@ -239,6 +245,61 @@ export const RECEIVERS = {
         request: z.object({ gid: z.string(), name: z.string().optional(), tags: z.array(z.string()).optional(), meta: z.unknown().optional() }),
         response: ok, effect: "ask", auth: "manage_groups", roleAction: "update_group",
     }),
+    /**
+     * The only non-HTTP door to a workspace's brand. Tokens previously reached R2
+     * through `pages/api/{branding,settings,onboarding}.ts` only, so a workflow
+     * step, an agent, the CLI and MCP could not persist a theme at all.
+     *
+     * `auth: "manage_workspace"` is chosen because it is already in
+     * bind-receiver.ts's AUTH_POLICY mapping to the ENFORCED `tenant` class — an
+     * invented label would fall through `AUTH_POLICY[label] ?? 'authenticated'`
+     * to the WARN-only class and ship a workspace write with no enforced floor.
+     *
+     * `cost: "free"` is a declaration, not an omission: an R2 read+put costs no
+     * provider dollars, and per text/credit-allocation.md an UNDECLARED cost must
+     * not read as free. `reversible: false` is honest — the response reports which
+     * keys were written but not their prior values, so the caller cannot restore
+     * them from it. Handler: one.ie/web/src/lib/resolvers/brand.ts.
+     *
+     * The write is held to WCAG AA by the SAME `auditBrandContrast` the brand
+     * editor route calls, so a theme written by a workflow step meets the bar a
+     * human-written one does.
+     */
+    "world:set-brand-tokens": receiver({
+        receiver: "world:set-brand-tokens",
+        summary: "Write validated colour tokens to a workspace's brand (site.md)",
+        request: z.object({
+            /** The workspace being rebranded. The ONLY workspace field: authority is
+             *  decided against this value and it is the only one written to. */
+            workspace: z.string(),
+            /** Frontmatter keys to set. The six light tokens (primary, secondary,
+             *  tertiary, background, foreground, font) and their `dark-` overrides;
+             *  any other key is ignored, never written. `"unset"` on a `dark-` key
+             *  deletes the override, re-linking it to the light value. Values are
+             *  syntax-gated with the same HEX_OR_HSL regex `parseSite` reads with, then
+             *  checked readable with `parseColor`, then held to WCAG AA by the same
+             *  `auditBrandContrast` the brand editor route calls. Any invalid value —
+             *  or any AA failure on a pair THIS write touches — refuses the WHOLE
+             *  write; pre-existing failures come back as `warnings`. */
+            tokens: z.record(z.string(), z.string()),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            workspace: z.string().optional(),
+            written: z.array(z.string()).optional(),
+            bytes: z.number().optional(),
+            ignored: z.array(z.string()).optional(),
+            error: z.string().optional(),
+            invalid: z.array(z.object({ field: z.string(), value: z.string(), reason: z.string() })).optional(),
+            /** WCAG AA pairs THIS write touches that fail — the write is refused. */
+            failures: z.array(z.record(z.string(), z.unknown())).optional(),
+            /** Pairs it leaves alone that already fail — reported, never blocking. */
+            warnings: z.array(z.record(z.string(), z.unknown())).optional(),
+        }),
+        effect: "ask", auth: "manage_workspace", roleAction: "update_group",
+        cost: "free", reversible: false, idempotent: true, settles: "none",
+        examples: [{ workspace: "acme", tokens: { primary: "#1a73e8", "dark-primary": "#8ab4f8" } }],
+    }),
     "world:remove-group": receiver({
         receiver: "world:remove-group",
         summary: "Delete a group",
@@ -440,6 +501,73 @@ export const RECEIVERS = {
         effect: "ask", auth: "manage_integrations", reversible: false,
         examples: [{ slug: "acme", toolkit: "stripe", credentials: { api_key: "sk_test_..." } }],
     }),
+    // git:pr — open or update ONE pull request on the repository a workspace owns.
+    //
+    // THE REPO IS NOT A PARAMETER, and that is the security property, not an
+    // ergonomic one. `bind-receiver.ts` splits the work: the binder asks "does this
+    // caller hold this CLASS of authority?", the handler asks "…over this
+    // PARTICULAR object?". Every other tenant receiver can answer the second
+    // because its object is a node in the six dimensions. A GitHub repository is
+    // not one — grep every schema/*.tql and the only hit is a `front-door`
+    // attribute whose VALUE may be the string "github". So `git:pr({ repo, … })`
+    // would take its target from the body and its credential from env: workspace
+    // authority anywhere becoming a write to any repo the token can reach, signed
+    // by ONE. That is the confused deputy, and it is the same defect class as
+    // trusting an actorId from a request body.
+    //
+    // So the caller never names the repository. The object of the decision is the
+    // WORKSPACE — dimension 1, a real node — resolved from the attested
+    // `ctx.ownerSlug` exactly as `tools:composio` resolves its entity ("never a
+    // body field", in that resolver's own words), and the repo is looked up FROM
+    // the workspace. No binding is a refusal, never a fallback to a default repo.
+    //
+    // `auth` is `manage_integrations` because it must be: AUTH_POLICY maps that to
+    // the `tenant` floor, and an unrecognised label falls to `authenticated`
+    // (bind-receiver.ts:120) — a novel name would have shipped this WEAKER, and
+    // nothing in the suite would have said so.
+    //
+    // It cannot derive its own title or body: there is no git and no shell in a
+    // Worker. Those are the caller's, which is why this receiver is the DOOR and
+    // `.claude/scripts/pr-body.sh` is the document.
+    "git:pr": receiver({
+        receiver: "git:pr",
+        summary: "Open or update one pull request on the repository this workspace is bound to — the repo is resolved from the workspace, never from the payload",
+        request: z.object({
+            workspace: z.string().optional().describe("Workspace slug; defaults to the attested caller's. The bound repo is resolved FROM this."),
+            head: z.string().describe("Branch to merge from — must already be pushed"),
+            base: z.string().optional().describe("Branch to merge into; defaults to main"),
+            title: z.string().describe("PR title"),
+            body: z.string().optional().describe("PR body — derive it with .claude/scripts/pr-body.sh; a Worker cannot"),
+            draft: z.boolean().optional().describe("Open as a draft"),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            url: z.string().optional(),
+            number: z.number().optional(),
+            updated: z.boolean().optional().describe("true = an open PR was updated rather than a new one created"),
+            repo: z.string().optional(),
+            error: z.string().optional(),
+            detail: z.string().optional(),
+        }),
+        effect: "ask",
+        auth: "manage_integrations",
+        // A PR is closable, and a re-run updates the open one rather than opening a
+        // second — so a retried workflow step is safe as-is.
+        reversible: true,
+        idempotent: true,
+        cost: "free",
+        settles: "none",
+        version: "1.0.0",
+        examples: [{ head: "feat/x", base: "main", title: "feat: x" }],
+    }),
+    "tools:composio": receiver({
+        receiver: "tools:composio",
+        summary: "Execute one connected Composio tool from a workflow `tool` step (config.composio)",
+        request: z.object({ workspace: z.string().optional().describe("Workspace slug; defaults to the attested caller's"), tool: z.string().describe("Composio tool slug to execute"), args: z.record(z.string(), z.unknown()).optional().describe("Arguments passed to the tool") }),
+        response: z.object({ ok: z.boolean(), tool: z.string().optional(), result: z.unknown().optional(), error: z.string().optional() }),
+        effect: "ask", auth: "manage_integrations", reversible: false, idempotent: false,
+        examples: [{ workspace: "acme", tool: "GMAIL_SEND_EMAIL", args: { to: "x@y.com" } }],
+    }),
     "brand:set": receiver({
         receiver: "brand:set",
         summary: "Write up to 6 brand color tokens (primary/secondary/accent/bg/text/border) to a workspace theme",
@@ -947,6 +1075,70 @@ export const RECEIVERS = {
         }),
         effect: "ask", idempotent: true,
     }),
+    "factory:size": receiver({
+        receiver: "factory:size",
+        summary: "How big is this change — the tier `.claude/scripts/do-tier.sh` returns for the same paths, answered where a Worker can ask (a Worker cannot run a shell script, which is the only reason the Size card at factory flow.ts:306 is a gap). Zero real paths is REFUSED as `unsized`, mirroring the script's exit 3: absence of recon must not read as simplicity. The pin ladder in the response is a pure function of the tier; the surfaces are additive obligation, never a second gate selector",
+        request: z.object({
+            // The changed paths, repo-relative. do-tier sizes a DIFF, never a sentence,
+            // so this is the only field that can decide the answer.
+            paths: z.array(z.string()).max(2000),
+            // Free text. It can only RAISE the answer to FEATURE, and is ignored entirely
+            // when `paths` is empty — "add a null check" and "add a settings page" share a verb.
+            intent: z.string().max(2000).optional(),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            tier: z.enum(["PATCH", "FIX", "FEATURE", "SCHEMA"]).optional(),
+            spine: z.string().optional(),
+            classifier: z.string().optional(),
+            ceilingTokens: z.number().optional(),
+            // The pinned suites this tier buys — derived from `tier` alone, mirroring
+            // .claude/scripts/verify-fast.sh:302-306. There is no second selector.
+            pins: z.array(z.string()).optional(),
+            // What the paths touch, and the ceremony rung after every surface floor is
+            // applied. Obligations, not gate selection.
+            surfaces: z.array(z.string()).optional(),
+            risk: z.string().optional(),
+            ratcheted: z.boolean().optional(),
+            produces: z.array(z.object({ what: z.string(), source: z.string() })).optional(),
+            gates: z.array(z.object({ what: z.string(), source: z.string() })).optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", idempotent: true, reversible: true,
+    }),
+    "factory:recon": receiver({
+        receiver: "factory:recon",
+        summary: "What does this sentence touch — the paths, the route and the verdict `.claude/scripts/do-triage.sh` returns for the same text, answered where a Worker can ask (a Worker cannot exec a shell script, which is the only reason the recon card at factory flow.ts:480 was a gap). Runs UPSTREAM of factory:size: prose in, repo paths out, and the sizer's own contract unchanged. No model call. It ALWAYS answers with a verdict and never refuses — it runs as a workflow tool step (one.ie/ai/workflows/eng-intake.tql:33), where a failed step poisons every step downstream of it; factory:size's `unsized` stays the one refusal on this lane",
+        request: z.object({
+            // The captured sentence. do-triage reads what the text LITERALLY names —
+            // there is no model here, so a sentence that names nothing answers `idea`.
+            intent: z.string().max(2000),
+            // Paths a caller already knows. Accepted so a workflow step can pass the
+            // trigger through whole; recon derives its own from `intent` and does not
+            // widen the answer with these.
+            paths: z.array(z.string()).max(2000).optional(),
+            // The trigger's tags, carried not read. Declared for one measured reason:
+            // zod `.object()` STRIPS unknown keys, so an undeclared field arriving from
+            // a workflow step is a shape error rather than a no-op. It decides nothing —
+            // same rule as factory:size's `workspace`: a body field that decided nothing
+            // cannot be spoofed into deciding something.
+            tags: z.array(z.string()).max(64).optional(),
+        }),
+        response: z.object({
+            // Always true. There is no `ok:false` branch in this receiver.
+            ok: z.boolean(),
+            verdict: z.enum(["sizeable", "idea", "dupe", "split"]).optional(),
+            // Repo-relative, existing, in the order the sentence names them. This is the
+            // array that goes to factory:size unchanged.
+            paths: z.array(z.string()).optional(),
+            route: z.string().nullable().optional(),
+            // Every path-SHAPED token the sentence named, before the existence filter.
+            // The edge can confirm fewer paths than the shell can (it has a page glob,
+            // not a repo), and this is that difference made legible rather than hidden.
+            named: z.array(z.string()).optional(),
+        }),
+        effect: "ask", idempotent: true, reversible: true,
+    }),
     "factory:attempt": receiver({
         receiver: "factory:attempt",
         summary: "Open an attempt contained by its task, or close it with the production edge to what it produced plus the rubric. A do-cycle IS an attempt (factory-plan.md §3.1) — do:cycle-close arms as a caller of the close phase, never as a second writer",
@@ -986,6 +1178,257 @@ export const RECEIVERS = {
         }),
         effect: "ask", idempotent: true,
     }),
+    "deploy:event": receiver({
+        receiver: "deploy:event",
+        summary: "One deploy gate lands on the same run/event stream the canvas already reads — the ten-gate pipeline (tree·credentials·typecheck·tests·build·smoke·approval·migrations·ship·health) that until now touched the substrate NOWHERE, leaving a committed JSON file as a deploy's only trace. Carries the metrics that file has no shape for: whether the suite was REUSED or re-run, whether a gate passed under a waiver, and which services actually shipped. An unknown stage, status or verdict is REFUSED, never recorded as a default frame",
+        request: z.object({
+            // The deploy's own run id — deploy.sh already mints one for its log name.
+            // It IS half the run key, which is why a retried gate appends to its own
+            // run instead of minting a second one. The sha cannot serve: the same sha
+            // ships to the same target repeatedly (2026-09-06: af3ba5919 gates-only,
+            // red, green, then shipped), and keying on it would interleave them.
+            run: z.string(),
+            // Where it ships. The other half of the key, so "did pay go out" is
+            // answerable without disambiguating five services by timestamp.
+            target: z.string(),
+            // Must equal DEPLOY_SPINE_STEPS (one.ie/web/src/lib/deploy/event.ts).
+            // Retyped because packages/sdk cannot import from one.ie/web; pinned by
+            // tests/unit/deploy/event.test.ts so the two cannot drift.
+            stage: z.enum([
+                "tree", "credentials", "typecheck", "tests", "build",
+                "smoke", "approval", "migrations", "ship", "health",
+            ]).optional(),
+            // There is deliberately no "skip": a gate that did not run must be ABSENT.
+            // deploy.sh already reports four gate states (pass|fail|unrun|n/a) and an
+            // unrun gate is never a pass — a "skip" frame would render like one.
+            status: z.enum(["start", "ok", "fail"]).optional(),
+            // Present only on the final call, and it is what CLOSES the run. Separate
+            // from the stages because --gates-only is a complete, successful run that
+            // legitimately never reaches `ship` or `health`; closing on the last stage
+            // would leave every one of those runs "open" forever.
+            verdict: z.enum(["green", "red"]).optional(),
+            sha: z.string().optional(),
+            // Which door ran it: ./deploy, release.sh ship, land --pr --deploy.
+            door: z.string().optional(),
+            // Board workspace. TAGS ONLY inside the resolver — effectiveWorkspace
+            // reads `workspace` and never `slug`. The same caller-nomination note as
+            // factory:event's `slug` field applies verbatim for a service caller.
+            slug: z.string().optional(),
+            // "dev" flags the projected run is_test so dev.one.ie never pollutes the
+            // production list. --dry-run does not reach here at all: the emitter is
+            // not called on that path, because a run row for a deploy that did not
+            // happen is the theater /deploy already refuses to render.
+            env: z.string().optional(),
+            reason: z.string().optional(),
+            // This gate's own wall clock. Written to workflow_run_event.latency_ms —
+            // the column factory:event binds NULL because a factory stage has no
+            // measured duration. It is the number this whole receiver exists for.
+            wallMs: z.number().optional(),
+            // reused / waived / services — see DeployEventPayload.detail.
+            detail: z.record(z.string(), z.unknown()).optional(),
+            workspace: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            runId: z.string().optional(),
+            stage: z.string().optional(),
+            status: z.string().optional(),
+            verdict: z.string().optional(),
+            events: z.number().optional(),
+            slug: z.string().optional(),
+            error: z.string().optional(),
+        }),
+        // Same floor and same reasoning as factory:event: authClassFor(undefined)
+        // returns 'open', and the 'authenticated' floor tests exactly the predicate
+        // the handler's own guard uses, one layer earlier. Declaring it makes the
+        // fail-closed intent survive a refactor of the handler.
+        auth: "required",
+        effect: "ask", idempotent: true,
+    }),
+    "factory:event": receiver({
+        receiver: "factory:event",
+        summary: "One factory-executor stage lands on the same run/event stream the canvas already reads — the six-stage pipeline (ready·claim·build·review·prove·close) that until now touched the substrate only at claim and close, so every surface could show a job before and after but never during. An unknown stage or status is REFUSED, never recorded as a default frame",
+        request: z.object({
+            // The task id being built. It IS the run key (`factory:<job>`), which is why
+            // a retried stage appends to its own run instead of minting a second one.
+            job: z.string(),
+            // Must equal FACTORY_SPINE_STEPS (one.ie/web/src/lib/factory/event.ts).
+            // Retyped because packages/sdk cannot import from one.ie/web; pinned by
+            // tests/unit/factory/event-receiver.test.ts so the two cannot drift.
+            stage: z.enum(["ready", "claim", "build", "review", "prove", "close"]),
+            // There is deliberately no "skip": a stage that did not run must be ABSENT.
+            status: z.enum(["start", "ok", "fail"]),
+            // Board workspace. TAGS ONLY *inside the resolver* — effectiveWorkspace
+            // (resolvers/tasks.ts:35) reads `workspace` and never `slug`, so the resolver
+            // itself cannot be steered by this field.
+            //
+            // BUT NOT BEFORE IT. For a VERIFIED SERVICE CALLER the ask route nominates
+            // the identity from the body and `slug` WINS:
+            //   pages/api/ask/[...receiver].ts:237
+            //     nominated = typeof p.slug === 'string' ? p.slug
+            //               : typeof p.workspace === 'string' ? p.workspace : undefined
+            //   :324  ownerSlug = locals.slug ?? callerUid ?? serviceOwnerSlug
+            // A sessionless curl (no `locals.slug`, and `callerUid` is only resolved in the
+            // `bearerToken && !isServiceCaller` branch) therefore lands ctx.ownerSlug =
+            // data.slug, and effectiveWorkspace returns that owner unchanged. So on the
+            // shipped emitter — .claude/scripts/factory-emit.sh, which posts
+            // `Authorization: Bearer $GATEWAY_API_KEY` (isVerifiedServiceCaller case 2,
+            // gateway-guard.ts:118) and sends `--slug` but never `workspace` — the `slug`
+            // COLUMN is data.slug, chosen by the caller. That is by design for a caller
+            // holding a shared service secret, and it is NOT what "never authz" says.
+            // The tags/authz split is a property of the RESOLVER, not of this field.
+            slug: z.string().optional(),
+            model: z.string().optional(),
+            detail: z.record(z.string(), z.unknown()).optional(),
+            reason: z.string().optional(),
+            // "dev" flags the projected run is_test so a worktree never pollutes the list.
+            env: z.string().optional(),
+            // Which authorized workspace the `slug` COLUMN resolves to (effectiveWorkspace,
+            // resolvers/tasks.ts). Never identity: an unauthorized value falls back to the
+            // attested ownerSlug rather than escalating.
+            workspace: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            runId: z.string().optional(),
+            stage: z.string().optional(),
+            status: z.string().optional(),
+            events: z.number().optional(),
+            slug: z.string().optional(),
+            error: z.string().optional(),
+        }),
+        // VERIFIED, not assumed: authClassFor(undefined) returns 'open'
+        // (bind-receiver.ts:117-120), and the 'authenticated' floor tests exactly
+        // `ctx.staff === true || Boolean(ctx.ownerSlug)` (bind-receiver.ts:159) — the
+        // same predicate the handler's own guard uses, one layer earlier, never
+        // stricter. The four siblings omit the label; declaring it here makes the
+        // fail-closed intent survive a refactor of the handler.
+        //
+        // HOW THE FLOOR ACTUALLY CLEARS — the previous note here said "the executor's
+        // world-key call carries `data.workspace`, which the ask route turns into
+        // ctx.ownerSlug". Both halves were wrong. The shipped emitter
+        // (.claude/scripts/factory-emit.sh) is NOT a world-key call: it posts
+        // `Authorization: Bearer $GATEWAY_API_KEY`, which is isVerifiedServiceCaller
+        // case 2 (gateway-guard.ts:118) — the SERVICE-secret door, not the per-actor
+        // one. A world-key bearer takes the other branch entirely
+        // (`bearerToken && !isServiceCaller`, [...receiver].ts:238) and resolves
+        // `callerUid`, never `serviceOwnerSlug`. And it does not send `workspace` at
+        // all; it sends `slug`, which is the FIRST nomination at :237 and therefore
+        // wins for a service caller. So the floor clears on a caller-supplied `slug`
+        // reaching ctx.ownerSlug — see the note on the `slug` field above.
+        auth: "required",
+        // Two `build/ok` events for one job are two real frames with rising seq, not
+        // a dedupe. The RUN row dedupes (INSERT OR IGNORE); the events do not.
+        effect: "ask", idempotent: false,
+    }),
+    "story:chain": receiver({
+        receiver: "story:chain",
+        summary: "The stories, counted: sets of two or more signals sharing one `origin`, read from the D1 lineage ledger (migrations/0244_story_link.sql). A story is a COUNT over a shared origin, not an entity \u2014 zero new types, zero new dimensions. The number moves as a side effect of signals that already flow; nobody types a row. `count` is the whole qualifying population, `stories` a page of at most 50 ordered by members desc \u2014 a capped count would plateau exactly when the substrate got busy. Zero is a real answer, never an error",
+        request: z.object({
+            // Where "a story is two or more" lives. The floor is the caller's, so 1
+            // legitimately means "every origin"; the default is the contract's 2.
+            minMembers: z.number().int().min(1).max(1_000_000).optional(),
+            // Narrow to one story. The same floor still applies: an origin holding a
+            // single signal answers count:0, because one signal is not yet a story.
+            origin: z.string().max(128).optional(),
+            // Page size only. Capped at 50 by the reader; it can never widen the scan.
+            limit: z.number().int().min(1).max(50).optional(),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            count: z.number(),
+            minMembers: z.number().optional(),
+            stories: z.array(z.object({
+                origin: z.string(),
+                members: z.number(),
+                // NULLABLE on purpose: `ts` is nullable in 0244, so MIN/MAX over a row
+                // that carried none is NULL. Typing these bare numbers would be a lie
+                // the response validator eventually catches in prod.
+                first: z.number().nullable().optional(),
+                last: z.number().nullable().optional(),
+            })).optional(),
+        }),
+        // PUBLIC, and the reason is the ledger's shape, not an oversight. 0244 stores
+        // signal_id, origin, receiver and ts \u2014 "no actor, no payload and no ip", in
+        // its own words \u2014 so there is nothing here to scope to a tenant and nothing
+        // to leak by reading it. The alternative is worse than permissive: the binder
+        // attests on `staff || ownerSlug` (bind-receiver.ts applyAuth), and a service
+        // caller nominates ownerSlug only via a `slug`/`workspace` body field, which
+        // this contract has no reason to carry \u2014 so an `authenticated` label would
+        // refuse the very call the promise's Proof makes.
+        auth: "public",
+        // A pure read. Same inputs, same answer, until a signal moves the number.
+        effect: "ask", idempotent: true, reversible: true,
+    }),
+    // story:event — the funnel's doors. text/story-framework.md § "The story is
+    // alive" names nine steps and schema/story.tql block 4 declares the EVENT
+    // CONVENTION they are counted by; until this receiver existed nothing in the
+    // estate WROTE one, so every block-4 fun answered 0 and block 5's story_death
+    // answered "queen" for every story that had ever been told
+    // (text/story-tracking-plan.md § Gaps 4). This is the write half.
+    //
+    // ONE signal per call, under the story's origin, carrying the block-4 payload
+    // pairs: {"origin":"<o>","event":"story:<kind>"} plus "parent" on a retell and
+    // an `amount` attribute on a convert. The graph write and the trail marks are
+    // deferred to waitUntil — the brain takes the write, never the request path
+    // (root CLAUDE.md § The brain and the edge).
+    //
+    // AUTH IS PER-KIND, which no single label can express, so the label is the
+    // widest kind and the resolver holds the rest: `told`, `convert` and `retell`
+    // refuse an unattested caller (they name a teller, move money, or claim
+    // lineage), while `framed`/`view`/`complete`/`share` are open — a reader of a
+    // published story has no session and a view nobody can send is not a funnel.
+    // The identity is ALWAYS ctx, never the body (memory: resolver-body-actorid).
+    "story:event": receiver({
+        receiver: "story:event",
+        summary: "One step of a story's life, written as a signal under its origin: told · framed · view · complete · share · convert · retell. The payload carries the block-4 event convention (schema/story.tql), so story_views / story_conversions / story_revenue / story_retells / story_teller start answering from real traffic instead of 0. A convert also marks the two craft trails — tag:<board>:story → tag:<board>:frame:<x> and → tag:<board>:medium:<x> — and a retell marks teller → reteller, the referral edge. told/convert/retell need an attested caller; view/complete/share may be anonymous and are deduped per (origin, viewer, event) for an hour",
+        request: z.object({
+            // The story. Minted by the door (C3) and echoed on every response, so a
+            // caller always has one to quote; never derived from a task id.
+            origin: z.string().min(1).max(128),
+            // The nine-step funnel's kinds, minus the four a rung already writes
+            // (promised/building/settled are the promise's own states).
+            event: z.enum(["told", "framed", "view", "complete", "share", "convert", "retell"]),
+            // Revenue on a convert. 0 is a real answer — a sign-up converts and moves
+            // no money — so it is not conflated with absent.
+            amount: z.number().nonnegative().max(1_000_000).optional(),
+            // REQUIRED on a retell: the origin of the story this one was told from.
+            // A retell without it is lineage that names no parent, which is what
+            // story_children reads, so it is refused rather than written half-formed.
+            parent: z.string().max(128).optional(),
+            // What converted — the framework and the medium. Named on a convert, they
+            // become the two marks; absent, the convert still counts and marks nothing.
+            frame: z.string().max(64).optional(),
+            medium: z.string().max(64).optional(),
+            // TENANCY: honoured only when it equals the attested caller's own slug.
+            // A caller that could name another board could poison another tenant's
+            // routing weights (resolvers/subscriptions.ts:399-403).
+            board: z.string().max(64).optional(),
+            // Whether the medium played to the end — the one thing story_completes
+            // reads `has success true` for. Defaults true.
+            success: z.boolean().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            origin: z.string().optional(),
+            // The full pair as written, e.g. "story:view" — so a caller can grep the
+            // same string schema/story.tql matches on.
+            event: z.string().optional(),
+            // TRUE means the window already held this (origin, viewer, event) and no
+            // second signal was written. A real answer, never an error.
+            deduped: z.boolean().optional(),
+            // The trails this call will move, as "<source>→<target>". Empty is honest:
+            // a convert naming no frame and no medium marks nothing.
+            marked: z.array(z.string()).optional(),
+            error: z.string().optional(),
+        }),
+        // The widest kind. See the note above: the narrower kinds are gated in the
+        // resolver on ctx, because one label cannot say "open to read, closed to tell".
+        auth: "public",
+        // It writes. Not idempotent: two views an hour apart are two views, and the
+        // dedupe window is a window, not a key.
+        effect: "signal", cost: "free", reversible: false, idempotent: false,
+    }),
     "do:halt": receiver({
         receiver: "do:halt",
         summary: "Stop a factory run, or release the stop. Sets a halt latch on the plan thing that `factory:attempt` phase \"open\" refuses against, so no new attempt can be claimed; with `attempt`, also closes that in-flight attempt as dissolved. It does NOT kill an OS process — a cycle already executing stops at its next substrate write",
@@ -1024,13 +1467,18 @@ export const RECEIVERS = {
             // Prose goal / what "done" looks like — the context a human attaches at create so
             // the task is pickable by an agent or a Claude Code session without a round trip.
             notes: z.string().optional(),
+            // Optional parent tid — writes the `containment` edge in the SAME pipeline as the
+            // row, so the factory's downward walk (fn ready-tasks -> derived-from) can reach the
+            // task. Without it the task is an orphan: on the board, unreachable from any plan.
+            // Refused unless the caller has operate access to the parent.
+            parent: z.string().optional(),
             // The viewed /u/<slug> workspace to file the task under. Honored only when the
             // caller is authorized for it (attested staff or owner-tree control); otherwise
             // the resolver falls back to the caller's own slug. Reconciles the create tag
             // with the /api/things read filter so a created task survives reload.
             workspace: z.string().optional(),
         }),
-        response: z.object({ ok: z.boolean(), tid: z.string().optional(), tags: z.array(z.string()).optional() }),
+        response: z.object({ ok: z.boolean(), tid: z.string().optional(), tags: z.array(z.string()).optional(), parent: z.string().optional() }),
         effect: "ask", idempotent: false,
     }),
     "tasks:claim": receiver({
@@ -1140,12 +1588,70 @@ export const RECEIVERS = {
         }),
         effect: "ask", idempotent: true, auth: "member",
     }),
+    // tasks:generate — read what a page says, propose the work it implies, and file it.
+    //
+    // The one task verb that does not take a title: the caller hands over the PAGE
+    // (its title, its own summary, its visible text) and gets back real rows on the
+    // board. Every row is written through `tasks:create`, so the workspace gate, the
+    // announce and the write-failure semantics are the ones that verb already holds —
+    // this receiver only decides WHAT to file, never who may file it.
+    //
+    // No URL is fetched server-side. The caller sends the text it can already see
+    // (the browser reads its own DOM, or same-origin-fetches a page under the
+    // viewer's own session); a receiver that fetched an arbitrary `url` would be an
+    // SSRF door on a surface that spends LLM tokens. `url` is a LABEL here — it
+    // names the source and seeds the dedupe key, and is never dereferenced.
+    //
+    // Idempotent by (source, title): each row carries a derived `slug:` tag, which
+    // tasks:create dedupes on. Clicking twice on the same page cannot double the
+    // board, while a genuinely new suggestion still lands.
+    "tasks:generate": receiver({
+        receiver: "tasks:generate",
+        surfaces: { mcp: true },
+        summary: "Turn a page into tasks: read the page text the caller supplies, propose 3-7 concrete next actions, and write each one through tasks:create (deduped by source+title). Never fetches the URL — `url` labels the source and seeds the dedupe key",
+        request: z.object({
+            /** Source label + dedupe seed. Never fetched. */
+            url: z.string().optional(),
+            title: z.string().optional(),
+            /** The page's own description / heading trail — what `readPageSummary()` returns. */
+            summary: z.string().optional(),
+            /** Visible page text, if the caller has it. Capped server-side. */
+            text: z.string().optional(),
+            /** How many tasks to aim for. Clamped to 1-8. */
+            count: z.number().optional(),
+            /** Extra tags every generated task carries, on top of `from-page`. */
+            tags: z.array(z.string()).optional(),
+            /** The viewed /u/<slug> workspace — same authorization contract as tasks:create. */
+            workspace: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            created: z.number().optional(),
+            deduped: z.number().optional(),
+            /** The workspace the rows actually landed in — the resolver's own answer,
+             *  not the caller's request. A caller that guessed this instead would link
+             *  the operator at a board their tasks are not on whenever the workspace
+             *  override was refused. */
+            workspace: z.string().optional(),
+            tasks: z.array(z.object({ tid: z.string(), title: z.string(), deduped: z.boolean().optional() })).optional(),
+            error: z.string().optional(),
+        }),
+        // Spends LLM tokens and writes rows. An undeclared label is an anonymous door
+        // (see receiver-envelope.ts § requiresAttestedCaller) — this one refuses.
+        effect: "ask", auth: "member", reversible: false, idempotent: true,
+    }),
     "tasks:list": receiver({
         receiver: "tasks:list",
         surfaces: { mcp: true },
         summary: "Every task carrying a tag, with its task-status — the read that lets a plan's checkboxes be a PROJECTION of task state instead of a second copy. Scoped to the caller's workspace on the server",
         request: z.object({
             tag: z.string(),
+            // Optional task-status filter (open|blocked|picked|done|verified|failed|dissolved).
+            // Declared here because the HTTP edge dispatches zod's PARSED output — an
+            // undeclared field is silently stripped before the resolver reads it, and the
+            // factory turn (one.ie/ai/workflows/factory-turn.tql step:rows) needs the
+            // plan's OPEN rows to fan tasks:launch over.
+            status: z.string().optional(),
             workspace: z.string().optional(),
         }),
         response: z.object({
@@ -1267,6 +1773,26 @@ export const RECEIVERS = {
             slug: z.string().optional(),
             body: z.string().optional(),
             workspace: z.string().optional(),
+            // WHICH CONVERSATION THIS CAME FROM. A comment and a chat message already
+            // live in the same D1 message store (`getOrCreateThread`, keyed
+            // `task:<tid>`); what was missing was a field naming the OTHER thread, so
+            // a discussion in the inbox and the row it is about could not be joined.
+            //
+            // It must be DECLARED to exist: `validateReceiver` returns the parsed
+            // object and a zod schema STRIPS undeclared keys, so an undeclared field
+            // never reaches the resolver. That is the same mechanism behind this
+            // door's older surprise — an unknown key degrades the call to a read that
+            // still answers ok:true.
+            threadId: z.string().optional(),
+            // WHO WROTE IT. Declared because a zod schema STRIPS an undeclared key
+            // before the resolver ever sees it — the exact mechanism that left
+            // `thread:append`'s already-implemented agent branch unreachable for every
+            // gateway caller. `authorKind` stays UNDECLARED for the same reason it
+            // does there: its value is a TRUST LABEL, and a caller naming its own is
+            // the estate's most-repeated defect. The resolver derives the label and
+            // honours this field only for an ATTESTED platform-staff caller; a bare
+            // agent key already speaks as itself from ctx and needs no field.
+            author: z.string().optional(),
         }).refine((v) => !!v.tid || !!v.slug, {
             message: "address the task by tid or slug",
             path: ["tid"],
@@ -1282,12 +1808,20 @@ export const RECEIVERS = {
     "tasks:subtask": receiver({
         receiver: "tasks:subtask",
         surfaces: { mcp: true },
-        summary: "Create a child task and hang it under its parent with `containment` in one write. Reuses create's insert path — there is no second task-insert anywhere",
+        summary: "Create a child task COMPLETE — row, notes, tags, its `containment` edge to the parent and every `blockedBy` prerequisite — in ONE pipeline, so a child never appears claimable with an empty body or missing ordering",
         request: z.object({
             parent: z.string(),
             title: z.string(),
             tags: z.array(z.string()).optional(),
             assignee: z.string().optional(),
+            // The prose goal, written at creation. A child that arrives with an empty body is
+            // claimable-but-unbuildable; notes here close that window.
+            notes: z.string().optional(),
+            // One tid or a list (max 16) of prerequisites. Each writes a `blocks` edge in the
+            // same pipeline as the row, so ordering is created at intake rather than remembered
+            // later. Validated exactly as tasks:depend does: operate-role on each prerequisite
+            // and the transitive cycle walk.
+            blockedBy: z.union([z.string(), z.array(z.string())]).optional(),
             workspace: z.string().optional(),
         }),
         response: z.object({
@@ -1295,6 +1829,7 @@ export const RECEIVERS = {
             tid: z.string().optional(),
             parent: z.string().optional(),
             tags: z.array(z.string()).optional(),
+            blockedBy: z.array(z.string()).optional(),
             error: z.string().optional(),
         }),
         effect: "ask", idempotent: false, auth: "member",
@@ -1390,7 +1925,14 @@ export const RECEIVERS = {
                 tid: z.string(),
                 ok: z.boolean(),
                 actorId: z.string().optional(),
-                reason: z.enum(["unassigned", "human-assignee", "blocked", "forbidden", "fire_failed"]).optional(),
+                // `unspecced` = the task has no Proof: row (factory/spec-gate.ts).
+                // `spec_unreadable` = we could not READ the task to decide — an outage,
+                // kept distinct from a verdict per factory-spec.md demand 6.
+                reason: z.enum(["unassigned", "human-assignee", "blocked", "forbidden", "fire_failed", "unspecced", "spec_unreadable"]).optional(),
+                /** Why the gate refused, in one human-readable line. */
+                detail: z.string().optional(),
+                /** Set when the task launched only on the spec gate's grandfather clause. */
+                warning: z.string().optional(),
             })),
         }),
         effect: "ask", idempotent: false,
@@ -1755,10 +2297,12 @@ export const RECEIVERS = {
         request: z.object({
             limit: z.number().optional(), since: z.number().optional(),
             from: z.number().optional(), to: z.number().optional(),
+            intent: z.string().optional(),
         }),
         response: z.array(z.object({
             id: z.string(), from: z.string(), to: z.string(), skill: z.string().optional(),
             outcome: z.enum(["success", "failure", "timeout"]), revenue: z.number(), ts: z.number(),
+            intent: z.string().optional(),
         })),
         effect: "ask", cost: "free", idempotent: true,
     }),
@@ -1873,6 +2417,78 @@ export const RECEIVERS = {
         effect: "ask", cost: "free", idempotent: true,
         examples: [{ feature: "premium" }],
     }),
+    // ════════════════════════════════════════════════════════════════════════
+    // id: — one door for every address in the estate. `id:resolve` is a pure
+    // projection over `one.ie/web/src/data/id-inventory.json`, the artifact
+    // `.claude/scripts/id-inventory.mjs` writes and its `--check` regenerates in
+    // memory to fail on drift. NOTHING HERE IS HAND-DECLARED: kind, provenance,
+    // count, id_prefix, summary and source are each read off that file, so this
+    // door cannot claim a population the generator never counted.
+    //
+    // Seven kinds — signal · skill · workflow · component · doc · function ·
+    // thing. `thing` is the LOCKED dimension-3 word: a ref whose prefix is
+    // `object:` is REFUSED, never silently rewritten, because a door that
+    // rewrites teaches callers a name the substrate does not have. Functions
+    // address as `fn:` (the estate's existing address — `fn:run`'s FN_MAP),
+    // never `fun:`.
+    // ════════════════════════════════════════════════════════════════════════
+    "id:resolve": receiver({
+        receiver: "id:resolve",
+        summary: "Resolve one address to its metadata card — seven generated kinds behind one door, every field projected from the generated id inventory. `object:` is refused in favour of `thing`; a ref the inventory does not hold answers `unknown_ref` rather than a guess",
+        request: z.object({
+            // The grammar `TID_RE` already admits (resolvers/factory.ts:32): MINTED
+            // `<type>:<24-hex>` or DERIVED `<type>:<scope>[:<n>][/<part>]`. A bare
+            // receiver name is its own address — `factory:size` resolves as a signal,
+            // not as a `factory` scope, because an exact registry name is matched
+            // before any prefix is read (21 receiver names would collide otherwise).
+            ref: z.string().min(1).max(128),
+        }),
+        // `factory:size`'s idiom deliberately: one flat schema, `ok: z.boolean()`,
+        // everything else optional — never a discriminated union. A refusal is the
+        // same shape as an answer, so a caller reads `ok` and nothing else.
+        response: z.object({
+            ok: z.boolean(),
+            ref: z.string().optional(),
+            kind: z.string().optional(),
+            // Lexical, per trace.ts:26-31 — the last colon segment decides. Never
+            // temporal: `attempt:<hex>:<n>` is DERIVED because its last segment is an
+            // ordinal, which is the same answer `traceIdMintedAt` already gives.
+            lane: z.enum(["minted", "derived"]).optional(),
+            name: z.string().optional(),
+            title: z.string().optional(),
+            summary: z.string().optional(),
+            source: z.string().optional(),
+            // BARE, never composed — the inventory stores `fn`, and `fn:<name>` is
+            // built at read time. null for `signal`: a receiver's name IS its address.
+            id_prefix: z.string().nullable().optional(),
+            // Read off the kind record, not asserted here. `generated` for the five
+            // counted kinds; `graph` is what `workflow` and `thing` carry, and they
+            // hold no entries, so they answer `unknown_ref` until the graph is walked.
+            provenance: z.string().optional(),
+            // The kind's population, or null where the inventory refused to count.
+            // null is UNRUN, never zero.
+            count: z.number().nullable().optional(),
+            // The commit the inventory was generated at — the answer's receipt.
+            generated_at: z.string().optional(),
+            error: z.string().optional(),
+        }),
+        // `auth: "authenticated"` — C20, the auditor's second finding. This door has
+        // no `auth:` field until now, and an ABSENT label is the one case
+        // `authClassFor` answers 'open' for (bind-receiver.ts:119), while the doc
+        // five lines above it says an unlisted label falls to 'authenticated'. So
+        // the declaration and the default disagreed, and this receiver was on the
+        // wrong side of it: what it projects IS the web's internals — every id,
+        // summary, source path and population count in the estate, from one
+        // uncredentialed POST. 320 of 335 receivers share the absent label; the
+        // default is NOT inverted this cycle (that needs the census bind-receiver.ts
+        // now logs), so this one says so explicitly instead of waiting for it.
+        //
+        // Costs the contract nothing: text/story.md:24's accept sends
+        // GATEWAY_API_KEY, which `isVerifiedServiceCaller` attests, so the promise's
+        // own check passes unchanged.
+        effect: "ask", auth: "authenticated", cost: "free", idempotent: true,
+        examples: [{ ref: "factory:size" }, { ref: "fn:uncovered" }],
+    }),
     "plugins:list": receiver({
         receiver: "plugins:list",
         summary: "List all available ONE plugins with their feature key, price, and description",
@@ -2041,6 +2657,16 @@ export const RECEIVERS = {
             content: z.string(),
             ts: z.number().optional(),
             tags: z.array(z.string()).optional(),
+            // The resolver implements this branch (messaging.ts) — an agent mirroring
+            // its own reply back into the inbox writes role "assistant", which the
+            // resolver turns into authorKind "agent". Undeclared, zod stripped it
+            // before the resolver ever saw it, so the branch was unreachable for
+            // EVERY gateway caller and every agent post landed as role "user" /
+            // authorKind "customer". `authorKind` stays UNDECLARED deliberately: its
+            // only reachable value is "staff", which is a caller naming its own
+            // author (resolver-body-actorId-not-identity) and needs an attestation
+            // decision, not a schema line.
+            role: z.enum(["user", "assistant"]).optional(),
         }),
         response: z.object({
             ok: z.boolean(),
@@ -2283,6 +2909,55 @@ export const RECEIVERS = {
         }),
         effect: "ask", cost: "free", reversible: true, idempotent: false, auth: "member",
     }),
+    // ── EVENTS (dim 5) — the analytics ingress ───────────────────────────────────
+    // event:track — the write behind POST /api/events, the browser pixel's door.
+    // PUBLIC by construction: the pixel runs on third-party pages with no session,
+    // no key and no cookie the substrate controls, so an auth label here would
+    // throw in bindReceiver's applyAuth and silently kill 46k events/30d.
+    // Identity is never taken from this payload; the route attests the caller and
+    // hands the resolver an already-enriched row.
+    "event:track": receiver({
+        receiver: "event:track",
+        summary: "Record one analytics event (agent_events_warm) and broadcast it to the workspace AnalyticsRelay",
+        request: z.object({
+            id: z.string(),
+            ts: z.number(),
+            slug: z.string(),
+            event: z.string(),
+            source: z.string(),
+            visitor_hash: z.string().optional().nullable(),
+            agent_id: z.string().optional().nullable(),
+            variant: z.string().optional().nullable(),
+            thread_id: z.string().optional().nullable(),
+            actor_id: z.string().optional().nullable(),
+            actor_type: z.string().optional().nullable(),
+            channel: z.string().optional().nullable(),
+            campaign: z.string().optional().nullable(),
+            link_id: z.string().optional().nullable(),
+            referrer: z.string().optional().nullable(),
+            user_agent_class: z.string().optional().nullable(),
+            locale: z.string().optional().nullable(),
+            payload: z.record(z.string(), z.unknown()).optional().nullable(),
+            consent_state: z.string().optional().nullable(),
+            region: z.string().optional().nullable(),
+            tags: z.array(z.string()).optional().nullable(),
+        }),
+        response: z.object({ ok: z.boolean(), id: z.string().optional(), error: z.string().optional() }),
+        examples: [
+            {
+                id: "01J8ZQ3K2P0000000000000000",
+                ts: 1767225600000,
+                slug: "one",
+                event: "pageview",
+                source: "web",
+                visitor_hash: "d41d8cd98f00b204",
+                consent_state: "granted",
+                region: "IE",
+                payload: { page: "/pricing" },
+            },
+        ],
+        effect: "signal", cost: "free", reversible: false, idempotent: true, auth: "public",
+    }),
     // ── FUNNELS (text/funnels-plan.md) — author + run funnel definitions ──────────
     // funnel:create — create a new funnel definition (draft).
     "funnel:create": receiver({
@@ -2737,6 +3412,9 @@ export const RECEIVERS = {
                 actor: z.string(), chain: z.string(), address: z.string(), balance: z.string().nullable(),
             })).optional(),
             addresses: z.array(z.object({ actor: z.string(), chain: z.string(), address: z.string() })).optional(),
+            // The per-agent PROJECTION of the on-chain ceiling (text/launch.md §0d).
+            // Zod strips unknown keys, so a field absent here never reaches AgentCaps.
+            agentCaps: z.array(z.record(z.string(), z.unknown())).optional(),
             delegated: z.array(z.record(z.string(), z.unknown())).optional(),
             error: z.string().optional(),
         }),
@@ -2761,6 +3439,37 @@ export const RECEIVERS = {
         effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "none", auth: "member",
         examples: [{ limit: 20 }, { workspace: "acme", limit: 100 }],
     }),
+    // wallet:transfer — INTERNAL credits only. TRANSFER, NEVER MINT: a
+    // solvency-checked debit and a credit that sum to zero, so a compromised caller
+    // can move credits around but cannot create them. Bounded by the payer's cap so
+    // an agent cannot transfer its way past its ceiling. Deliberately NOT
+    // `surfaces: { mcp: true }` — it never touches a chain and settles in the
+    // ledger, so it declares `settles: "offchain"` and stays reversible by a
+    // compensating transfer, unlike wallet:send.
+    "wallet:transfer": receiver({
+        receiver: "wallet:transfer",
+        summary: "Move credits between workspaces inside the ledger — solvency-checked, cap-bounded, zero-sum. Never mints; never touches a chain",
+        request: z.object({
+            to: z.string().describe("Recipient workspace slug"),
+            amount: z.number().describe("Credits; must be > 0 and an integer"),
+            workspace: z.string().optional().describe("Payer workspace; falls back to `from`, then the attested caller"),
+            from: z.string().optional().describe("Alias for `workspace` — the source the authority walk runs against"),
+            transferId: z.string().optional().describe("Idempotency key; both legs share it as rail_ref"),
+            memo: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            from: z.string().optional(),
+            to: z.string().optional(),
+            amount: z.number().optional(),
+            transferId: z.string().optional(),
+            error: z.string().optional().describe("forbidden | insufficient_credits | cap_exceeded | invalid_amount"),
+        }),
+        // Zero-sum inside the credit ledger — real value, settled OFFCHAIN (never on
+        // chain), reversible by a compensating transfer. Idempotent on `transferId`.
+        effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "offchain", auth: "manage_workspace",
+        examples: [{ to: "acme", amount: 500 }],
+    }),
     // The caller signs and broadcasts the transfer CLIENT-SIDE and passes the
     // resulting `paymentTx`; this composes pay.one.ie's create → quote → claim and
     // never holds a key. It VERIFIES that an on-chain transfer settled, so it
@@ -3628,7 +4337,7 @@ export const RECEIVERS = {
     "workflow:step-stats": receiver({
         receiver: "workflow:step-stats",
         surfaces: { mcp: true },
-        summary: "Per-step run counts and latency for one workflow (aggregated over D1 workflow_run_event) — what the canvas prints on each step card",
+        summary: "Per-step run counts, latency and last messages for one workflow (over D1 workflow_run_event) — what the canvas prints on each step card",
         request: z.object({ workflowId: z.string(), sinceMs: z.number().int().optional() }),
         response: z.object({
             stats: z.array(z.object({
@@ -3636,8 +4345,28 @@ export const RECEIVERS = {
                 runs: z.number().int(),
                 failures: z.number().int(),
                 avgMs: z.number().nullable(),
+                minMs: z.number().nullable(),
                 maxMs: z.number().nullable(),
+                /** Total ms this step has spent across every completed run. */
+                totalMs: z.number(),
+                /** This step's slice of the whole workflow's execution time, 0-1 — which
+                 *  step is the bottleneck. null when nothing has completed yet (never 0:
+                 *  no share of nothing is not "0% of the time"). */
+                share: z.number().nullable(),
                 lastAt: z.number().nullable(),
+                // The step's last few events, newest first — what it SAID, not just how
+                // often it ran. `text` is already truncated server-side; a card that wants
+                // the whole payload opens the run monitor.
+                messages: z.array(z.object({
+                    kind: z.string(),
+                    status: z.string().nullable(),
+                    latencyMs: z.number().nullable(),
+                    at: z.number(),
+                    text: z.string(),
+                })),
+                /** Recent completed latencies, OLDEST → NEWEST, for the card's sparkline.
+                 *  Empty when the step has completed nothing recently. */
+                series: z.array(z.number()),
             })),
             error: z.string().optional(),
         }),
@@ -4667,6 +5396,21 @@ export const RECEIVERS = {
         }),
         effect: "ask", auth: "public", cost: "free", reversible: false, idempotent: true,
     }),
+    // ── health — the doctor. Handler in resolvers/health.ts ───────────────────
+    "health:diagnose": receiver({
+        receiver: "health:diagnose",
+        summary: "Probe every deployed surface and the receiver failure rates D1 already records, then write the verdict back as weighted paths (mark on up, warn on down or on a sick receiver) so the next sweep starts from what the last one learned. Diagnoses only — it never restarts, redeploys or kills anything, because the remote half has no provably safe remedy. Fired by the health-tick cron trigger.",
+        request: z.object({}),
+        response: z.object({
+            ok: z.boolean(),
+            verdict: z.enum(["healthy", "degraded", "unhealthy"]).optional(),
+            symptoms: z.array(z.string()).optional(),
+            surfaces: z.array(z.unknown()).optional(),
+            sick: z.array(z.unknown()).optional(),
+            checkedAt: z.string().optional(),
+        }),
+        effect: "ask", auth: "public", cost: "free", reversible: false, idempotent: true,
+    }),
     // ── seo — handlers in resolvers/seo.ts (C1 live; C2 async) ─────────────────
     "seo:backlinks-summary": receiver({
         receiver: "seo:backlinks-summary",
@@ -4722,6 +5466,50 @@ export const RECEIVERS = {
         effect: "ask", cost: "variable", reversible: true, idempotent: false, auth: "member",
         examples: [{ site_url: "https://one.ie/", start_date: "2026-01-01", end_date: "2026-06-01" }],
     }),
+    // ── promise: — the contract a story signs (resolvers/promises.ts) ──────────
+    // Declared here because a workflow step may only bind a REGISTERED name:
+    // `story-intake` binds both, and campaign-ads-social.test.ts refuses a binding
+    // no receiver implements. `promise:get` is deliberately NOT declared — nothing
+    // binds it and this cycle registers only what a template reaches.
+    "promise:make": receiver({
+        receiver: "promise:make",
+        summary: "State terms and exactly one proof observable — the terms FREEZE (sha-256 terms_hash, insert-once) and the promise enters state 'promised'. The maker is the attested caller, never a body field",
+        request: z.object({
+            slug: z.string().describe("Stable id for the promise, e.g. story:<origin>. [A-Za-z0-9_:/-], max 128"),
+            terms: z.string().describe("What is promised — hashed verbatim into terms_hash and never rewritten"),
+            proof: z.string().describe("The ONE observable that decides kept vs broken. A shell-shaped proof settles at PROVE via the CLI, never in the worker"),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            slug: z.string().optional(),
+            state: z.literal("promised").optional(),
+            terms_hash: z.string().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", auth: "member",
+        reversible: false, idempotent: true, settles: "none",
+        examples: [{ slug: "story:demo", terms: "a mover in Austin tells her origin story on her own page", proof: "test -f one.ie/web/src/pages/story.astro" }],
+    }),
+    "promise:settle": receiver({
+        receiver: "promise:settle",
+        summary: "Close the loop on a promise — kept marks the path, broken warns it, and a terminal promise never re-settles. Only the PERSISTED maker may settle; the verdict is the maker's assertion, the resolver never runs the proof",
+        request: z.object({
+            slug: z.string(),
+            kept: z.boolean().optional().describe("Defaults to true. false ⇒ settled-broken: resistance += 1, the path decays honestly"),
+            composite: z.number().optional().describe("Rubric composite; scales the mark by 5× when kept"),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            slug: z.string().optional(),
+            state: z.enum(["settled-kept", "settled-broken", "dissolved"]).optional(),
+            strength: z.number().optional(),
+            resistance: z.number().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", auth: "member",
+        reversible: false, idempotent: false, settles: "none",
+        examples: [{ slug: "story:demo", kept: false }],
+    }),
 };
 /**
  * RECIPES — the four agent journeys as typed, ordered receiver sequences (C6).