feat(surface): Slack Block Kit typing on f.slack.post (#347)

[kjgbot]

Closes #347. Delivered via implement-slice.flow.ts (flows-driven dogfood, mixed codex/claude).

---

Note

Medium Risk
Changes Slack effect journaling and writeback payloads on a core integration path, but plain-text behavior is preserved and coverage is mostly unit-level; full daemon integration was not verified in the author’s environment.

Overview
f.slack.post now accepts Block Kit–style payloads: a string, a structured message (text, blocks, attachments), or plain text with blocks/attachments in options (options win on overlap). replyTo still maps to the adapter’s parentRef. Plain-text posts keep the same receipt and body shape; interaction callbacks are not added.

The surface adds slackPostBody (also exported from @relayflows/surface/runtime) and OpenAPI-derived SlackBlock / SlackAttachment types via scripts/slack-message-schema.json and an updated generate-helpers.mjs, because pinned @relayfile/relay-helpers only types text-only post.

SDK slackWriteback builds the relayfile write body with slackPostBody at the transport layer while still calling the ergonomic client with a string fallback, so journals and mock writebacks carry full structured content. SlackCall typing follows the expanded surface post signature. New unit and type tests cover normalization; an authored-flow test asserts journal snapshot immutability and delivery body. docs/evidence/spec-Y/README.md records local verification (daemon/socket tests noted as environment-blocked).

^{Reviewed by Cursor Bugbot for commit 204472d. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: d3064735-eecb-4a52-927a-f72e5ba2927f

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[kjgbot]

maintainability lens — PASS

Maintainability review — PR #352 (Slack Block Kit slice)

Blockers: none.

Concerns

1. Fragile empty-string fallback at the adapter boundary — packages/sdk/src/slack-writeback.ts:75-76 dispatches structured posts to the pinned text-only client.post with typeof call.params.text === 'string' ? call.params.text : call.params.text.text ?? ''. When the caller supplies { blocks } with no fallback, the adapter's ergonomic client receives ''. Nothing local documents that the client is now a stub whose job is only to invoke transport.write. If the pinned adapter ever tightens text validation, structured-only posts break silently at a call site that reads harmless. Add a comment on both sides of the boundary explaining that the real body flows through the transport override at slack-writeback.ts:44-47.

2. Unverified end-to-end test — docs/evidence/spec-Y/README.md:65-89 reports the new authored-flow-slack.test.ts snapshot test could not run locally (socket bind refused, Rust build ENOSPC). Per AGENTS.md:81-100, this is a claim without captured passing output — the SDK suite has not passed with this change. Not a code defect, but merge should be gated on CI executing this test; a future reader inheriting a broken snapshot won't know it was never green.

Notes

• SlackCall.params.text: Parameters<SlackHelper['post']>[1] at slack-writeback.ts:11 couples the SDK's discriminated union to the surface type. Reading the union no longer tells you the accepted shapes; you have to hop to packages/surface/src/slack.ts:22. Consider a local alias or an inline expansion for readability.
• The mock-writeback re-serializer at slack-writeback.ts:51 maps parentRef → replyTo, so the same field lives under two names on either side of the transport. Fine, but a one-line comment on slackPostBody would flag that parentRef is the wire name.
• scripts/generate-helpers.mjs:35 special-cases post with a hardcoded spread signature. Comment explains why; if reply/dm grow structured payloads before the upstream types land, a second reader will have to rediscover the pattern. Consider a TODO tied to the @relayfile/relay-helpers version that will supply the types.
• packages/surface/tests/slack-block-kit.test.ts:56 asserts slackPostBody doesn't mutate its input, but the function is a shallow spread — the authored-flow test at packages/sdk/tests/authored-flow-slack.test.ts:76-79 relies on synchronous journal serialization to hold the invariant. A one-line comment near slackPostBody (slack.ts:33-43) noting that immutability is provided by journal-time JSON, not the helper, would prevent a future "just make it lazy" refactor from silently breaking the snapshot semantics.
• SlackBlock/SlackAttachment are effectively Record<string, unknown> with only type enforced. helpers/README.md documents the limit; the @ts-expect-error cases in the surface test show the useful narrow. Acceptable.

The diff is small, documented in-tree, and preserves the pass-through contract. Six months from now a reader can follow the trail README → schema JSON → generator → interface.

REVIEW_PASSED

[kjgbot]

history lens — PASS

Blockers: none. PR #352 passes the HISTORY lens.

• Previously removed behavior: Commit 86a2ec20 deliberately deferred direct bot-token transport and required supported relayfile mounts. The changes in packages/sdk/src/slack-writeback.ts:43–48,75–76 normalize structured content within the existing adapter transport. They retain the mount requirement, receipt checks, and idempotency key; they do not restore direct Slack API delivery. I found no supported connection to a deliberately removed pattern recorded in DRIVE-LOG.

• Settled RFC decisions: The new authoring types and normalization remain in the surface and SDK (packages/surface/src/slack.ts:1–43). No kernel primitive, provider dependency inside the kernel, or alternative execution record is introduced. This is consistent with decisions gate1: kernel + sdk skeletons (bootstrap relayflow output) #1 and drive: WP-13: Fix SDK test failures from sandbox environment gaps #13: provider delivery remains adapter-backed, while helper vocabulary extends the surface.

• Commit truthfulness: Commit be5bc41d says “feat(surface): Slack Block Kit typing on f.slack.post (flows: Y — rich Slack Block Kit typing on f.slack #347)” and has no body. That describes the delivered feature without claiming exclusive file scope, passing integration tests, or completed crash verification. The supporting SDK changes do not make that subject false.

Concerns: docs/evidence/spec-Y/README.md:69–106 explicitly records that daemon integration and the full SDK suite did not pass locally. Those remain verification follow-ups; the report does not disguise them as successes. I did not rerun tests for this historical review.

Notes: packages/surface/src/helpers/README.md:14–23 documents the open nested types and temporary adapter workaround. scripts/generate-helpers.mjs:35–51 implements that disclosed exception. These limitations do not establish a regression or new settled-decision contradiction. The older gate reference in ops/NEXT.md is outside this diff’s correctness scope.

REVIEW_PASSED

[kjgbot]

structure lens — MISSING

[kjgbot]

🎯 review-swarm: FAILED (M:pass H:pass S:missing)

Lens transcripts posted as sibling comments above.