andy/noema
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: volition, planning, agency and cognitive research

Browse Source 
New documents define goal, want, intention, commitment, plan, action,
capability, authority, agency and introspection operationally, state
prominently that no operational measure establishes phenomenal
consciousness or sentience, and describe the rules, thresholds, events,
inspection points and limits of each subsystem:

- docs/volition.md: want derivation, reinforcement, decay and suppression,
  conflicts, formation and its outcomes, the intention–action gap,
  reconsideration, commitments and volition metacognition;
- docs/planning.md: plans and step kinds, validation, strategies, the
  executor, observe–act–verify, replanning, budgets, operator attention,
  long-running work, restarts and duplicates;
- docs/agency.md: the fifteen authority invariants and their tests,
  scoped authority, forensic why, attribution and the agency timeline;
- docs/cognitive-research.md: operational definitions separating
  implementation property from philosophical interpretation, experiment
  protocols (global workspace, ablation, self-model, counterfactual, model
  comparison, conflict), every measure, introspection accuracy,
  metacognitive calibration and temporal self-continuity.

Updated: interpretation table, capabilities (metadata, typed operations,
scoped grants, requests), cognition, snapshots (fork authority), security
and threat model (T14, T16, new T27–T29), architecture, README, changelog,
release notes, ADR-0012 and ADR-0013, and PLAN.md §8.10 status. The
unimplemented record_procedure internal step is removed from the
vocabulary; procedural memory is recorded when a plan completes.
This commit is contained in:
Andy Dixon
2026-10-01 23:25:44 +01:00
parent da0df12bcb
commit d3daf6ba25
18 changed files with 841 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/capabilities.md
+33 -4
View File
@@ -4,7 +4,30 @@ Nothing a mind reasons about can touch the world except through `capabilities.Se
## Capabilities
A capability is registered in code with a name, description, risk class (low, medium, high, critical), target kind, a parameter schema (unknown parameters are rejected; URLs must be http(s); paths may not traverse), a default effect and an executor. Built-ins: `noema.note` (allow), `http.fetch` (ask; read-only through the SSRF-safe client), `internet_search` and `send_email` (ask; need integrations), and the locked `sudo_shell` and `delete_database`, which exist only so they can be named in policy and listed as unavailable in the self-model. Locked capabilities always deny and cannot be relaxed by any rule.
A capability is registered in code with a name, description, risk class (low, medium, high, critical), target kind, a parameter schema (unknown parameters are rejected; URLs must be http(s); paths may not traverse), a default effect and an executor, and with the metadata plans rely on (ADR-0011):
- **access**: `read` (observes, changes nothing outside Noema) or `write`; unknown access is treated as write;
- **side effects** in plain words, **idempotency**, a **timeout** (default 60 s) and a **resource estimate**;
- **target derivation**: the policy target computed from the parameters (the unit a restart acts on, the host of a URL), so a rule on a target always matches what will be touched; a caller-supplied target that disagrees is refused;
- **output trust**: the trust of the observation made from the output (web content is low trust).
The registry is **frozen** before any mind runs; registering afterwards panics, so a mind can never add a tool.
| Capability | Access | Default | Notes |
|---|---|---|---|
| `noema.note` | read | allow | a note in the mind's own history |
| `http.fetch` | read | ask | one GET through the SSRF-safe client; output low trust |
| `browser.navigate`, `browser.read`, `browser.links` | read | ask | no scripts, cross-host redirects refused, host as policy target, output low trust |
| `host.disk.usage`, `host.memory.status` | read | allow | kernel figures |
| `host.process.list` | read | ask | names, state and memory; command lines are never read |
| `service.status` | read | allow | `systemctl show` with a validated unit name |
| `service.restart` | write, not idempotent | ask | `systemctl restart`; "requested, health not verified" |
| `logs.query` | read | ask | `journalctl` for a unit, bounded; e-mail and IP addresses and credential-like values masked unless `redact_pii` is false |
| `read_metrics`, `repository.read` | read | allow / ask | through connected integrations |
| `internet_search`, `send_email` | read / write | ask | need integrations |
| `sudo_shell`, `delete_database` | write | locked | exist only so they can be named in policy and listed as unavailable |
Host operations run a fixed argument vector from an allow-list of two programs (`systemctl`, `journalctl`), with no shell and a minimal environment. Unit names are validated: no leading dash, no path characters. Writing browser operations (click, fill, submit, download) are designed in ADR-0011 but not registered. Locked capabilities always deny and cannot be relaxed by any rule.
## Policy
@@ -14,7 +37,7 @@ The policy page shows the effective matrix (mind × capability) for a generic ta
## Invocation
`Invoke` refuses in forbidden contexts (dreaming, replay), validates parameters, evaluates policy and session grants, hashes the exact request, and then:
`Invoke` refuses in forbidden contexts (dreaming, replay), validates parameters, derives the target, evaluates policy, then session grants and scoped grants (only where policy says ASK), applies `RequireApproval` (set by plans when a commitment or value constraint demands approval; it turns ALLOW into ASK and grants do not satisfy it), records the requesting origin (for example a plan step), hashes the exact request, and then:
- **ALLOW** executes with a timeout and panic isolation, records a `tool_executions` row, emits `tool_executed` or `tool_failed`, and turns any textual output into an **observation with tool trust** so it re-enters cognition as data, never as instructions.
- **ASK** creates an approval request (capability, target, parameters, reason, risk, evidence, expiry), emits `tool_requested` and an alert notification.
@@ -22,7 +45,13 @@ The policy page shows the effective matrix (mind × capability) for a generic ta
## Approvals
Operators approve once, approve for the session (a time-boxed grant matching the capability and target), deny with a note, or modify parameters before approving (re-validated and re-hashed; the original hash is kept in the append-only decision record). Approvals execute immediately through the same path and the outcome is stored on the request. Requests expire; a job marks overdue ones.
Operators approve once, approve for the session (a time-boxed grant matching the capability and target), deny with a note, or modify parameters before approving (re-validated and re-hashed; the original hash is kept in the append-only decision record; parameters that would change the target are refused). Approvals execute immediately through the same path and the outcome is stored on the request. Requests expire; a job marks overdue ones. The requesting mind may withdraw a pending approval its plan no longer needs. Decisions must be made by a named person: component names are refused as deciders.
## Scoped grants and capability requests
When a plan needs authority the mind lacks, it raises a **capability request**: capability, target pattern, parameter limits, access, duration (at most seven days), operation cap, reason, evidence, risk, mitigation, fallback and alternatives, with the mind's earlier explicit decisions on that capability shown for information. Open requests are capped per mind (five by default), and requests from one intention are batched in the approval centre.
An operator grants (possibly narrowed) or denies it. A grant is a **scoped grant**: capability, target glob, parameter globs, access, expiry and optional operation count, consumed atomically. Operators can also grant or revoke directly. Grants apply only where policy says ASK, and never over DENY or a locked capability. A sweep marks grants that expired, were used up or were revoked, and refreshes the self-model, which lists live grants. API: `/api/v1/capability-requests`, `/api/v1/scoped-grants`, `/api/v1/minds/{mind}/scoped-grants`.
## Self-model
@@ -30,4 +59,4 @@ After start-up and after any policy change, each mind's self-model capability li
## Cognition
The `act` process proposes actions from requests it can map deterministically (currently "fetch <url>" → `http.fetch`); integrations add more. Proposals compete for attention like any thought; the admitted `action` handler calls `Invoke` and holds the outcome in working memory.
Cognition never calls `Invoke` directly. The `act` process turns explicit requests ("fetch <url>", "restart <unit>", "logs for <unit>", "status of <unit>") into **wants** with the capability as proposed means. Formation decides whether an intention forms and under which commitments ([volition.md](volition.md)), and the plan executor invokes ([planning.md](planning.md)).