From e2cb79c971c4e4b62d5e021dee6734bc56854f02 Mon Sep 17 00:00:00 2001 From: Sam Maassen <215926119+MSD21091969@users.noreply.github.com> Date: Sat, 20 Jun 2026 23:22:24 +0200 Subject: [PATCH] docs: refresh README + add AGENTS.md mirror Accurate-to-source README (graph->fold->operad->kernel layering, four rewrites, M11/M12 gates, HTTP+MCP surface, sweep, seed, build/test) + thin AGENTS.md mirror pointing at ffs0/AGENTS.md as project SOT. No .go changes. authored-by: agent:claude-cowork.hp-z440 / session:sam.z440-cowork-workspace / readme-foldering Co-Authored-By: Claude Opus 4.8 --- AGENTS.md | 34 +++++++++ README.md | 218 ++++++++++++++++++++++++++++++++++-------------------- 2 files changed, 172 insertions(+), 80 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..f02f464 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,34 @@ +# AGENTS.md — moos-kernel (Go runtime) + +> **Mirror of `ffs0/AGENTS.md`** (project SOT) · manual · don't edit except emergency de-rot. +> This repo carries runtime-deltas only — it does not restate the seat table or the full fleet brief. + +## Orientation +This repository is the **Go runtime** for mo:os — the rewrite engine (log/fold/operad/kernel/ +transport/mcp). It is the OS-facing runtime function program, **not** an application domain. The +**docs/KB SOT lives in the `ffs0` repo** (`ffs0/AGENTS.md` + `kb/superset/running-state.md` + +`kb/superset/ontology.json`); the **semantic SOT is the folded HG + live `/healthz`** readback. A +Markdown file is never final truth — if a doc and the readback disagree, the readback wins. + +## The rule (non-negotiable) +Four rewrites only: **ADD · LINK · MUTATE · UNLINK**. **Log is truth. State is derived.** +Nomenclature — use: node · relation · rewrite · property · operad · port · rewrite_category +WF01..WF21 · `_urn`/`_urns`. Never: edge · wire · field · schema · mutation · association · +binding · `_ref`. Authoritative vocabulary: `ontology.json` in ffs0. + +## Branching +Runtime repos branch **`feat/`** (trunk-first on `main` only for verified +single-lane, non-colliding work). Merge with provenance; commit trailer +`authored-by: / / `. + +## Safety +Never commit `secrets/`, API tokens, or build artifacts (`moos-kernel*.exe`, `*.bak-*`, `*~`, +ephemeral state). `ffs0/` is a **sibling** repo, not part of this module. + +## Pointers +- Project SOT / seat table / fleet brief → **`ffs0/AGENTS.md`**. +- Live round-to-round state → `ffs0/kb/superset/running-state.md`. +- Kernel internals, gates, package map, CLI → this repo's `README.md` and `CLAUDE.md`. + +--- +authored-by: agent:claude-cowork.hp-z440 / session:sam.z440-cowork-workspace / config-overhaul diff --git a/README.md b/README.md index f19cc48..6148080 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,14 @@ A categorical hypergraph rewriting kernel for distributed knowledge work. Go, stdlib-first. -As of T189, this repository is the OS-facing runtime function program for mo:os. It is separate from application/domain groups such as `my-tiny-data-collider`, which run on the HG through kernels and may own websites, DNS, servers, Calendar/GitHub/Workspace surfaces, and public/private projection targets. +This repository is the OS-facing **runtime function program** for mo:os — the rewrite engine. It is +separate from application/domain groups such as `my-tiny-data-collider`, which run *on* the HG through +kernels and may own websites, DNS, servers, Calendar/GitHub/Workspace surfaces, and projection targets. +The semantic source of truth is the folded hypergraph and the live `/healthz` readback, not this file. -## What it is +## The rule -mo:os is a **semantic functorial network over distributed compute**, where all components — hardware and programs — are considered categorically. The hypergraph (HG) is the source of truth; state is derived from a log of four primitive rewrites: +Nothing happens except rewrites. **Four operations only:** ``` ADD — create a node with typed properties @@ -15,110 +18,165 @@ MUTATE — change one property value on one existing node UNLINK — remove a relation ``` -`state(t) = fold(log[0..t])`. The log is append-only; the kernel is a fold over it. Replay is prospective-only. +`state(t) = fold(log[0..t])`. **Log is truth. State is derived.** The log is append-only; the kernel +is a fold (catamorphism) over it. Replay is prospective-only. -The session is the centerpiece. A session is a 5-facet scoped context: `(scope, purpose) x (host, owner, occupant)`. Its relations make it findable by G-direction ingest from surfaces like Drive, Gmail, Calendar, GitHub, websites, and DNS, and make it capable of writing programs that pull explicit actuator leaves in the F direction. Leaves are boundary actions with graph-derived arguments, not hidden side effects. +Nomenclature is enforced: node · relation · rewrite · property · operad · port · rewrite_category +WF01..WF21 · `_urn`/`_urns`. Never edge/wire/field/schema/mutation/association/binding/`_ref`. -## What's in the box +## Layering + +The kernel is a strict tower; effects live only at the top. + +``` +graph (pure types, no IO) + └─ fold (pure catamorphism: state = fold(log)) + └─ operad (registry: WF01..WF21, port pairs, validation — read-only after load) + └─ kernel (the ONLY mutator: Runtime, Store, §M11/§M12 gates, sweep) + └─ transport / mcp (adapters: HTTP+SSE, MCP JSON-RPC) +``` | Layer | Path | Role | |---|---|---| -| `internal/graph` | pure types | `Node`, `Relation`, `Property`, `Rewrite`, `Envelope`, `GraphState` (with indexes), `URN`, `Stratum`, `RewriteCategory`. No IO. | +| `internal/graph` | pure types | `Node`, `Relation`, `Property`, `Rewrite`, `Envelope` (+ optional `SessionURN` for explicit §M11 context), `GraphState` (with `NodesByType` / `RelationsBySrc` / `RelationsByTgt` 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` (current ontology v3.16.1: 53 node types; WFs WF01–WF21), strict port-pair `ValidateLINK`, `ValidateMUTATE`, occupancy resolution, session-context 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/*` (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/hdc` | hyperdimensional computing | spectral, fiber, crosswalk, encode, live-index. | -| `internal/mcp` | MCP JSON-RPC | SSE + stdio + Streamable HTTP. | +| `internal/operad` | type system | `Registry` (ontology **v3.16.2** — 53 node types, WF01–WF21) with `Version` for `/healthz`; strict port-pair `ValidateLINK` (pair must be declared; src/tgt type enforcement), `ValidateMUTATE`; `AdminScopeRewrite`, `SystemInternalEnvelope`, `ResolveSessionForEnvelope`; occupancy + admin-capability walks. | +| `internal/kernel` | **effect layer** | `Runtime`, `Store`, `LogStore` / `MemStore`. §M11 session-liveness + §M12 admin-capability gates (`liveness.go`). Sweep loop emits WF13 governance proposals on `t_hook.firing_state` transitions. The only place state mutates. | +| `internal/reactive` | predicate evaluator | Watch / React / Guard engine; `EvaluateThookPredicate` covers 10+ §M14 predicate kinds (incl. `when_capability`). Read-only — returns proposed `[]Envelope`, never mutates. | +| `internal/transport` | HTTP + SSE | the REST surface below. Reports `ontology_version` on `/healthz`. | +| `internal/hdc` | hyperdimensional computing | spectral, fiber, crosswalk, encode, live-index. Derived from state after each apply. | +| `internal/mcp` | MCP JSON-RPC 2.0 | SSE + stdio + Streamable HTTP. | +| `internal/tday` | T-day epoch | single source of `T0` + `Now()` + `At()`. | +| `cmd/moos` | entry point | flag parsing, registry/store load, seed, server wiring, sweep, graceful shutdown. | + +**Layer discipline:** `graph` has no IO; `fold` is pure; only `kernel` has effects. `Registry` is +read-only after load; `GraphState` is replaced on each rewrite, never mutated in place. + +## Runtime gates (live since T=171) + +Every envelope passes two gates in `Runtime.Apply` / `Runtime.ApplyProgram` **before fold**: + +- **§M11 liveness** (`checkLivenessM11`) — the emitter must have a session context. Explicit + `env.session_urn` wins; fallback is a reverse `has-occupant` lookup from `env.actor` (unambiguous + single session = pass; ambiguous or absent = reject). Runs against batch-initial state. +- **§M12 admin-capability** (`checkLivenessM12`) — admin-scope rewrites must hold WF02 superadmin. + Admin scope = ADD/MUTATE on ontology-governed types (`system_instruction`, `gate`, `twin_link`, + `transport_binding`, `kernel`) OR MUTATE of a property with `authority_scope: "kernel"` on a + non-kernel node, classified by `operad.(*Registry).AdminScopeRewrite`. Runs against working-state + inside the ApplyProgram loop, so it catches an intra-batch ADD-then-MUTATE bypass. + +A **system-internal allowlist** (`operad.SystemInternalEnvelope` — kernel-URN actors emitting +infrastructure types `user` / `workstation` / `kernel`) precedes both gates. `SeedIfAbsent` +additionally bypasses §M11 structurally for bootstrap. **Replay is prospective-only**: `fold.Replay` +does not re-check liveness, so pre-gate persisted logs rebuild identically. + +Operad validation (type / port-pair / authority) runs ahead of the gates; `fold` then enforces +structural invariants and maintains indexes. -Layer discipline: `graph` has no IO; `fold` is pure; only `kernel` has effects. +## HTTP API surface -## Running +Served on `--listen` (default `:8000`), CORS-wrapped. + +| Route | Method | Purpose | +|---|---|---| +| `/healthz` | GET | liveness + `ontology_version`, `t_day`, `log_len` | +| `/state/nodes`, `/state/nodes/{urn}` | GET | folded node state | +| `/state/relations`, `/state/relations/src/{urn}`, `/state/relations/tgt/{urn}` | GET | folded relations by side | +| `/log`, `/log/stream` | GET | raw rewrite log (+ SSE tail) | +| `/fold`, `/fold/stream` | GET | full folded state (+ SSE) | +| `/rewrites` | POST | submit one rewrite envelope (through both gates) | +| `/programs` | POST | submit an atomic batch of envelopes (all-or-nothing) | +| `/operad/node-types`, `/operad/rewrite-categories`, `/operad/port-colors` | GET | registry introspection | +| `/hdc/*` | GET | derived HDC views (similarity-matrix, eigenvalues, fiedler, fiber, crosswalk, …) | +| `/twin/ingest`, `/twin/status` | POST / GET | M9 twin-kernel adjoint sync | +| `/t-hook/evaluate/{urn}`, `/t-hook/evaluate` | GET / POST | §M14 predicate evaluation (single + batch) | +| `/t-cone` | GET | §M15 occupant's view of nodes with open hooks | + +## MCP server + +Served on `--mcp-addr` (default `:8080`) over SSE; also stdio (`--mcp-stdio` / `--stdio-only`) and +Streamable HTTP. JSON-RPC 2.0. Five tools: + +- **Writes** — `apply_rewrite` (one envelope), `apply_program` (atomic batch). Both go through the + same §M11/§M12 gates as the HTTP `/rewrites` and `/programs` routes. +- **Reads** — `graph_state`, `node_lookup` (by URN), `operad_registry` (points at the `/operad/*` + HTTP routes for full introspection). + +## Sweep + +`Runtime.RunTimedSweep` / `SweepTick` runs on its own goroutine every `--sweep-interval` +(default `30s`, `0` disables). Each tick walks all pending `t_hook`s and, for every hook whose +predicate fires, **proposes** a WF13 `governance_proposal` (status `pending`). The sweep **never +auto-applies** — proposals await admin ratification. `t_hook.firing_state` state machine: +`pending → proposed → approved | rejected → applied | closed`. The sweep actor defaults to +`urn:moos:kernel:sweep`, overridden to `urn:moos:kernel:.primary` when `--seed` is set. + +## Seed mode + +`--seed` idempotently seeds the S2 core via `SeedIfAbsent` (liveness-bypassed): a `user` node, a +`workstation` node (with detected OS/arch), a `kernel` node, plus WF01 `owns` (user→workstation) and +WF03 `hosts` (workstation→kernel) relations. Names come from `--seed-user` (default `sam`) and +`--seed-ws` (default `hp-laptop`). Safe to run on every restart. + +## Build / Run / Test ```bash +go build ./... + go run ./cmd/moos \ --ontology ../ffs0/kb/superset/ontology.json \ --log /tmp/moos.log \ - --listen :8000 \ - --mcp-addr :8080 \ --seed ``` -Key flags: - -| Flag | Default | Purpose | -|---|---|---| -| `--ontology` | (none) | path to `ontology.json`; without it, ontology-backed type validation is disabled and liveness/admin gates are bypassed because there is no registry-backed operad | -| `--log` | (none) | JSONL log path; in-memory if omitted | -| `--listen` | `:8000` | HTTP transport | -| `--mcp-addr` | `:8080` | MCP SSE | -| `--sweep-interval` | `30s` | t-hook sweep cadence (0 disables) | -| `--quic-addr` | (none) | UDP/HTTP3 listener (requires `--tls-cert` + `--tls-key`) | - -Direct dependencies are stdlib-only except `quic-go` (gated behind `--quic-addr`); transitive dependencies include `golang.org/x/net` and `golang.org/x/crypto` via `quic-go`. - -## Testing - ```bash go test ./... +MOOS_INTEGRATION=1 go test ./... # integration tests read sibling ffs0/kb/superset/ontology.json ``` -Race-detector requires cgo. Integration tests gated behind `MOOS_INTEGRATION=1` (read sibling `ffs0/kb/superset/ontology.json`). - -## Runtime gates (live since T=171 round 11) +Race-detector run requires cgo/gcc. -Every envelope passes two gates before fold: +### CLI flags -- **§M11 liveness** — emitter must have a session context. Explicit `env.session_urn` wins; fallback is reverse-`has-occupant` lookup from `env.actor` (single-session = pass; ambiguous or absent = reject). -- **§M12 admin-capability** — admin-scope rewrites (ADDs on ontology-governed types, MUTATEs of `authority_scope: kernel` properties on non-kernel nodes) walk `WF02 governs` from actor through `role:superadmin` to verify capability. - -System-internal allowlist (kernel-URN actors emitting infrastructure types) bypasses both. `SeedIfAbsent` additionally bypasses §M11 structurally for bootstrap. - -Fold-time replay does **not** re-check liveness — pre-gate persisted logs rebuild identically. +| Flag | Default | Purpose | +|---|---|---| +| `--ontology` | (none) | path to `ontology.json`; omit → no type validation, gates bypass (registry-less) | +| `--log` | (none) | JSONL log path; omit → in-memory (non-persistent) | +| `--listen` | `:8000` | HTTP transport address | +| `--mcp-addr` | `:8080` | MCP SSE address | +| `--mcp-stdio` | false | also run MCP on stdin/stdout | +| `--stdio-only` | false | MCP stdio only — no HTTP/SSE (Desktop integration) | +| `--seed` | false | seed infrastructure nodes (idempotent, liveness-bypassed) | +| `--seed-user` | `sam` | username for seed node | +| `--seed-ws` | `hp-laptop` | workstation name for seed node | +| `--sweep-interval` | `30s` | t-hook sweep tick (`0` disables) | +| `--quic-addr` | (none) | UDP HTTP/3 QUIC listener; requires `--tls-cert` + `--tls-key` | +| `--tls-cert` / `--tls-key` | (none) | PEM cert/key for the QUIC listener | + +## Dependencies + +Stdlib-first. The only direct dependency is `github.com/quic-go/quic-go` (gated behind +`--quic-addr`); transitive deps (`golang.org/x/net`, `golang.org/x/crypto`, …) arrive via quic-go. ## Ontology -[`ffs0/kb/superset/ontology.json`](https://github.com/Collider-Data-Systems/ffs0) (private workspace) — v3.16.1 — 53 node types, WFs WF01–WF21. Loaded at boot; immutable thereafter. - -Selected node types: `session`, `program`, `purpose`, `agent`, `kernel`, `channel`, `knowledge_item`, `claim`, `derivation`, `calendar_event`, `clock`, `t_hook`, `reactor`, `watcher`, `tool_call`, `tool_result`, `external_op`, `compute`, `storage`, `harness`, `workflow`, `group`, `role`, `gate`, `system_instruction`, `transport_binding`, `twin_link`, `governance_proposal`, `grammar_fragment`. - -WF categories include WF01 owns/owned-by, WF02 governs/delegates-to, WF12 provides-kb/kb-source, WF13 governance-proposes/proposed-by, WF18 composition/dependency/scheduling pairs, WF19 opens-on/has-occupant/has-purpose/pins-urn/filtering/tool-mount pairs, WF20 grammar-promotion ceremony, and WF21 causes/caused-by. - -## Kernel, Host OS, And Applications - -The kernel's job is runtime substrate: log/fold, operad validation, session liveness, admin capability, transport, HDC derivation, and explicit actuator boundaries. Longer-term OS integration may include a Rust host extension on Linux/Windows for local watchers, credentials, policy, and user-approved data channels. That host extension should still be substrate/runtime code, separate from application code. - -Applications are HG groups/program families that use the runtime. `my-tiny-data-collider` is one such application/domain: websites, DNS, content/data servers, Calendar, GitHub, Workspace, and other projection surfaces can belong to that group without becoming part of `moos-kernel`. - -## Federation +Canonical at [`ffs0/kb/superset/ontology.json`](../ffs0/kb/superset/ontology.json) — **v3.16.2**, +53 node types, WF01–WF21. Loaded at boot, immutable thereafter. The kernel reports its loaded version +on `/healthz`; if a doc and the readback disagree, the readback wins. -Twin kernels ride the same hypervisor host via `twin_link` edges and the WF16 router (`Collider-Data-Systems/moos-router`). Cross-machine federation rides Cloudflare tunnels (Z440 ↔ hp-laptop). The router shards by URN prefix; each kernel keeps its own sovereign log. - -## Status - -Current hp-laptop runtime context at T189: ontology v3.16.1, `session:sam.governance` live, Calendar/time-fabric and T189/T200 recommendation carriers pinned into governance session scope, 16 `calendar_event` observations present in HG, and the local ffs0 projection dashboard reporting `warn` with 18 pass, 1 warn, 0 fail. - -Near-term kernel work remains correctness-focused: keep the log/fold/operad/session/authority contract small and dependable while projection/ingest applications develop in `ffs0` and application-specific repos. One visible T189 operad cleanup remains: align WF07's top-level declaration with the existing `anchors/anchor` port-color compatibility before Calendar source-anchor relations are applied. - -## Repository layout - -``` -cmd/moos # entry point -internal/... # see "What's in the box" table -go.mod # stdlib + quic-go only -``` +WF families include WF01 owns/owned-by, WF02 governs/delegates-to, WF03 hosts/hosted-on, +WF12 provides-kb/kb-source, WF13 governance-proposes/proposed-by, WF18 composition/dependency/ +scheduling pairs, WF19 opens-on/has-occupant/has-purpose/pins-urn pairs, WF20 grammar-promotion, +WF21 causes/caused-by. ## Companion repositories -- **moos-router** — WF16 federation gateway; URN-prefix and type routing across kernels. -- **ffs0** — private workspace, ontology source, skills, projection planners, reports, and operator dashboards. -- **Application groups** — e.g. `my-tiny-data-collider`, modeled as HG group/purpose/program/channel families, not as kernel code. - -## License - -(TBD — assignment in progress) - -## Contact +- **moos-router** — WF16 federation gateway; URN-prefix + type routing across kernels. +- **ffs0** — private control/research workspace: ontology source, skills, projection planners, + doctrine notes, running-state. The docs/KB SOT lives there (`ffs0/AGENTS.md`). +- **Application groups** — e.g. `my-tiny-data-collider`, modeled as HG group/purpose/program/channel + families, **not** as kernel code. -Maintained by [@Collider-Data-Systems](https://github.com/Collider-Data-Systems). Two teams: **Sam** (kernels + delegates + most sessions), **Moos** (multimodal diary curation). +--- +*Mirror note: this README is a hand-authored projection. The semantic SOT is the folded HG + +`/healthz`; the project brief SOT is `ffs0/AGENTS.md`. See `AGENTS.md` (this repo) for the thin mirror.*