stack/docs/plans/2026-09-20_discord-setspark-client.md

# Discord Sage: SetSpark record client (#1509, QUEUE row 25)

Jason's decision, 2026-09-18, relayed by the SetSpark record-system
coordinator (thread 8543de4b, confirmed by Jason as acting on his
authority): record authority moves from the shared-signals Git vault to
NocoDB (structured records) plus Outline (prose), behind one write
service, `setspark-api` at api.setspark.io. Plan v3.2 is committed on
shared-signals main as 55b2515. Jason gave the go for phase 3 on
2026-09-20. The row 24 git verbs stay live until cutover; the vault then
becomes a read-only mirror.

## 1. Outcome

A record decided in Discord is created or updated in SetSpark by Sage in
the same conversation, through fixed verbs against setspark-api, with
the request, the idempotency key, the returned revision and any refusal
in the turn record. A proposal that needs founder approval is posted by
the connector as a message with an Approve button; the approval is the
button or an exact `approve` reply from a required approver, verified by
the connector, never asserted by the model. Sage holds no NocoDB or
Outline token; the seat's API key is the only credential.

## 2. What is built

Two parts. The first does not depend on the API contract and is built
first; the second waits for `stack/api/README.md` and
`stack/api/openapi.json` on shared-signals main.

### 2a. Connector side (contract-independent)

- `packages/discord/src/setspark.mjs`: the `setspark` key of the tools
  config (`baseUrl`, `keyFile`, `principal`), validated at load like a git
  key: https base url with no path, query, user or password; key file
  absolute, regular, not a symlink, mode 0600, non-empty. The key is read
  from the file on every call, never cached, never printed or journaled.
  One HTTP core: JSON body, `Authorization: Bearer`, fixed User-Agent,
  timeout, response capped, no redirects. The error body (`code`,
  `message`, and on 409 `current_revision` and `changed_fields`) becomes
  a refusal rendered from `code` and the fixed fields only; free text
  from the server is data, cut at a cap. The idempotency key is
  `<principal>:<turn id>:<call index>` where the turn id is the Discord
  message id from the envelope and the call index is the tool set's call
  counter for that turn.
- `packages/discord/src/approvals.mjs`: the connector's approval ledger,
  `approvals.jsonl` under the binding's journal directory, appended only:
  `opened` (request id, decision id, proposal version, digest, required
  approver ids, the posted message id and channel), `bind` and `approval`
  (request id, author id, event id, message id, how: button or reply),
  each as intent before the service call and done, refused or unknown
  after it; `start` retries the unknown ones under their original keys.
  Resolution:
  a reply whose referenced message is an open request and whose content
  is exactly `approve` after trimming, or a button interaction whose
  custom id names the request and whose message id matches. The author
  must be in the request's required approvers; anyone else gets one fixed
  line and a `drop` entry. A second approval by the same author is
  ignored with a drop entry.
- `packages/discord/src/rest.mjs`: `createMessage` accepts `components`
  (one Approve button); `interactionCallback` answers a component
  interaction within Discord's three-second window;
  `editInteractionMessage` edits the request message afterwards.
- `packages/discord/src/connector.mjs`: `INTERACTION_CREATE` joins the
  dispatch switch; a reply message that resolves to an open request is
  handled as an approval before the normal admission path, so it never
  starts a model turn. After a turn whose tool calls include
  `open_approval_request`, the connector posts the request message with
  the fixed rendering (decision id, version, digest, who may approve,
  how) and the button, records `opened`, and binds the message id to the
  request through the API.
- The API client used by the connector for `bind` and `add_approval` is
  passed in like `rest`, so the offline suite drives it with a fake.

### 2b. Model-side verbs (built 2026-09-20 against a5425a2)

Contract: shared-signals `stack/api/openapi.json` and `stack/api/README.md`
at a5425a2. Fixed verbs registered in the extension, each one HTTP call:
`record_list`, `record_get`, `record_create`, `record_update`,
`resolve_id`, `open_approval_request`, `get_approval_request`,
`create_document`. `add_approval` and `bind_approval_message` are the
connector's, not the model's; `get_counters` is left out; the contract
has no prose search or document read, so `search_prose` and
`get_document` from the plan are not built. Paths, bodies and codes come
from the contract. Arguments are checked in the client before any request
(record type from the five, `AA-1` ids, lower snake case property names,
size caps); a write outside a turn is refused. `record_update` carries
the revision from `record_get`; 409 renders the current revision and the
changed fields. Writes send `context` (turn id, requester id and name,
client version), audit only. Output caps: a record at 6000 characters, a
property value at 500, a list at 50 items.

