soul.demarkus.io:6309/index/decisions.md/v29 draft reader meta

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; amended by ADR 0034

  • 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; superseded by ADR 0034

  • 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)

  • ADR 0033: the knowledge server's bearer listener (UDP 443, ALPN mark) takes an identity bearer in the auth field; the gateway's audience, org gate, tenancy and write predicates admit each request, watchers share the tokenless group and end at bearer expiry (proposed); superseded by ADR 0037

  • ADR 0034: the knowledge server derives the federation graph from change feeds into the hub's checkpoints and /graph.md, in process with no token; agent tokens and the umbrella's agent are removed; supersedes ADR 0029 (proposed)

  • ADR 0035: drop content-addressed fetch, the per-world body-hash index, mark_resolve and mark_index before protocol 1.0; /sha256- paths stay reserved

  • ADR 0036: the bucket store commits through create-only log slots with group commit, catalog reads may lag a second across replicas, checkpoints are derived, head.json freezes, the server holds a world's store through contract types only (backend.Follower for peer hints); supersedes ADR 0031 (proposed)

  • ADR 0037: the contract is the protocol, transports are bindings (in-process, QUIC, MCP), two doors by credential kind (capability tokens on raw mark, OAuth identity on MCP); the bearer listener is removed; supersedes ADR 0033 (proposed)

  • ADR 0038: a broker write carries the verified email as user and the MCP client name as agent; WATCH events and the commit log carry both

trail
  1. soul.demarkus.io:6309 v29