docs(readme): add public README by MSD21091969 · Pull Request #32 · Collider-Data-Systems/moos-kernel

MSD21091969 · 2026-04-25T12:58:55Z

Summary

First public-facing README for moos-kernel. Frames the project as a semantic functorial network over distributed compute; documents the four primitive rewrites (ADD/LINK/MUTATE/UNLINK), layer discipline (graph → fold → kernel), runtime gates (§M11 + §M12), and federation shape via the WF16 router.

"What it is" — substrate framing, session as centerpiece, F⊣G adjunction
"What''s in the box" — package map (graph/fold/operad/kernel/reactive/transport/hdc/mcp)
Running + key flags
Testing
Runtime gates summary
Ontology pointer (v3.13.0, 52 node types, WFs WF01–WF21)
Federation
Status entry: round-11 closed (T=174 ~24:00 CEST), round-12 active (T=175) with five v3.14 grammar_fragment proposals
Companion repos cross-link

Test plan

README renders correctly on the GitHub repo landing page
Topic chips visible (categorical, hypergraph, knowledge-graph, golang, etc. — set on this PR''s commit window)
No code changes; CI not affected

🤖 Generated with Claude Code

First public README for moos-kernel. Frames the project as a semantic functorial network over distributed compute, documents the four primitive rewrites, layer discipline, runtime gates (§M11 + §M12), and federation shape. Status entry cites round-11 close + round-12 active scope. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Copilot

Pull request overview

Adds an initial public-facing README.md for moos-kernel, describing the project’s conceptual model (hypergraph + rewrite log), package/layer structure, runtime gates, and basic operational usage.

Changes:

Introduces a public README with project framing and core rewrite primitives (ADD/LINK/MUTATE/UNLINK).
Documents package map / layer discipline (graph → fold → kernel) and runtime gates (§M11/§M12).
Adds run/test instructions, ontology/federation notes, and a status/roadmap section.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-25T13:01:53Z

+
+## Status
+
+Round-11 closed (T=174 ~24:00 CEST). Round-12 active (T=175): five v3.14 grammar_fragment proposals expanding the ontology with `derivation` (reify session inference), `clock` (generalized time fabric — `t_hook` becomes a special case), WF21 `causes/caused-by` (causation distinct from succession), `substrate` property (where node-truth lives), and leaf-firing-state semantics.


“Round-11 closed (T=174 ~24:00 CEST)” uses 24:00, which is easy to misread/parse (many systems treat it as invalid). Consider using 00:00 with an explicit date rollover (or omit the wall-clock time) to keep the status note unambiguous.

Suggested change

Round-11 closed (T=174 ~24:00 CEST). Round-12 active (T=175): five v3.14 grammar_fragment proposals expanding the ontology with `derivation` (reify session inference), `clock` (generalized time fabric — `t_hook` becomes a special case), WF21 `causes/caused-by` (causation distinct from succession), `substrate` property (where node-truth lives), and leaf-firing-state semantics.

Round-11 closed (T=174 ~00:00 CEST next day). Round-12 active (T=175): five v3.14 grammar_fragment proposals expanding the ontology with `derivation` (reify session inference), `clock` (generalized time fabric — `t_hook` becomes a special case), WF21 `causes/caused-by` (causation distinct from succession), `substrate` property (where node-truth lives), and leaf-firing-state semantics.

Copilot · 2026-04-25T13:01:53Z

+
+| Flag | Default | Purpose |
+|---|---|---|
+| `--ontology` | (none) | path to `ontology.json`; without it, type validation + liveness/admin gates bypass |


The --ontology flag note says that without it “type validation + liveness/admin gates bypass”, but the current startup path always passes a non-nil registry to the runtime (operad.LoadRegistry("") returns EmptyRegistry()), so §M11/§M12 checks still run (they only bypass when rt.registry == nil). Please update this description to match the actual behavior (e.g., only type validation is disabled, or adjust runtime wiring if the intent is to disable gates too).

Suggested change

| `--ontology` | (none) | path to `ontology.json`; without it, type validation + liveness/admin gates bypass |

| `--ontology` | (none) | path to `ontology.json`; without it, ontology-backed type validation is disabled, but liveness/admin gates still run with the default empty registry |

Copilot · 2026-04-25T13:01:53Z

+| `--sweep-interval` | `30s` | t-hook sweep cadence (0 disables) |
+| `--quic-addr` | (none) | UDP/HTTP3 listener (requires `--tls-cert` + `--tls-key`) |
+
+Stdlib-only except `quic-go` (gated behind `--quic-addr`).


The README says “Stdlib-only except quic-go”, but go.mod also brings in non-stdlib transitive deps (e.g. golang.org/x/net, x/crypto, etc.). Consider rewording to clarify this is about direct deps only, to avoid misleading readers.

