Framework design upload

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`
+