Skip to content

docs: README refresh + AGENTS.md mirror #39

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
MSD21091969 merged 1 commit into from
Jun 20, 2026
Merged

docs: README refresh + AGENTS.md mirror #39

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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/<purpose-slug>`** (trunk-first on `main` only for verified
single-lane, non-colliding work). Merge with provenance; commit trailer
`authored-by: <agent-urn> / <session-urn> / <purpose-slug>`.

## 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
218 changes: 138 additions & 80 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Comment on lines +73 to +74

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:<ws>.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.*