Suggested change

Stdlib-only except `quic-go` (gated behind `--quic-addr`).

Direct dependencies are stdlib-only except `quic-go` (gated behind `--quic-addr`).

Copilot · 2026-04-25T13:01:53Z

+| `internal/operad` | type system | `Registry` (ontology v3.13.0: 52 node types, 21 WFs WF01–WF21), strict port-pair `ValidateLINK`, `ValidateMUTATE`, occupancy resolution, admin-capability walks. |
+| `internal/kernel` | effect layer | `Runtime`, `Store`, `LogStore`/`MemStore`. §M11 session-liveness + §M12 admin-capability gates. Sweep loop emits WF13 governance proposals on `t_hook.firing_state` transitions. |
+| `internal/reactive` | predicate evaluator | Watch / React / Guard engine; `EvaluateThookPredicate` covers 10+ §M14 predicate kinds. |
+| `internal/transport` | HTTP + SSE | `/state`, `/log`, `/rewrites`, `/programs`, `/operad`, `/hdc`, `/t-hook/evaluate`, `/t-cone`, `/twin/ingest`, `/fold` (with SSE), `/healthz`. |


The transport endpoint list is a bit misleading: the server doesn’t expose a GET /state, GET /operad, or GET /hdc root handler (it exposes /state/nodes, /state/relations, /operad/node-types, /hdc/..., etc.). Suggest updating the list to either include the concrete paths or make it explicit these are path prefixes.

Suggested change

| `internal/transport` | HTTP + SSE | `/state`, `/log`, `/rewrites`, `/programs`, `/operad`, `/hdc`, `/t-hook/evaluate`, `/t-cone`, `/twin/ingest`, `/fold` (with SSE), `/healthz`. |

| `internal/transport` | HTTP + SSE | `/state/*` (e.g. `/state/nodes`, `/state/relations`), `/log`, `/rewrites`, `/programs`, `/operad/*` (e.g. `/operad/node-types`), `/hdc/*`, `/t-hook/evaluate`, `/t-cone`, `/twin/ingest`, `/fold` (with SSE), `/healthz`. |

Copilot · 2026-04-25T13:01:54Z

+|---|---|---|
+| `internal/graph` | pure types | `Node`, `Relation`, `Property`, `Rewrite`, `Envelope`, `GraphState` (with indexes), `URN`, `Stratum`, `RewriteCategory`. No IO. |
+| `internal/fold` | pure catamorphism | `Evaluate`, `Replay`, `EvaluateProgram`. Maintains state indexes on ADD/LINK/UNLINK. |
+| `internal/operad` | type system | `Registry` (ontology v3.13.0: 52 node types, 21 WFs WF01–WF21), strict port-pair `ValidateLINK`, `ValidateMUTATE`, occupancy resolution, admin-capability walks. |


The README states the ontology has “WF01–WF21” and later mentions WF20/WF21, but this repo’s internal/graph currently defines typed RewriteCategory constants only through WF19. If WF20/21 are planned/ontology-only, consider rephrasing to avoid implying they’re already represented as typed constants in the code.

Suggested change

| `internal/operad` | type system | `Registry` (ontology v3.13.0: 52 node types, 21 WFs WF01–WF21), strict port-pair `ValidateLINK`, `ValidateMUTATE`, occupancy resolution, admin-capability walks. |

| `internal/operad` | type system | `Registry` (ontology v3.13.0: 52 node types, 21 WFs WF01–WF21; current typed `RewriteCategory` constants in `internal/graph` run through WF19), strict port-pair `ValidateLINK`, `ValidateMUTATE`, occupancy resolution, admin-capability walks. |

