mmolloy/Cognition-OS
1
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor of repo

Browse Source
This commit is contained in:
deamonkai
2026-02-17 21:33:38 -06:00
parent 9ce36d2385
commit 60b1da0cc2
17 changed files with 28 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
MM/README.md
View File

@@ -1,23 +0,0 @@
# 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/

20
MM/docs/KERNEL-ROADMAP.md
View File

@@ -1,20 +0,0 @@
# 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

10
MM/docs/RFC-INDEX.md
View File

@@ -1,10 +0,0 @@
# 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

18
MM/docs/rfcs/RFC-0007-Delegating-Router.md
View File

@@ -1,18 +0,0 @@
# 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.

14
MM/docs/rfcs/RFC-0008-Capability-Guard-Framework.md
View File

@@ -1,14 +0,0 @@
# 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)

15
MM/docs/rfcs/RFC-0009-Event-Ledger-Primitive.md
View File

@@ -1,15 +0,0 @@
# 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.

13
MM/docs/rfcs/RFC-0010-Guarded-Emit-Syscall.md
View File

@@ -1,13 +0,0 @@
# 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.

36
MM/docs/rfcs/RFC-0011-Session-Spawn-Primitive.md
View File

@@ -1,36 +0,0 @@
# 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

36
MM/docs/rfcs/RFC-0012-Deterministic-Retry-Controller.md
View File

@@ -1,36 +0,0 @@
# 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

3
MM/kernel/proto/README.md
View File

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

14
MM/kernel/proto/delegation_proof_schema.json
View File

@@ -1,14 +0,0 @@
{
"$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"}}
}
}

16
MM/kernel/supervisor-go/README.md
View File

@@ -1,16 +0,0 @@
# 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.

3
MM/kernel/supervisor-go/go.mod
View File

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

205
MM/kernel/supervisor-go/main.go
View File

@@ -1,205 +0,0 @@
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)
}
}