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

97 lines
5.2 KiB
Markdown

---
type: decision
tldr: 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.
status: accepted
decided_on: 2026-11-11
decided_by: Michał Kopeć
affects: .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
confidence: 0.7
quality: 0.8
last_updated: 2026-11-11
freshness_window_days: 365
retention: 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.