Framework design upload

CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing
+
+## Ground rules (please read)
+
+This project defines OS-level **governance** and **contracts** for probabilistic computation. It is not an “AGI” repo and it does not place LLMs in kernel space.
+
+### Non-negotiables
+
+- The control plane MUST be deterministic and auditable.
+- Models/workers MUST NOT receive ambient authority.
+- All tool execution MUST be capability-scoped and sandboxed.
+- Policies MUST live outside model weights.
+- Prefer small, composable primitives over monolithic designs.
+
+### What to contribute
+
+- Design docs with concrete invariants and failure modes.
+- Spec proposals for object model / syscalls (with versioning discipline).
+- OS mapping notes (FreeBSD and Linux).
+- Minimal prototypes that demonstrate enforcement boundaries.
+
+### What not to contribute (early)
+
+- “Put the model in the kernel” proposals.
+- Benchmark-driven complexity without a contract.
+- Unscoped tool execution paths.
+
+## Spec change process
+
+Specs in `spec/` are treated as contracts:
+- Breaking changes require an explicit note in the PR description.
+- Prefer additive changes.
+- Include an example flow in `examples/` when adding new primitives.
+

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,48 @@
+# Cognition OS
+
+Cognition OS is an operating-system-adjacent framework that treats probabilistic inference, context, attention, and memory as schedulable, governable resources. It provides deterministic control, isolation, capability-based security, and provenance for non-deterministic computation, while keeping all learning and inference in userland services.
+
+## What this is
+
+- A **spec + reference design** for a “cognitive kernel” (control plane) and userland++ services.
+- A place to define **contracts** (object model, syscalls/APIs, policy model, provenance) that can be implemented on top of classic OS kernels.
+
+## What this is not
+
+- **Not** “LLMs in kernel space.”
+- **Not** an AGI project.
+- **Not** a fork of FreeBSD/Linux (at least initially).
+
+## Core principles
+
+- Deterministic control plane; probabilistic workers.
+- Capability-based security; no ambient authority.
+- Explicit budgets (time, compute, context, risk).
+- Provenance as a first-class output.
+- Isolation domains for workers and tools.
+
+## Repository layout
+
+- `docs/` — narrative design docs (“why”).
+- `spec/` — contracts and invariants (“must not change casually”).
+- `freebsd/` — mapping to FreeBSD primitives (jails, Capsicum, kqueue, …).
+- `linux/` — mapping to Linux primitives (namespaces, seccomp, LSM, epoll, …).
+- `runtime/` — userland++ reference components (scheduler, tool broker, memory services).
+- `examples/` — end-to-end flows and scenarios.
+
+## Getting started
+
+Start reading:
+1. `docs/000-introduction.md`
+2. `docs/010-design-goals.md`
+3. `docs/030-architecture-overview.md`
+4. `spec/cognitive-syscalls.md`
+
+## Status
+
+This repository is **pre-implementation**. The initial goal is to stabilize a minimal v0.1 contract for:
+- cognitive object model
+- cognitive syscalls/APIs
+- provenance event model
+- OS mapping notes (FreeBSD first, Linux mapping in parallel)
+

docs/000-introduction.md

@@ -0,0 +1,15 @@
+# Introduction
+
+Classic operating systems were built to manage scarce physical resources (CPU time, memory pages, disk blocks, network sockets) and to provide deterministic execution semantics.
+
+Modern AI/LLM systems introduce a new class of workload:
+- probabilistic outputs
+- context-dependent behavior
+- expensive inference
+- heterogeneous accelerators
+- tool-based grounding with side effects
+
+Today these systems are assembled in userland using RPC, containers, and orchestration frameworks. That works, but the abstractions leak: context, provenance, budgets, and authority are not first-class OS concepts.
+
+**Cognition OS** is a spec and reference design for a “cognitive kernel” control plane that governs non-deterministic computation deterministically, while keeping all learning and inference in userland services.
+

docs/010-design-goals.md

@@ -0,0 +1,30 @@
+# Design goals
+
+## Primary goals
+
+1. **Deterministic governance**
+   - enforce policy outside model weights
+   - deterministic decisions for authority, budgeting, and audit
+
+2. **Capability-based execution**
+   - no ambient permissions for models or tools
+   - explicit, revocable capabilities with TTL and scope
+
+3. **Cognitive resources as first-class**
+   - context budgets, compute budgets, risk budgets
+   - cost-aware scheduling (latency vs confidence)
+
+4. **Provenance**
+   - structured event model for “what happened and why”
+   - support tamper-evident logging (later)
+
+5. **Isolation domains**
+   - strong sandboxing for tools and untrusted workers
+   - fault containment and graceful degradation
+
+## Non-goals (for v0.x)
+
+- kernel-resident LLM inference
+- universal scheduler for all workloads
+- solving “alignment” in the model
+