Five fixes per Copilot review: 1. WF range: clarify WF01-WF20 promoted, WF21 proposed in v3.14 candidate set; typed RewriteCategory constants run through WF19 in graph package. 2. Transport paths: change /state to /state/* (and similar) to match the actual handler paths. 3. --ontology flag: correct the description — gates still run with the default empty registry; only ontology-backed type validation disables. 4. Stdlib statement: clarify direct deps are stdlib-only except quic-go; acknowledge transitive deps via quic-go. 5. T=174 ~24:00 CEST: replace ambiguous wall-clock notation with a date- relative description. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

MSD21091969 · 2026-04-25T13:38:02Z

Thanks @copilot — five real catches. Pushed ffddc59 applying all five:

WF range — clarified WF01–WF20 are promoted in v3.13.0; WF21 is in the v3.14 candidate set; typed RewriteCategory constants in internal/graph currently run through WF19. The "WF01–WF21" framing was forward-looking; the README now distinguishes ontology-level from typed-constant-level.
Transport paths — changed /state → /state/* and similar so the prefixes don''t imply a single-handler root.
--ontology flag — corrected the description: ontology-backed type validation disables when omitted, but §M11 + §M12 gates still run via the default empty registry. Verified against cmd/moos startup wiring.
stdlib statement — clarified "direct dependencies are stdlib-only except quic-go"; acknowledged transitive deps via quic-go (golang.org/x/net, x/crypto).
T=174 ~24:00 CEST — replaced with "at T=174 (April 24, 2026, just past midnight CEST)" — explicit date-relative description, no ambiguous wall-clock.

PR ready for human review.

Copilot AI review requested due to automatic review settings April 25, 2026 12:58

Copilot started reviewing on behalf of MSD21091969 April 25, 2026 12:59 View session

Copilot AI reviewed Apr 25, 2026

View reviewed changes

Copilot started work on behalf of MSD21091969 April 25, 2026 13:38 View session

Copilot finished work on behalf of MSD21091969 April 25, 2026 13:39

MSD21091969 merged commit e295016 into master Apr 25, 2026
1 check passed

MSD21091969 deleted the docs/round-12-readme branch April 25, 2026 13:46

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(readme): add public README#32

docs(readme): add public README#32
MSD21091969 merged 2 commits intomasterfrom
docs/round-12-readme

MSD21091969 commented Apr 25, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 25, 2026

Uh oh!

Copilot AI Apr 25, 2026

Uh oh!

Copilot AI Apr 25, 2026

Uh oh!

Copilot AI Apr 25, 2026

Uh oh!

Copilot AI Apr 25, 2026

Uh oh!

MSD21091969 commented Apr 25, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		## Status

		Round-11 closed (T=174 ~24:00 CEST). Round-12 active (T=175): five v3.14 grammar_fragment proposals expanding the ontology with `derivation` (reify session inference), `clock` (generalized time fabric — `t_hook` becomes a special case), WF21 `causes/caused-by` (causation distinct from succession), `substrate` property (where node-truth lives), and leaf-firing-state semantics.

	Round-11 closed (T=174 ~24:00 CEST). Round-12 active (T=175): five v3.14 grammar_fragment proposals expanding the ontology with `derivation` (reify session inference), `clock` (generalized time fabric — `t_hook` becomes a special case), WF21 `causes/caused-by` (causation distinct from succession), `substrate` property (where node-truth lives), and leaf-firing-state semantics.
	Round-11 closed (T=174 ~00:00 CEST next day). Round-12 active (T=175): five v3.14 grammar_fragment proposals expanding the ontology with `derivation` (reify session inference), `clock` (generalized time fabric — `t_hook` becomes a special case), WF21 `causes/caused-by` (causation distinct from succession), `substrate` property (where node-truth lives), and leaf-firing-state semantics.

	\| `--ontology` \| (none) \| path to `ontology.json`; without it, type validation + liveness/admin gates bypass \|
	\| `--ontology` \| (none) \| path to `ontology.json`; without it, ontology-backed type validation is disabled, but liveness/admin gates still run with the default empty registry \|

	Stdlib-only except `quic-go` (gated behind `--quic-addr`).
	Direct dependencies are stdlib-only except `quic-go` (gated behind `--quic-addr`).

	\| `internal/transport` \| HTTP + SSE \| `/state`, `/log`, `/rewrites`, `/programs`, `/operad`, `/hdc`, `/t-hook/evaluate`, `/t-cone`, `/twin/ingest`, `/fold` (with SSE), `/healthz`. \|
	\| `internal/transport` \| HTTP + SSE \| `/state/` (e.g. `/state/nodes`, `/state/relations`), `/log`, `/rewrites`, `/programs`, `/operad/` (e.g. `/operad/node-types`), `/hdc/*`, `/t-hook/evaluate`, `/t-cone`, `/twin/ingest`, `/fold` (with SSE), `/healthz`. \|

	\| `internal/operad` \| type system \| `Registry` (ontology v3.13.0: 52 node types, 21 WFs WF01–WF21), strict port-pair `ValidateLINK`, `ValidateMUTATE`, occupancy resolution, admin-capability walks. \|
	\| `internal/operad` \| type system \| `Registry` (ontology v3.13.0: 52 node types, 21 WFs WF01–WF21; current typed `RewriteCategory` constants in `internal/graph` run through WF19), strict port-pair `ValidateLINK`, `ValidateMUTATE`, occupancy resolution, admin-capability walks. \|

Conversation

MSD21091969 commented Apr 25, 2026

Summary

Contents

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 25, 2026

Choose a reason for hiding this comment

Uh oh!

MSD21091969 commented Apr 25, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants