ckb/docs/decisions/0018-share-mailbox-module.md
Michał Kopeć 8dc3445b27 Template 1.28.0: share module — mailboxes in a git channel (D-0018)
New opt-in `share` module with skill `ckb-share` and stdlib `share.py`
(join/send/unshare/list/receive/status). KBs exchange documents through a
git channel with one append-only mailbox per KB; sends are packed
self-contained, secret-scanned and confirmed; received documents land in
raw/inbox/ (untrusted), retractions in raw/retractions/; the git author
must own the mailbox. dedup_inbox.py reports SAME SHARE; ckb-ingest and
ckb-retract know share files. Smoke test covers two KBs end to end.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 13:31:51 +01:00

5.2 KiB

type tldr status decided_on decided_by affects confidence quality last_updated freshness_window_days retention
decision KBs exchange documents through an opt-in `share` module — a git channel per trust group with one append-only mailbox per KB; sends are packed self-contained, secret-scanned and confirmed; receives land in raw/inbox/ (untrusted) or raw/retractions/; the git author must own the mailbox; handled messages are recorded in a ledger in ckb.yaml. accepted 2026-11-11 Michał Kopeć .agents/modules/share/, .agents/skills/ckb-ingest/SKILL.md, .agents/skills/ckb-ingest/scripts/dedup_inbox.py, .agents/skills/ckb-retract/SKILL.md, tests/smoke.sh, README.md, docs/MANUAL.md 0.7 0.8 2026-11-11 365 high

D-0018 — A share module: mailboxes in a git channel

Status: Accepted · Decided: 2026-11-11 · Deciders: Michał Kopeć

Context

One KB often holds something another KB needs: a summary, a decision, an answer. Until now the options were linked/, which mounts a whole KB and needs local filesystem access, and the mcp module's add_to_inbox, which needs the receiver to run a server. A team wanted to prepare a document in one KB and drop it where another KB can pick it up, using only git.

Decision

  1. An opt-in module (D-0001 pattern), share, with one skill, ckb-share, and one stdlib script, share.py. Most KBs never send anything, so the base pays no context for it.
  2. The channel is a separate git repo per trust group, with CHANNEL.md, members.yaml (KB name → owner emails) and mail/<kb>/. Each KB writes only to its own mailbox and never edits or deletes a file there, so merge conflicts cannot happen. A new version or a retraction is a new file. The channel is cloned into tmp/share/<channel>/, and creating the repo stays manual.
  3. Messages carry an envelope: type: share, kind (document/retraction), a stable share_id (<kb>/<slug>), version, from, to (names or *), sent_by, sent_on, untrusted: true.
  4. Send packs a self-contained copy. <private> spans and ## Notes are dropped. Local links become text. Sources and Crux paths are marked <kb>:, so the receiver's lint treats them as not checkable rather than broken. Only outputs/documents/, outputs/answers/ and wiki/ pages can be sent; raw/archive/ needs an extra yes. Lint's secret patterns block the send. A dry run shows the ABOUT.md sensitivity section, and the user confirms every send.
  5. Receive never touches wiki/. Documents go to raw/inbox/, with submitted_by set to the git author who added the message, so ckb-retract's owner check works unchanged. A newer version points at the earlier one with supersedes_source, and ingest treats it as supersession. A retraction becomes one raw/retractions/ request per held version.
  6. The sender is checked on receive. The git author who added a message must be an owner of its mailbox in members.yaml. If not, the message is UNVERIFIED and is taken only when the user insists. Git cannot enforce per-folder writes; a git host's path protection can, and that is documented as optional hardening.
  7. What was handled is a ledger, not derived from files. The plan was to derive "already taken" from raw/inbox/ and raw/archive/, but ckb-retract deletes the archived file, so a retracted document would be offered again. The received: list in the share: block of ckb.yaml records every message taken, declined, filed or seen. The script owns the whole block.

The plan's open questions were settled on their recommended answers: notes are dropped by default (--keep-notes to send them); documents, answers and wiki pages can be sent, raw sources only with a yes; declines live in committed ckb.yaml; a routine only reports what is waiting; channels are created by hand.

Alternatives considered

  • Sync one folder with a submodule or subtree. Pinned commits, a detached HEAD and history mixed into the KB. Rejected for a separate clone in tmp/.
  • One shared folder all KBs write to, deleting what they take. Conflicts between writers, and one receiver's delete hides the file from the others.
  • linked/ to a shared KB. Better for knowledge everyone keeps reading. Still available, but it doesn't fit handing one document over.
  • mcp add_to_inbox. Needs a running server at the receiver. Still the right tool when one exists.
  • Read receipts written back to the channel. Deferred: the receiver would write outside its own mailbox, or into it, which mixes roles.

Consequences

  • Sent material stays in the channel's git history. Unsharing makes receivers unwind it, but it doesn't unpublish.
  • ckb.yaml grows by one line per message received. That is acceptable for years of use, and the ledger can be trimmed by hand once its messages are gone from the channel.
  • The Hub plan's git push transport (raw/outbox/ to an inbound branch) can adopt this envelope instead of inventing its own.
  • Not done in this release: a lint check for type: share files, a share: N waiting line at session start, eval cases (a channel needs a git remote, which the eval fixtures don't provide yet), and a PowerShell check.