docs/020-threat-model.md

@@ -0,0 +1,22 @@
+# Threat model (draft)
+
+## Assets to protect
+- host filesystem and secrets
+- network access and credentials
+- tool side effects (writes, API calls, deletes)
+- user data and memory stores
+- audit and provenance integrity
+
+## Adversaries / failure modes
+- prompt injection leading to unsafe tool usage
+- malicious tool plugins
+- hallucinated or forged tool outputs
+- data exfiltration via tool channels
+- runaway cost due to repeated retries/loops
+
+## Strategy
+- least authority via capabilities
+- isolation domains for tool execution
+- policy gate for side effects
+- provenance for every tool call and memory commit
+

docs/030-architecture-overview.md

@@ -0,0 +1,43 @@
+# Architecture overview
+
+Cognition OS is layered:
+
+## Layer 0: Classic kernel
+FreeBSD / Linux provides:
+- process isolation
+- memory protection
+- basic resource controls
+- device drivers
+- confinement primitives (jails/namespaces)
+- security primitives (Capsicum / seccomp+LSM)
+
+## Layer 0.5: Cognitive kernel (control plane)
+A minimal trusted base that provides:
+- identity + provenance hooks
+- capability minting and enforcement boundaries
+- budget enforcement hooks (time/compute/context/risk)
+- isolation domain management
+- event bus for intent + constraints
+
+This can begin as a userland daemon, later optionally gaining kernel hooks.
+
+## Layer 1: Cognitive runtime (userland++)
+Composable services:
+- scheduler/router
+- context manager
+- memory services (working/episodic/semantic/symbolic)
+- tool broker (sandboxed execution)
+- policy engine (deterministic)
+
+## Layer 2: Workers
+Replaceable modules:
+- LLM inference worker(s)
+- retrieval workers
+- verification workers
+- perception workers (future)
+
+## Invariants
+- models do not directly invoke tools
+- tool execution requires explicit capabilities
+- provenance is produced for every side effect
+

docs/090-roadmap.md

@@ -0,0 +1,19 @@
+# Roadmap (draft)
+
+## v0.1 (contract-first)
+- cognition object model (Intent/Constraints/Capability/Event/Result)
+- cognitive syscalls/API (daemon IPC initially)
+- event provenance model
+- FreeBSD mapping notes (jails, Capsicum, kqueue)
+- minimal example flows
+
+## v0.2 (prototypes)
+- tool broker with capability-scoped execution
+- isolation domain prototypes (FreeBSD first)
+- audit log implementation (append-only)
+
+## v0.3 (workers)
+- pluggable worker interface
+- LLM worker as a replaceable component (CPU or remote)
+- verifier worker integration
+

examples/failure-handling.md

@@ -0,0 +1,8 @@
+# Failure handling (draft)
+
+## Hallucination / unsafe tool request
+- Worker proposes a risky action
+- Policy engine denies capability grant
+- Runtime returns a refusal or asks for confirmation per policy
+- Provenance logs the denial event
+

examples/minimal-flow.md

@@ -0,0 +1,11 @@
+# Minimal flow (draft)
+
+1. Client submits an `Intent` with `Constraints`.
+2. Runtime creates/uses a `domain_id`.
+3. Runtime invokes a worker to draft output.
+4. If tools are needed:
+   - runtime requests a capability from cognitive kernel
+   - tool runs in isolated domain with scoped authority
+5. Runtime synthesizes final `Result` with provenance links.
+6. Optional: memory commit is gated by policy and logged.
+

examples/tool-invocation.md

@@ -0,0 +1,12 @@
+# Tool invocation (draft)
+
+## Scenario
+User asks for DNS lookup.
+
+## Flow
+- Intent: "resolve A/AAAA for example.com"
+- Constraints: no network egress beyond DNS, low risk, small budget
+- Tool broker requests cap for `dns_lookup` tool
+- Tool runner executes with only required network access
+- Output is validated, logged as an Event, and returned
+

freebsd/README.md

@@ -0,0 +1,3 @@
+# FreeBSD mapping
+
+See `mapping.md`.

freebsd/mapping.md

@@ -0,0 +1,18 @@
+# FreeBSD mapping notes (draft)
+
+## Isolation domains
+- Use **jails** to isolate tools/workers.
+- Map `domain_id` to a jail instance.
+
+## Capabilities
+- Use **Capsicum** to restrict tool runners.
+- Capabilities are represented as scoped grants in the cognitive kernel and realized via Capsicum + pre-opened descriptors.
+
+## Eventing
+- Use **kqueue** for event-driven IO in the cognitive runtime.
+- Provenance logs are append-only files (optionally per-domain datasets on ZFS).
+
+## Resource control
+- rctl, login classes, cpuset can enforce limits.
+- Budgeting logic lives in the cognitive runtime; enforcement uses kernel primitives.
+

