Decisions

Part of the demarkus-soul hub. Architecture decision records for the core project, canonical here since 2026-09-28; docs/adr/ in git is a frozen archive of 0001 to 0027 (see where decisions live). Sub-project decisions live in their own series, for example /demarkus-library/adr/. Status and dates live in each ADR.

• ADR 0001: broker confidential web-client registry

• ADR 0002: align store frontmatter with the Open Knowledge Format

• ADR 0003: default OKF type on publish

• ADR 0004: edge semantics, provenance on every edge, typed relations via rel- metadata

• ADR 0005: node identity omits the default port

• ADR 0006: the Postgres backend is an optional build, not a dependency; superseded by ADR 0010

• ADR 0007: SNI selects and pins one virtual Mark server per QUIC connection

• ADR 0008: GCS world state commits through one root CAS

• ADR 0009: AGPL for the core, MIT for plugins and satellites

• ADR 0010: remove the Postgres backend; the knowledge server owns shared multi-writer state

• ADR 0011: allowlisted private-use scheme redirects for MCP hosts, unblocking Cursor's MCP OAuth against the broker

• ADR 0012: body match is an optional mode of LOOKUP; recall specified, ranking left to the implementation

• ADR 0013: source revisions, extraction views, graph freshness and generated-format compatibility

• ADR 0014: the protocol module is wire and stored format only

• ADR 0015: the backend contract takes a context per call and reads through views

• ADR 0016: the publish policy is enforced above the store, inside its commit

• ADR 0017: archive preconditions, closed views, and seeding above the store

• ADR 0018: one mark URL parser, and host case is not identity

• ADR 0019: tool bodies and the write contract live in shared packages

• ADR 0020: one reconcile owner in docwrite, and write tools check arguments before authorization

• ADR 0021: a world registry that announces drops, DNS label world names, one tenant door for tools and resources

• ADR 0022: the MCP gateway takes its dependencies from Run, not the Server; NewServer takes a deps struct

• ADR 0023: the broker is core, oauthsrv, gateway and storage behind one Run, with brokertest for shared fixtures

• ADR 0024: the plugin binary is provision and registry package families by concern, and a harness is a host.Host value

• ADR 0025: WATCH is the eighth verb, the store emits hints only, and protocol 1.0 freezes after WATCH and ALPN mark/1

• ADR 0026: a client SDK under MIT with its own semver, CC0 wire fixtures, the server never imports it, exact relicensed file list

• ADR 0027: world token files are optional at open and split into a broker-owned runtime file and an operator-owned static file; the chart's bootstrap Job becomes optional for GitOps

• ADR 0028: every store owns a durable change epoch and sequence behind backend.ChangeSource, proven by one conformance suite; the file store keeps a journal

• ADR 0029: the broker issues the federation agent's hub token from agentTokens, with a broker record as the ownership marker; the umbrella drops the bootstrap Job (proposed)

• ADR 0030: the broker generates and persists its state cookie key, so the chart render is deterministic under Argo CD (proposed)

• ADR 0031: the bucket store seals receipts into change blocks outside the commit, and the hub reads them as a cached backlog, so a knowledge cursor resumes across a restart up to the ring

• ADR 0032: the knowledge and memory brokers run inside the knowledge server process as two gateways on one mux; in-process dispatch, no write token handoff, WATCH fan-out on the hub, resource bound tokens (proposed)