Docs Portal

Appearance

Known gaps, quirks, and design decisions ​

This page is the cross-package register of things future readers should know before they trust their assumptions about the system. Every item here was surfaced while writing the source-grounded docs in this portal — sub-agents read the actual code and flagged divergences, footguns, or load-bearing design choices.

Three categories:

  1. Real gaps — behavior the docs describe but code doesn't implement. Filed as P-items.
  2. Intentional designs — code that looks like a bug or wart but is load-bearing on purpose. Don't "fix" without reading the rationale.
  3. Doc and spec hygiene — labels and references that have drifted from code reality. Janitorial.

Real gaps (file or close) ​

system-factotum ships only dist/, no src/ ​

projects/matrix-3/packages/system-factotum/ contains a built dist/index.js but no source directory. Factotum is the one actor (per CLAUDE.md Rule 4) that reads/writes credential files. Iteration on factotum is currently impossible without recovering the source from another repo or git history.

  • Risk: high. Credential code must be source-tracked before launch.
  • Action: trace where the source lived, restore to repo, or rewrite from scratch.
  • Filed: not yet filed in WORKSTREAMS/loose-ends/INDEX.md — needs a P-item.

No rollback subcommand for package updates ​

hivecast has up / down / update. There is no rollback. After a bad release the operational path is "manually reinstall the prior version." That's not a roll-out story; that's an outage tool.

  • Risk: high at scale. Rollback is critical for safe deployment.
  • Action: implement hivecast rollback <package> [--to <version>] or matrix rollback ....
  • Filed: referenced in docs-package-lifecycle/running/rollback.md, but not yet a discrete P-item.

$prompt is sealed silently ​

MatrixActor.on$prompt is sealed against subclass overrides — if a package author writes their own on$prompt, the framework's dispatcher silently drops it without warning. Worst kind of footgun: no error, no log, just nothing happens.

  • Risk: medium. SDK users will lose hours debugging this once.
  • Action: throw at class-init time when a subclass declares on$prompt, or change the seal to allow a documented override path.
  • Source: projects/matrix-3/packages/core/src/core/MatrixActor.ts
  • Filed: not yet filed.

Asset relay capped at 10 MB, no ETag / Last-Modified ​

system-gateway-http has MAX_RELAY_BODY_BYTES = 10 * 1024 * 1024 hard-coded. Larger assets fail with 502. The relay also sends cache-control: no-cache on every response with no ETag or Last-Modified header — every request is a miss.

  • Risk: medium. Real CDN/perf cost at launch traffic.
  • Action: make cap configurable; add ETag (content-hash) + Last-Modified.
  • Source: projects/matrix-3/packages/system-gateway-http/src/
  • Filed: not yet filed — likely P1.

No hivecast rotate-credentials CLI ​

The cloud op auth.hostLink.credentials.refresh exists and rotates both NATS user JWT and heartbeat token. There is no CLI wrapper. Operators rotate credentials today by hivecast logout --local-only followed by hivecast login --device.

  • Risk: medium. Re-pair workflow loses session state and is jarring; a real rotate-credentials is a cleaner ops story.
  • Action: add hivecast rotate-credentials that wraps the existing op.
  • Source: projects/matrix-3/packages/system-auth/src/host-auth.ts
  • Filed: not yet filed.

Plan 9 system commands in spec but not in code ​

WORKSTREAMS/core-and-packaging/ACTOR-COMMUNICATION-CONTRACT.md lists $ctl, $status, $children, $ns, $env, $health as universal system commands. The live SYSTEM_COMMANDS array in MatrixActor.ts:111 does not include them — only $introspect, $prompt, $activity are implemented.

  • Risk: low. Aspirational spec.
  • Action: either implement, or remove from the contract spec.
  • Source: projects/matrix-3/packages/core/src/core/MatrixActor.ts:111
  • Filed: not yet filed — owner of ACTOR-COMMUNICATION-CONTRACT.md decides direction.

Intentional designs worth knowing ​

NATS deliberately avoids _INBOX.* reply subjects ​

The NATS adapter does NOT use NATS's standard _INBOX.* reply-subject pattern. It uses subjects under the actor's authority root for replies. The code comment cites: "breaks ACL enforcement." Using _INBOX.* would let any subscriber receive replies regardless of topic claims.

mx run and mx up share the same implementation ​

projects/matrix-3/packages/mx-cli/src/commands/run.ts is the body for both mx run and mx up. They are aliases. This is intentional — up is the operational verb, run is the developer verb, but they do the same supervised-runtime work.

Caddy /nats-ws bypasses the gateway in production ​

Two paths reach NATS WebSocket:

  • Production: Caddyfile.bare proxies /nats-ws directly to NATS WS port 4223. The gateway never sees the request.
  • Local mode: system-gateway-http has an internal /nats-ws upgrade handler as a fallback.

Both work. If you're debugging "why does WS work on prod but not in dev" or vice versa, the answer is which path is active.

Smithers' CodingAgent imports @open-matrix/inference-catalog directly ​

SmithersSupervisor orchestrates through agencyInvoke for propose / evaluate sessions. But CodingAgent (in coding-agent/CodingAgent.ts) also imports @open-matrix/inference-catalog directly for some cognitive steps, bypassing the agency layer.

Doc and spec hygiene ​

system.devices actor lives in @open-matrix/system, not a system-devices package ​

There is no @open-matrix/system-devices package. SystemDevicesActor is implemented inside @open-matrix/system at projects/matrix-3/packages/system/src/SystemDevicesActor.ts. References to a separate package are wrong.

  • Action: treat system.devices as an actor mounted by the system package, not as a separate package. Naming convention only — no code change needed unless we adopt a "one actor = one package" policy.

Request timeout is 5000 ms, not 3000 ms ​

The default MatrixActor request timeout is 5000 ms (projects/matrix-3/packages/core/src/core/RequestReply.ts:263). Auto-memory and informal references say 3000 ms — folklore is wrong; code is right.

  • Action: correct any internal docs that cite 3000 ms.

realm→root rename incomplete in JSDoc ​

The realm → root rename happened in identifiers and types across the repo. 60+ JSDoc @deprecated tags still reference the old realm name. Migration 1 in docs-sdk → Reference → Migration guides covers this.

  • Action: janitorial cleanup pass to remove @deprecated realm: ... tags now that nothing uses them.

"Gitea-backed publication" vs "npm-compatible publication" are the same code path ​

Both phrases describe the same mx-cli publish flow. The portal TOC originally listed them as separate pages, which made it look like there were two implementations. There aren't.

  • Action: either consolidate the docs entries, or be explicit that they're two labels for one mechanism (current state in the docs).

Items NOT in this list ​

The following are NOT framework gaps — they were misframings the portal authoring caught:

  • FlowPad's "boards / cards / links" vs the actual Flow DSL pipeline editor. The boards/cards/links framing was a TOC fabrication during scaffolding (not present in code, not in any spec). The agent caught it and corrected the TOC. Code is right; the original TOC scaffold was wrong.

Process: how this list was built ​

Every item here came from a sub-agent reading actual source while authoring its docs package. Rules each agent followed:

  1. Present state from code.
  2. Target state explicitly marked when planned.
  3. Never fantasy.

When code-vs-spec or code-vs-folklore divergence appeared, the agent recorded it. This page rolls those reports up.

The list is not exhaustive — it's the set of items that surfaced naturally during a one-pass authoring sweep. Future passes will find more. Adding to this page is encouraged.

See also ​