The extension now reads the author id and the message id from the
envelope as well as the requester, and the tool set keeps them as the
turn (`setTurn`); the write key is `<principal>:<message id>:<call
index>` with the index counting every call in the turn.

Evidence per approval (coordinator's ruling, 2026-09-20): the service's
`source_url` is one Discord message url unique to the approver and the
export validator rejects a shared url or a fragment. A reply is its own
evidence. For a button press the connector first posts a confirmation
line in the request's channel and submits its url and exact text as
`source_url` and `statement`, with `message_id` and `bound_message_id`
both the request message; if the post fails nothing is submitted and the
approver is told to press again. The ledger keeps the evidence id and
statement so a retry on start submits the same evidence.

### 2c. Why the connector posts the approval message

The model's tool call runs mid-turn, before the connector delivers the
reply, so no message id exists yet for `open_approval_request` to carry.
The verb therefore creates the request without a message; the connector
posts the message after the turn and binds its id to the request. That
needs three server operations the plan's prose folds into one: open the
request (model, returns request id and required approvers), bind a
message id and channel to it (connector), add an approval (connector,
with request id, author id, message id and the bound message id). Sent
to the coordinator on 2026-09-20 and adopted the same day:
`open_approval_request`, `bind_approval_message`, `add_approval` (codes
not_open, not_approver, already_approved, message_mismatch,
request_stale) and `get_approval_request` for reconciliation.

## 3. Not built

No NocoDB or Outline token in Sage. No delete verb. No prose update or
append. No free-form HTTP: the base url and every path are fixed. No
approval by the model's word. No approval from an author outside the
request's required approvers. No key on a command line or in any journal.

## 4. Evidence

- `packages/discord/tests/setspark.test.mjs`: config validation (bad
  url, http, path in url, key file mode, missing), key read per call
  through a fake server (rotation between two calls works without
  restart), idempotency key shape, 409 and 422 rendering, cap on server
  text, timeout, no key in any journal or output.
- `packages/discord/tests/approvals.test.mjs` (8 tests): request
  validation and rendering (names, never ids), ledger append and fold,
  reply resolution (exact `approve`, wrong text, wrong message, wrong
  author, second approval, one in flight), button resolution (wrong
  message, wrong custom id, wrong author), connector flow with fake rest
  and fake api: message posted with the button, `opened` and `bind`
  recorded, one approver by reply and one by button, message edited and
  button disabled, fixed lines and drop entries for a non-approver, a
  repeat and a foreign custom id, a service refusal retried, an invalid
  request and a refused post recorded and nothing bound, no api client,
  `start` retrying an unknown bind and approval under the original keys.
- Part 2a on 2026-09-20: node tests 157 pass, `scripts/test-discord.sh`
  62 passed, unslop clean.
- Part 2b on 2026-09-20 (`/tmp/suites/discord-2b.log`): node tests 162
  pass, suite 63 passed. New: `tests/setspark.test.mjs` verbs through
  the tool set against a local server playing the contract (keys per
  call index, `context` on writes, no key on reads, 409 rendering, list
  query string, request view rendering, no api key in any result), no
  turn refuses every write before a request, twelve bad-argument cases
  refuse before a request, `renderRecord` caps; the connector client
  (integer request ids, bind and approval bodies, button and reply
  kinds, a 404 as a refusal); `tests/approvals.test.mjs` asserts the
  confirmation line, its url and text on the button call, the reply's
  own url and text, and the retry with the ledger's evidence;
  `tests/context.test.mjs` the SetSpark paragraph without the base url;
  the suite's real-pi probe with a setspark key lists the reads and the
  eight verbs and never shows the key.
- Review by rev-code-02 on #1509 (D7), local commit after approval.
- Live: Jason asks Sage in #sage-admin to create one work item; the
  API shows it with revision 1; the turn record shows the verb, key and
  revision. Then a proposal; the button approves it; the audit row
  carries Sage's key id and Jason's Discord id separately.

## 5. Boundaries

Push only on Jason's word. The binding's `setspark` key is fixed (stop
and start). The seat's API key file is written by the infrastructure
seat, never by this session. Cutover of record authority is a separate
row.