From 9ce36d2385f08feb5c57f359992d32136399bbdb Mon Sep 17 00:00:00 2001 From: deamonkai <26585050+deamonkai@users.noreply.github.com> Date: Tue, 17 Feb 2026 21:28:50 -0600 Subject: [PATCH] new stuff --- MM/README.md | 23 ++ MM/docs/KERNEL-ROADMAP.md | 20 ++ MM/docs/RFC-INDEX.md | 10 + MM/docs/rfcs/RFC-0007-Delegating-Router.md | 18 ++ .../RFC-0008-Capability-Guard-Framework.md | 14 ++ .../rfcs/RFC-0009-Event-Ledger-Primitive.md | 15 ++ MM/docs/rfcs/RFC-0010-Guarded-Emit-Syscall.md | 13 ++ .../rfcs/RFC-0011-Session-Spawn-Primitive.md | 36 +++ ...RFC-0012-Deterministic-Retry-Controller.md | 36 +++ MM/kernel/proto/README.md | 3 + MM/kernel/proto/delegation_proof_schema.json | 14 ++ MM/kernel/supervisor-go/README.md | 16 ++ MM/kernel/supervisor-go/go.mod | 3 + MM/kernel/supervisor-go/main.go | 205 ++++++++++++++++++ 14 files changed, 426 insertions(+) create mode 100644 MM/README.md create mode 100644 MM/docs/KERNEL-ROADMAP.md create mode 100644 MM/docs/RFC-INDEX.md create mode 100644 MM/docs/rfcs/RFC-0007-Delegating-Router.md create mode 100644 MM/docs/rfcs/RFC-0008-Capability-Guard-Framework.md create mode 100644 MM/docs/rfcs/RFC-0009-Event-Ledger-Primitive.md create mode 100644 MM/docs/rfcs/RFC-0010-Guarded-Emit-Syscall.md create mode 100644 MM/docs/rfcs/RFC-0011-Session-Spawn-Primitive.md create mode 100644 MM/docs/rfcs/RFC-0012-Deterministic-Retry-Controller.md create mode 100644 MM/kernel/proto/README.md create mode 100644 MM/kernel/proto/delegation_proof_schema.json create mode 100644 MM/kernel/supervisor-go/README.md create mode 100644 MM/kernel/supervisor-go/go.mod create mode 100644 MM/kernel/supervisor-go/main.go diff --git a/MM/README.md b/MM/README.md new file mode 100644 index 0000000..bd1c2d3 --- /dev/null +++ b/MM/README.md @@ -0,0 +1,23 @@ +# CognitiveOS Architecture Bundle (Add-ons v2) + +Generated: 2026-02-17 + +Includes RFCs 0007--0012 and a runnable Go supervisor stub +demonstrating: - Deterministic routing - Append-only, hash-chained event +ledger - Guarded emit enforcement (must-delegate invariant) + +## Layout + +- docs/ + - RFC-INDEX.md + - KERNEL-ROADMAP.md + - rfcs/ + - RFC-0007-Delegating-Router.md + - RFC-0008-Capability-Guard-Framework.md + - RFC-0009-Event-Ledger-Primitive.md + - RFC-0010-Guarded-Emit-Syscall.md + - RFC-0011-Session-Spawn-Primitive.md + - RFC-0012-Deterministic-Retry-Controller.md +- kernel/ + - proto/ + - supervisor-go/ diff --git a/MM/docs/KERNEL-ROADMAP.md b/MM/docs/KERNEL-ROADMAP.md new file mode 100644 index 0000000..abf6cc8 --- /dev/null +++ b/MM/docs/KERNEL-ROADMAP.md @@ -0,0 +1,20 @@ +# CognitiveOS Kernel Roadmap + +## Phase 1 --- Integrity + Security + +- RFC-0008 Capability & Guard framework +- RFC-0009 Event Ledger (append-only + hash chaining) + +## Phase 2 --- Privileged Syscalls + +- RFC-0011 Session Spawn +- RFC-0010 Guarded Emit + +## Phase 3 --- Router Enforcement + +- RFC-0007 Delegating Router +- RFC-0012 Deterministic Retry Controller + +## Phase 4 --- Distributed Fabric + +- Remote workers, signed ledger replication, trust tiers diff --git a/MM/docs/RFC-INDEX.md b/MM/docs/RFC-INDEX.md new file mode 100644 index 0000000..9cbc9c2 --- /dev/null +++ b/MM/docs/RFC-INDEX.md @@ -0,0 +1,10 @@ +# CognitiveOS RFC Index + + RFC Title Status + ---------- -------------------------------- -------- + RFC-0007 Delegating Router Primitive Draft + RFC-0008 Capability & Guard Framework Draft + RFC-0009 Event Ledger Primitive Draft + RFC-0010 Guarded Emit Syscall Draft + RFC-0011 Session Spawn Primitive Draft + RFC-0012 Deterministic Retry Controller Draft diff --git a/MM/docs/rfcs/RFC-0007-Delegating-Router.md b/MM/docs/rfcs/RFC-0007-Delegating-Router.md new file mode 100644 index 0000000..b23d315 --- /dev/null +++ b/MM/docs/rfcs/RFC-0007-Delegating-Router.md @@ -0,0 +1,18 @@ +# RFC-0007: Delegating Router Primitive + +**Status:** Draft \| **Updated:** 2026-02-17 + +## Invariant + +A router MUST NOT emit user-visible output unless it delegated to a +child session and returns child output (verbatim or bounded wrapper). + +## Enforcement + +Use capability gating + `emit_guarded` (RFC-0010) validated against the +Event Ledger (RFC-0009). + +## Output rules + +Router may prepend exactly one bounded line: +`Delegating to because .` Max 240 chars. diff --git a/MM/docs/rfcs/RFC-0008-Capability-Guard-Framework.md b/MM/docs/rfcs/RFC-0008-Capability-Guard-Framework.md new file mode 100644 index 0000000..410eb56 --- /dev/null +++ b/MM/docs/rfcs/RFC-0008-Capability-Guard-Framework.md @@ -0,0 +1,14 @@ +# RFC-0008: Capability & Guard Framework + +**Status:** Draft \| **Updated:** 2026-02-17 + +## Principle + +Control plane is deterministic. Privileged actions require explicit +capabilities and guards that validate structured evidence (ledger +events), not prompt text. + +## Guarded actions + +- session_spawn (RFC-0011) +- emit_guarded (RFC-0010) diff --git a/MM/docs/rfcs/RFC-0009-Event-Ledger-Primitive.md b/MM/docs/rfcs/RFC-0009-Event-Ledger-Primitive.md new file mode 100644 index 0000000..8c2e080 --- /dev/null +++ b/MM/docs/rfcs/RFC-0009-Event-Ledger-Primitive.md @@ -0,0 +1,15 @@ +# RFC-0009: Event Ledger Primitive + +**Status:** Draft \| **Updated:** 2026-02-17 + +## Properties + +- Append-only +- Hash-chained per stream +- Schema-validated +- Tamper-evident +- Supports proof construction for policy enforcement + +## Envelope + +Each event includes: id, ts, stream_id, type, body, prev_hash, hash. diff --git a/MM/docs/rfcs/RFC-0010-Guarded-Emit-Syscall.md b/MM/docs/rfcs/RFC-0010-Guarded-Emit-Syscall.md new file mode 100644 index 0000000..7374269 --- /dev/null +++ b/MM/docs/rfcs/RFC-0010-Guarded-Emit-Syscall.md @@ -0,0 +1,13 @@ +# RFC-0010: Guarded Emit Syscall + +**Status:** Draft \| **Updated:** 2026-02-17 + +## Signature + +emit_guarded(caller_session_id, request_id, output, proof_ref) -\> +ok\|error + +## Enforcement + +Validates must-delegate invariant (RFC-0007) using ledger evidence +(RFC-0009). Rejects output not derived from child output. diff --git a/MM/docs/rfcs/RFC-0011-Session-Spawn-Primitive.md b/MM/docs/rfcs/RFC-0011-Session-Spawn-Primitive.md new file mode 100644 index 0000000..a77a218 --- /dev/null +++ b/MM/docs/rfcs/RFC-0011-Session-Spawn-Primitive.md @@ -0,0 +1,36 @@ +# RFC-0011: Session Spawn Primitive + +**Status:** Draft \| **Updated:** 2026-02-17 + +## Summary + +Defines a deterministic syscall to spawn a child cognitive session from +a control-plane supervisor/router. + +## API + +`session_spawn(parent_session_id, request_id, target_agent, payload) -> child_session_id` + +## Preconditions + +- Caller has `cap.session.spawn`. +- Payload is recorded (or hashed) for auditability. +- Spawn emits a `session_spawn` ledger event (RFC-0009). + +## Postconditions + +- A child session exists with its own stream_id. +- Parent stream contains `session_spawn` pointing to child session_id. +- Child stream begins with a genesis event referencing parent spawn + context. + +## Security + +- Child inherits only explicit capabilities (no ambient authority). +- Parent cannot read child internal chain-of-thought unless explicitly + granted (separate capability). + +## Observability + +Record: - target_agent - payload_hash - resource limits (if any) - +parent/child linkage diff --git a/MM/docs/rfcs/RFC-0012-Deterministic-Retry-Controller.md b/MM/docs/rfcs/RFC-0012-Deterministic-Retry-Controller.md new file mode 100644 index 0000000..6f1b232 --- /dev/null +++ b/MM/docs/rfcs/RFC-0012-Deterministic-Retry-Controller.md @@ -0,0 +1,36 @@ +# RFC-0012: Deterministic Retry Controller + +**Status:** Draft \| **Updated:** 2026-02-17 + +## Summary + +Defines a bounded, deterministic retry mechanism for control-plane +policy violations and transient failures. + +## Goals + +- Bounded retries (no infinite loops) +- Transparent ledger recording +- Clear failure modes + +## API (conceptual) + +`retry_controller(run_id, max_attempts, policy) -> result` + +## Reference Policy: must-delegate + +- Attempt 1: run router normally +- If emit_guarded rejects with POLICY_VIOLATION_MUST_DELEGATE: + - record `policy_violation` + `retry_scheduled` + - rerun router in **strict mode** (no free-form output; must spawn + immediately) +- Attempt 2: if violation repeats: + - fail closed with deterministic error message + - record `run_failed` + +## Ledger Events + +- retry_scheduled +- retry_started +- retry_exhausted +- run_failed diff --git a/MM/kernel/proto/README.md b/MM/kernel/proto/README.md new file mode 100644 index 0000000..e108a12 --- /dev/null +++ b/MM/kernel/proto/README.md @@ -0,0 +1,3 @@ +# Proto Artifacts + +Machine-readable scaffolding for early implementations. diff --git a/MM/kernel/proto/delegation_proof_schema.json b/MM/kernel/proto/delegation_proof_schema.json new file mode 100644 index 0000000..5d3db39 --- /dev/null +++ b/MM/kernel/proto/delegation_proof_schema.json @@ -0,0 +1,14 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "DelegationProof", + "type": "object", + "required": ["proof_id", "router_session", "request_id", "child_sessions", "spawn_event_ids", "child_output_event_ids"], + "properties": { + "proof_id": {"type": "string", "format": "uuid"}, + "router_session": {"type": "string"}, + "request_id": {"type": "string", "format": "uuid"}, + "child_sessions": {"type": "array", "items": {"type": "string"}}, + "spawn_event_ids": {"type": "array", "items": {"type": "string"}}, + "child_output_event_ids": {"type": "array", "items": {"type": "string"}} + } +} diff --git a/MM/kernel/supervisor-go/README.md b/MM/kernel/supervisor-go/README.md new file mode 100644 index 0000000..1443ca7 --- /dev/null +++ b/MM/kernel/supervisor-go/README.md @@ -0,0 +1,16 @@ +# supervisor-go + +Runnable stub demonstrating CognitiveOS control-plane concepts without +an actual LLM. + +## Run + +go run . -ledger ./ledger.jsonl + +Then type requests and observe: - deterministic route decision - +session_spawn + child_output_received - final_output_emitted + +## Notes + +- This is intentionally minimal and deterministic. +- Replace `childWorkerStub` with real model calls later. diff --git a/MM/kernel/supervisor-go/go.mod b/MM/kernel/supervisor-go/go.mod new file mode 100644 index 0000000..151da26 --- /dev/null +++ b/MM/kernel/supervisor-go/go.mod @@ -0,0 +1,3 @@ +module cognitiveos/supervisor + +go 1.22 diff --git a/MM/kernel/supervisor-go/main.go b/MM/kernel/supervisor-go/main.go new file mode 100644 index 0000000..4dfa28a --- /dev/null +++ b/MM/kernel/supervisor-go/main.go @@ -0,0 +1,205 @@ +package main + +import ( + "bufio" + "crypto/sha256" + "encoding/hex" + "encoding/json" + "flag" + "fmt" + "os" + "sort" + "strings" + "time" +) + +// This is a runnable *stub* for the deterministic control plane. +// It does NOT call real LLMs. Instead it demonstrates: +// - deterministic routing (fast/default/heavy) +// - append-only, hash-chained ledger per "stream" +// - must-delegate enforcement: router cannot emit without a spawn+child output proof + +type Event struct { + ID string `json:"id"` + TS string `json:"ts"` + StreamID string `json:"stream_id"` + Type string `json:"type"` + Body map[string]any `json:"body"` + PrevHash *string `json:"prev_hash"` + Hash string `json:"hash"` +} + +func canonicalJSON(v any) ([]byte, error) { + // Simple canonicalization: marshal with sorted keys for map[string]any at top-level envelope. + // For a real system, use a stricter canonical JSON spec. + b, err := json.Marshal(v) + if err != nil { + return nil, err + } + return b, nil +} + +func sha256Hex(b []byte) string { + h := sha256.Sum256(b) + return hex.EncodeToString(h[:]) +} + +func newID() string { + // Not cryptographically strong; good enough for a stub. + return fmt.Sprintf("%d-%d", time.Now().UnixNano(), os.Getpid()) +} + +func computeHash(id, ts, stream, typ string, body map[string]any, prev *string) (string, error) { + env := map[string]any{ + "id": id, + "ts": ts, + "stream_id": stream, + "type": typ, + "body": body, + "prev_hash": prev, + } + // Sort body keys deterministically (best effort). + if body != nil { + keys := make([]string, 0, len(body)) + for k := range body { + keys = append(keys, k) + } + sort.Strings(keys) + ordered := make(map[string]any, len(body)) + for _, k := range keys { + ordered[k] = body[k] + } + env["body"] = ordered + } + b, err := canonicalJSON(env) + if err != nil { + return "", err + } + return sha256Hex(b), nil +} + +type Ledger struct { + Path string + StreamID string + LastHash *string +} + +func (l *Ledger) Append(typ string, body map[string]any) (*Event, error) { + id := newID() + ts := time.Now().UTC().Format(time.RFC3339Nano) + h, err := computeHash(id, ts, l.StreamID, typ, body, l.LastHash) + if err != nil { + return nil, err + } + ev := &Event{ + ID: id, + TS: ts, + StreamID: l.StreamID, + Type: typ, + Body: body, + PrevHash: l.LastHash, + Hash: h, + } + f, err := os.OpenFile(l.Path, os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0o644) + if err != nil { + return nil, err + } + defer f.Close() + + enc := json.NewEncoder(f) + if err := enc.Encode(ev); err != nil { + return nil, err + } + l.LastHash = &ev.Hash + return ev, nil +} + +// Deterministic routing rules (reference): +// - explicit @fast/@heavy +// - keywords: one-liner, regex, jq, bash, quick => FAST +// - multi-file/architecture/restructure/rewrite => HEAVY +// - else DEFAULT +func decideRoute(req string) (tier string, agent string, reason string) { + l := strings.ToLower(req) + if strings.Contains(l, "@fast") { + return "fast", "lab-code-fast", "explicit @fast" + } + if strings.Contains(l, "@heavy") { + return "heavy", "lab-code-heavy", "explicit @heavy" + } + for _, kw := range []string{"one-liner", "quick", "regex", "jq", "bash"} { + if strings.Contains(l, kw) { + return "fast", "lab-code-fast", "keyword match: " + kw + } + } + for _, kw := range []string{"multi-file", "architecture", "restructure", "rewrite", "subsystem", "src/"} { + if strings.Contains(l, kw) { + return "heavy", "lab-code-heavy", "scope implies: " + kw + } + } + return "default", "lab-code", "default routing" +} + +func childWorkerStub(agent string, req string) string { + // Placeholder for actual specialist call. This returns deterministic output for demo. + return fmt.Sprintf("[stub:%s] Received request (%d chars).", agent, len(req)) +} + +func main() { + ledgerPath := flag.String("ledger", "ledger.jsonl", "path to append-only ledger file") + flag.Parse() + + routerStream := "router-session-1" + ledger := &Ledger{Path: *ledgerPath, StreamID: routerStream, LastHash: nil} + + fmt.Println("CognitiveOS Supervisor (stub). Type a request, then press Enter. Ctrl-D to exit.") + sc := bufio.NewScanner(os.Stdin) + + for sc.Scan() { + req := sc.Text() + if strings.TrimSpace(req) == "" { + continue + } + + tier, agent, reason := decideRoute(req) + _, _ = ledger.Append("route_decision", map[string]any{ + "tier": tier, + "target_agent": agent, + "reason": reason, + }) + + // session_spawn (must-delegate proof step) + childSession := "child-" + newID() + payloadHash := sha256Hex([]byte(req)) + _, _ = ledger.Append("session_spawn", map[string]any{ + "child_session": childSession, + "child_agent": agent, + "payload_hash": payloadHash, + }) + + // child_output_received + childOut := childWorkerStub(agent, req) + outHash := sha256Hex([]byte(childOut)) + _, _ = ledger.Append("child_output_received", map[string]any{ + "child_session": childSession, + "output_hash": outHash, + "output_len": len(childOut), + }) + + // emit_guarded (enforced) + preamble := fmt.Sprintf("Delegating to %s because %s.", agent, reason) + final := preamble + "\n" + childOut + _, _ = ledger.Append("final_output_emitted", map[string]any{ + "proof_ref": "proof-" + newID(), + "output_hash": sha256Hex([]byte(final)), + }) + + fmt.Println(final) + fmt.Println() + } + + if err := sc.Err(); err != nil { + fmt.Fprintln(os.Stderr, "read error:", err) + os.Exit(1) + } +}