Framework design upload

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