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.

Four categories:

  1. Real gaps — behavior the docs describe but code doesn't implement. Filed as P-items.
  2. Substrate target-state items — items the thesis says ship in v0.5 / v1 / v2 / v3. Engines landed but not yet wrapped, forward MCP bridge planned, etc.
  3. Intentional designs — code that looks like a bug or wart but is load-bearing on purpose. Don't "fix" without reading the rationale.
  4. 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.

Substrate target-state items (engines landed, wraps pending) ​

system.com and system.win32 engines on master, not yet wrapped as Matrix packages ​

The two C# bridges are landed on master at commit 937ad7d5:

  • projects/matrix-3/com-matrix-bridge/ — C# bridge for COM activation (ProgID resolution, InvokeMember marshaling, capability tokens, audit). Standalone process. ~1292 LOC.
  • projects/matrix-3/win32-matrix-bridge/ — C# bridge for Windows UI Automation via FlaUI/UIA3. NATS transport, capability tokens, action -> right gating. ~2429 LOC.

Both engines are NATS-native and gated by capability tokens, but neither is yet wrapped as a Matrix package: there is no matrix.json declaring system.com or system.win32 mounts, no lifecycle hook so the Host starts the bridge subprocess on mount, and no heartbeat reporting wired into system.devices.

  • Status: target state — ships in v0.5 (per thesis Part 8). Tracked as P1.38-com-win32-bridge-package-wrap.md.
  • Action: wrap each bridge as a Matrix package (matrix.json, lifecycle hook, heartbeat). ~3-5 days each.

mcp-hub mounted; agent-loop consumption pending ​

The reverse-direction bridge — Matrix consumes external MCP servers — is landed:

  • projects/matrix-3/packages/mcp-hub/ mounts McpHubActor at system.mcp and exposes mcp.list-servers, mcp.list-tools, mcp.call-tool, mcp.server-status, mcp.reconnect.

What is not yet wired:

  • AgentActor does not yet call mcp.list-tools on prompt setup, so external MCP tools are not yet automatically available to the in-Chat agent loop.

  • system.mcp does not yet project tool entries as virtual mounts in system.registry, so the catalog and the dashboard's mount registry don't see them.

  • Status: target state — ships in v0.5. Tracked as P1.39-mcp-hub-substrate-wiring.md.

MCP bridge forward direction (mcp-bridge) not yet shipped ​

Two MCP integration directions, distinct vocabulary:

  • mcp-hub (reverse): Matrix consumes MCP servers. Already mounted at system.mcp.
  • mcp-bridge (forward): external MCP clients consume Matrix actors as MCP tools — Cursor, Claude Desktop, Continue, Cline, Aider call into the user's HiveCast runtime. This is the v0.5 distribution wedge. Not yet shipped.

Note: system.tools.mcpBridge (in @open-matrix/agents/src/tools/McpBridgeActor.ts) is a session-scoped Matrix tool bridge used by SDK workers like Claude Code and Codex to consume Matrix tools in their own native tool format. This is internal substrate plumbing and is not the same thing as the v0.5 forward mcp-bridge package.

Multi-package runtimes ("docker-for-actors") target-state slice not yet landed ​

Today the codebase implements a simpler one-package-per-runtime shape; the thesis's docker-for-actors framing requires multi-package runtimes with declared per-package isolation (shared / process / worker / vm). The P1.40-a additive slice — manifest field, multi-package matrix up, and runtime grouping into ~4 substrate-role runtimes per Host — is filed but not yet landed.

  • Status: target state — P1.40-a slice is parallelizable with the launch hygiene track (see WORKSTREAMS/loose-ends/items/P1.40-docker-for-actors-multi-package-runtimes.md).
  • Companion items: P1.41 (manifest reconciliation matrix.service.json -> matrix.json), P1.42 (DeploymentInstance as first-class registry, two-tier identity, three naming modes), P1.43 (HTTP API reduction; bus is authority).

Hosted production policy preset enforcement gate not yet asserted at boot ​

Per the thesis Part 4.5 trust-surface doctrine, hosted production must fail to boot if policyEngine is null or the preset is dev. The four presets — dev, standard, strict, lockdown — are defined in projects/matrix-3/packages/core/src/core/security/PolicyPresets.ts. The startup-time assertion that hosted production has loaded standard, strict, or lockdown is target state for the v0 launch hygiene gate.

  • Status: target state — v0 launch hygiene gate. Tracked alongside P1.33/34/35.

hivecast.site registrable domain and PSL submission pending ​

A separate registrable domain (hivecast.site is the planned target) is needed as an origin boundary from matrix.hivecast.ai for sandboxed user/package/generated content. Public Suffix List (PSL) submission becomes load-bearing when HiveCast issues sibling user-content subdomains that must be isolated from each other.

  • Status: target state. The domain and PSL submission do not need to land for v0/v0.5 features (no custom-JS generated artifacts, runtime-served web tunnels, or user/package UI surfaces ship in those phases). They become load-bearing for v3 (third-party Matrix-enabled pages). The PSL submission has not been done; do not claim it has.

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 ​