Linked products
How a Madebook workspace is linked to its sibling in CodeBook or OpenBook, what a link authorizes, how CodeBook runs work under Madebook's supervision, signed callbacks and what happens when they fail — and which parts of the lifecycle have run for real.
Workspace → Settings → Linked products.
OpenBook plans the work, CodeBook executes it, and Madebook governs it. A link records that a workspace here and a workspace there are the same work. Both sides store it, and it authorizes everything else: the credential a CodeBook factory uses here, and the callbacks it receives.
Making a link
Two ways:
- On create. Creating a workspace in either product with also create in makes the sibling and records the link on both sides.
- Linking existing workspaces. From Linked products here, or from the sibling. This needs a workspace admin or an organization admin, with the role read live from Bookbag — never from anything the other product claims. Link a CodeBook workspace (or OpenBook) lists only the workspaces you administer there, as cards with a search box; see Search and pickers.
Unlinking is audited, tells the peer, revokes anything issued for the link, and ends any live sessions the link was running (as ended, reason link ended).
A link does not approve anything. A mission contract is still approved by a person in Madebook. CodeBook is still a coding client the organization must approve under Governance; it is never approved automatically.
Governed execution
A linked CodeBook asks Madebook for a credential: a token for that one workspace, acting as the person who linked it, replaced on re-issue and revoked with the link. Each CodeBook job then registers as a work session, gets its brief, reports its changes and asks for decisions exactly as an editor session does — with two additions:
- reports and decision requests carry an id, so a retry after a lost answer records nothing new;
- the job may name a callback URL, which must be under CodeBook's address as registered at Bookbag account. A personal token cannot ask for one.
The session appears on Work sessions and Live agents like any other. What CodeBook's own checks reported about the work is shown, labelled provisional; see The CodeBook governance handoff.
Signed callbacks
When a person acts here, the linked product is told: a gate decided, a fix requested, a session paused or resumed, the compliance verdict on its pull request changed, a link ended. Each message is:
- written to an outbox in the same request as the fact it describes;
- delivered with an HMAC signature over the exact body and an idempotency key naming the fact, so a receiver applies it once;
- retried with backoff for about six hours.
A delivery that gives up is failed, not dropped. It shows on the session page and on Linked products with its last error, raises an item in the attention queue (cleared on recovery), and can be retried by hand once the cause is fixed. Operators see the same across organizations on Admin → Readiness.
Messages arriving from a peer are checked the same way: the signature over the exact body, each key applied once, and a spoofed link or peer refused.
Where the addresses come from
Which sibling products exist, their API addresses, the secret all three share for signing, and Madebook's own public API address are read from Bookbag account's app registry. Nothing about a sibling is configured on the Madebook host. A platform administrator fixes an address at Bookbag account (Platform admin → Apps), and every product picks it up.
- Madebook reads the registry when it starts and every 60 seconds after. A failed read is retried after 10 seconds.
- At startup it waits at most 5 seconds for the first answer, then starts anyway. No call from a sibling is accepted until the registry has answered.
- If Bookbag account becomes unreachable later, Madebook keeps using the last answer it had. If Bookbag account lists Madebook as disabled, Madebook uses no siblings at all.
- When the shared secret is rotated at Bookbag account, the previous secret is still accepted for one hour after the rotation, so messages already on their way are not refused. Only the new secret is used for signing.
- The credential a linked CodeBook receives names the API address it is good for.
Only CodeBook, Madebook and OpenBook are read from the registry; any other app listed there is ignored.
For local development, PEER_SECRET, PEER_<APP>_URL and MADEBOOK_PUBLIC_URL on the host override the registry. A production host should have none of them set. Admin → Readiness shows where the answer came from; see Operational readiness.
What has run for real, and what has not
The four steps of the lifecycle, and how far each has been proven. Ran for real means the three actual products on one Bookbag account, talking to each other with nothing standing in. Stand-ins only means each product's own test suites against a fake of the others or of GitHub.
| # | Step | Status |
|---|---|---|
| 0 | A story written in OpenBook is sent to a CodeBook factory and becomes a card; editing the story sends a new revision to the same card. | Ran for real |
| 1 | A CodeBook worker picks up the card and appears in Madebook as a supervised session; it asks a question, a person answers here, the worker resumes and finishes. Pause, resume, a peer that goes down and catches up, and unlinking from each side were exercised too. | Ran for real |
| 2 | The worker's code becomes a pull request on GitHub; Madebook judges it and posts madebook/compliance. |
Never run for real. Covered by the compliance test suite against a GitHub stand-in sending real signed webhooks. |
| 3 | Madebook tells CodeBook the verdict changed; CodeBook passes it to OpenBook as the story's evidence, with the pull request link and the verdict. | Never run for real. Covered by CodeBook's and OpenBook's end-to-end tests against stand-ins. |
Steps 2 and 3 need an actual pull request on a repository a Madebook workspace is watching. The real run had no repository connected, so there was never a pull request to judge. The application's docs/PEER-PROTOCOL.md has the procedure for testing them yourself.