linux/README.md

@@ -0,0 +1,3 @@
+# Linux mapping
+
+See `mapping.md`.

linux/mapping.md

@@ -0,0 +1,18 @@
+# Linux mapping notes (draft)
+
+## Isolation domains
+- namespaces (pid, net, mount, user) + cgroups.
+
+## Capabilities / sandbox
+- seccomp for syscall filtering
+- LSM (AppArmor/SELinux/Landlock) for policy enforcement
+- ambient capabilities should be avoided; prefer explicit capability passing.
+
+## Eventing
+- epoll + structured logs
+- optional auditd hooks
+
+## Resource control
+- cgroups for CPU/memory/IO
+- accelerator scheduling will depend on driver/runtime stack
+

runtime/README.md

@@ -0,0 +1,10 @@
+# Runtime (userland++)
+
+This directory will contain reference components:
+- scheduler/router
+- context manager
+- tool broker
+- memory services
+
+Implementations should remain portable across FreeBSD/Linux.
+

spec/cognition-object-model.md

@@ -0,0 +1,26 @@
+# Cognition object model (draft)
+
+This document defines the core objects that flow through the system.
+
+## Intent
+- What is being requested?
+- Expected outputs and side effects (if any)
+
+## Constraints
+- Budgets: time, compute, context, risk
+- Policy set references
+- Tool allow/deny lists
+
+## Capability
+- Granted authority for a specific action/tool
+- Scope, TTL, limits, revocation
+
+## Event (provenance)
+- Immutable record of an action taken
+- Includes: who/what, inputs, outputs, timestamps, capability IDs
+
+## Result
+- Output payload
+- Confidence/uncertainty metadata
+- Provenance links (event IDs)
+

spec/cognitive-syscalls.md

@@ -0,0 +1,35 @@
+# Cognitive syscalls / API (v0.1 draft)
+
+These are conceptual “syscalls” exposed by the cognitive kernel control plane.
+They may be implemented via IPC initially.
+
+## Domain management
+- `cog_domain_create(policy_ref) -> domain_id`
+- `cog_domain_destroy(domain_id)`
+
+## Capability management
+- `cog_cap_grant(domain_id, target, scope, ttl, limits) -> cap_id`
+- `cog_cap_revoke(cap_id)`
+- `cog_cap_introspect(cap_id) -> metadata`
+
+## Invocation
+- `cog_invoke(worker_id, intent, constraints) -> result`
+- `cog_tool_exec(cap_id, tool_ref, args, io_handles) -> tool_result`
+
+## Accounting / budgets
+- `cog_meter(domain_id) -> usage`
+- `cog_budget_set(domain_id, budgets)`
+- `cog_budget_enforce(domain_id)`
+
+## Provenance
+- `cog_event_append(event) -> event_id`
+- `cog_event_query(filters) -> events`
+
+## Memory gates
+- `cog_mem_commit(domain_id, record, policy_ref) -> commit_id`
+- `cog_mem_query(domain_id, query, constraints) -> records`
+
+Notes:
+- v0.1 favors auditable simplicity over completeness.
+- Worker and tool references should be stable identifiers.
+

spec/event-provenance.md

@@ -0,0 +1,23 @@
+# Event provenance (draft)
+
+## Goals
+- Record what happened and why.
+- Enable audit and debugging.
+- Support tamper-evident logging later.
+
+## Event fields (suggested)
+- `event_id`
+- `ts`
+- `domain_id`
+- `actor` (worker/tool)
+- `intent_ref`
+- `capability_id` (if applicable)
+- `inputs` (hashed or redacted as policy requires)
+- `outputs` (hashed or redacted)
+- `status` (ok/denied/error)
+- `cost` (latency, cpu, etc.)
+
+## Storage
+- append-only log per domain
+- optional ZFS dataset per domain in homelab deployments
+

spec/memory-hierarchy.md

@@ -0,0 +1,14 @@
+# Memory hierarchy (draft)
+
+## Tiers
+- Ephemeral context (prompt/session window)
+- Working memory (session state)
+- Episodic memory (event timeline)
+- Semantic memory (facts/documents)
+- Symbolic memory (rules/constraints)
+
+## Rules
+- commits are gated by policy
+- decay/retention is explicit
+- provenance links to commits
+

spec/policy-model.md

@@ -0,0 +1,17 @@
+# Policy model (draft)
+
+Policies are deterministic rules enforced outside model weights.
+
+## Policy dimensions
+- tool allow/deny
+- network egress constraints
+- filesystem scope constraints
+- side-effect confirmation requirements
+- budget ceilings and escalation rules
+- data classification rules (PII, secrets, etc.)
+
+## Representation
+Initial representation may be:
+- YAML/JSON policy documents
+- versioned and referenced by `policy_ref`
+