new stuff

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/

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

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

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 <agent> because <reason>.` Max 240 chars.

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)

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.

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.

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

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

MM/kernel/proto/README.md

@@ -0,0 +1,3 @@
+# Proto Artifacts
+
+Machine-readable scaffolding for early implementations.

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"}}
+  }
+}

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.

MM/kernel/supervisor-go/go.mod

@@ -0,0 +1,3 @@
+module cognitiveos/supervisor
+
+go 1.22

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)
+	}
+}