If you are new to CCA8: read 1-minute + 5-minute summary, try the 5-step demo, then jump to ‘The WorldGraph in detail’ and ‘Action Selection’.

The Tutorials below (see Table of Contents) are designed to teach you the practical aspects of the CCA8 as well as some of the theory behind it.

Questions? Send me an email: hschneidermd@alum.mit.edu

The CCA8 Project is the simulation of the brain of a mountain goat through the lifecycle with hooks for different robotic embodiments.

Scaffolding in place (partially operational) for simulation of a chimpanzee-like brain, human-like brain, human-like brain with five brains operating in parallel in the same agent, human-like brain with multiple agents interacting, human-like brain with five brains operating in parallel with combinatorial planning ability.

This single document is the canonical “compendium” for the Causal Cognitive Architecture 8 (CCA8). It serves as: README, user guide, architecture notes, design decisions, and maintainer reference.

Repo: https://github.com/howard8888/workspace Entry point: >python cca8_run.py

The program will run on most computers, although different sets of features (as well as embodiments, of course) will be available.

Adult Mountain Goat with recently born Calf (walking within minutes of birth, and by one week can climb most places its mother can)

CCA8 Simulation of a mountain goat through the lifecycle CCA8b Simulation of a mountain goat-like brain with 5 brains within the same agent CCA8c Simulation of multiple agents with goat-like brains able to interact CCA8d Simulation of a mountain goat-like brain with 5 brains within the same agent with combinatorial planning CCA9 Simulation of a chimpanzee through the lifecycle CCA10 Simulation of a human through the lifecycle

See References Section for published peer reviewed articles on the CCA7 and earlier versions

Notes:

-Versions of Python that will work with code: check docstring of cca8_run.py or requirements.txt (at time of writing, tested on Windows 11 Pro with Python 3.11.4)

-Dependencies required: check docstring of cca8_run.py or requirements.txt     --> Software should be able to run on most systems without any issues (GPU and LLM API requirements, if used, are very fail-safe)

-Windows: >python cca8_run.py will also usually work, depending on Python setup; it will ignore the shebang line (>cca8_run.py may work if Windows file associations set up for the Python version)

-Mac, Linux: >python3 cca8_run.py

-Virtual environment Venv (must activate) (Windows, Mac or Linux): >python cca8_run.py

-Graphical User Interface (GUI): Due to ongoing software development, the CCA8 Simulation is Command-Line Interface (CLI) only. (Tkinter Windows GUI-based cca8_run.pyw module is available but not supported at this time.)

-Robotics real-world environment: You need to run the Python environment version of cca8_run.py as shown above, and specify the robotics embodiment as shown above. (Ensure that the correct hardware abstraction layer (HAL) exists and is installed for the robotics equipment version you are using.)

CCA8 aims to simulate early mammalian cognition with a small symbolic episode index (the WorldGraph) coordinating rich engrams (perceptual/temporal content) in a column provider. Symbols are used for fast indexing & planning, not as a full knowledge store.

Core model:

• Binding — a node instance that carries one or more tags, including pred:<token>, plus meta and optional engrams; bindings can hold predicates pred:, actions action:, anchors, cues

• Edge — a directed link between bindings with a label (often "then") representing weak, episode-level causality (“this led to that”).

• WorldGraph — the directed graph composed of these bindings and edges, supports BFS planning.

• Policy (primitive) — an instinctive behavior with trigger() + execute(). The Action Center scans policies in order and runs the first whose trigger matches current drive tags (hunger/fatigue/warmth).

• Provenance — when a policy creates a new binding, its name is stamped into binding.meta["policy"].

• Autosave/Load — a JSON snapshot persists (world, drives, skills) with saved_at, written via atomic replace. --> See Tutorial Sections below for more information

Here is a concrete example of a short episode you can build by hand or through the menu. (Note: Software may change in the future. If exact menu selections are not available, please choose similar items. Nov, 2025.)

1. Start or resume

python cca8_run.py --autosave session.json

Pick Profile 1: Mountain Goat when prompted.

2. Note binding IDs you’ll need

Show last 5 bindings anytime to grab the newest IDs you create.

3. (Optional) Prime drives and cues

• Select 'Autonomic tick' once or twice, then D Show drives (aim for drive:hunger_high).

• Select Add sensory cue a few times:

  • vision → silhouette:mom

  • smell → milk:scent

  • sound → bleat:mom

4. Create milestones (add predicates), then wire edges

A. Stand first

1. Add predicate → stand → note ID, e.g., b2.

2. Connect two bindings:

   • Source: <NOW_id> (e.g., b0)

   • Destination: <stand_id> (e.g., b2)

   • Relation: stand_up

B. Approach mom

1. Add predicate → mom:close → note ID, e.g., b3.

2. Connect:

   • Destination: <mom_id> (e.g., b3)

   • Relation: approach

C. Find nipple

• Source: <stand_id> (e.g., b2)

1. Add predicate → nipple:found → ID b4.

2. Connect b3 → b4 with relation search.

D. Latch

1. Add predicate → nipple:latched → ID b5.

2. Connect b4 → b5 with relation latch.

E. Drink

1. Add predicate → milk:drinking → ID b6.

2. Connect b5 → b6 with relation suckle.

5. Verify with planning

• Plan from NOW → <predicate>

• Target: milk:drinking

• Expect a path like: NOW (b0) → stand (b2) → mom:close (b3) → nipple:found (b4) → nipple:latched (b5) → milk:drinking (b6)

Useful Command-line Quickstarts:

Start a new simulation: >python cca8_run.py

Start a new simulation and autosave it: >python cca8_run.py --autosave mysession.json

Resume a previous simulation and autosave it to the same file:          >python cca8_run.py --load mysession.json --autosave mysession.json

Resume a previous simulation and autosave it to a new file:          >python cca8_run.py --load mysession.json --autosave newfile.json

(Note: the order of --load and --autosave doesn't matter )

Version info (all components): >python cca8_run.py --about

Runner (main program) Version only: >python cca8_run.py --version

Preflight self-testing (four parts): >python cca8_run.py --preflight

Use with robotic embodiment: >python cca8_run.py --hal --body myrobot

CCA8 Python Major Modules:

cca8_run.py (informal name: "Runner module" or "Main module")

cca8_world_graph.py (informal name: "WorldGraph module")

cca8_column.py (informal name: "Column module")

cca8_controller.py (informal name: "Controller module")

cca8_features.py (informal name: "Features module")

cca8_temporal.py (informal name: "Temporal module")

cca8_env.py (informal name: "Environment module")

cca8_test_worlds.py (informal name: "Test Worlds module")

Q: What is the core split in CCA8’s memory representation? A: A small symbolic WorldGraph (~5%) used for fast indexing and planning, and rich engrams (~95%) stored in Columns. The graph knows “what led to what”; the engrams hold heavy perceptual/temporal content.

Q: In the 5-step newborn demo, what does the planner actually search over? A: It runs BFS from the NOW anchor over directed edges and looks for any binding whose tags contain the target pred: (e.g., pred:milk:drinking). It doesn’t care about engram payloads; only tags and edges matter for planning.

Q: Why is StandUp the first primitive in the newborn goat’s repertoire? A: Because standing up is a precondition for almost everything else in the newborn vignette (orienting to mom, seeking the nipple, moving to shelter). It’s both ethologically plausible and structurally convenient: it creates the first meaningful S–A–S pattern (fallen → actions → standing) in the WorldGraph.

Q: Where is provenance recorded in step 5 (drink)? A: On each binding created by a policy, e.g. binding.meta["policy"] = "policy:seek_nipple" or "policy:suckle". This lets you reconstruct “which policy wrote this node” when reading graphs or debugging.

Q: Why did you decide to keep control flow (policies) outside the graph instead of encoding everything as rules in the graph? A: To keep the system readable, testable, and flexible. Small, handwritten policies are easy to reason about and modify; the graph records what actually happened (episodes), not entire control logic. This follows the “index vs representation” and “program + data” split, rather than trying to cram cognition into a single giant graph.

Q: Which primitives form “standing”?
A: action:push_up, action:extend_legs, and the predicate pred:posture:standing (based on the posture:standing tag).

Q: What’s the planner algorithm?
A: BFS from NOW to the first pred: match.

Q: What’s the key separation in CCA8?
A: A compact symbolic episode index** (WorldGraph) for fast lookup/plan, and rich engrams** outside the graph for heavyweight content.

Q: Are edges logical implications?
A: No—edges encode weak, episode-level causality** (“then”), good for action and recall without heavy inference.

Q: Why not store everything in the graph? A: Keeping symbols small avoids brittleness and keeps planning fast, the heavy 95% lives in engrams referenced by bindings.

Q: How does this help planning? A: BFS over a sparse adjacency list gives shortest-hop paths quickly, the graph is shaped for that.

Introduction to the Causal Cognitive Architecture 8 (CCA8)

• Executive Overview
• Opening screen (banner) explained
• Profiles (1–7): overview and implementation notes
• The WorldGraph in detail
• Tagging Standard (bindings, predicates, cues, anchors, actions, provenance & engrams)
• Restricted Lexicon (Developmental Vocabulary)
• Signal Bridge (WorldGraph ↔ Engrams)
• Architecture
  • Modules (lean overview)
  • Timekeeping in CCA8 (five measures)
  • Data flow (a controller step)
• Action Selection: Drives, Policies, Action Center
• Planner Contract
• Planner: BFS vs Dijkstra (weighted edges)
• Persistence: Autosave/Load
• Runner, menus, and CLI
• Logging & Unit Tests
• Preflight (four-part self-test)
• CCA8 as a Robotic Cognitive Operating System (RCOS)
• Hardware Abstraction Layer (HAL)
• Hardware preflight lane (status stub)
• How-To Guides
• Data schemas (for contributors)
• Traceability (requirements to code)
• Roadmap
• Debugging Tips (traceback, pdb, VS Code)
• FAQ / Pitfalls
• Intro Glossary

Tutorials and technical deep dives

• Tutorial on WorldGraph, Bindings, Edges, Tags and Concepts
• Binding and Edge Representation
• Anchors, LATEST, and Base-Aware Writes
• Tutorial on Drives
• Tutorial on WorldGraph Technical Features
• Tutorial on Breadth-First Search (BFS) Used by the CCA8 Fast Index
• Tutorial on BodyMap
• Tutorial on Main (Runner) Module Technical Features
• Tutorial on Controller Module Technical Features
• Tutorial on Reinforcement Learning in the CCA8
• Tutorial on Temporal Module Technical Features
• Tutorial on Features Module Technical Features
• Tutorial on Column Module Technical Features
• Tutorial on Approach to Simulation of the Environment
• Tutorial on Environment Module Technical Features
• Planner contract (for maintainers)
• Persistence contract

References and Notes

• References
• Developer and Maintainer Notes

Opening screen:

A Warm Welcome to the CCA8 Mammalian Brain Simulation (cca8_run.py v0.7.11)

Entry point program being run: C:\Users\howar\workspace\cca8_run.py OS: win32 (run system-dependent utilities for more detailed system/simulation info) (for non-interactive execution, ">python cca8_run.py --help" to see optional flags you can set)

Embodiment: HAL (hardware abstraction layer) setting: off (runs without consideration of the robotic embodiment) Embodiment: body_type-version_number-serial_number (i.e., robotic embodiment): none specified

The simulation of the cognitive architecture can be adjusted to add or take away various features, allowing exploration of different evolutionary-like configurations.

1. Mountain Goat-like brain simulation
2. Chimpanzee-like brain simulation
3. Human-like brain simulation
4. Human-like one-agent multiple-brains simulation
5. Human-like one-brain simulation × multiple-agents society
6. Human-like one-agent multiple-brains simulation with combinatorial planning
7. Super-Human-like machine simulation

Pending additional intro material here.... Please make a choice [1-7]:*

What each part means:

• Version and path: printed by the runner, the version comes from __version__ in the runner. The path helps confirm which file you launched.

• OS/flags line: a reminder that you can run --help or the non-interactive flags such as --about, --plan, --preflight.

• Embodiment (HAL/body): shows whether the hardware abstraction layer is enabled and which body profile (if any) was provided. The current build runs fine with HAL off.

• Profile menu: seven presets that configure or demonstrate different cognitive configurations (documented below). Selection is handled by choose_profile, which records your choice in the runtime context and proceeds with the session.

Q: Why does the banner show a full filesystem path to cca8_run.py? A: To make it obvious which file you actually launched (and from where). This avoids confusion if you have multiple checkouts or stale copies; you can confirm you’re running the expected entry point.

Q: What is the practical use of the OS/flags line (win32, --help, etc.)? A: It reminds you that (1) you’re on a particular platform (Windows/macOS/Linux), which may affect file paths and HAL support, and (2) you can always run --help, --about, or --preflight from the CLI instead of entering the menu.

Q: What does “HAL (hardware abstraction layer) setting: off” actually mean? A: It means the simulation is currently running headless: policies and WorldGraph are active, but no physical robot or real sensors are connected. When HAL is ON with a body profile, controller outputs can be forwarded to hardware via the HAL.

This section documents what each profile intends to represent and how the current runner implements it. Items 2–7 are demonstration stubs that explain the idea, print a short trace, and then fall back to the Mountain Goat profile so today’s simulation continues unchanged.

1. Mountain Goat-like brain simulation
   Baseline profile focused on a neonate mountain goat. Defaults: sigma=0.015, jump=0.2, winners_k=2. A boot step ensures a stand intent early in the episode. Use this profile for all current demos and for reading the code.

2. Chimpanzee-like brain simulation
   Narrative only. Prints an explanation of enhanced feedback pathways and combinatorial language relative to the goat, then falls back to the Mountain Goat defaults. This is a placeholder for a richer causal model.

3. Human-like brain simulation
   Narrative only. Prints an explanation of further-enhanced feedback pathways, causal and analogical reasoning, then falls back to the Mountain Goat defaults.

4. Human-like one-agent multiple-brains simulation
   Implements a dry-run “multi-brains” scaffold inside one agent. The runner forks five sandbox WorldGraphs (deep copies of the live world for now), each proposes a next action with a confidence and rationale, and a voting rule selects the winner (most popular, ties broken by average and maximum confidence). No changes are committed to the live world, it is a read-only demonstration of the mechanism. Future work would merge only new nodes/edges from the winning sandbox and re-id them to avoid collisions.

5. Human-like one-brain × multiple-agents society
   Implements a dry-run “society” scaffold. The runner creates three independent agents, each with its own WorldGraph and Drives, runs one action-center tick per agent, and demonstrates a simple inter-agent message as a cue (e.g., A1 bleats, A2 receives a sound cue). No snapshots are written, this is a safe, print-only demo. In a full build, you would iterate over agents each tick and exchange messages via a queue or shared mailbox.

6. Human-like one-agent multiple-brains with combinatorial planning
   Implements a dry-run combinatorial planner. Five “brains” each run many von Neumann processors (configurable, the current stub uses 256 per brain) to explore short candidate plans, score them with a simple utility (sum of action rewards minus a per-step cost), report the per-brain best and average score, and then select a champion brain. In a real system only the first action of the winning plan would be committed to the live world after a safety check, the stub prints the commit rule but does not modify state.

7. Super-Human-like machine simulation
   Implements a dry-run meta-controller. Three proposal sources (symbolic search, neural value, program synthesis) each provide an action and a utility, the meta-controller picks the winner by score with a fixed tie-break preference. The printout illustrates how a higher-level controller could arbitrate between heterogeneous planners. No state is modified.

Q: Which profile should I use for real experiments right now? A: Use Profile 1 (mountain goat). At the time of this writing, it's the profile that is fully wired to drives, policies, the newborn storyboard environment, and the runner. The others are narrative/dry-run stubs that fall back to Profile 1.

Q: Do the multi-brain / multi-agent profiles modify the live WorldGraph today? A: No. At present, they typically operate on sandbox copies of the world (or separate worlds) and print results, but they do not commit changes back to the live WorldGraph. That keeps the core goat simulation deterministic and easy to reason about.

Q: What is the practical difference between “human-like” and “super-human-like” profiles today? A: At the time of writing, the difference is mainly in the story and trace they print: the “super-human-like” profile demonstrates a dry-run meta-controller that arbitrates between heterogeneous proposal sources. Neither profile currently runs a distinct, fully human-level cognitive architecture; they are scaffolds for future work.

Q: How do profiles interact with the rest of the code? A: Each profile sets initial parameters in Ctx (sigma, jump, profile label), may run a stub/demo, and then hands control back to the same runner loop. The WorldGraph, controller, and environment interfaces remain the same; only initial configuration and demonstration traces change.

Nodes (Bindings):

A binding carries:

• tags: a list of strings. One is always a predicate like pred:stand or pred:nurse. Optional tags include anchors (anchor:NOW) or cues (cue:scent:milk).
• engrams: optional pointers to richer content, e.g., {"column01": {"id": "...", "act": 1.0}}.
• meta: provenance and light context (policy name that created it, timestamps, etc.).

Bindings live in an index by id (b1, b2, …). The id is what edges point to.

Edges (Links):

Edges live in a simple adjacency list: src_id -> [{ "to": dst_id, "label": "then", "meta": {...}}, ...].

Design decision (ADR-0001 folded in): We keep edges small and directed, multiple distinct edges between the same nodes are allowed if their labels differ (e.g., “then”, “causes”), dedup is left to the caller and the UI can warn on duplication.

Anchors:

The graph maintains special anchor bindings such as NOW (the current temporal anchor). The UI prints NOW and LATEST to orient you while you explore or plan.

Planning:

Planning is BFS (breadth first search) from a start binding (usually NOW) to any binding that has a goal tag (e.g., pred:nurse). We search over the adjacency list and keep a parent map to reconstruct the shortest path in edges. Because edges are unweighted, BFS is sufficient and guarantees fewest hops.

Design decision (was ADR-0004, runner UX): The CLI provides a one‑shot plan with --plan <token> and a menu item to plan interactively from NOW. For clarity, plans are shown both as raw ids and as a “pretty path” where each id is printed with its first pred:* tag. The HTML graph export can make these paths visible at a glance.

We decided not use a library to implement the WorldGraph but instead have coded it entirely in Python within the program because:

1. The symbolic WorldGraph only holds about 5% of the information of the CCA8 cognitive architecture. The rich store of information is in the engrams to which the WorldGraph must link. This was difficult to do with SciPy sparse or retworkx/igraph.

2. For development scale simulations the Python code should run fast enough. For larger simulations (e.g., a billion nodes) the WorldGraph and BFS will, of course, need more scalable representations.

3. Note that we are using deques in our Python code which unlike the O(n) behavior of lists, gives O(1) behavior for popleft() -- manipulation of the WorldGraph appears quick enough for small to medium simulations.

Indexing & goal resolution (how the planner finds a match)

The planner checks each popped node’s tags for a goal predicate (pred:<token>). Implementations may also keep a tiny tag→binding index to accelerate goal detection on large runs. Either way, a match is defined as “any binding whose tags contains the requested goal token.” If multiple candidates exist, BFS guarantees the first one popped is on a shortest-hop path from the start. This makes planning both predictable and easy to reason about in logs and demos.

Edge-label conventions (house style)

• Operationally, all edges mean “then”: “this binding tended to be followed by that binding in this episode”.

• The default label is "then". You may use short domain labels as human-facing aliases when helpful, but the engine treats them as “then”:

  • approach: locomote toward a target (standing → mom:close).
  • search: information-seeking (mom:close → nipple:found).
  • latch: discrete contact (nipple:found → nipple:latched).
  • suckle: sustained feeding (nipple:latched → milk:drinking).

  Think of these as "then (approach)", "then (search)" etc.

• Actions themselves live as action:* bindings in the graph (e.g., action:push_up, action:extend_legs). Policies create small predicate–action–predicate chains by connecting predicate states and action bindings with then edges.

Consistency invariants (quick checklist)

• Every binding has a unique id (bN), and anchors (e.g., NOW) map to real binding ids.

• Edges are directed, the adjacency lives on the source binding’s edges[].

• A binding without edges is a valid sink.

• The first pred:* tag is used as the default UI label, if absent, the id is shown.

• Snapshots must restore latest, anchor ids, and advance the internal bN counter beyond any loaded ids.

Scale & performance notes

For development scale (up to hundreds of thousands of bindings), the dict-of-lists adjacency plus a deque frontier is fast and transparent. If the graph grows toward tens of millions of edges, swap the backend (e.g., CSR or a KV store) behind the same interface without changing runner semantics or user-facing behavior..

Families recap. WorldGraph stores only pred:*, action:*, cue:*, and anchor:*. The controller may compute drive:* flags for triggers, but they are never written into the graph unless you explicitly add pred:drive:* or cue:drive:*.

Q&A to help you learn this section

Q: How are edges stored?
A: On the source binding in an adjacency list: each edge is {to, label, meta}.

Q: Do we dedupe edges?
A: The design allows multiple edges, the UI warns if you add an identical labeled edge so you can skip duplicates.

Q: What labels should I use?
A: "then" for episode flow, you can add others like approach, search, latch, suckle to clarify intent.

Q: How does NOW behave?
A: It’s a named binding used as the plan start and orientation point in the runner and visualizations.

Q: Why a deque?
A: O(1) popleft() for BFS frontiers (lists would be O(n) for pop(0)).

Drives, Policies, and the Action Center:

The controller tracks simple drives (hunger, fatigue, warmth). Policies consume those signals and look for tags in the WorldGraph or context to decide whether to act. The Action Center asks policies in a fixed order “are you ready? ” and executes the first one that returns true.

Example (stand up):

Example (stand up):

• Trigger: posture:fallen is near NOW and the body is not severely fatigued.
• Execute: emit an action:push_up binding and an action:extend_legs binding, then a pred:posture:standing binding, linked in a short chain from NOW/LATEST with then edges.

Q&A to help you learn this section Q: How is an action chosen each tick?
A: The Action Center scans policies in a fixed order and runs the first whose trigger() returns True given current drives/tags.

Q: What prevents re-firing the same action?
A: Guards in trigger() (e.g., StandUp checks that standing isn’t already true).

Q: What does a policy return?
A: A small status dict (policy name, ok/fail/noop, reward, notes) and it stamps provenance on any binding it creates.

Q: What if drive predicates aren’t available?
A: Policies degrade gracefully by relying on existing graph tags, the system keeps running.

How do policies work in the CCA8 architecture?

You should think of how policies work in terms of three states (which actually map very cleanly to what CCA8 is doing in code):

1. Gating

   • “Is this policy even allowed in the candidate set right now?”

   • Includes:

     • dev_gate(ctx) (e.g., neonatal-only policies)
     • safety overrides (e.g., “if fallen, only allow StandUp/RecoverFall”)

   • Everything that fails here is out before we even look at drives or world.

2. Triggering

   • For the policies that passed gating: “Given world + drives + BodyMap, does this policy want to fire now?”
   • Implemented by each policy’s trigger(world, drives, ctx).
   • If trigger(...) is True → the policy is triggered and joins the candidate list for this tick.

3. Executing

   • Among all triggered policies, pick one to actually run.

   • This is where we define “best”:

     • drive deficit scores (hunger vs fatigue, etc.),
     • maybe a preferred action,
     • tie-breaking / ordering.

   • The winner gets:

     • logged as [executed] policy:...,
     • its primitive run in the Action Center,
     • its name fed into env.step(action=...) next tick.

So in short:

Allowed → Triggered → Executed (gating → triggering → winner)

Q&A to help you learn this section

Q: What is a “policy” in CCA8? A: A policy is a named behaviour like policy:stand_up, policy:seek_nipple, policy:follow_mom, or policy:rest. Each policy has:

a gate (dev + safety),

a trigger function,

and a primitive that actually runs when the policy is selected to execute.

Q: What does “gating” really do? A: Gating answers: “Is this policy even allowed to be considered right now?” Examples:

dev_gate(ctx) filters out policies that don’t apply to the current profile (e.g., neonatal-only).

The safety override may say “if BodyMap says fallen, only allow StandUp/RecoverFall.” If a policy fails gating, its trigger is never even called that tick.

Q: How is “triggering” different from “gating”? A: Gating is a coarse include/exclude filter. Triggering is a context check for policies that survived the gate:

Gating: “Am I even allowed in the candidate set?”

Triggering: “Given world + drives + BodyMap, do I want to fire now?”

Triggering is implemented by trigger(world, drives, ctx). If this returns True, the policy is marked as triggered and joins the candidate list.

Q: Can a policy pass gating but fail to trigger? A: Yes. For example, policy:rest might:

Pass gating (dev + safety say it is allowed), but

Fail trigger if fatigue is below FATIGUE_HIGH or zone is unsafe.

In that case, Rest is “allowed in principle” but does not join the triggered candidate set for that tick.

Q: Can multiple policies trigger in the same tick? A: Yes. For example, both SeekNipple and Rest can be triggered if hunger and fatigue are both high and zone is safe. In that case, they both enter the candidate list and the execution stage must pick a winner.

Q: How do we choose which triggered policy actually executes? A: Execution is handled by the Action Center / PolicyRuntime:

It takes the triggered policies,

Computes some notion of “best” (e.g., drive deficit scores, preferred action, ordering),

Chooses a single winner for this tick.

That winner:

is logged as [executed] policy:...,

runs its primitive,

and its name becomes the action string for env.step(...) in the next environment tick.

Q: Where does the safety override fit into this picture? A: Safety is implemented as an extra gating layer:

First, we collect policies that pass dev_gate(ctx) and trigger True.

Then, if _fallen_near_now(...) says “fallen”, we filter that list down to a small safety set (e.g., {StandUp, RecoverFall}).

Only after that do we pick the “best” policy to execute.

So safety never directly executes a policy; it restricts which policies are even allowed to compete.

Q: How does this relate to what I see in the env-loop logs? A: Roughly:

[gate:rest] ... lines show triggering and gating conditions (fatigue, zone, BodyMap freshness, etc.).

[env→controller] policy:... shows what the gate catalog and safety layer proposed for this tick.

[executed] policy:... (in the controller logs) shows which policy actually executed.

env.step(action='policy:...') uses that executed policy name to advance the storyboard and world geometry on the next environment tick.

In other words, the logs are just different windows onto the three phases you summarized as:

Allowed → Triggered → Executed (gating → triggering → winner)

A session snapshot is a JSON file that contains: the world graph (bindings + edges + internal counters), drives, minimal skill telemetry, and small context items. Saving is atomic, loading restores indices and advances the id counter so new bindings don’t collide with old ids.

Design decision (ADR-0003 folded in): We use human‑readable JSON for portability and easy field debugging. A binary format would be smaller but harder to inspect. The JSON structure is stable enough to be versioned if we add fields later.

Design decision (ADR-0005 folded in): A runner‑level “Reset” is preferable to ad‑hoc deletes when starting a clean demo—this guarantees counters and anchors are consistent.

Q&A to help you learn this section

Q: What exactly is persisted?
A: Bindings, edges, anchors, id counters, drives, and simple skill telemetry, plus saved_at.

Q: Are saves safe against partial writes?
A: Yes—snapshots are written via atomic replace.

Q: After load, why don’t my new nodes collide with old ids?
A: The loader restores and advances the internal id counter.

Q: Binary vs JSON?
A: JSON keeps sessions portable and debuggable, binary would be smaller but opaque.

CCA8 now maintains a WorkingMap, a short‑term “write everything” graph intended to hold the full episodic trace of what is happening tick‑by‑tick.

WorldGraph can become cluttered quickly when we log repeated predicates (e.g., posture, distances, cues) every tick. Biologically, this mirrors a common separation:

• working / short‑term memory: high‑bandwidth, constantly updated, may be pruned
• long‑term memory: lower bandwidth, consolidated, less redundant

WorkingMap lets us record the detailed stream without forcing long‑term memory to store every redundant node.

• ctx.working_world is a separate WorldGraph instance (WorkingMap).
• Environment observations are mirrored into WorkingMap on each tick (when enabled).
• WorkingMap is capped by ctx.working_max_bindings to prevent unlimited growth.
• WorkingMap is intended to become the source graph for consolidation policies later: “write everything to WorkingMap → copy/consolidate selected information into WorldGraph”.

• Menu #__: WorkingMap + WorldGraph memory mode

  • Toggle WorkingMap mirroring
  • Toggle WorkingMap verbose logging
  • Set WorkingMap size cap
  • Toggle long‑term WorldGraph memory mode (episodic vs semantic)
  • Optionally clear WorkingMap

• Menu #__: WorkingMap snapshot

  • Print the last N bindings from WorkingMap
  • Optionally clear WorkingMap

WorldGraph supports two storage modes for predicates/cues:

• Each add_predicate(...) / add_cue(...) creates a new binding.
• Best when you want a rich timeline and do not mind redundancy.

• Identical pred: / cue: tags are consolidated to a single canonical binding.
• Reduces repeated nodes in long‑term graphs and can improve readability.

Important note: If policy code treats “tag exists anywhere in WorldGraph” as meaning “true right now”, semantic mode can make stale facts appear permanently true. The safe trajectory is:

• use WorkingMap / BodyMap as the source of “current tick” state,
• use WorldGraph (semantic) as consolidated long‑term structure.

(Note at time of this writing: CCA8 is being developed in that direction; semantic mode is optin and intended for experimentation.)

This section standardizes how we name and store information in the WorldGraph so planning stays simple, policies remain readable, and snapshots are easy to inspect.

A binding is a small “episode card” that binds together:

• lightweight symbols (tags: predicates, cues, anchors),

• pointers to engrams (rich memory stored outside the graph),

• and provenance/meta (who/when/why).

“Binding” emphasizes that we’re recording a coherent moment with attached facts and references, not just a graph vertex.

• id — b<number>; referenced by edges.

• tags: list[str] — the symbolic labels for this moment (see families below).

• engrams: dict (optional) — pointers to rich content (e.g., { "column01": {"id": "...", "act": 1.0} }).

• meta: dict (optional) — provenance & light context (e.g., {"policy": "policy:stand_up", "t": 123.4}).

• edges: list[{"to": id, "label": str, "meta": dict}] (optional) — directed links from this binding (adjacency list).

Keep families distinct so humans (and the planner) never have to guess.

1. Predicates — states/goals/events you might plan to

   • Prefix: pred:
   • Purpose: targets for planning and state description.
   • Examples:
     pred:born, pred:posture:fallen, pred:posture:standing,
     pred:mom:close, pred:nipple:found, pred:nipple:latched, pred:milk:drinking,
     pred:event:fall_detected, pred:goal:safe_standing,
     pred:drive:hunger_high (if you want a plannable drive condition).

   The planner looks for pred:*. The first pred:* (if present) is used as the human label in pretty paths/exports.

2. Cues — evidence/context you notice, not goals

   • Prefix: cue:
   • Purpose: sensory/context hints for policy trigger() logic.
   • Examples:
     cue:scent:milk, cue:sound:bleat:mom, cue:vision:silhouette:mom,
     cue:terrain:rocky, cue:vestibular:fall, cue:touch:flank_on_ground,
     cue:drive:hunger_high (if used only as a trigger).

   We do not plan to cues; they’re conditions that help decide which policy fires.

3. Anchors — orientation markers

   • Prefix: anchor: (e.g., anchor:NOW).
   • Also recorded in the engine’s anchors map, e.g., {"NOW": "b1"}.
   • A binding can be only an anchor (no pred:*) — that’s fine.

4. Actions — motor / behavioral steps

   • Prefix: action:
   • Purpose: explicit action/motor steps in state–action–state chains.
   • Examples:
     action:push_up, action:extend_legs, action:orient_to_mom,
     action:bleat_twice, action:look_around.

   Actions are bindings, not edge types. Policies create action:* bindings and connect them between predicate states with then edges.

5. Drive flags (controller-only)

   • The controller computes ephemeral flags like drive:hunger_high, drive:fatigue_high, drive:cold from numeric levels.
   • These bare drive:* strings are not stored in the WorldGraph.
   • If you want a persisted/plannable drive condition, use pred:drive:* (pred) or cue:drive:* (trigger).

• Actions are their own bindings: they carry action:* tags inside the same WorldGraph as predicates/cues/anchors. Typical pattern for policy:stand_up:

  (state)  pred:posture:fallen
     │
     ├─then→  (action) action:push_up
     │
     ├─then→  (action) action:extend_legs
     │
     └─then→  (state)  pred:posture:standing
  
  

• Edges are conceptually all “then” (episode flow). The label field is kept mainly for readability and history. The default label is "then".

• If you prefer, you can still use domain labels as synonyms for “then” (e.g., "approach", "search", "latch", "suckle") when it helps humans read the path. The engine treats them as “then” for planning.

• Put quantities about the transition (meters, duration, success, etc.) in edge.meta, not in tags:

{ "to": "b101", "label": "then", // or "search" as a human-facing alias "meta": { "meters": 8.5, "duration_s": 3.2, "created_by": "policy:seek_nipple" } }

The planner today is structure-first: it follows edges, ignores labels for correctness, and looks only at node tags to detect goals. Later, labels/meta can inform costs (Dijkstra/A*) or filters (“avoid transitions marked as recover_fall”).

• Provenance:

  • Binding creator: binding.meta["policy"] = "policy:<name>"

  • Edge creator: edge.meta["created_by"] = "policy:<name>"

• Engrams:

  • Only pointers live on the binding: binding.engrams["column01"] = {"id": "...", "act": 1.0}

  • The large payloads live outside WorldGraph (resolved via column provider).

• Use lowercase, colon-separated segments: pred:locomotion:running.

• Prefer 2–3 segments for clarity; avoid very deep chains:

  • pred:mom:location:north_forest (ok)

  • pred:location:mom:north_forest (also ok)
    Choose one pattern and stay consistent within a domain.

• If you might search by a broader class later, consider adding a second umbrella tag (e.g., pred:location:mom:northish) when useful.

• Every binding has a unique id (bN).

• Edges are directed; stored on the source binding’s edges[]. A binding without edges is a valid sink.

• Anchors (e.g., NOW) exist and point to real binding ids (they may also carry anchor:* tags).

• The first pred:* (if present) is used as the node label in UIs; fallback is the id.

• Snapshots restore latest, anchors, and advance the id counter past loaded ids.

| Family     | Examples                                                                                                                                                           | Purpose                              |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ |
| `pred:`    | `pred:born`, `pred:posture:standing`, `pred:nipple:latched`, `pred:milk:drinking`, `pred:event:fall_detected`, `pred:goal:safe_standing`, `pred:drive:hunger_high` | planner targets; human labels        |
| `cue:`     | `cue:scent:milk`, `cue:sound:bleat:mom`, `cue:vision:silhouette:mom`, `cue:terrain:rocky`, `cue:vestibular:fall`                                                  | policy triggers; not planner goals   |
| `anchor:`  | `anchor:NOW`, `anchor:HERE`                                                                                                                                        | orientation; also in `anchors` map   |
| `action:`  | `action:push_up`, `action:extend_legs`, `action:orient_to_mom`, `action:bleat_twice`                                                                              | explicit motor / behavioral steps    |
| Edge label | `then` (default), and optional human aliases like `"approach"`, `"search"`, `"latch"`, `"suckle"`                                                                  | episode flow; semantics = “then”     |

• Use one predicate prefix: pred:* for states/goals/events (and drives, per project default above).

• Keep cues separate (cue:*), used by policies (not planner goals).

• Put creator/time/notes in meta; put action measurements in edge.meta.

• Allow anchor-only bindings (e.g., anchor:NOW).

• Don’t invent ad-hoc families like state:*; stick to the four canonical families: pred:*, action:*, cue:*, anchor:*.

• Don’t encode rich data in tags; use engrams for large payloads.

Q: Can a binding exist with only an anchor and no predicate?
A: Yes. Anchors (e.g., anchor:NOW) are bindings and don’t require a pred:*.

Q: Can a binding exist with only a cue and no predicate?
A: Yes. It’s valid for a cue-only moment; just remember you can’t plan to a cue.

Q: How do I record that “running happened”?
A: Put it on the edge label (e.g., --run-->) and any measurements in edge.meta. If you also want a plannable “running” state, add pred:locomotion:running as the destination binding label.

Q: Do we allow duplicate edges?
A: The structure allows them; the UI warns on exact duplicates of (src, label, dst) so you can skip unintended repeats.

Q: Which tag shows up as the node’s label?
A: The first pred:* tag; otherwise we fall back to the binding id.

Early mammals don’t start life with an unlimited conceptual vocabulary. Following the spirit of Spelke’s core knowledge (a constrained, structured set of early abilities), CCA8 introduces a restricted lexicon for tags at early developmental stages and then unlocks a broader vocabulary as the agent “matures.” The goal is to keep symbols clean, avoid tag drift, and make early planning/search tractable and biologically plausible.

• Developmental realism. Neonates have a small, structured set of capacities (posture, proximity, feeding milestones, a few salient cues). The lexicon mirrors this and scales up later.

• Software hygiene. Constraining tags prevents ad-hoc token variations (e.g., pred:standing, pred:posture_standing, pred:posture:standing) from creeping in.

• Search simplicity. A smaller, consistent tag set makes paths/states easier to debug and keeps the fast index coherent.

• Stages. The world tracks a developmental stage ("neonate", "infant", "juvenile", "adult"). Stages are cumulative: later stages include all earlier tokens.

• Automatic stage setting. The runner derives the stage from ctx.age_days (toy rule: <= 3.0 → neonate, otherwise infant). This happens right after profile selection and after each autonomic tick (so the stage follows age).

• Enforcement policy. Creation-time checks use one of:

  • "allow" — accept any tag silently.

  • "warn" (default) — accept out-of-lexicon or legacy tags but print a short warning.

  • "strict" — reject out-of-lexicon tags with an error.

• Legacy tokens. A small legacy map accepts older forms (e.g., state:posture_standing) while suggesting the canonical form (posture:standing). This keeps old snapshots workable while you migrate.

Everyday behavior you’ll notice:

• When you add a predicate/cue in early life, it is checked against the stage vocabulary. In "warn" mode you’ll see a one-line hint if the token is off-lexicon (still accepted). In "strict" mode you’ll get a clear error.

• Planning, pretty-printing, autosave, etc., are unchanged; the lexicon guards creation, not reading.

• Add tokens to a stage. Edit the stage sets in TagLexicon.BASE[...] (inside cca8_world_graph.py). New tokens added under "infant" (or higher) automatically become available after the agent “grows” into that stage.

• Rename/normalize tokens. Put old → new mappings in TagLexicon.LEGACY_MAP. Old tags are still accepted; a warning suggests the canonical form until you finish migration.

• Change stage thresholds. Update WorldGraph.set_stage_from_ctx(ctx) (e.g., change the age rule or read a profile flag).

• Adjust enforcement. Call world.set_tag_policy("allow"|"warn"|"strict"). During development you can start with "warn", switch to "strict" when the vocabulary stabilizes.

• TagLexicon (in cca8_world_graph.py)

  • STAGE_ORDER = ("neonate","infant","juvenile","adult") — later stages include earlier tokens.

  • BASE[stage][family] — preferred tokens per family (pred, cue, anchor) and stage.

  • LEGACY_MAP — accepts legacy tokens (e.g., state:posture_standing) and suggests the canonical form (posture:standing).

  • Methods:

    • is_allowed(family, token, stage) — “Is this token ok at this stage?”

    • preferred_of(token) — returns canonical name if token is legacy.

• WorldGraph integration

  • Initialization wires the lexicon and defaults the stage to "neonate" and policy to "warn".

  • Stage helpers:

    • set_stage(stage) — explicitly set stage.

    • set_stage_from_ctx(ctx) — derive from ctx.age_days (runner calls this after profile selection and after each autonomic tick).

    • set_tag_policy("allow"|"warn"|"strict") — choose enforcement.

  • Enforcement hook:

    • add_predicate(...) and add_cue(...) normalize input (pred:/cue: prefixes), then call a private _enforce_tag(...). In "warn" it logs once and allows; in "strict" it raises ValueError.

• Preflight coverage (no warning noise). Preflight exercises attach semantics, action metrics, and BFS with temporary worlds set to "allow" (so runs are quiet), and separately verifies "strict" on an intentionally illegal token. You’ll still see a clean PASS wall.

• pred: posture/proximity/feeding

  • posture:standing, posture:fallen

  • proximity:mom:close, proximity:mom:far

  • nipple:found, nipple:latched, milk:drinking

  • seeking_mom

  • “action-like” states we currently model as predicates: action:push_up, action:extend_legs, action:orient_to_mom

  • (Optional) drive:hunger_high if you intend to plan to a drive threshold

• cue: sensory/context

  • vision:silhouette:mom, scent:milk, sound:bleat:mom

  • vestibular:fall, touch:flank_on_ground, balance:lost

  • (Optional) drive:hunger_high if used only as a trigger

• anchor: NOW, HERE

You can expand "infant" and later stages as you add tasks (e.g., navigation landmarks, social signals).

• Set the stage automatically (runner):

  world.set_stage_from_ctx(ctx)     # after profile selection and after autonomic tick
  world.set_tag_policy("warn")      # start permissive; flip to "strict" when stable
  

• Add a canonical predicate (neonate-ok):

  world.add_predicate("posture:standing", attach="latest")
  

• Add a cue (neonate-ok):

  world.add_cue("vision:silhouette:mom", attach="now")
  

• Accept an old snapshot silently (warn today, migrate later):

  # legacy 'state:posture_standing' is accepted; warning suggests 'posture:standing'
  

Does this break old runs?
No. Legacy tokens are accepted; in "warn" you’ll see a one-line hint suggesting the canonical form. Switch to "strict" after you migrate.

Will planning fail because of the lexicon?
No. The lexicon checks creation time. Planner behavior (BFS over existing tags) is unchanged.

Can I silence warnings during automated checks?
Yes. Use temporary worlds with set_tag_policy("allow") inside tests/preflight. The codebase already does this for its synthetic preflight tokens.

How do I add a new domain (e.g., landmarks)?
Add tokens under the appropriate stage in TagLexicon.BASE (and LEGACY_MAP if you’re renaming), then adjust your policies to emit/check the new tokens.

Early animals do not decide purely in symbols; spatial/visual structure in perception strongly shapes behavior. In CCA8, WorldGraph is the fast symbolic index (states, cues, anchors, transitions), while columns/engrams hold richer scene-like data (vectors, features, metadata). The signal bridge connects the two without committing to heavy perception yet:

• Emit a lightweight scene/cue into the column (creates an engram and returns its id).

• Attach the engram id back to the current binding in binding.engrams (pointer only).

• Fetch the engram later for inspection or analytics.

This lets you keep planning/search simple and fast while still recording a traceable link to the perception that motivated a step.

Implemented now (lightweight, safe):

• Create a binding (pred:* or cue:*) and assert a tiny engram record in the column memory.

• Store only a pointer on the binding:

  "engrams": {
    "column01": { "id": "<engram_id>", "act": 1.0, "meta": {…optional…} }
  }
  

• Retrieve the full column record by id for debugging/analytics.

Soon (drop-in extensions, no format change):

• Search similar engrams (nearest neighbors) to bias which policy fires.

• Enrich payloads (e.g., multi-modal features) while keeping the binding pointer small.

• Summaries in UI/HTML (e.g., show engram ids or small stats in tooltips).

From the runner:

1. Capture scene → emit cue/predicate with tiny engram (menu 24):

   • Choose channel (vision/scent/sound/touch), token (e.g., silhouette:mom), family (cue or pred), attach (now/latest/none), and an optional vector (e.g., 0.1, 0.2, 0.3).

   • The runner prints the created binding id and the attached engram id.

   • “Display snapshot” lists engrams=[column01] on that binding; “Inspect binding details” shows the pointer JSON.

   • Pyvis HTML shows the node; hover for tags/meta. (Labels fall back to cue when no pred:* is present.)

2. Resolve engrams on a binding (existing menu): enter a binding id (e.g., b9) to dump its engrams map.

Tip: Attach mode matters for episode wiring—now will add NOW → new (label then) and update LATEST; latest attaches from the previous LATEST; none creates a floating binding (valid sink).

On the binding (WorldGraph):

• tags — symbols (pred:*, cue:*, anchor:*)

• edges — transitions (edge label is the action; measurements in edge.meta)

• engrams — pointer(s) only:

  {
    "column01": {
      "id": "<engram_id>",
      "act": 1.0,
      "meta": { "...optional..." }
    }
  }
  

In the column (engram store):

• A small record keyed by engram_id, typically containing a payload and/or metadata.

• For “scene” captures we create a tiny numeric payload (vector) and optional descriptors (links/attrs).

• Heavy data stays out of WorldGraph; you only carry the id.

Bridge API (inside WorldGraph):

• attach_engram(bid, column="column01", engram_id, act=1.0, extra_meta=None)
  Attach an existing engram pointer to a binding.

• get_engram(column="column01", engram_id)
  Fetch the column record by id (read-only).

• emit_pred_with_engram(token, payload=None, name=None, column="column01", attach="now", links=None, attrs=None, meta=None) -> (bid, engram_id)
  Create a predicate binding and assert an engram in one call; attach the pointer.

• emit_cue_with_engram(cue_token, payload=None, name=None, column="column01", attach="now", links=None, attrs=None, meta=None) -> (bid, engram_id)
  Same as above for a cue binding.

• capture_scene(channel, token, vector, attach="now", family="cue", name=None, links=None, attrs=None) -> (bid, engram_id)
  Convenience wrapper: builds a tiny scene payload (vector) and calls the appropriate emit function.

  • family: cue (default) or pred

  • attach: now/latest/none

Column functions (internal):

• cca8_column.mem.assert_fact(name, payload, fact_meta) -> engram_id

• cca8_column.mem.get(engram_id) -> dict

Features helpers (optional):

• cca8_features.TensorPayload, cca8_features.FactMeta — typed wrappers for payload and metadata; the bridge gracefully falls back to plain dicts if these are unavailable.

A. Cue + scene pointer (vision silhouette, neonate) menu 24 → channel=vision, token=silhouette:mom, family=cue, attach=now

• Creates bX: [cue:vision:silhouette:mom]

• Adds NOW --then--> bX

• Attaches engrams["column01"].id = <engram_id>

• (Optional) a policy may react (e.g., orient or follow)

B. Predicate + scene pointer (if plannable state) menu 24 → family=pred, token=location:mom:north_forest, attach=latest

• Creates a pred:* node (ensure the token is allowed by the restricted lexicon for the current stage)

• Records an engram id for later inspection; planning can now target the predicate token.

• The restricted lexicon still applies at creation time. In neonates, cue:vision:silhouette:mom is allowed; off-lexicon tokens print a warn (or raise in strict mode).

• Keep payloads small (vectors, light descriptors). Use the column to store/compute heavier structures; the binding only needs the pointer.

• Planning/search is unchanged: BFS uses tags/edges; the bridge does not slow down the fast index.

• Provenance remains visible: bindings created by a policy stamp binding.meta["policy"]; engrams created via the bridge store their id in the binding pointer and a record in the column memory.

Q: Why store only a pointer on the binding instead of the full scene?
A: To keep the fast index small and predictable. Bindings carry lightweight symbols for planning; the heavy payloads (tensors, features, frames) live in the column. A pointer preserves traceability without slowing graph operations.

Q: Does the bridge change how planning works today?
A: No. Planning is still BFS over bindings/edges. The bridge adds provenance to perception (via pointers) but does not alter search or path cost.

Q: When should I emit a cue:* vs a pred:* with an engram?
A: Use cue:* when the scene is evidence for policy triggers (not a goal). Use pred:* when the scene defines a state you may plan to (e.g., pred:location:mom:north_forest).

Q: How do I see that a binding has an engram attached?
A: In Display snapshot, you’ll see engrams=[column01] on that binding; in Inspect binding details you’ll see the pointer JSON, e.g.
"column01": {"id": "<engram_id>", "act": 1.0, "meta": {...}}.

Q: How do I retrieve the actual engram record?
A: The bridge provides get_engram(engram_id=...). The column returns the full record (payload + descriptors) so you can inspect data shape, kind, links, etc.

Q: Can a binding point to more than one engram?
A: Yes. The engrams map is column-name → pointer. You can attach multiple columns (e.g., column01, column_vision, column_audio) to the same binding.

Q: What does act (activation) in the pointer represent?
A: A lightweight scalar you can use as a confidence/strength hint. It does not affect planning; it’s there for downstream analytics or heuristics.

Q: What happens if the column entry is missing or cannot be found?
A: The binding remains valid (it only stores a pointer). get_engram(...) will raise an error; you can handle it to report a broken pointer and continue.

Q: How is this used from the menu today?
A: Use menu 24 (“Capture scene → emit cue/predicate with tiny engram”). It creates a cue/predicate, asserts an engram in the column, and attaches the pointer—everything in one step.

Q: How do I attach an existing engram id to a binding?
A: Call attach_engram(bid, column="column01", engram_id=...). This is useful when a policy or external tool computed an engram beforehand.

Q: Does the restricted lexicon still apply when using the bridge?
A: Yes. The creation-time check still enforces stage-appropriate tokens (neonate/infant/...). Use cue:* tokens that are allowed at the current stage, or switch to strict mode to catch mistakes early.

Q: How will similarity search or value estimates plug in later?
A: The pointer makes it easy: a future call (e.g., search_similar(engram_id)) can fetch nearest neighbors in the column and return candidate bindings or hints for policy arbitration—without disrupting WorldGraph’s structure.

Q: Can I show engram details in the HTML visualization?
A: Tooltips already display tags/meta; you can extend them to include engram keys or a short id preview if you’d like (cosmetic change in the exporter).

Q: Any guidance on payload size?
A: Keep payloads small (tiny vectors, short descriptors). The bridge is meant for quick linking; large arrays should stay in the column (and be summarized when displayed).

Q: What’s the minimal recommended pattern when adding perception today?
A: (1) Emit a cue:* that captures the gist (e.g., cue:vision:silhouette:mom), (2) attach a tiny scene vector through the bridge, (3) let policies read the cue and stamp provenance; planning remains structure-first.

• cca8_world_graph.py — Directed episode graph (bindings, edges, anchors), plus a BFS planner. Serialization via to_dict() / from_dict().
• cca8_controller.py — Drives (hunger, fatigue, warmth), primitive policies (e.g., StandUp), Action Center loop, and a small skill ledger (n, succ, q, last_reward).
• cca8_run.py — CLI & interactive runner: banner/profile, menu actions (inspect, plan, add predicate, instincts), autosave/load, --plan flag, [D] Show drives.
• cca8_column.py — Engram provider (stubs now): bindings may reference column content via small pointers.
• cca8_features.py — Feature helpers for engrams (schemas/utilities).
• cca8_temporal.py — Timestamps and simple period/year tagging (used in binding meta).

Q&A to help you learn this section

Q: Which module stores nodes/edges? A: cca8_world_graph.py.

Q: Which runs instincts? A: cca8_controller.py (policies + Action Center).

Q: Which shows the menu & autosave/load? A: cca8_run.py.

Q: Where do engrams live? A: cca8_column.py, referenced by bindings’ engrams.

CCA8 uses four orthogonal time measures. They serve different purposes and are intentionally decoupled.

1) Controller steps — one Action Center decision/execution loop (aka “instinct step”).
Purpose: cognition/behavior pacing (not wall-clock).
Source: a loop in the runner that evaluates policies once and may write to the WorldGraph. When that write occurs, we mark a temporal boundary (epoch++). :contentReference[oaicite:0]{index=0}

With regards to its effects on timekeeping, when a Controller Step occurs: i) controller_steps: ++ once per controller step
ii) temporal drift: ++ (one soft-clock drift) per controller step
iii) autonomic ticks: no change
iv) developmental age: no change
v) cognitive cycles: ++ if there is a write to the graph (nb. need to change in the future) Cognitive cycles are currenlty counted only in Instinct Step (productive writes) (to change in future)

With regards to terminology and operations that affect controller steps: “Action Center” = the engine (PolicyRuntime). “Controller step” = one invocation of that engine. “Instinct step” = diagnostics + one controller step. “Autonomic tick” = physiology + one controller step. “Simulate fall” = inject fallen + one controller step (no drift) (but no cognitive cycle increment)

2) Temporal drift — the soft clock (unit vector) that drifts a bit each step and jumps at boundaries.
Purpose: similarity + episode segmentation that’s unitless and cheap (cosine of current vs last-boundary vector).
Drift call: ctx.temporal.step(); Boundary call: ctx.temporal.boundary(); vectors are re-normalized every time. See module notes on drift vs boundary. :contentReference[oaicite:1]{index=1}
Runner usage: we drift once per instinct step and once per autonomic tick in the current build; boundary is taken when an instinct step actually writes new facts. :contentReference[oaicite:2]{index=2}

3) Autonomic ticks — a fixed-rate heartbeat (physiology/IO), independent of controller latency.
Purpose: hardware/robotics cadence; advancing drives; dev-age.
Source variable: ctx.ticks (int).
Where incremented today: the Autonomic Tick menu path increments ticks, nudges drives, and performs a drift; it can also trigger a thresholded boundary. :contentReference[oaicite:3]{index=3} :contentReference[oaicite:4]{index=4}

4) Developmental age (days) — a coarse developmental measure used for stage gating.
Source variable: ctx.age_days (float), advanced along with autonomic ticks; used by world.set_stage_from_ctx(ctx). :contentReference[oaicite:5]{index=5}

5) Cognitive cycles — a derived counter for end-to-end loops that produced an output
(sense → decide → act that resulted in a write).

Purpose: progress gating & timeouts (e.g., “if no success in N cycles, switch strategy”), analytics.

Source variable: ctx.cog_cycles (int).
Runner rule (current build): increment when an Instinct step returns status=="ok" and the graph grew (bindings_after > bindings_before).
Contrast with controller steps: a controller step runs every time you invoke the Action Center once; a cognitive cycle only increments on steps that actually produced an output/write.

Recommended invariants: cog_cycles ≤ controller_steps; epochs increment only on boundary jumps (writes or τ-cuts), never decrement.

When the controller actually writes (graph grew), we take a boundary jump and increment ctx.boundary_no (epoch). We also update a short fingerprint of the boundary vector (ctx.boundary_vhash64) for snapshot readability. :contentReference[oaicite:6]{index=6}
A thresholded segmentation (“τ-cut”) can also force a boundary when cos_to_last_boundary falls below τ (default shown in code). :contentReference[oaicite:7]{index=7}

• autonomic ticks: ctx.ticks (runner increments) :contentReference[oaicite:8]{index=8}
• developmental age: ctx.age_days (runner increments) & world.set_stage_from_ctx(ctx) :contentReference[oaicite:9]{index=9}
• temporal drift: ctx.temporal.step(); boundary: ctx.temporal.boundary(); epoch: ctx.boundary_no++ :contentReference[oaicite:10]{index=10}
• soft-clock fingerprints: current ctx.tvec64(); last boundary ctx.boundary_vhash64; cosine via ctx.cos_to_last_boundary() (shown in snapshot/probe UIs). :contentReference[oaicite:11]{index=11}

• Controller-driven mode (today): each instinct controller step performs one temporal drift; boundary (epoch++) only on a real write. :contentReference[oaicite:12]{index=12}
• Autonomic-driven mode (future HAL): drift belongs to the heartbeat; controller step reads time but does not drift.
• Epochs never decrement; cos_to_last_boundary resets ≈1.000 on boundary. :contentReference[oaicite:13]{index=13}

1. Action Center computes active drive flags.
2. Scans policies in order, first trigger() that returns True fires.
3. execute() appends a small chain of predicates + edges to the WorldGraph, stamps meta.policy, returns a status dict, and updates the skill ledger.
4. Planner (on demand) runs BFS from NOW to a target pred:<token>.

Q: What’s the difference between controller_steps and cog_cycles? A: controller_steps counts every invocation of the Action Center (each time we ask “what should I do?”). cog_cycles only increments when a controller step actually produced a write to the WorldGraph in the Instinct step. So cog_cycles ≤ controller_steps by design.

Q: When do we increment ticks (autonomic ticks) versus controller_steps? A: ticks increment only in the Autonomic Tick path (heartbeat: physiology, drive updates, time-based age). controller_steps increment whenever a controller step runs (Instinct step, Autonomic tick, simulate fall, env-loop, etc.). They are orthogonal measures.

Q: What is the semantic difference between age_days and ticks? A: age_days is a coarse developmental clock (used to set lexicon stage and developmental gates), while ticks is a fine-grained physiological heartbeat counter. Typically age_days advances in proportion to ticks but on a much slower scale.

Q: What does a “temporal boundary” (epoch++) represent? A: A boundary is taken when a controller step writes new facts (or when a thresholded τ-cut triggers). It’s a way of saying “a new episode chapter started here” in the soft-clock vector space. We then jump the temporal vector, increment boundary_no (epoch), and reset cos_to_last_boundary to ~1.0.

Q: Why do we maintain both wall-clock created_at timestamps and a soft temporal vector? A: Wall-clock is great for logs and cross-run inspection, but awkward for unitless similarity and segmentation. The soft temporal vector gives a cheap, unitless notion of “near in time” (via cosine) and supports operations like “time-aware similarity” and “episode segmentation” without relying on wall-clock units.

• Policies are small classes with:

  • trigger(world, drives) -> bool
  • execute(world, ctx, drives) -> {"policy", "status", "reward", "notes"}

• Ordered list PRIMITIVES = [StandUp(), SeekNipple(), FollowMom(), ExploreCheck(), Rest(), ...].
  Updated: PRIMITIVES = [StandUp(), SeekNipple(), Rest(), FollowMom(), ExploreCheck(), ...]
  ( code now evaluates Rest before FollowMom.)

• Action Center runs the first policy whose trigger is True.

• StandUp guard: StandUp.trigger() checks for an existing pred:posture:standing to avoid “re-standing” every tick.

Status dict convention:
{"policy": "policy:<name>" | None, "status": "ok|fail|noop|error", "reward": float, "notes": str}

Policies are evaluated in a fixed order to keep behavior explainable. If two policies could fire on the same tick, the one earlier in the list wins that tick, the other will get a chance later if its trigger remains true. For fairness in long runs, you can:

• periodically rotate policy order, or

• add light inhibition windows (e.g., “don’t refire within N ticks”).

Good triggers are narrow and testable:

• Test for absence of the goal state (not standing yet).

• Include drive thresholds when appropriate (hunger_high).

• Prefer explicit tags or anchors over ad-hoc string checks.
  This makes behavior auditable: anyone can read a binding’s tags/drives and understand why a policy did or did not fire.

• Trigger: drive:hunger_high and no pred:nipple:latched.

• Execute: add pred:nipple:found, connect from the current state with search, optionally emit a cue tag (cue:scent:milk) when present.

• Provenance: stamp meta.policy = "policy:seek_nipple" on any new binding.

Q&A to help you learn this section

Q: Two methods every policy must have? A: trigger, execute.

Q: What prevents “re-standing”? A: Guard in StandUp.trigger() that checks for pred:posture:standing.

Q: What does a policy return? A: A status dict (policy, status, reward, notes).

Q: What does the skill ledger track? A: Counts, success rate, running q, last reward.

• Goal: Find a path from anchor NOW to the first binding carrying pred:<token>.
• Algorithm: BFS (O(|V|+|E|)) over edges.
• Returns: List of binding ids (["b1", "b9", "b12", ...]) or None if not found.
• When paths don’t exist: Either you haven’t created the predicate yet (e.g., no instinct tick) or it’s disconnected.

Two equivalent conventions exist:

• Stop-on-pop (default): return when a goal binding is popped from the frontier.

• Stop-on-discovery: return as soon as a goal binding is enqueued.
  Both yield shortest paths in unweighted graphs, stop-on-pop tends to produce cleaner logs because the pop order matches the BFS layers.

The frontier is the FIFO queue of discovered-but-not-expanded nodes. A node is marked “discovered” at enqueue time, never enqueue a discovered node again. This invariant prevents cycles from causing duplicates.

For humans, show both ids and predicates:
b3[born] --then--> b4[wobble] --then--> b5[stand] --then--> b6[nurse].
For programs, keep returning the id list (stable, parseable, compact).

Q&A to help you learn this section

Q: Where does planning start? A: Anchor NOW.

Q: How is the goal detected? A: First binding whose tags contain pred:.

Q: Complexity? A: O(|V|+|E|) BFS. Q: Why might a path be missing? A: Predicate not created yet or the graph is disconnected.

What’s available

• Default = BFS (fewest edges/hops).

• Dijkstra (optional) computes the lowest total edge weight; uses the same API and return type as BFS (WorldGraph.plan_to_predicate(...) returns a list of binding ids). In the real world, pathways from node to node are not at the same advantage or cost, and we end up using weighted edges past the neonatal state very quickly.

Edge weights

• Each directed edge can carry metadata; cost is read in this priority: weight → cost → distance → duration_s → 1.0 (fallback).
• If you don’t set any weights, Dijkstra and BFS usually produce the same path.

Switching planners

• Interactive: menu item 25) Planner strategy (toggle BFS ↔ Dijkstra) (if your runner exposes it).

• Environment:

  • Windows (cmd):
    set CCA8_PLANNER=dijkstra && python cca8_run.py --plan goal:whatever
  • macOS/Linux (bash/zsh):
    CCA8_PLANNER=dijkstra python3 cca8_run.py --plan goal:whatever

• In code:

  world.set_planner("dijkstra")    # or "bfs"
  current = world.get_planner()

• Snapshot file (JSON) includes:

  {"saved_at": "...", "world": {...}, "drives": {...}, "skills": {...}}

• Autosave: --autosave session.json writes after each completed action (atomic replace). Overwrites prior file if same name.

• Load: --load session.json restores world/drives/skills, id counter advances to avoid bNN collisions.

• Fresh start: Use a new filename, delete/rename old file, or load a non-existent file (runner continues with a fresh session and starts saving after first action).

Atomic writes & recovery

Snapshots are written via atomic replace: write to a temp file in the same directory and rename over the old snapshot. If a crash occurs mid-write, the old file remains intact. On load:

1. Parse JSON safely, if it fails, print a clear error with the path and keep the process alive so the user can save to a new file.

2. Validate minimal invariants (anchors, latest, bN shape). If any are missing, reconstruct conservative defaults and continue (prefer a live session to a hard fail).

Versioning the shape

Include a small {"version": "0.7.x"} under world. If you add fields later, bump this string and keep best-effort compatibility in from_dict()—log a one-liner describing any defaulted fields so users know what changed.

Q: When do I actually need Dijkstra instead of BFS? A: Use BFS when all edges are effectively equal-cost (e.g., neonatal episodes where each “then” step is similar). Use Dijkstra when you’ve started annotating edges with meaningful costs (distance, duration, risk, etc.) and you care about lowest total cost, not just fewest hops.

Q: How does Dijkstra know what cost to use for an edge? A: It checks edge.meta in priority order: weight → cost → distance → duration_s → 1.0. If none are present, it falls back to 1.0, which makes Dijkstra behave like BFS.

Q: If all my edges have weight=1.0, will BFS and Dijkstra give different paths? A: No. With equal weights, Dijkstra and BFS usually produce the same set of shortest paths (up to tie-breaking). Dijkstra is only useful once some edges have lower/higher costs than others.

Q: How can I check which planner is currently active? A: Call world.get_planner() in code or use the Planner strategy (toggle BFS ↔ Dijkstra) menu item. The menu prints the current strategy before planning so you can see whether you’re on BFS or Dijkstra.

Q: Does switching planner change how WorldGraph stores edges? A: No. Edges are stored the same way (adjacency list on the source binding). Only the search algorithm that walks those edges changes (BFS vs Dijkstra).

Q: What does autosave write? A: {saved_at, world, drives, skills}.

Q: How do we avoid id collisions after load?
A: from_dict() advances the internal bNN counter.

Q: Missing --load file?
A: Continue fresh, file created on first autosave.

Q: Why atomic replace on save?
A: Prevents partial/corrupt snapshots.

You can explore the graph via an interactive menu. The most useful items while learning are:

• The “Snapshot” entry
  Prints bindings, edges, drives, CTX, TEMPORAL, and policy telemetry. Shows NOW/LATEST, event boundary (epoch), soft-clock cosine, and which policies are eligible at the current developmental stage. This is your “state of the world and controller” dashboard.

• The “Drives & drive tags” entry
  Shows numeric drives (hunger, fatigue, warmth) and the derived drive flags (drive:*) that policies use in trigger(). These flags are ephemeral, not written into the graph unless you explicitly create pred:drive:* or cue:drive:* tags.

• The “Input [sensory] cue” entry
  Writes a cue:<channel>:<token> binding (e.g., cue:vision:silhouette:mom) and runs one controller step so you can see how policies respond to evidence. This is the “Sense → Process → Act” entry point.

• The “Instinct step (Action Center)” entry
  Runs the policy runtime once, with explanatory pre/post text. If a policy fires, you get a small chain of bindings/edges (e.g., the standing chain) and a status dict (policy, status, reward, notes).

• The “Inspect binding details” entry
  Given a binding id (or ALL), shows:

  • tags (families: pred:*, cue:*, anchor:*),
  • meta as JSON,
  • a short Provenance: summary (meta.policy/created_by/boot/ticks/epoch),
  • attached engrams (slot → short id + act + OK/dangling),
  • both outgoing and incoming edges and a degree line (out=N in=M). Use this to audit where a node came from and how it is connected.

• The “List predicates” entry
  Groups all pred:* tokens and shows which bindings carry each token. You can optionally filter by substring (e.g., rest or posture) to reduce clutter. This is a good way to see which planner targets exist.

• The “Add predicate” entry
  Prompts for a token (e.g., posture:standing, without the pred: prefix) and an attach mode (now/latest/none – default latest). It:         creates a new binding tagged pred:<token>,

        optionally auto-links it from NOW/LATEST with a "then" edge,

        stamps provenance (meta.added_by="user", meta.created_by="menu:add_predicate", meta.created_at=ISO-8601). It’s your primary way to “teach” the graph new states by hand.

• The “Connect bindings” entry
  Adds a directed edge src --label--> dst (default label then), with a simple duplicate guard that skips an exact (src, label, dst) edge if it already exists. Edges created here carry meta.created_by="menu:connect" and a timestamp. Use this to wire episodes with meaningful labels such as approach, search, latch, suckle.

• The “Delete Edge” entry
  Interactive helper for removing edges. It handles different legacy edge layouts and prints how many edges were removed between src and dst (with an optional label filter). This is the safest way to repair a mistaken link without editing JSON by hand.

• • The “Plan to predicate” entry
    Asks for a target predicate token (e.g., posture:standing) and:
  • prints the current planner strategy (BFS or DIJKSTRA),
  • calls WorldGraph.plan_to_predicate from the NOW anchor,
  • prints both the raw id path and a pretty path (b3[posture:standing] --then--> b4[milk:drinking] ...). With all edges weight=1, BFS and Dijkstra produce the same paths; once you assign weights, Dijkstra uses edge.meta['weight'/'cost'/'distance'/'duration_s'] as the cost.

• The “Export and display interactive graph” entry
  Writes a Pyvis HTML file for the current graph, with options for label mode (id, first_pred, or id+first_pred), edge label display, and physics. Open the HTML in your browser to hover nodes/edges and orient yourself visually.

• The “Save session” entry
  Manual one-shot snapshot to a JSON file you specify. It writes the same shape as autosave (saved_at, world, drives, skills) via atomic replace. It does not change your --autosave setting and is ideal for named checkpoints (e.g., session_after_first_hours.json).

• The “Load session” entry
  Loads a prior JSON snapshot (world, drives, skills) and replaces the current in-memory state. It never overwrites the file on load. After loading, the I/O banner explains whether autosave is ON/OFF and where the next autosaves will go.

• The “Reset current saved session” entry
  Available only when you started with --autosave <path>. After an explicit confirmation (DELETE in uppercase), it:

  • deletes the autosave file at that path,
  • re-initializes a fresh WorldGraph, Drives, and skill ledger in memory,
  • keeps --autosave pointing at the same path.
    From the simulation’s point of view you are now in essentially the same state as a fresh run with --autosave set; the next action that triggers autosave will create a new snapshot at that path.

Design decision (folded in): The runner offers a quick-exit --plan <token> flag when you only need to compute a plan once and exit. In interactive mode, the menu shows a small drives panel because drives are central to policy triggers.

Design decision (folded in): Attachment semantics are explicit and lowercase: attach="now", attach="latest", or "none". This removes ambiguity when auto-wiring the newest binding into the episode chain.

Two runner menu selection entries work together to make the newborn-goat simulation easier to explore:

• Run N environment steps (closed-loop timeline)
  Runs a short loop between the HybridEnvironment and the Action Center:

  1. If needed, calls env.reset() to start a newborn-goat episode.
  2. On each step, calls env.step(action=ctx.env_last_action, ctx=ctx), where ctx.env_last_action is the name of the last executed policy (e.g., policy:stand_up, policy:seek_nipple, policy:follow_mom).
  3. Injects EnvObservation into the main WorldGraph and updates BodyMap from the predicates.
  4. Runs one controller step to select and execute a policy, logging it as [executed] policy:..., and stores its name back into ctx.env_last_action for the next environment tick.

  The log for each step includes:

  • an [env] line (stage, posture, mom/nipple, last action),
  • [env→world] lines (what predicates/cues were written),
  • [env→controller] lines (which policy fired and why),
  • a compact [env-loop] summary ... line, plus:
    • explain posture: ... — why posture stayed fallen/standing/latched/resting,
    • explain nipple: ... — how nipple moved hidden → reachable → latched,
    • explain zone: ... — why geometry is currently classified as unknown / unsafe_cliff_near / safe.

  Together, these lines turn the closed-loop run into a readable text storyboard (“fell, stood, followed mom off the cliff, moved into shelter, latched, rested”).

• Configure episode starting state (drives + age_days)
  Allows you to adjust the internal starting conditions without editing code:

  • drives.hunger (0.0–1.0)
  • drives.fatigue (0.0–1.0)
  • drives.warmth (0.0–1.0)
  • ctx.age_days (≥ 0.0)

  The runner:

  1. Prints current values.
  2. Prompts for new values (blank = keep current), clamping drives to [0.0, 1.0] and age to ≥ 0.0.
  3. Writes them back into the live drives and ctx objects.
  4. Prints an updated summary line.

  This is the main way to explore different behavioural regimes:

  • Hungry, not tired → expect SeekNipple to dominate once geometry is safe.
  • Very tired, moderately hungry → Rest competes strongly once the kid is in shelter.
  • Low drives → permissive FollowMom behaviour dominates, moving geometry without strong drive pressure.

After configuring drives and age with menu 40, you can immediately run menu 37 to see how those initial conditions change the closed-loop story.

Q&A to help you learn this section

Q: What are the most useful menu items while learning?
A: Display snapshot, Add predicate, Connect two bindings, Plan from NOW, and the interactive graph export.

Q: Is there a quick way to visualize the graph?
A: Yes—export an interactive HTML graph from the menu, labels can show id, first_pred, or both.

Q: Why does the menu warn about duplicate edges?
A: To avoid clutter when auto-attach already created the same (src, label, dst) relation.

Q: Can I skip the menu and just plan?
A: Use --plan pred:<token> from the CLI for a one-shot plan.

The runner initializes logging once at startup:

• Writes to cca8_run.log (UTF-8) and also echoes to the console.
• One INFO line per run (runner version, Python, platform).
• You can expand logging later by sprinkling logging.info(...) / warning(...) where useful.

Change level or file:

Edit cca8_run.py in main(...) where logging.basicConfig(...) is called.

Get-Content .\cca8_run.log -Wait

We keep tests under tests/.

Preflight runs pytest first (so failures stop you early).

Stdout from tests is captured by default; enable prints byrunning pytest with -s (see below).

Run preflight (will run tests first):

Copy code

python cca8_run.py --preflight

Run tests directly (show prints):

Copy code

pytest -q -s

Included starter tests:

• tests/test_smoke.py — basic reasonableness (asserts True).
• tests/test_boot_prime_stand.py — seeds stand near NOW and asserts a path NOW → pred:stand exists.
• tests/test_inspect_binding_details.py — uses a small demo world and asserts that inspect-binding reports edge degrees as expected by the “Inspect binding details” menu.
• tests/test_phase_vi_c_spatial.py — checks that the newborn-goat environment’s spatial movement and safety gating behave as described: follow_mom moves the kid off the cliff and into shelter, and the Rest gate respects BodyMap’s safety zone (vetoes rest near the cliff, allows rest when shelter is near and the cliff is far).

The demo world for these tests is built via cca8_test_worlds.build_demo_world_for_inspect(), which creates a tiny, deterministic WorldGraph (anchors NOW/HERE, stand/fallen/cue_mom/rest predicates, and a single engram pointer) that you can also use interactively via --demo-world. Unit tests (pytest)

Run all checks and exit:

> python cca8_run.py --preflight

What runs

1. Unit tests (pytest + coverage).
   Prints a normal pytest summary. Coverage is percent of executable lines (comments/docstrings ignored). Ordinary code—including print(...) / input(...)—counts toward coverage. Target ≥30%.
   Note: console vs footer may differ by ~1% due to reporter rounding.

2. Scenario checks (whole-flow).
   Deterministic probes that catch issues unit tests miss:

   • Core imports & symbols present; version printouts
   • Fresh-world invariants and NOW anchor
   • set_now tag housekeeping (old NOW tag removed, new NOW tagged)
   • Accessory files exist (e.g., README, images)
   • Optional PyVis availability
   • Planner probes (BFS/Dijkstra toggle), attach semantics (now/latest)
   • Cue normalization, action metrics aggregation
   • Lexicon strictness (neonate stage rejects off-vocab), engram bridge
   • Action helpers summary is printable

3. Robotics hardware preflight (stub).
   Reports HAL/body flag status. Example line:
   [preflight hardware] PASS - NO-TEST: HAL=OFF (no embodiment); body=0.0.0 : none specified — pending integration Note: Pending integration of HALs.

4. System-functionality fitness (stub).
   Placeholder for end-to-end task demos (will exercise cognitive + HAL paths). Note: Pending integration of HALS.

Footer format & exit code

The last line gives a compact verdict and returns a process exit code:

[preflight] RESULT: PASS | tests=118/118 | coverage=33% (≥30) |
probes=41/41 | hardware_checks=0 | system_fitness_assessments=0 | elapsed=00:02

• PASS/FAIL reflects both pytest and probe results.
• probes counts scenario checks (part 2).
• hardware_checks / system_fitness_assessments are 0 until those lanes are implemented.

Artifacts

• JUnit XML: .coverage/junit.xml
• Coverage XML: .coverage/coverage.xml (console prints a human summary)

Tip: a lightweight startup check can be toggled with CCA8_PREFLIGHT=off (disables the “lite” banner probe at launch).

Q: What does --preflight actually guarantee when it says PASS? A: It guarantees that:

all unit tests passed,

basic WorldGraph invariants hold (anchors valid, ids consistent),

planner/attach/cue/engram probes behaved as expected,

and the hardware and system-fitness lanes didn’t report critical issues. It’s not a proof of correctness, but it’s a strong “everything basic is wired up” signal.

Q: Why is coverage only ~30% and not 100%? A: CCA8 is an evolving research codebase. The goal is to keep coverage high enough (≥30%) to catch regressions in the core engine, not to exhaustively test every UI/menu branch yet. As the code stabilizes, more tests can be added around new features.

Q: If a probe fails but pytest is green, what should I suspect? A: Probe failures usually mean a behavioral contract was broken (e.g., NOW not tagged, attach semantics changed, lexicon enforcement drifted). Unit tests check small pieces; probes check whole-flow assumptions. Treat probe failures as “something important in the pipeline changed.”

Q: Can I skip preflight for quick ad-hoc runs? A: Yes. Preflight only runs when you explicitly pass --preflight. Normal cca8_run.py runs don’t automatically run tests. There is also a lightweight startup check you can disable with CCA8_PREFLIGHT=off if needed.

Q: Where do the preflight artifacts go, and why do I care? A: JUnit XML and coverage XML are written under .coverage/. They’re useful for CI integration, trend tracking (coverage drifting up/down), and investigating test failures without re-running everything interactively.

CCA8 can be considered in two ways:

As a developmental cognitive architecture inspired by early mammalian brains.

As the kernel of a Robotic Cognitive Operating System (RCOS) – a layer that manages embodiment, behavior, and cognition on top of low‑level robot firmware, real‑time OSes, and middleware such as ROS 2.

Traditional operating systems (OS/360, Unix, Windows, Linux) sit between hardware and applications, providing stable abstractions: processes, files, memory, I/O. In robotics today, we typically have:

microcontroller firmware and drivers

a general‑purpose OS (Linux, RTOS)

robotics middleware (e.g., ROS 2) for messaging, topics, services

What is usually missing is an operating system for behavior and cognition – something that:

unifies goals, drives, skills, memory, and action selection

treats the robot’s world as an explicit structure (not just ad‑hoc node graphs and callbacks)

exposes a consistent “app platform” so users can install and compose new behaviors on their embodiment

CCA8 aims to fill this role.

You can think of CCA8 as sitting above the hardware and middleware in roughly this shape:

+-------------------------------------------------------------+ | **User behavior packs / tasks / curricula ("apps") **
+-------------------------------------------------------------+ | CCA8 RCOS kernel
| - WorldGraph (episodic world model)
| - ColumnMemory (engrams, traces)
| - Drives & homeostasis
| - Policies (primitive skills) & Action Center
| - Temporal scaffolding (ticks, episodes, age)
+-------------------------------------------------------------+ | Robot HAL / middleware
| - ROS 2, PetitCat-style minimal OS, simulators
| - sense() / act() / status() surfaces
+-------------------------------------------------------------+ | Hardware & low-level OS
| - motors, joints, sensors, microcontrollers, RTOS/Linux
+-------------------------------------------------------------+

In this view:

A HAL or ROS 2 stack plays a role analogous to a BIOS + device drivers in a PC: it knows how to talk to motors, joints, cameras, etc.

CCA8 is the cognitive OS: it knows about episodes, goals, drives, skills, policies, and worlds.

User-defined skills, policies, and task scripts are the equivalent of applications.

Small platforms like the PetitCat robot can sit under CCA8 just as well as richer ROS 2 platforms. As long as there is a HAL that implements the expected surfaces, the same CCA8 brain can drive different embodiments.

From a user’s point of view, CCA8 as an RCOS should eventually feel a bit like “Windows for your robot”:

you configure the body and environment,

you install or write behaviors (“apps”),

you specify goals and constraints,

and the RCOS manages the ongoing lifecycle of perception, memory, and action.

Concretely, CCA8 exposes (or is intended to expose) a few stable surfaces.

1. Embodiment and HAL configuration

The user (or integrator) plugs a robot into CCA8 by supplying a HAL adapter:

sense() → returns structured observations which can be turned into cues/engram payloads

act(intent) → takes a small set of action tags / parameters (e.g., action:step_forward, action:look_around) and translates them into motors, joint trajectories, or ROS 2 messages

status() → reports health, battery, fault states, etc., which can be reflected as predicates in the WorldGraph

CCA8 does not care whether act(intent) ends up calling ROS 2, a PetitCat‑style mini OS, or direct serial commands. That complexity stays below the RCOS boundary.

2. Drives, goals, and profiles

On top of the embodiment, the user configures the internal “needs” and goals:

numeric drives (hunger, fatigue, warmth, safety, etc.) with thresholds

profiles (e.g., “newborn mountain goat”, “explorer bot”) that set default drive parameters, exploration policies, and curricula

optional task‑level goals (e.g., “stay upright”, “follow mom”, “inspect room”, “return to dock”) that guide what “success” means over episodes

Drives are exposed to the controller as tags like drive:hunger_high, which policies can trigger on. This is where “what the robot should care about” gets declared.

3. Skills and policies as “apps”

The primary way users extend CCA8 is by installing or authoring policies and skills.

At the lowest level, a primitive policy is just a small behavior object with two methods:

trigger(world, drives) → should this skill run now?

execute(world, drives, ctx) → append a small chain of bindings/edges to the WorldGraph, optionally call the HAL, update drives, and return a status dict.

Policies are registered with the Action Center, which acts as the scheduler:

it inspects the current world + drives

it chooses which policy fires next (safety policies first, then homeostatic needs, then fallbacks)

it tracks provenance and learning signals (skill ledger, rewards)

From a user’s point of view, each policy is a bit like an installed application:

It has a name and version (policy:seek_nipple, policy:avoid_edge).

It declares preconditions (what states/drives it needs).

It leaves a trace in the world (provenance tags, binding chains) for later analysis or learning.

Higher-level skills can be built as small libraries of policies plus helper functions, packaged as Python modules or “behavior packs” that CCA8 discovers and loads.

4. Task scripts and curricula

On top of skills, the user writes task scripts that set up experimental or operational episodes. For example:

choose a profile and embodiment (e.g., goat vs. PetitCat)

load a particular world template or terrain

enable a set of skills/policies (e.g., StandUp, FollowMom, AvoidEdge, ExploreRoom)

define stopping conditions and logging preferences

This can be done via:

Python entry points (e.g., cca8_run.py with arguments), and

eventually, configuration files (e.g., YAML/JSON manifests) that describe “what brain, what body, what skills, what goals”.

The intent is that non‑specialist users should be able to say, in effect:

“Here is my robot body, here are the behaviors I want available, and here is what I want it to try to do.”

and let the CCA8 RCOS handle the ongoing cycle of perception → world update → drive update → action selection → embodiment.

5. Introspection and debugging surfaces

Like a conventional OS exposes tools such as ps, logs, and debuggers, the CCA8 RCOS exposes (or will expose) introspection surfaces:

WorldGraph views: what bindings and edges are currently active, where “NOW” is, what predicates are true

Skill ledger: per‑policy statistics (counts, rewards, success/fail history)

Drive traces: how internal needs evolved over time and which policies responded

Embodiment traces: what actions were actually sent through the HAL and with what results

These let the user treat behaviors as first‑class, inspectable objects rather than opaque ROS node graphs.

PetitCat and other small embodiments

For small robots such as PetitCat, CCA8’s RCOS view is especially useful:

a minimal robot “OS” handles low‑level timing, motor control, and safety (PetitCat‑like firmware / micro‑OS),

a thin HAL adapter translates between CCA8’s action tags and the robot’s specific capabilities,

the same CCA8 brain can then be reused across simulation and physical hardware, or across different small bodies.

In that sense, CCA8 is not just a simulator of a mountain goat calf, but a general-purpose Robotic Cognitive Operating System designed to be ported to many embodiments while giving users a consistent way to “install” behaviors and tell their robot what they want it to do.

A Hardware Abstraction Layer (HAL) separates what the cognitive system wants to do from how a specific robot makes it happen. In robotics, a HAL normalizes diverse sensors (camera, IMU, microphones, joint encoders) and actuators (motors, servos, grippers) behind a stable interface: perception enters the stack as time-stamped, unit-annotated measurements; actions leave as parameterized commands with feedback and safety guarantees. This indirection lets the same policy or planner run on simulation today and a very different platform tomorrow (e.g., a wheeled rover vs. a quadruped), without rewriting cognition. A good HAL also handles low-level concerns—synchronization, rate limiting, watchdogs/estops, and health reporting—so higher layers reason in task space, not device idiosyncrasies.

In practice, a HAL defines a few consistent surfaces: sense() for bulk sensor pulls or event callbacks, act(command, params) for goals in actuator space, and status() for state, limits, and faults. It owns the mapping from device coordinates to canonical frames, applies calibration/units, enforces safety envelopes, and returns structured acknowledgements (accepted/Executing/Done/Error) with timestamps. With this contract, cognition can compose behaviors from predicates and policies, while the HAL translates to hardware-specific drivers and transport.

The importance of embodiment in the generation and development to cognition is acknowledged. Embodiment shapes cognition—sensorimotor contingencies, action affordances, latency, noise, and body-centric frames all co-determine how an agent learns and reasons. CCA8’s HAL deliberately abstracts embodiment during core development to decouple variables: it gives us reproducible experiments, deterministic tests, and portability across platforms without rewriting cognition. This isn’t a denial of embodiment; it’s a seam. We mitigate “embodiment debt” by (1) keeping time, units, frames, limits, and latencies explicit in the HAL manifest; (2) expressing actions as intents (e.g., move/gaze/manipulate) rather than device torques; (3) mirroring real timing into engrams (ticks, tvec64, epoch) so learning remains time-aware; and (4) swapping in realistic adapters (noise/latency/domain-randomization) when moving from headless runs to hardware. In short, HAL postpones implementation details of a body while preserving the constraints that matter, so embodiment can be reintroduced precisely—at the right layer—without entangling the cognitive core.

While the importance of embodiment to cognition is acknowledged, the CCA8 architecture is structured to drop in a HAL without disturbing cognition. The Runner already distinguishes the cognitive context (policies, temporal clock, world graph) from embodiment details; by default HAL is OFF and the system runs “headless.” The seams are intentional: (1) perception bridge — features/engrams can be filled from HAL sensor streams with time linkage (ticks, tvec64, epoch); (2) action bridge — controller primitives/policies can emit normalized action intents (e.g., move_base(dx,dy,theta), gaze(target), manip(grasp=open/close)), which a HAL adapter maps to device commands; (3) timing — the cognitive TemporalContext stays procedural and device-agnostic, while the HAL can expose a wall-clock/rt clock when needed.

When a HAL is enabled, CCA8 will load an embodiment manifest (sensors, frames, capabilities, limits), bind HAL streams to the Features module (creating engrams with temporal fingerprints), and route controller outputs to act() with safety interlocks (dead-man, estop, limit checks). This keeps the WorldGraph an episodic index (lightweight, device-neutral), lets policies remain portable, and confines hardware specialization to HAL adapters. The same simulation you run today can, with a manifest and a driver pack, target different robots with minimal code changes—exactly the portability a HAL is meant to provide.

Q: Why is HAL kept separate from the cognitive architecture? A: To keep cognition portable and testable. The same WorldGraph/controller stack should run:

in a pure simulation,

on different robots,

or in hybrid sim+sensor regimes without rewriting core cognitive logic. HAL localizes sensor/actuator quirks and safety constraints to one layer.

Q: What changes in CCA8 when HAL is turned ON? A: Cognition (WorldGraph, controller, TemporalContext) stays the same. The difference is that:

perception features/engrams can be fed from real sensors via the HAL, and

policy actions can be turned into device commands (act()) with safety envelopes (limits, estops, etc.).

Q: Does HAL know about predicates and policies? A: No. HAL deals in sensor streams and action intents (move/gaze/manipulate). Policies and predicates remain in CCA8. The runner/bridge is responsible for mapping action:* / policy decisions into HAL act(...) calls.

Q: How does HAL help with sim-to-real transfer? A: It defines a stable contract:

sense() → returns normalized, time-stamped sensor data,

act(intent, params) → executes primitive actions in actuator space,

status() → reports health/limits/faults. By adhering to this contract in both sim and real deployments, you can reuse cognitive code and gradually swap simulators for real hardware.

When you run --preflight, CCA8 reports HAL/body flags in a dedicated lane. This is a status stub—no hardware I/O yet.

Example: [preflight hardware] PASS - NO-TEST: HAL=ON (...); body=0.1.1 hapty — pending integration

Enable it via CLI: > python cca8_run.py --hal --body hapty

Future checks will cover: transport handshake (USB/serial/network), sensor enumeration, actuator enable/disable, estop/limits, and simple round-trip commands (with timestamps and unit checks).

Q: What does it mean when hardware preflight prints “NO-TEST: HAL=OFF … pending integration”? A: It means the hardware lane ran, but there were no active hardware checks to perform:

HAL is off, or

no body profile is configured. It’s a reminder that the HAL lane is wired but not yet doing real transport/sensor tests.

Q: How do I enable the hardware lane for future robots? A: Start the runner with --hal --body , e.g.: python cca8_run.py --hal --body hapty. Once real HAL implementations exist, preflight will use that configuration to check connectivity, sensors, estops, etc.

Q: Will hardware failures make --preflight return non-zero exit codes? A: Yes, once implemented. The intention is that:

any serious hardware connectivity/safety issue

should cause the hardware preflight lane to FAIL and thus make the overall --preflight exit code non-zero so CI or scripts can react.

Q: Does HAL preflight change anything in the cognitive state? A: No. It should only probe transport, sensors, actuators and log health. WorldGraph, drives, and policies should remain unaffected by hardware preflight.

Q: How should I read the “hardware_checks=0” field in the preflight footer today? A: Literally: there are currently zero implemented hardware checks. It’s a placeholder count that will increase as real HAL checks (sensor enumeration, estop status, etc.) are added.

cca8_run.py --load session.json --autosave session.json

cca8_run.py --load session.json --autosave session_NEXT.json

cca8_run.py --load session.json --plan pred:posture:standing

Menu → 11 → channel vision, cue mom:close → creates cue:vision:mom:close (depending on your input normalization). Note: menu 11 adds a cue not a pred.

In the menu, choose “Drives & drive tags” (you can also type drives or d at the prompt).
This prints numeric drives and active drive flags (drive:*, ephemeral). These flags are computed by the controller (Drives.flags() / Drives.predicates()) and used in policy trigger() logic; they are not persisted in the WorldGraph unless you explicitly create pred:drive:* or cue:drive:* tags.

Sometimes you want a small, deterministic graph to test the graph menus without building everything via instincts first.

cca8_run.py --demo-world

This:

• Seeds a tiny WorldGraph with 6 bindings and 7 edges (anchors NOW/HERE, a stand predicate, a fallen state, a cue-like vision:silhouette:mom, and a state:resting node with provenance and an engram pointer).

• Prints a short banner such as: [demo_world] Preloaded demo world (NOW=b1, bindings=6) at startup.

• Lets you immediately use:

  • the “Snapshot” entry to see the pre-wired edges and tags,

  • the “Inspect binding details” entry (e.g., on the “resting” node) to inspect tags/meta/provenance/engrams and incoming/outgoing edges,

  • the “List predicates”, “Connect bindings” / “Delete Edge”, and “Plan to predicate” entries, all against the same stable mini-world.

The same demo builder is used by tests/test_inspect_binding_details.py via cca8_test_worlds.build_demo_world_for_inspect(), so interactive experiments and unit tests share the same graph shape.

From the main menu choose Export and display interactive graph (Pyvis HTML), then:

• Node label mode → id+first_pred (shows both bN and the first predicate).

• Edge labels → Y for small graphs, n for big graphs to reduce clutter.

• Physics → Y unless the graph is very large.
  Open the saved HTML in your browser and hover nodes/edges for tooltips, the NOW anchor is highlighted to orient you.

If you accidentally created a duplicate or wrong link:

1. Note src_id and dst_id from the snapshot view.

2. Use the “edge delete” helper (if present in tools/) or manually edit the snapshot JSON (edges[] on the source binding), then Load that edited snapshot.

3. Re-export the graph to confirm the fix.

Q&A to help you learn this section

Q: Resume + autosave same file? A: --load session.json --autosave session.json.

Q: Start fresh but keep old? A: Autosave to a new filename.

Q: One-shot planning? A: --load session.json --plan state:posture_standing.

Q: Reset? A: Press R (with autosave set).

This section documents the canonical in-memory shapes and their JSON snapshot equivalents. The goal is that a maintainer can read the structures, eyeball a saved session, and reconstruct what happened without digging into code.

A saved session is a single JSON object that bundles the world, drives, skills, and a timestamp: { "saved_at": "2025-10-16T12:34:56.789012", "world": { "version": "0.7.x", "next_id": 7, "latest": "b6", "anchors": { "NOW": "b1" }, "bindings": { "b1": { "...binding object..." }, "b2": { "...binding object..." } } }, "drives": { "hunger": 0.70, "fatigue": 0.20, "warmth": 0.60 }, "skills": { "policy:stand_up": { "n": 3, "succ": 3, "q": 0.58, "last_reward": 1.0 } } }

Note: only numeric levels are persisted. Drive flags (drive:*) are ephemeral controller signals and are not stored in the snapshot. If you need persisted drive state, write pred:drive:* (or cue:drive:*) explicitly.

Invariants (top level):

• next_id is the next numeric suffix to allocate (b{next_id}), advanced on load to avoid collisions.

• latest is the most recently created binding id (used for default attachments).

• anchors is a small map of named anchors (e.g., NOW, HERE) to binding ids.

Bindings are the atomic “episode cards” in the graph. { "id": "b42", "tags": [ "pred:posture_standing",         "cue:vision:silhouette:mom" }

Invariants (binding):

• id is a string of the form b<num>, unique within the world.

• tags is a list of strings, at least one tag for a “stateful” node should be a pred:* token (e.g., pred:stand).

• meta.policy records provenance (which policy created the node), meta can hold timestamps or light context.

• engrams holds pointers to rich content (stored outside the WorldGraph).

Edges are stored on the source binding in its edges[] list, forming a classic adjacency list. { "to": "b43", "label": "then", "meta": {} }

Conventions (edge):

• to is the destination binding id.

• label is a short relation name. Use "then" for episode flow, feel free to add domain labels (e.g., approach, search, latch, suckle) when helpful.

• Multiple edges between the same pair are allowed if labels differ, the UI warns when you attempt to add an identical (src, label, dst) edge.

Anchors are just bindings with special meaning, referenced in world.anchors. Many anchor bindings also carry a tag like anchor:NOW for visibility in UIs. Planning typically starts from the NOW anchor.

{ "hunger": 0.70, "fatigue": 0.20, "warmth": 0.60 }

The controller may derive helper tags (e.g., drive:hunger_high) for policy triggers. If those tags aren’t available, policies should degrade gracefully by using graph state alone.

A lightweight, per-policy roll-up to support introspection and future learning hooks: "policy:stand_up": { "n": 3, "succ": 3, "q": 0.58, "last_reward": 1.0 }

Field meanings are intentionally minimal: total runs n, number succeeded succ, an optional running quality estimate q, and the last reward.

• Serialization: WorldGraph.to_dict() emits version, next_id, latest, anchors, and bindings.

• Deserialization: WorldGraph.from_dict() restores the structures and advances the internal id counter beyond any loaded ids.

• Sinks: a binding without edges is a valid sink.

• Labels & pretty print: when displaying paths or graphs, the first pred:* tag is used as a human label if present, otherwise the id is shown.

Storing edges on the source binding gives:

• O(1) neighbor iteration for BFS (no global lookups needed).

• Locality of reasoning: everything needed to “expand” a node is on that node.

• Simple persistence: the snapshot is a direct dump of each binding’s edges.
  The trade-off is that reverse lookups (who points to bK?) require scanning or a small auxiliary index, in practice we only need forward edges for planning.

Q&A to help you learn this section

Q: What’s inside a Binding? A: id, tags, edges[], meta, engrams.

Q: How are edges stored? A: On the source binding as {"to", "label", "meta"}.

Q: One drive:* flag example? A: drive:hunger_high (hunger > 0.6). (This is an ephemeral controller flag; for persisted use, write pred:drive:hunger_high.)

Q: A skill stat besides n? A: succ, q, or last_reward.

Q: Where do edges live relative to nodes? A: On the source binding, inside its edges[] list. That’s the adjacency list the planner traverses.

Q: Are duplicate edges allowed? A: The structure allows them, but the UI warns when an identical (src, label, dst) already exists so you can skip duplicates.

Q: Which tag shows as the node label in UIs? A: The first pred:* tag if present, otherwise the binding id.

Q: How does the loader avoid bNN collisions after a load? A: It advances next_id past the highest numeric suffix seen in bindings.

Q: Do I need to add an edge for a terminal node? A: No. A binding with an empty (or missing) edges list is a valid sink.

Q: What makes a predicate “atomic”?A: It’s a single namespaced token (pred:…) carried by a binding, we don’t decompose it further inside the graph.

Q: One concrete example of provenance?A: meta.policy = "policy:stand_up" on the standing binding created by the StandUp policy.

Q: What is the “skill ledger”?A: Lightweight per-policy stats (counts, success, running q, last reward) to support analytics or future RL.

A traceability lite table maps major requirements to the modules and functions that satisfy them. Keep this short and keep it close to code names so a maintainer can jump straight into the right file. Examples:

• REQ‑PLAN‑01: BFS finds a shortest path in edges.Satisfied by WorldGraph.plan_to_predicate (BFS), pretty_path (display).

• REQ‑POL‑02: Policies run in priority order with small guards.Satisfied by cca8_controller.ActionCenter, policy trigger() guards, and provenance in meta.

• REQ‑PERS‑03: Loading a snapshot advances the id counter.Satisfied by WorldGraph.from_dict.

You can expand this list as the codebase grows. Note -- Currently paused. To revisit as the codebase grows and requirements stabilize.

Q&A to help you learn this section

Q: How do I keep requirements and code in sync?
A: Add a short REQ row and tag the relevant functions/classes with the REQ id in comments.

Q: Where should new ADRs go now that decisions are in-line?
A: Summarize in the section where the topic appears and, if large, put the full ADR under docs/adr/ with a link.

Q: What belongs in a REQ vs. ADR?
A: REQ = behavior the system must provide, ADR = why a design choice was made among alternatives.

• Enrich engrams and column providers, add minimal perception‑to‑predicate pipelines.
• Add “landmarks” and heuristics for long‑distance plans (A* when we add weights).
• Optional database or CSR backend if the graph grows beyond memory.
• Exporters: NetworkX/GraphML for interoperability, continue shipping the Pyvis HTML for quick, zero‑install visualization.

Q&A to help you learn this section

Pending as codebase grows and features stabilize

• traceback: In except Exception: add traceback.print_exc() to print a full stack. Use when a loader/snapshot fails.
• pdb: Drop breakpoint() in code or run python -m pdb cca8_run.py --load .... Commands: n (next), s (step), c (continue), l (list), p/pp (print), b (breakpoint), where.
• VS Code debugger: Create .vscode/launch.json with args, set breakpoints in the gutter, F5 to start. Great for multi-file stepping.

• Tracebacks: the runner keeps exceptions readable, copy the stack into an issue if you see unexpected behavior.
• pdb: insert import pdb, pdb.set_trace() where needed to inspect bindings and edges.
• VS Code: run cca8_run.py with the debugger and place breakpoints in plan_to_predicate() or policy trigger()/execute().

A common pitfall is duplicate edges when both auto‑attach and a manual connect create the same relation. The UI warns when you try to add a duplicate, you can also inspect the edges list on a binding directly in the debugger.

1. Verify the predicate exists (snapshot shows a binding with that pred:*).

2. Check connectivity (ensure there’s a forward chain of edges from NOW to that binding).

3. Look for reversed edges (common error: added B→A instead of A→B).

4. Confirm the goal token (exact pred:<token> string, avoid typos/extra spaces).

5. Inspect layers (use the interactive graph, the missing hop will be visually obvious).

1. Confirm StandUp.trigger() checks for an existing standing predicate.

2. Verify policy order (another policy shouldn’t insert a second standing node as a side effect).

3. Grep recent bindings for meta.policy to see who created duplicates.

Q&A to help you learn this section

Q: Quick way to print a stack? A: traceback.print_exc() in except.

Q: Start debugger from CLI? A: python -m pdb cca8_run.py --load ....

Q: Persistent breakpoint in code? A: breakpoint() (Python 3.7+).

Q: IDE workflow? A: VS Code launch config + gutter breakpoints.

• “No path found to state:posture_standing” — You planned before creating the state. Run one instinct step (menu 12) first or --load a session that already has it.
• Repeated “standing” nodes — Tightened StandUp.trigger() prevents refiring when a standing binding exists. If you see repeats, ensure you’re on the updated controller.
• Autosave overwrote my old run — Use a new filename for autosave (e.g., --autosave session_YYYYMMDD.json) or keep read-only load + new autosave path.
• Loading says file not found — We continue with a fresh session, the file will be created on your first autosave event.

Q&A to help you learn this section

Q: Why “No path found …” on a new session? A: You planned before adding the predicate, run one instinct step.

Q: Why duplicate “standing” nodes? A: Old controller, update to guarded StandUp.trigger().

Q: How to keep an old snapshot? A: Autosave to a new filename. Q: Is load failure fatal? A: No, runner continues with a fresh session.

• Predicate — symbolic fact token (atomic).
• Binding — node that carries predicate tag(s) and holds meta/engrams/edges.
• Edge — directed relation labeled "then", encoding episode flow.
• WorldGraph — the episode index graph.
• Policy — primitive behavior with trigger + execute.
• Action Center — ordered scan of policies, runs first match per controller step
• Drives — homeostatic variables (hunger/fatigue/warmth) that generate drive flags for triggers.
• Engram — pointer to heavy content (features/sensory/temporal traces) stored outside the graph.
• Provenance — meta.policy stamp recording which policy created a binding.

Predicate (tag)
Namespaced symbolic token (string) carried by a binding, e.g., pred:stand, pred:mom:close, pred:milk:drinking. A binding can carry multiple predicates.

Binding (node / episode)
A time-slice container that holds: predicate tags, lightweight meta, and pointers to rich engrams (not the engrams themselves).

Edge (directed link)
A directed connection src → dst with optional relation label (e.g., approach, search, latch, suckle). Think temporal/causal adjacency.

Anchors
Special bindings (e.g., NOW). Use World stats to find the actual binding ID (e.g., NOW=b0).

WorldGraph
Holds bindings + edges and fast tag→binding indexes for planning and lookup (~the compact symbolic 5%).

Engram (rich memory)
Large payloads stored outside the graph and referenced by pointers from bindings (~the rich 95%). Resolved via the column provider.

Column provider
cca8_column.py resolves binding→engrams and manages simple engram CRUD for demos.

Policy
Trigger (conditions on predicates/drives/sensory cues) + primitive (callable). Lives in code (cca8_controller.py), not in the graph.

Drives
Scalar homeostatic variables (0–1): hunger, warmth, fatigue. When crossing thresholds, the runner emits drive flags like drive:hunger_high.

Search knobs

• k: branch cap during expansion (smaller = decisive, larger = broader).

• sigma: small Gaussian jitter to break ties/avoid stagnation.

• jump: ε-exploration probability to occasionally take a random plausible move.

Cues & ticks

• Sensory cue adds transient evidence (vision/smell/sound/touch).

• Autonomic tick updates drives (e.g., hunger rises) and can emit drive flags.

Instinct step
One step chosen by the controller using policies + drives + cues. You can accept/reject proposals.

Planning
BFS-style search from the NOW anchor to any binding carrying a target predicate (pred:<name>), traversing directed edges.

Q&A to help you learn this section

Q: Binding vs Predicate? A: Binding = node container, Predicate = symbolic fact carried by the binding.

Q: Edge label semantics today? A: "then" = weak episode causality.

Q: Engram? A: Pointer to heavy content (outside the graph).

Q: Provenance? A: meta.policy records which policy created the node.

This tutorial introduces the mental model behind WorldGraph and shows how to encode experience in a way that is:

• simple for planning (BFS / Dijkstra),
• clear for humans (bindings are little episode cards),
• and consistent with the four binding kinds: anchors, predicates, cues, and actions.

It complements the “WorldGraph in detail” and “Tagging Standard” sections by walking through the why and how with newborn-goat flavored examples.

WorldGraph is a compact, symbolic episode index. Each “moment” is captured as a small record (a binding) that carries tags and optional pointers to richer memory (engrams). Edges connect moments to show how one led to another. Planning is graph search from a temporal anchor (usually NOW) toward a goal predicate.

A readable example path:

born --then--> wobble --then--> posture:standing --then--> nipple:latched --then--> milk:drinking In CCA8:

the things on the nodes are tags (predicates, cues, anchors, actions),

the things on the arrows are edge labels (often just "then").

We now treat actions primarily as action:* nodes, not as special edge labels.

A binding is more than a bare vertex. It binds together:

lightweight symbols (tags: pred:, action:, cue:, anchor:),

pointers to engrams (rich memory outside the graph),

and provenance/meta (who created it, when, why),

plus outgoing edges that capture “what happened next”.

Think of each binding as a tiny episode card:

“At this moment, the kid was posture:fallen, we saw vision:silhouette:mom, and the StandUp policy fired.”

That’s why we call it a “binding”: it’s a coherent, inspectable snapshot.

Every binding has a unique id like b42. Conceptually it looks like:

jsonc Copy code { "id": "b42", "tags": [ "pred:posture:standing", "cue:vision:silhouette:mom" ], "edges": [ { "to": "b43", "label": "then", "meta": {"created_by": "policy:seek_nipple"} } ], "meta": { "policy": "policy:stand_up", "created_at": "2025-11-27T10:09:56", "ticks": 5, "tvec64": "..." }, "engrams": { "column01": { "id": "<engram_id>", "act": 1.0 } } } Invariants that keep the graph healthy:

Ids are unique (bN).

Edges are directed and live on the source binding (edges[] list).

A binding with no edges is a valid sink.

The first pred:* tag (if present) is used as the node label in pretty paths/exports; fallback is the id.

The engine keeps an anchors map (e.g. {"NOW": "b5", "NOW_ORIGIN": "b1"}); the corresponding anchor:* tags are for human readability.

We use exactly four families of tags in the WorldGraph:

Predicates — what is true about body/world

Prefix: pred:

Examples:

pred:posture:fallen, pred:posture:standing, pred:resting

pred:mom:close, pred:nipple:latched, pred:milk:drinking

pred:seeking_mom

Purpose: planner goals and state descriptions.

Cues — evidence, not goals

Prefix: cue:

Examples:

cue:vision:silhouette:mom

cue:scent:milk

cue:drive:hunger_high

Purpose: policy triggers and FOA seeds. We do not plan to cues.

Anchors — orientation markers

Prefix: anchor:

Examples:

anchor:NOW – current focus of attention / local time,

anchor:NOW_ORIGIN – starting point of this episode.

The anchors map is authoritative (anchors["NOW"] = "b5"); tags make them visible in UIs.

Actions — motor / behavioral steps

Prefix: action:

Examples:

action:push_up

action:extend_legs

action:orient_to_mom

Purpose: explicit action nodes between predicate states.

You can think of:

pred:* = nouns/adjectives: what is (posture, proximity, feeding state),

action:* = verbs: what the goat actually did,

cue:* = sensory hints,

anchor:* = index pegs.

Edges are directed links between bindings:

jsonc Copy code { "to": "b4", "label": "then", "meta": {"created_by": "policy:stand_up"} } Design:

Semantics: every edge is conceptually “then” — “this binding tended to be followed by that binding in this episode.”

Label: defaults to "then"; you may use domain labels like "approach", "search", "latch", "suckle" as human-facing aliases ("then (approach)").

Meta: numeric/action metrics belong in edge.meta:

{"meters": 8.5, "duration_s": 3.2, "created_by": "policy:seek_nipple"}.

Algorithms (planner, FOA) treat edges as structure-first:

They look at which nodes are connected, not the exact label string.

Labels can later inform costs (Dijkstra) or filters (“avoid edges marked recover_fall”), but are not required for correctness.

We use two important anchors in the neonate:

anchor:NOW_ORIGIN

Set once at the start of the episode (birth).

Never moves; a natural starting point for “whole story” plans.

anchor:NOW

Follows the latest stable predicate state (e.g., posture:standing, seeking_mom, resting).

Moved by the runner after successful policy executions.

Common uses:

Planning from NOW: “Given where I am, how do I reach X?”

Planning from NOW_ORIGIN: “What path did I take from birth to X?”

Resetting NOW in experiments (e.g. set NOW=b3 temporarily to explore a local neighborhood).

Consider the simplified StandUp episode:

Start: goat is fallen near NOW_ORIGIN.

StandUp fires:

action:push_up

action:extend_legs

End: goat is standing; NOW moves to this new binding.

WorldGraph after one StandUp:

text Copy code b1: [anchor:NOW_ORIGIN] b2: [pred:posture:fallen] b3: [action:push_up] b4: [action:extend_legs] b5: [anchor:NOW, pred:posture:standing] Edges:

text Copy code b1 --then--> b2 # NOW_ORIGIN → fallen b1 --then--> b3 # NOW_ORIGIN → push_up b3 --then--> b4 # push_up → extend_legs b4 --then--> b5 # extend_legs → standing (NOW) From a map perspective, the S–A–S segment is:

text Copy code [pred:posture:fallen] → [action:push_up] → [action:extend_legs] → [pred:posture:standing] The standalone b1 anchor plus b2 predicate both represent the “fallen” situation; the actions attach off NOW and lead to a new predicate where NOW is finally placed.

Two encoding styles exist; CCA8 uses a snapshot-of-state style by default:

Snapshot-of-state (recommended):

Each predicate binding carries the current body/world facts (posture, proximity, feeding state, etc.).

Stable invariants (e.g., posture:standing) are repeated for a while, only changed when the fact changes.

Transient milestones (nipple:found) are often dropped once a stable state (nipple:latched) is reached.

Delta/minimal (not used today):

Each binding only adds what changed (“found”, then “latched”) without repeating posture/proximity.

Fewer tags per node, but harder to interpret a single binding in isolation.

The snapshot style keeps planning and debugging simple: each pred:* binding is a self-contained “what is true now” card.

Using the runner menus, you can manually build paths that match the tutorial diagrams:

Add predicate (3)

e.g., posture:standing, nipple:latched, milk:drinking.

Connect two bindings (4)

e.g., b2 --latch--> b3.

A typical hand-built path:

text Copy code NOW(b1) --then--> b2[pred:posture:standing] --latch--> b3[pred:nipple:latched] --suckle--> b4[pred:milk:drinking] The planner (Plan to predicate menu) will then find this path when you ask for milk:drinking as the goal.

“No path found”:
Check that:

You spelled the goal token exactly (pred:posture:standing vs pred:posture_standing),

There is a forward chain of edges from NOW (or your chosen start) to the target binding,

Edges are not reversed (B→A when you meant A→B).

Too many actions on edges: It’s tempting to encode everything as labels (--stand_up-->). Prefer to:

make actions into action:* bindings (action:push_up), and

use edge labels mainly as annotations ("then", "latch", "search").

Tagless nodes: Bindings with no tags are hard to interpret. Give each meaningful binding at least one pred:, cue:, or anchor:* tag.

11. Quick reference cheat sheet (WorldGraph concepts) Binding: id + tags (pred/cue/anchor/action) + edges[] + meta + engrams.

Edge: {"to": dst_id, "label": "then", "meta": {...}}; stored on source binding.

Anchors: NOW, NOW_ORIGIN, HERE → map names to binding ids.

Families: pred:, action:, cue:, anchor:.

Planner goal: any binding whose tags include pred:.

Snapshot vs delta: we use snapshot-of-state by default.

Source of truth for NOW/NOW_ORIGIN: world.anchors (tags are for readability).

With this picture in mind, the later tutorials (“WorldGraph Technical Features”, “Controller”, “Environment”) should feel much more natural: they’re all just elaborations of this same map—bindings and edges, tagged with four families, driven by policies and the environment.

Q: What’s the difference between a “binding” and a generic graph node? A: A binding is a rich node: it carries tags (pred/cue/action/anchor), optional engram pointers, provenance (meta), and outgoing edges. It’s closer to an “episode card” than a bare vertex — it describes what was true, what happened next, and how to get to richer memory.

Q: Why do we separate pred:, cue:, action:, and anchor: families? A: To keep semantics clear and algorithms simple. Predicates are facts/states, cues are evidence, actions are behavioral steps, and anchors are orientation points. This separation lets policies and the planner read tags without guessing what a string means.

Q: Why do we treat actions as nodes (action:*) instead of edge labels? A: Because in the “everything is a map” view, actions are events in time, not just labels on edges. Recording them as nodes makes it easy to attach engrams, provenance, and additional structure (timing, cost) to actions, and to traverse state–action–state chains uniformly.

Q: What does “snapshot-of-state” style mean here? A: It means each pred-binding is intended to be a self-contained state card (“what is true now”: posture, proximity, feeding state, etc.). We may repeat posture:standing across several bindings as the episode unfolds rather than only storing deltas. That makes planning and debugging much easier.

Q: How does the planner know which label to show for a binding? A: The first pred:* tag (if present) is used as the node’s human label in pretty paths and exports. If there is no pred:* tag, we fall back to the binding id (bN).

Note: Nov 2025 -- In other part of this README, you may still see the simpler “actions-as-edge-labels” pattern that has been deprecated at this time. This section describes a richer ontology (and one that better reflects the mammalian brain) where actions become explicit action:* bindings and edges are conceptually just “then”.

CCA8 is intended to model a mammalian‑style cognitive architecture, not just a symbolic planner. The core hypothesis behind the project is that:

Mammalian cortex is built from repeated spatial / navigation maps (cortical minicolumns), evolutionarily related to the hippocampal–entorhinal system.
A “brain” is therefore a vast collection of overlapping maps, with hippocampal structures acting as higher‑level maps tying local maps together.

At the implementation level, CCA8 has two main representational layers:

• A representation layer (Columns / engrams / payloads) – analogous to distributed neural ensembles and local maps.

• An index / map layer (WorldGraph bindings and edges) – analogous to hippocampal / MTL maps over states, actions and episodes.

This is based on Schneider's work, e.g., Frontiers | The emergence of enhanced intelligence in a brain-inspired cognitive architecture ,

Navigation Map-Based Artificial Intelligence . In the CCA8 we formalize a bit more and adopt more of the common terminology of the standard symbolic predicate and subsymbolic representation layer toolboxes.

](https://www.youtube.com/watch?v=Ld7I5EFpSYI&t=213s)

The focus of this section is to nail down a clean, consistent ontology (i.e., formal specification of a conceptualization) for:

• what a binding represents,

• what an edge represents,

• and how we represent actions and state changes,

in a way that:

1. Is neuro‑plausible relative to hippocampal/engram work, cognitive map theory, and the evolutionary minicolumn hypothesis our model uses;

2. Is simple and consistent enough to scale (billions of bindings over long simulations);

3. Gives the codebase a clean, minimal set of patterns that policies, FOA, planning and RL can rely on.

Modern memory and navigation neuroscience gives us a few constraints and inspirations:

• Engrams: memories are stored in sparse ensembles of neurons (“engram cells”) whose activity and connectivity change during learning and can later be reactivated to express the memory.

• Cognitive maps: the hippocampus and related areas implement map‑like representations of space and, more broadly, structured task/concept spaces. Place cells, grid cells, and related populations support flexible navigation and episodic memory.

• Index vs representation layers: The “Tensor Brain” model and related work argue for a distinction between:

  • a representation layer (distributed activations in sensory and associative cortex), and

  • an index layer that holds discrete symbols for entities, predicates, and episodic instances, with tensor‑like links between the two.

CCA8 instantiates a similar distinction:

• Columns / engrams = representation layer (what the “cortical minicolumns” are doing).

• WorldGraph = index/map layer (what hippocampal‑like structures are doing).

In that picture, bindings and edges are not neurons; they are index‑layer nodes and links that point into and organize the representation layer.

We standardize on four conceptual kinds of bindings:

1. Anchor bindings

2. Predicate bindings

3. Cue bindings

4. Action bindings

In the implementation, a binding is still just a node with a set of tags, meta, and edges. The “kind” is given by the leading tag family:

• anchor:*

• pred:*

• cue:*

• action:*

Bindings may carry multiple tags, but there is typically one dominant “kind” that determines how algorithms treat them.

Anchor bindings are special, sparse nodes that orient the graph and FOA:

• anchor:NOW – the current “moment” or temporal focus.

• anchor:HERE – current spatial focus (if/when we add spatial anchors).

• anchor:EPISODE_ROOT – optional roots for episodes or scenarios.

These are not states or actions; they are reference points for:

• FOA seeding (start expansion from NOW/HERE),

• temporal / episode segmentation,

• navigation over the graph (“where am I in this story?”).

In practice, we want:

• one anchor:NOW binding pointing to the latest stable state (see below),

• and a small number of other anchors as needed.

Predicate bindings represent semantic / state facts about the agent and world:

• Body / posture:

  • pred:posture:fallen

  • pred:posture:standing

  • pred:posture:resting

• Proximity / relations:

  • pred:mom:close

  • pred:nipple:latched

  • pred:milk:drinking

• Drives and internal conditions (optionally mirrored):

  • pred:drive:hunger_high

  • pred:drive:fatigue_high

We deliberately prefer simple, brain‑like labels such as pred:posture:standing rather than more computer‑science‑ish pred:state:posture:standing. The extra “state” sub‑namespace may be useful for a formal ontology, but your modeling intuition (and probably the biological reality) is that the brain is concerned with what is happening (“standing”, “falling”, “predator near”), not with an abstract “state:” wrapper. The meaning of “this is a state” is in how the predicate is used – by policies, FOA, planner, etc. – not in the literal string.

Semantically:

• Predicate nodes are the “noun / adjective world”: what is true about the body or environment at a particular moment.

Cue bindings are pseudo‑nodes for incoming sensory information in a form accessible to the maps:

• cue:vision:silhouette:mom

• cue:vestibular:tilt

• cue:somatosensory:pressure:flank

• cue:drive:cold_skin

These are short‑lived, input‑facing representations: they reflect what just hit the senses, not necessarily what the agent believes or remembers.

The typical flow:

• Sensors (or HybridEnvironment) produce EnvObservation → WorldGraph gets cue bindings attached near NOW.

• Policies read cues + predicates + drives to decide what to do.

• Later, “stable” interpretations of cues (e.g., mom:close, nipple:found) become predicate bindings.

So:

• Cue nodes = “what just came in”.

• Predicate nodes = “what the agent believes / treats as facts”.

Action bindings represent motor / behavioral steps:

• Micro‑actions:

  • action:push_up

  • action:extend_legs

  • action:bleat_twice

  • action:orient_to_mom

• Macro‑actions / policies (optional):

  • action:stand_up (if we want a macro node)

  • action:suckle

These bindings live in the same graph as predicates and anchors. They are created when policies execute, and they show up in episode traces as the “verb” nodes between “noun” states.

Each action binding typically carries meta such as:

• meta["policy"] = "policy:stand_up" (which policy created it),

• temporal stamps (ticks, epoch, tvec64, etc.),

• optional links to motor commands sent to a robot or environment.

Semantically:

Action nodes are the “verb world”: what the agent did at that point along the path.

Edges in WorldGraph are directed links between bindings. In the early code and docs, we used edge labels both for:

• temporal/causal transitions (then, fall, recovered_to),

• and structural relations (initiate_stand, spatial relations, etc.).

To bring this closer to the “everything is a node on a map” picture and simplify algorithms, we standardize as follows:

1. Default edge semantics:

   • All episode / transition edges are conceptually “then”:

     • “this binding came after / was derived from that binding in this story.”

   • Implementation may store the label as "then" (or leave label blank and treat it as then).

2. Edge labels are optional history annotations:

   • We may keep a label field for readability and logging:

     • e.g. fall, recovered_to, on, under.

   • But algorithms (FOA, planner, policies) primarily treat these edges as generic transitions.

   • Special labels are only introduced when we have a clear algorithmic reason to treat those transitions differently.

3. Semantics move to node tags and meta:

   • “What happened” is determined by the sequence of node types (predicate, action, cue) and their tags, not by fancy edge labels.

   • Edges are the glue; nodes carry the semantics.

This matches your intuition that in the brain:

• temporal sequence, causal flow, “pointer” relationships and even spatial adjacency are all different uses of the same underlying connectivity, not different “edge types” at the synapse level.

• Weak causality: Mammalian episodes often encode soft chains (“this happened, then that”), sufficient for immediate action without formal causal inference. In CCA8, edges labeled "then" capture this episode flow.
• Two-store economy: Keep the symbolic graph small (~5%): tags & edges for recall and planning. Keep the heavy content (~95%) in engrams (features, traces, sensory payloads). This avoids the brittleness of “all knowledge in a graph.”
• From pre-causal to causal: The symbolic skeleton is compatible with later, stronger causal reasoning layered above (e.g., annotating edges with conditions, failure modes, or learned utilities).

Q&A to help you learn this section

Q: Define “weak causality.” A: Soft episode links (“then”) without asserting logical necessity.

Q: Why engrams vs symbols? A: Symbols = fast index, engrams = heavy content → avoids brittle all-graph designs.

Q: Can we add stronger causal reasoning later? A: Yes, layered above (edge annotations, utilities).

When a policy executes, it leaves behind a simple state–action–state pattern in the graph.

Consider policy:stand_up.

Before the policy fires, we want:

• An anchor:

  b_now: [anchor:NOW]
  

• A predicate representing current posture:

  b_fallen: [pred:posture:fallen, ...]
  

• A link so NOW’s FOA can “see” that state:

  b_now --then--> b_fallen
  

In context, there may also be:

• pred:drive:hunger_high,

• cues like cue:vestibular:tilt,

which all live in the FOA neighborhood of b_now.

The dev gate for policy:stand_up looks at that local map:

• posture fallen,

• age in neonatal range,

• drives not too extreme.

If satisfied, the controller chooses policy:stand_up.

When policy:stand_up executes, it writes a short chain: (anchor) b_now | v (then) (state) b_fallen : [pred:posture:fallen] | v (then) (action) b_act1 : [action:push_up] | v (then) (action) b_act2 : [action:extend_legs] | v (then) (state) b_stand : [pred:posture:standing, ...]

Implementation details:

• b_act1 and b_act2 are action bindings with:

  • tags = {"action:push_up"} and {"action:extend_legs"} respectively,

  • meta {"policy": "policy:stand_up", "created_by": "policy:stand_up", ...}.

• b_stand is a predicate binding with:

  • tags including pred:posture:standing,

  • meta {"policy": "policy:stand_up", ...}.

Every edge is: source --then--> target

and may optionally record a label like "then" in its field for clarity.

After the stand sequence completes, we want NOW to track the latest stable state. Conceptually:

• anchor:NOW should ultimately refer to b_stand (“right now, the goat is standing”).

Implementation options:

• Update an existing anchor:NOW binding to point (via a then or internal field) to b_stand, or

• Create a fresh anchor:NOW binding b_now2 with a then path from b_fallen → b_act1 → b_act2 → b_stand → b_now2.

For navigation and FOA, the key invariant is:

From anchor:NOW, FOA can quickly reach the binding(s) that encode current posture, proximity, drives, etc.

If we later add a NOW_origin or episode roots, they can be separate anchors; but for basic behavior we keep: NOW points to the latest state.

During this whole process:

• Cue bindings near NOW (e.g., cue:vestibular:tilt, cue:somatosensory:pressure) provide the sensory evidence that posture is fallen.

• Drives live in a separate Drives object but can be mirrored as predicates (e.g., pred:drive:hunger_high) if needed.

• Dev gates and policies read:

  • pred:posture:fallen,

  • cues,

  • drives,
    to decide when to fire.

So the role split is:

• Bindings / edges: “what the episode looked like” (states, actions, transitions).

• Drives / context / policies: “why we decided to do that”.

Critically:

• Actions are invoked by policies, not by edges.

• Edges do not “tell the system what to do”; they are records of what was done.

Control flow:

1. FOA:

   • starts from anchor:NOW and nearby bindings (predicates, cues),

   • builds a small subgraph (few hops) in focus.

2. Policy gating:

   • sees patterns like “pred:posture:fallen near NOW + neonatal age + hunger”,

   • selects policy:stand_up.

3. Policy execution:

   • calls motor controllers / environment (actuation),

   • writes action bindings (action:*) and final predicate bindings (new state) into WorldGraph, connected by then.

4. Graph as trace:

   • Later, FOA, planner, and RL see a stored state–action–state path they can learn from or re‑use.

This keeps the architecture clean:

• Policies are the “spinal cord / motor programs”.

• WorldGraph is the “notebook” where stories of state/action/state are written down.

In the full CCA8 picture:

• Each binding may have engram pointers into column stores (representation layer):

  • a posture binding might have an engram for the proprioceptive/visual pattern of “standing”.

  • a cue binding might have an engram for a particular visual snapshot (“silhouette:mom”).

  • an action binding might have a motor‑related engram representing a learned action pattern (“push_up”).

WorldGraph then plays the hippocampal role:

• It links these local engrams into episodic and semantic maps, in line with engram and cognitive map theories.

This is exactly the index / representation layer story:

• Index layer (bindings + edges): discrete nodes for anchors, predicates, cues, actions, organized into a map.

• Representation layer (columns/engrams): distributed neural‑style representations, pointed to by bindings.

Your “cortical minicolumns are spatial maps” hypothesis fits here by treating each column as a local map over its feature space, with WorldGraph indexing and sequencing them at a higher level.

Adopting this scheme implies several concrete steps.

1. Standardize binding types:

   • Ensure that:

     • anchors carry anchor:* tags,

     • semantic facts carry pred:* tags (e.g., pred:posture:standing),

     • cues carry cue:* tags,

     • actions carry action:* tags.

   • We can keep legacy tags like pred:state:posture_standing temporarily for compatibility, but the canonical name should be pred:posture:standing.

2. Refactor edge usage:

   • Default edge label is conceptually then.

   • Extra labels like fall, recovered_to can be kept as optional annotations, but algorithms should mostly rely on:

     • graph structure,

     • node tags/meta.

3. Refactor policies to write S–A–S chains:

   • policy:stand_up, policy:recover_fall, policy:seek_nipple, policy:suckle, etc., should:

     • create action bindings action:*,

     • connect them between predicate states with then edges,

     • update anchor:NOW so FOA can see the new state.

4. FOA and planning:

   • FOA should treat all four binding types as nodes in the same map, but may:

     • weight anchors and predicates more strongly,

     • treat action nodes as transitory steps.

   • Planner should search over state–action–state trajectories to reach target predicates (e.g., pred:nipple:latched, pred:milk:drinking).

5. Documentation alignment:

   • Docstrings in cca8_world_graph.py, cca8_controller.py, cca8_run.py, cca8_env.py should be updated to:

     • describe bindings as “anchor / predicate / cue / action” nodes,

     • describe edges as “then” transitions,

     • clarify that actions are nodes, not edges.

6. README / design docs:

   • README sections on WorldGraph and policies should be updated to reflect this white‑paper view, so future readers see:

     • a unified map story,

     • a clear binding ontology,

     • and a clean separation between control (policies) and trace (WorldGraph).

The central design decisions are:

• Four binding kinds:

  • anchor:* – special nodes for NOW/HERE/origins.

  • pred:* – semantic/state facts.

  • cue:* – sensory/input postings.

  • action:* – motor/behavioral steps.

• Edges as generic “then”:

  • Edges are primarily temporal/relational glue.

  • Labels are optional annotations, not the main source of semantics.

• Actions as nodes, not edges:

  • Policies invoke actions.

  • WorldGraph stores those actions as action:* bindings in state–action–state chains.

• WorldGraph as hippocampal / index map:

  • It ties Columns/engrams (representation layer) into a coherent cognitive map over episodes and semantics.

This architecture:

• aligns well with hippocampal / engram / cognitive‑map evidence,

• matches your “minicolumns are spatial maps” hypothesis (everything is a node on a map),

• gives us a clean base for later language work (nouns ↔ predicates, verbs ↔ actions, temporal connectives ↔ then),

• and simplifies the code: fewer relation types, clearer patterns, easier refactoring.

Once we’re both happy with this conceptual foundation, the next step is to:

1. Implement this state–action–state pattern concretely for a few key policies (e.g., stand_up),

2. propagate the pattern into the environment simulation,

3. and then bring all docs (docstrings + README) into alignment with this binding/edge ontology.

This section explains how the CCA8 runner uses anchors, the LATEST pointer, and the new base-aware write logic to keep episodes tidy and meaningful when adding new bindings.

The goal is that when you say “hang this new fact off the current situation,” the system knows where in the WorldGraph that is — not just “whatever node happened to be written last.”

The WorldGraph keeps two distinct orientation mechanisms: anchors and a LATEST pointer.

• Anchors are bindings tagged anchor:<NAME> and tracked in world._anchors (e.g., "NOW" → "b5").

  • anchor:NOW – the current situation or temporal orientation: where planning and FOA usually start.
  • anchor:NOW_ORIGIN – the episode root, pinned once on a fresh world (birth) and left alone later.
  • anchor:HERE – reserved for spatial orientation (“where the body is in space”); currently a stub.

• LATEST is not a binding tag; it’s an internal pointer world._latest_binding_id that always refers to the most recently created binding, regardless of whether it is a predicate, cue, or action.

At any moment:

• NOW answers: “Where am I in this story?”
• LATEST answers: “What was the last node I wrote?”

They often coincide right after a policy runs, but they are allowed (and expected) to diverge. For example, after a StandUp:

b1: [anchor:NOW_ORIGIN]  →  episode root  
b2: [pred:posture:fallen]  
b3: [action:push_up]  
b4: [action:extend_legs]  
b5: [anchor:NOW, pred:posture:standing]

NOW and LATEST are both b5 immediately after the StandUp policy executes. If you then add a cue:

b6: [cue:vision:my_cue:mom]    # attached from NOW → b5 --then--> b6

• NOW remains b5 (standing posture).
• LATEST becomes b6 (the cue).

This separation is intentional: NOW reflects the current state, while LATEST simply tracks the last binding created (which might be a transient cue or helper node).

All node-creation helpers in WorldGraph accept an attach= parameter:

• attach="now"

  • Create a new binding and add an edge NOW --then--> new.
  • Update LATEST = new.

• attach="latest"

  • Create a new binding and add an edge LATEST --then--> new.
  • Update LATEST = new.

• attach="none" / None

  • Create a new binding without any auto-edge.
  • Still updates LATEST = new.

In other words:

• attach="now" → “attach from the NOW anchor.”
• attach="latest" → “attach from the last node written.”
• attach="none" → “create a floating node; I’ll wire it manually.”

In simple demos, attach="latest" is good enough. But once you start mixing predicates, cues, actions, and scene captures, “latest” can drift to a node that is not the right semantic parent.

Example:

1. Instinct step runs StandUp → NOW and LATEST both at b5 (pred:posture:standing).

2. You add a cue (attach="now"):

   • b5 --then--> b6 (cue:vision:my_cue:mom)
   • LATEST = b6, NOW still b5.

3. You add a new predicate or scene with attach="latest".

Without base-aware logic:

• The new binding would hang off b6 (the cue) simply because that’s LATEST, even though semantically it belongs with the standing posture node b5.

To fix this, the runner now computes a write base each step — a suggested parent node for new writes that reflects the current situation, not just the last node touched.

A base is “where should this new binding be linked so the episode stays tidy and meaningful?”

choose_contextual_base(world, ctx, targets=[...]) computes a base_suggestion as a small dict:

{"base": "NEAREST_PRED", "pred": "posture:standing", "bid": "b5"}

or falls back to:

{"base": "HERE", "bid": "?"}      # HERE stub, unresolved
{"base": "NOW", "bid": "b_now"}   # if HERE and NEAREST_PRED aren’t available

In words:

• base["base"] – the strategy we used:

  • "NEAREST_PRED" – nearest binding (by BFS) around NOW carrying the target predicate (e.g., posture:standing, stand).
  • "HERE" – a spatial anchor (stubbed for now).
  • "NOW" – fallback to the NOW anchor.

• base["bid"] – the concrete binding id we suggest as the parent (e.g., b5).

• base["pred"] – the matching predicate token for diagnostics (e.g., "posture:standing").

This base_suggestion answers:

“Given the current situation (NOW + FOA), which binding is the best parent for new nodes this step?”

Some runner menus — notably Add Predicate and Capture Scene — now incorporate base-aware logic when you request attach="latest".

The pattern is:

1. Compute a base suggestion:

   base = choose_contextual_base(world, ctx, targets=["posture:standing", "stand"])

2. Decide an effective attach mode:

   effective_attach = _maybe_anchor_attach("latest", base)

   • If base["base"] == "NEAREST_PRED" and you asked for "latest", we return "none".
   • Otherwise, we leave attach unchanged.

3. Create the new binding with attach=effective_attach.

   • If effective_attach == "none", the node is created unattached (no auto edge from LATEST).

4. If we used a NEAREST_PRED base and suppressed auto-attach, we explicitly anchor the new node under the base:

   _attach_via_base(world, base, new_bid, rel="then", meta={...})
   # adds base['bid'] --then--> new_bid

In logs you’ll see:

[base] write-base suggestion for this add_predicate: NEAREST_PRED(pred=posture:standing) -> b5
[base] base-aware attach: new binding will be created unattached, then linked from the suggested NEAREST_PRED base instead of plain 'LATEST'.
Added binding b9 with pred:vision:silhouette:mom (attach=none)
[base] attached b9 under base b5 via then (NEAREST_PRED(pred=posture:standing) -> b5)

and in the mini-snapshot:

b5: [anchor:NOW, pred:posture:standing]
    edges: then:b6, then:b7, then:b9
b6: [cue:vision:my_cue:mom]
    edges: (none)
b7: [action:orient_to_mom] -> b8
b8: [pred:seeking_mom]
    edges: (none)
b9: [pred:vision:silhouette:mom]
    edges: (none)

Here:

• LATEST before the add was b8 (seeking_mom).
• attach="latest" would have made b8 --then--> b9.
• Base-aware logic instead anchored b9 under b5 (standing/NOW), which is semantically cleaner.

Base-aware writes currently apply to:

• Add Predicate menu (manual predicates):

  • When you choose attach="latest" (the default), the new pred:* is anchored under:

    • the nearest posture:standing / stand near NOW (if available),
    • otherwise behaves like a normal attach="latest".

• Capture Scene → tiny engram menu:

  • When you choose attach="latest", the new scene binding (cue or pred) is created unattached and then anchored under the same NEAREST_PRED base, so scene engrams cluster under the appropriate posture node (e.g., “scenes while standing”).

Attach modes are still fully under your control:

• If you explicitly pick attach="now" or "none", base-aware logic only prints a small “[base] write-base suggestion skipped…” note and respects your choice.

• NOW_ORIGIN

  • Episode root anchor; pinned once at startup, rarely used directly by policies.

• NOW

  • Semantic “current situation” anchor; planning and FOA start here.
  • Moved by the runner after significant events (e.g., StandUp).

• HERE

  • Reserved for future spatial anchoring (“where the body is in space”).

• LATEST

  • Internal pointer to the last binding created; used by raw attach="latest" semantics.

• base

  • A suggested parent binding ({"base": strategy, "bid": "bN", "pred": "…"}) computed near NOW.

• base_suggestion / choose_contextual_base(...)

  • Given NOW + FOA and target predicates, returns a base dict; NEAREST_PRED is the typical case for posture.

• Base-aware logic

  • For attach="latest" in certain menus, _maybe_anchor_attach(...) and _attach_via_base(...) cooperate to:

    • suppress naive auto-linking from LATEST,
    • explicitly anchor the new binding under the semantically meaningful base node near NOW.

The result is that this keeps the WorldGraph’s episode structure both readable for the human reader and usable for planning, even as cues and other small bindings proliferate around the current situation.

Q1. What’s the difference between NOW and LATEST? A. NOW is an anchor binding (tagged anchor:NOW) that represents the current situation in the episode — planning and FOA start here. LATEST is just an internal pointer to the last binding created (_latest_binding_id). They often coincide right after a big event, but they can diverge: NOW stays on the meaningful situation node, while LATEST chases every new binding (including transient cues).

Q2. What is NOW_ORIGIN used for? A. NOW_ORIGIN is an anchor marking the episode root — the binding where NOW started on a fresh world. It’s a stable “start” marker. The runner doesn’t change it during normal operation; it’s mostly there for orientation and future algorithms that need a canonical start.

Q3. What happens when I use attach="now" vs attach="latest"? A.

• attach="now": Creates a new binding and adds NOW --then--> new. The NOW anchor is the parent.
• attach="latest": Creates a new binding and adds LATEST --then--> new. The last-created binding is the parent.

Both modes update LATEST = new. Base-aware logic may intercept "latest" in some menus (see below), but "now" always attaches from the NOW anchor.

Q4. What do we mean by a “base” or base_suggestion? A. A base is the binding the system thinks is the best parent for new writes this step. base_suggestion is a small dict like:

{"base": "NEAREST_PRED", "pred": "posture:standing", "bid": "b5"}

It means:

“Starting from NOW, the nearest binding with pred:posture:standing is b5; that’s the node we should probably hang new facts under.”

If no such predicate is found, the strategy can fall back to HERE or NOW.

Q5. Is a base the same thing as NOW? A. No. NOW is the starting point for search. A base is the chosen parent within the neighborhood around NOW. In many simple cases NOW is the best base (e.g., NOW is the standing node), but in general:

• NOW = “where we are in the episode.”
• base = “which node under/around here should own this new fact.”

Q6. What problem does base-aware logic solve for attach="latest"? A. Without base-aware logic, attach="latest" blindly attaches new bindings from _latest_binding_id. If the last thing you wrote was a cue or a helper node, new predicates/scenes hang under that, even though they semantically belong under a posture or state node.

Base-aware logic:

1. Computes a base near NOW (e.g., nearest posture:standing).

2. If you requested attach="latest" and the base is NEAREST_PRED, it:

   • creates the new node with attach="none",
   • then explicitly adds base_bid --then--> new.

So the new binding is anchored under the meaningful state (e.g., “standing at b5”) instead of some random “last node” (e.g., a cue at b6).

Q7. Does base-aware logic affect attach="now" or attach="none"? A. No. If you explicitly choose attach="now" or "none":

• The runner prints a small note that it has a base suggestion but “skips” it because the attach mode was user-specified.

• The write behaves exactly as before:

  • "now" attaches from the NOW anchor,
  • "none" creates a floating node (you can wire it manually).

Base-aware write behavior only kicks in when you choose attach="latest" in certain menus.

Q8. Which menus currently use base-aware logic? A. Today:

• Add Predicate – default attach="latest" uses a NEAREST_PRED base near NOW (standing/stand) and anchors the new predicate under that node.
• Capture Scene – default attach="latest" creates the scene binding unattached and anchors it under the NEAREST_PRED base (e.g., “scene while standing”).

More menus (and maybe env injection) can be upgraded to use the same pattern in future phases.

drive:* as the notation for internal flags, but by design they are:

ephemeral controller-only flags — not stored as pred:* in the WorldGraph.

There are three layers to this:

a) Drives →drive: flags*

In Drives.flags() we turn raw numbers into ephemeral flags:

defflags(self) -> List[str]:

    tags: List[str] = []

    if self.hunger > HUNGER_HIGH:

        tags.append("drive:hunger_high")

    if self.fatigue > FATIGUE_HIGH:

        tags.append("drive:fatigue_high")

    if self.warmth < WARMTH_COLD:

        tags.append("drive:cold")

    return tags

These drive:flags live inside the Drives object,

• are recomputed on each controller step / autonomic tick,

• are used by policies in trigger(...) and deficit scoring. They are not automatically written to the WorldGraph. The controller docstring saysthis explicitly: “Drives: numeric homeostaticvalues (hunger, fatigue, warmth) → derive 'drive:' flags (ephemeral tagsthat are not written to worldgraph)”
  “Controller-only flags (never written as pred:): drive:* — ephemeral …” b)Runner-level helper _drive_tags(...) In cca8_run.py, _drive_tags(drives) is a robust helper that:

• Preferentially uses drives.flags() (new API),

• Falls back to drives.predicates() (legacy),

• Or derives flags directly from hunger/fatigue/warmth if needed: def_drive_tags(drives) -> list[str]:     ...     # Prefer the new API     if hasattr(drives, "flags"):         tags = list(drives.flags())         return [t for t in tags ifisinstance(t, str)]     ...     # Last-resort derived flags     tags = []     if drives.hunger > 0.6:tags.append("drive:hunger_high")     if drives.fatigue > 0.7:tags.append("drive:fatigue_high")     if drives.warmth < 0.3:tags.append("drive:cold")     return tags These are still internalflags; at this point nothing is in the graph yet. c) How/whendo drive flags touch the WorldGraph? Two ways:

1. As cues (our house style):_emit_interoceptive_cues converts rising-edge drive flags into cue:drive:* bindings: 2.  started =flags_now - flags_prev  # e.g.{"drive:hunger_high"} 3.  for f insorted(started): 4.      world.add_cue(f, attach=attach, 5.                    meta={"created_by":"autonomic", "ticks": ctx.ticks}) 6.      # → creates binding with tag"cue:drive:hunger_high" 7.  ctx.last_drive_flags= flags_now 8.  returnstarted So ifhunger crosses HUNGER_HIGH on an autonomic tick, you get a binding like: b6:[cue:drive:hunger_high] That’s evidence,not a goal.

2. As predicates (rare, explicit):
   If we ever want a plannable drive condition, we explicitly use pred:drive:* (or cue:drive:* as evidence). The docstring hints at this: “…controller-only flags … never written as pred:* …
   e.g., plannable drive condition → pred:drive:hunger_high, or evidence → cue:drive:hunger_high” But bydefault, we do not auto-write pred:drive:*; you’d only see that if you deliberately created it (e.g., for a demo). So the mental model: drive: = ephemeral flags on Drives (used by triggers/deficit scoring, not persisted). cue:drive: = WorldGraph evidence when drive thresholds start (rising edge). pred:drive: = explicit planner goals (only if we choose to add them).

TL;DR:

• drive:* are still ephemeral controller flags; we use cue:drive:* and pred:drive:* only when we explicitly want them in WorldGraph.

Q: Are drive:* flags stored in the WorldGraph by default? A: No. drive:* flags (e.g. drive:hunger_high, drive:fatigue_high, drive:cold) are ephemeral controller signals computed from numeric drives (hunger, fatigue, warmth) each tick. They live in the Drives object and are used by policy triggers and deficit scoring; they are not written as pred:* unless you explicitly create pred:drive:* or cue:drive:*.

Q: When do drive flags become visible as WorldGraph tags? A: Only in two cases: (1) the autonomic path deliberately emits interoceptive cues (e.g. cue:drive:hunger_high on a rising edge via _emit_interoceptive_cues), or (2) you explicitly choose to represent a plannable drive condition as pred:drive:*. By default, drive flags stay out of the graph.

Q: Why distinguish drive:* from pred:drive:* and cue:drive:? A: drive: flags are internal controller facts (“how hungry/fatigued/cold I am”) used by triggers. pred:drive:* would be a persisted fact you might plan toward, and cue:drive:* is evidence (“I just sensed cold skin”). Keeping these separate avoids cluttering the graph while still allowing you to model drive states explicitly when needed.

Q: How do policies actually see the drive state? A: Policies call drives.flags() (or the runner helper _drive_tags(drives)) to get a list of drive:* flags. They then test for the presence/absence of these flags in trigger(...) and possibly in deficit scoring, without touching the WorldGraph.

Q: If I want the agent to plan around hunger, what should I do? A: Decide whether you want hunger to be a goal or just evidence. Use pred:drive:hunger_high if you want planners to explicitly seek alleviation conditions; use cue:drive:hunger_high if it should only modulate which policies fire (e.g., SeekNipple) without becoming a planner target.

This tutorial teaches you how to build, inspect, and reason about the WorldGraph—the symbolic fast index that sits at the heart of CCA8. It’s written for developers new to the codebase.

The module implements:

• Bindings — nodes that carry tags, meta, optional engram pointers, and outgoing edges.
• Edges — directed "then" links between bindings with optional human-readable labels.
• Anchors — named bindings like NOW and NOW_ORIGIN.
• TagLexicon — a restricted, stage-aware vocabulary for tags.
• Planner — BFS (or Dijkstra) from a start binding to a pred:<token> goal.
• Persistence — to_dict() / from_dict() for snapshots.

Note: Code changes will occur over time, but the main ideas below should remain stable with the project

The snapshot shown in the Runner (menu: “Display snapshot”) pulls values directly from WorldGraph, Drives, and Ctx. It’s useful to know where they come from:

• NOW=b5 → _anchor_id(world, "NOW") (usually world._anchors["NOW"])

• NOW_ORIGIN=b1 → _anchor_id(world, "NOW_ORIGIN")

• LATEST=b9 → world._latest_binding_id (most recently created binding)

• NOW_LATEST=b9 → alias for LATEST for convenience

• CTX fields:

  • age_days → ctx.age_days
  • ticks → ctx.ticks
  • profile → ctx.profile
  • winners_k → ctx.winners_k
  • vhash64(now) → ctx.tvec64() (temporal vector fingerprint)
  • epoch → ctx.boundary_no
  • epoch_vhash64 → ctx.boundary_vhash64

• TEMPORAL:

  • dim → ctx.temporal.dim
  • sigma → ctx.temporal.sigma
  • jump → ctx.temporal.jump
  • cos_to_last_boundary → ctx.cos_to_last_boundary()

• DRIVES:

  • hunger, fatigue, warmth → drives.hunger/fatigue/warmth

• POLICIES telemetry:

  • n, succ, rate, q, last → from the “skill ledger” per policy (updated when execute() returns).

• BINDINGS / EDGES:

  • BINDINGS: iterate world._bindings in id order and print tags.
  • EDGES: scan each binding’s outgoing edges and print src --label--> dst (duplicates collapsed with ×N).

This is mostly convenience wiring around the core WorldGraph API.

At a high level, cca8_world_graph.py implements:

• A small episode graph (WorldGraph) where each binding is a time-slice,
• Edges (src → dst) with labels (often "then"),
• Anchors (NOW, NOW_ORIGIN, …) for orientation,
• A restricted lexicon (TagLexicon) to keep tags clean,
• Planning (BFS / Dijkstra) over that graph,
• Persistence (JSON-friendly snapshots).

The design is intentionally minimal: the graph is an index, not a full knowledge base. Heavy content lives in engrams; the graph just tells you what led to what.

Bindings and edges make up the graph; the lexicon and planner are the disciplines that keep it usable.

A Binding is a @dataclass(slots=True) with:

@dataclass(slots=True)
class Binding:
    id: str
    tags: set[str]
    edges: list[Edge]
    meta: dict
    engrams: dict

Families of tags we use:

• pred:* — predicates (facts/states), e.g. pred:posture:standing, pred:nipple:latched.

• action:* — actions (verbs), e.g. action:push_up, action:extend_legs.

• cue:* — cues/evidence, e.g. cue:vision:silhouette:mom, cue:drive:hunger_high.

• anchor:* — anchors, e.g. anchor:NOW, anchor:NOW_ORIGIN.

Invariants:

• Each binding has a unique id ("b1", "b2", …).

• Edges live in binding.edges on the source node.

• A binding with no tags is allowed but discouraged for long-term use (harder to interpret).

• The first pred:* tag, if present, is used as the default label in pretty paths and exports.

The public API for node creation is:

world = WorldGraph()world.set_tag_policy("allow") # or "warn"/"strict" now = world.ensure_anchor("NOW")

Anchors

now = world.ensure_anchor("NOW") # returns binding id for NOW

• If NOW exists → returns its id.

• If not → creates a binding with tags={"anchor:NOW"} and records it in world._anchors.

Predicates

b1 = world.add_predicate("posture:standing", attach="now") # writes pred:posture:standing; NOW -> b1 if attach="now"

Cues

c1 = world.add_cue("vision:silhouette:mom", attach="latest") # writes cue:vision:silhouette:mom; LATEST -> c1 if attach="latest"

Actions

a1 = world.add_action("push_up", attach="now")a2 = world.add_action("extend_legs", attach="latest") # writes action:push_up, action:extend_legs; NOW -> a1 -> a2

All three of add_predicate, add_cue, add_action accept:

• attach="now" — auto-edge NOW --then--> new.

• attach="latest" — auto-edge LATEST --then--> new.

• attach=None or "none" — no auto-edge; just create the binding and update LATEST.

world._latest_binding_id is updated to the new binding each time.

Edges are stored on the source binding:

e = {"to": dst_id, "label": "then", "meta": {...}}binding.edges.append(e)

The add_edge(...) helper is:

world.add_edge(src_id, dst_id, label="then", meta=None)

Attach helpers (attach="now"/"latest") just call add_edge(...) under the hood with label="then".

Conventions:

• Semantics: every edge is conceptually "then" — “this binding was followed by that one.”

• Labels: you may use labels like "approach", "search", "latch", "suckle" as human-facing aliases. The planner does not rely on them for correctness.

• Metrics: any numeric properties (distance, duration, speed, cost) belong in edge.meta, not in the tag name.

TagLexicon enforces a small, stage-aware vocabulary:

• STAGE_ORDER = ("neonate", "juvenile", "adult") (example).

• BASE[stage][family] lists allowed tokens for each family/stage.

• LEGACY_MAP is now empty (we’ve removed state:* and pred:action:*).

WorldGraph wires this up:

world.set_stage("neonate")world.set_tag_policy("warn") # "allow" | "warn" (default) | "strict"

When you call add_predicate/add_cue/add_action, the graph:

1. Normalizes family + token (e.g. "pred", "posture:standing"),

2. Uses _enforce_tag(family, token_local) to:

   • allow silently in "allow" mode,

   • warn (one-line log) and accept in "warn" mode,

   • raise ValueError in "strict" mode for off-lexicon tokens.

This protects you from accidental tag drift (e.g. posture_standing vs posture:standing) and keeps the early neonate vocabulary small and meaningful.

Anchors are managed via:

bid = world.ensure_anchor("NOW")

The runner also uses:

• world.set_now(bid, tag=True, clean_previous=True)
  to move NOW when a policy completes (so NOW always points to the latest stable predicate state),

• an ensure_now_origin(world) helper that sets NOW_ORIGIN once per episode.

Snapshot header shows:

NOW=b5 LATEST=b9NOW_ORIGIN=b1NOW_LATEST=b9

• NOW — the main planning start.

• NOW_ORIGIN — the root of this episode (birth).

• LATEST / NOW_LATEST — the most recently created binding id.

The planner entrypoint is:

path = world.plan_to_predicate(src_id=now, token="posture:standing")

• Goal test: “Does this binding’s tags contain pred:posture:standing?”

• Algorithm: BFS (default) or Dijkstra (if you call set_planner("dijkstra")).

• Return: list[str] of binding ids (["b1","b3","b4","b5"]) or None if the goal can’t be reached.

The Runner’s menu wraps this and prints:

• Path (ids): b1 -> b3 -> b4 -> b5

• A pretty path (with first pred:* tag per node).

• A typed path and reverse typed path that show [binding_id:label] pairs (anchor, actions, predicates).

Because edges are unweighted by default, BFS gives a shortest-hop path. If you later add costs in edge.meta (e.g. weight, cost, duration_s), Dijkstra uses those values.

Bindings can carry pointers to external memory (columns):

binding.engrams = { "column01": {"id": "<engram_id>", "act": 1.0, "meta": {...}}}

WorldGraph provides helpers (attach_engram, get_engram) but does not know what’s inside the engram payload. Heavy data is kept outside the graph for speed and simplicity.

Planner ignores engrams entirely; they matter only for analysis or for advanced perception hooks.

WorldGraph.check_invariants() can be used to validate:

• Every binding id is unique.

• All edges’ to fields point to existing bindings.

• Anchors in world._anchors point to valid bindings.

• latest (if not None) points to a valid binding.

• Optional: NOW has the anchor:NOW tag if tag=True was used in set_now.

The Runner uses various preflight probes to assert attach semantics, planner behavior, and lexicon enforcement are all working as intended.

from cca8_world_graph import WorldGraph # 1. Create world and anchors g = WorldGraph()g.set_tag_policy("allow") # be permissive while experimenting now = g.ensure_anchor("NOW") # 2. Build a tiny S–A–S episode: fallen → stand_up → standing fallen = g.add_predicate("posture:fallen", attach="now")a1 = g.add_action("push_up", attach="now")a2 = g.add_action("extend_legs", attach="latest")standing = g.add_predicate("posture:standing", attach="latest") # 3. Plan and pretty-print path = g.plan_to_predicate(now, "posture:standing") print("Path:", path) print(g.plan_pretty(now, "posture:standing"))

Typical output:

Path: ['b1','b3','b4','b5']b1(NOW_ORIGIN) --then--> b3[action:push_up] --then--> b4[action:extend_legs] --then--> b5[posture:standing](NOW)

From here you can add cues, attach engrams, export to Pyvis HTML, and exercise the rest of the WorldGraph features with confidence.

Note: Code changes will occur over time, but the main ideas below should remain stable with the project

These are the main internal fields of a WorldGraph instance:

• _bindings: dict[str, Binding]
  All bindings by id (e.g. "b7" → Binding(...)).

• _anchors: dict[str, str]
  Anchor name → binding id (e.g. "NOW" → "b5", "NOW_ORIGIN" → "b1").

• _latest_binding_id: str | None
  Id of the most recently created binding, regardless of family (pred, action, cue, or anchor).

• _id_counter: itertools.count
  Generator for "b<N>" ids (b1, b2, …).

• _lexicon: TagLexicon
  Restricted vocabulary for tags, per stage & family (pred, action, cue, anchor).

• _stage: str
  Current developmental stage (e.g. "neonate", "juvenile", "adult").

• _tag_policy: str
  Lexicon enforcement policy: "allow", "warn" (default), or "strict".

• _plan_strategy: str
  Planner choice: "bfs" (unweighted shortest-hop) or "dijkstra" (weighted edges).

Module-level constant:

• _ATTACH_OPTIONS: set[str] = {"now", "latest", "none"}
  Valid values for attach= in add_predicate, add_cue, and add_action.

This is a quick overview of the most important methods. The “Cheat-sheet: WorldGraph public API” section below contains a more detailed list.

Lifecycle & config

• WorldGraph() — empty graph, stage=neonate, policy=warn, planner from CCA8_PLANNER env (default bfs).

• set_stage(stage: str) / set_stage_from_ctx(ctx)

• set_tag_policy(policy: str) — "allow"|"warn"|"strict"

• set_planner(strategy: str = "bfs") / get_planner() -> str

Anchors & orientation

• ensure_anchor(name: str) -> str — create/get anchor binding (tags it anchor:<NAME>).

• set_now(bid: str, *, tag=True, clean_previous=True) — repoint the NOW anchor; tidy tags.

Nodes

• add_predicate(token: str, *, attach: str|None = None, meta=None, engrams=None) -> str

  • Creates pred:<token> node; updates latest.

  • attach="now"|"latest"|"none" → auto-edge (NOW→new) or (latest→new) or none.

• add_cue(token: str, *, attach: str|None = None, meta=None, engrams=None) -> str

  • Same semantics; creates cue:<token>; updates latest.

• add_action(token: str, *, attach: str|None = None, meta=None, engrams=None) -> str

  • Creates an action:<token> node; updates latest.

  • attach="now"|"latest"|"none" → auto-edge (NOW→new) or (latest→new) or none.

• add_binding(tags: set[str], *, meta=None, engrams=None) -> str

  • Low-level constructor (prefer the helpers above).

Edge (TypedDict)

• Shape: {"to": str, "label": str, "meta": dict}

• Purpose: stored on the source Binding to represent a directed edge and its label/metrics.

• Example: e: Edge = {"to": "b7", "label": "stand", "meta": {"duration_s": 2.5}}

Binding (dataclass, slots=True)

Fields:

• id: str — e.g., "b42".

• tags: set[str] — e.g., {"pred:posture:standing"} or {"anchor:NOW"}.

• edges: list[Edge] — outgoing edges.

• meta: dict — provenance/context.

• engrams: dict — small pointers into column memory.

Helpers: b_dict = b.to_dict() b2 = Binding.from_dict(b_dict) TagLexicon

• Class attrs (constants):
  STAGE_ORDER = ("neonate","infant","juvenile","adult")
BASE: dict[stage][family] -> set[str] (allowed tokens per stage & family)
  LEGACY_MAP: dict[str, str] (legacy → preferred)

• Instance:

  • self.allowed: dict[str, dict[str, set[str]]] (cumulative per stage)

  • Methods:

    • is_allowed(family, token, stage) -> bool

    • preferred_of(token) -> str | None

    • normalize_family_and_token(family, raw) -> (family, local_token)

      • E.g., ("pred", "pred:posture_standing") -> ("pred", "posture_standing")

• _bindings: dict[str, Binding]

• _anchors: dict[str, str] (e.g., "NOW" -> "b1")

• _latest_binding_id: str | None

• _id_counter: itertools.count ("b<N>" ids)

• _lexicon: TagLexicon

• _stage: str ("neonate" …)

• _tag_policy: str ("allow"|"warn"|"strict")

• _plan_strategy: str ("bfs"|"dijkstra")

Lifecycle & config

• WorldGraph() — empty graph, stage=neonate, policy=warn, planner from CCA8_PLANNER env (default bfs).

• set_stage(stage: str) / set_stage_from_ctx(ctx)

• set_tag_policy(policy: str) — "allow"|"warn"|"strict"

• set_planner(strategy: str = "bfs") / get_planner() -> str

Anchors & orientation

• ensure_anchor(name: str) -> str — create/get anchor binding (tags it anchor:<NAME>).

• set_now(bid: str, *, tag=True, clean_previous=True) — repoint the NOW anchor; tidy tags.

Nodes

• add_predicate(token: str, *, attach: str|None = None, meta=None, engrams=None) -> str

  • Creates pred:<token> node; updates latest.

  • attach="now"|"latest"|"none" → auto-edge (NOW→new) or (latest→new) or none.

• add_cue(token: str, *, attach: str|None = None, meta=None, engrams=None) -> str

  • Same semantics; creates cue:<token>; updates latest.

• add_action(token: str, *, attach: str|None = None, meta=None, engrams=None) -> str

  • Creates an action:<token> node; updates latest.

  • attach="now"|"latest"|"none" → auto-edge (NOW→new) or (latest→new) or none.

• add_binding(tags: set[str], *, meta=None, engrams=None) -> str

  • Low-level constructor (prefer the helpers above).

Edges & actions

• add_edge(src_id: str, dst_id: str, label: str, meta: dict|None = None, *, allow_self_loop=False) -> None

• delete_edge(src_id: str, dst_id: str, label: str|None = None) -> int (returns removed count)

Planning & display

• plan_to_predicate(src_id: str, token: str) -> list[str]|None

  • Uses bfs (default) or dijkstra depending on get_planner().

• pretty_path(ids: list[str]|None, *, node_mode="id+pred", show_edge_labels=True, annotate_anchors=True) -> str

• plan_pretty(src_id: str, token: str, **kwargs) -> str — convenience: plan + pretty.

Actions / metrics

• list_actions(*, include_then=True) -> list[str]

• action_counts(*, include_then=True) -> dict[str, int]

• edges_with_action(label: str) -> list[tuple[str, str]]

• action_metrics(label: str, *, numeric_keys=("meters","duration_s","speed_mps")) -> dict

• action_summary_text(label: str|None = None) -> str

Persistence / checks / viz

• to_dict() -> dict

• from_dict(data: dict) -> WorldGraph (class method; advances id counter above max "b<N>")

• check_invariants(*, raise_on_error: bool = True) -> list[str]

• to_pyvis_html(*, physics: bool = True, node_mode: str = "id+pred") -> str

from cca8_world_graph import WorldGraph
g = WorldGraph()
g.set_tag_policy("allow")  # keep lexicon quiet while learning
now = g.ensure_anchor("NOW")

b1 = g.add_predicate("posture:standing", attach="now")     # NOW -> b1
b2 = g.add_cue("vision:silhouette:mom", attach="latest")   # b1 -> b2
print(g.plan_pretty(now, "posture:standing"))              # NOW -> b1

fallen = g.add_predicate("posture:fallen", attach="none")
stand  = g.add_predicate("posture:standing", attach="none")
g.add_edge(fallen, stand, label="stand", meta={"duration_s": 3.2})
print(g.plan_pretty(fallen, "posture:standing"))  # fallen --stand--> standing

a = g.add_predicate("alert", attach="latest")
b = g.add_predicate("seeking_mom", attach="latest")
c = g.add_predicate("nipple:found", attach="latest")
print(g.plan_pretty(now, "nipple:found"))  # NOW -> ... -> c

print(g.get_planner())   # 'bfs'
g.set_planner("dijkstra")
print(g.get_planner())   # 'dijkstra'

print(g.list_actions())               # ['stand', 'then', ...]
print(g.action_counts())              # {'stand': 1, 'then': 4, ...}
print(g.action_metrics("stand"))      # aggregates edge.meta for 'stand'
print(g.action_summary_text())        # readable summary of actions

snap = g.to_dict()
# ... write to JSON if you like ...
g2 = WorldGraph.from_dict(snap)       # id counter advanced above max b<N>

issues = g.check_invariants(raise_on_error=False)
print(issues)  # [] when all good

path = g.plan_to_predicate(now, "seeking_mom")
print(g.pretty_path(path, node_mode="id+pred", show_edge_labels=True))
# variants: node_mode='id' or 'pred'; annotate_anchors=True/False

bid = g.add_predicate("alert", attach="latest")
g.attach_engram(bid, column="column01", engram_id="engr_123", act=0.9, extra_meta={"note": "demo"})
print(g.get_engram(bid, column="column01"))

This tutorial explains the exact BFS discipline the CCA8 planner uses over the WorldGraph’s adjacency list. It is written to be followed with pencil-and-paper; no code is required.

BFS is deliberately simple: a queue, a parent map, and two rules (visited-on-enqueue, stop-on-pop). In CCA8 this simplicity pays off—planning remains predictable and fast, and the returned paths are immediately readable against the episode structure.

• Goal: find a shortest-hop path (fewest edges) from a start binding (by default, the NOW anchor) to any binding whose tags contain the requested pred:<token>.

• Why BFS: WorldGraph edges are unweighted. BFS guarantees the first time you pop a node (remove it from the left of the queue) you have reached it by a shortest number of edges.

• Data you maintain while running BFS:

  • Frontier — a FIFO queue (think deque) of nodes discovered but not yet expanded.

  • Expanded — the set of nodes already popped/processed.

  • Parent — a discovery map {child: parent} that doubles as the visited set.

Rules used here (and by CCA8):
Visited-on-enqueue (never enqueue a node that already appears in parent) and Stop-on-pop (return as soon as the goal node is popped).

Adjacency (directed; neighbor order matters):

• S → [A, B]

• A → [C, D]

• B → [D, E]

• C → [G]

• D → [E, A] (cycle back to A)

• E → [G]

• G → []

Start: S  Goal: G

We will record the three buckets at each step:

• frontier = [...]

• expanded = {…}

• parent = {child: parent, ...}

frontier = [S] expanded = {} parent = {S: None}

Neighbors in order: A, B.

frontier = [A, B] expanded = {S} parent = {S: None, A: S, B: S}

Neighbors: C, D.

frontier = [B, C, D] expanded = {S, A} parent = {S: None, A: S, B: S, C: A, D: A}

Neighbors: D, E.
D is already in parent (visited-on-enqueue), so skip D; enqueue only E.

frontier = [C, D, E] expanded = {S, A, B} parent = {S: None, A: S, B: S, C: A, D: A, E: B}

Neighbor: G (the goal). Enqueue it.

frontier = [D, E, G] expanded = {S, A, B, C} parent = {S: None, A: S, B: S, C: A, D: A, E: B, G: C}

Neighbors: E, A. Both already discovered; skip.

frontier = [E, G] expanded = {S, A, B, C, D} parent = {S: None, A: S, B: S, C: A, D: A, E: B, G: C}

Neighbor: G (already discovered); skip.

frontier = [G] expanded = {S, A, B, C, D, E} parent = {S: None, A: S, B: S, C: A, D: A, E: B, G: C}

We are using stop-on-pop: the moment G is popped, we stop.

Final buckets:

frontier = [] expanded = {S, A, B, C, D, E, G} parent = {S: None, A: S, B: S, C: A, D: A, E: B, G: C}

Note: With visited-on-enqueue, you never actually hold duplicate entries like [G, E, G] in the frontier. The second G would have been skipped at discovery.

Use the parent map to walk backward from the goal to the start, then reverse:

• G ← C ← A ← S → reverse → S → A → C → G

Path length (edges): 3.

There is also an equally short route S → B → E → G. BFS returns the first shortest path it pops; neighbor order determines which one appears.

Compute distances (in edges) from S by layer:

• dist(S) = 0

• dist(A) = 1, dist(B) = 1

• dist(C) = 2, dist(D) = 2, dist(E) = 2

• dist(G) = 3

Layers (by distance):

• L0: {S}

• L1: {A, B}

• L2: {C, D, E}

• L3: {G}

Why BFS guarantees shortest paths: the frontier (a queue) ensures you completely explore Lk before touching Lk+1. When a node at Lk+1 is first popped, there cannot exist a path with fewer than k+1 edges to it that you haven’t already discovered.

If you swap the order at S to [B, A], you will still find a shortest path of length 3, but the pop order and the returned path may differ (e.g., via B → E → G). BFS correctness doesn’t change; only the specific shortest path chosen among equals may change.

The edge D → A introduces a cycle. Visited-on-enqueue prevents re-enqueuing already discovered nodes, so BFS never loops. This is the standard cycle-safety discipline.

Both conventions produce correct shortest paths in an unweighted graph:

• Stop-on-pop (used here): simpler logs; the pop order matches layers.

• Stop-on-discovery: returns as soon as the goal is enqueued; also correct but may be slightly less intuitive when you read queue traces.

CCA8 uses stop-on-pop.

• Start node: the binding id referenced by the NOW anchor.

• Goal test: “do the tags of this popped binding contain the exact token pred:<token>?”

• Path reconstruction: backtrack with parent to NOW, then reverse.

• Frontier implementation: a deque for O(1) popleft(); never re-enqueue a node once it appears in parent.

Practical example: To plan toward milk drinking, set NOW as your start and request the goal token pred:milk:drinking. The first binding popped that carries this tag ends the search; the reconstructed path is a shortest-hop route from NOW.

• Duplicate frontier entries: violated visited-on-enqueue. Always check if v not in parent before enqueue.

• “No path found”: verify the exact goal token (pred:...), confirm edges form a forward chain from NOW, and watch for reversed links (B→A instead of A→B).

• Neighbor order surprises: BFS may return a different (but equally short) path when neighbor orders change; that’s expected.

• Assuming labels matter: BFS follows structure, not action labels. Labels are for readability and (later) analytics/costs.

1. In the given adjacency, what is the pop order under stop-on-pop?
   Answer: S, A, B, C, D, E, G.

2. What are the three buckets immediately after popping G?
   Answer:
   frontier = []
expanded = {S, A, B, C, D, E, G}
parent = {S:None, A:S, B:S, C:A, D:A, E:B, G:C}

3. Give a shortest path and its length.
   Answer: S → A → C → G (3 edges) — S → B → E → G is also 3.

4. Distances from S?
   Answer: S:0, A:1, B:1, C:2, D:2, E:2, G:3.

CCA8 keeps two main maps:

WorldGraph – the episode index: “what happened over time” (states, actions, cues, weak causality).

BodyMap – a tiny, always-on map of the agent’s own body plus the immediate near world.

BodyMap is implemented as a separate WorldGraph instance (ctx.body_world) with a small, fixed set of slots (ctx.body_ids):

root – the body as a whole (anchor:BODY_ROOT).

posture – overall posture (pred:posture:fallen, pred:posture:standing, pred:resting).

mom – mom’s distance relative to the body (pred:proximity:mom:far / pred:proximity:mom:close).

nipple – nipple / latch state (pred:nipple:hidden, pred:nipple:found, pred:nipple:latched, plus pred:milk:drinking when feeding). (at the time of writing, the software emulates a newborn goat and thus this is an important part of its world; the fixed set of slots will expand and change with software development and of course, development of the goat)

Edges form a tiny body-centred scene graph:

BODY_ROOT --body_state--> POSTURE BODY_ROOT --body_relation--> MOM MOM --body_part--> NIPPLE

BodyMap is the body schema + peripersonal near space. It represents “how my body is configured right now, and where crucial things are relative to me” (mom, nipple, later shelter/cliff), not the full world.

WorldGraph is the story of the world over time. It accumulates all posture/feeding events, actions, cues, and transitions as an episode index for planning and inspection.

The environment pipeline keeps the separation clean:

HybridEnvironment maintains EnvState (God’s-eye world state) and produces EnvObservation.

The runner:

injects EnvObservation.predicates / .cues into the main WorldGraph as pred:* / cue:*, and

mirrors discrete posture / mom-distance / nipple predicates into BodyMap via update_body_world_from_obs(ctx, env_obs).

The controller then treats BodyMap as the authoritative, body-centred register for gating:

body_posture(ctx) → "standing" | "fallen" | "resting" | None

body_mom_distance(ctx) → "near" | "far" | None

body_nipple_state(ctx) → "latched" | "found" | "hidden" | None

Policies read BodyMap first, and fall back to the episode graph only when BodyMap is stale or missing. For example:

StandUp uses BodyMap posture to decide whether to stand and when to stop retrying.

SeekNipple uses BodyMap posture, nipple state, and (when available) mom distance (“don’t seek nipple if mom is clearly far”).

In short:

WorldGraph = compact symbolic episode index over time.

BodyMap = compact, body-centred near-space map (posture + mom + nipple, later shelter/cliff) reflecting “right now”.

The detailed structure and update rules for BodyMap are described below.

The newborn goat doesn’t just have a world graph – it has a sense of its own body and the immediate world around it. In the current CCA8 build, this is captured by a small, separate graph called the BodyMap.

BodyMap is implemented as a second WorldGraph instance (ctx.body_world) with a handful of fixed nodes (ctx.body_ids) that act like a structured register:

root – the body as a whole (anchor:BODY_ROOT).

posture – overall posture (pred:posture:fallen / pred:posture:standing / pred:resting).

mom – mom’s distance relative to the body (pred:proximity:mom:far / pred:proximity:mom:close).

nipple – nipple / latch state (pred:nipple:hidden / pred:nipple:found / pred:nipple:latched, plus pred:milk:drinking when latched and feeding).

Edges encode a tiny body-centered scene graph:

BODY_ROOT --body_state--> POSTURE BODY_ROOT --body_relation--> MOM MOM --body_part--> NIPPLE

This is enough to express the core neonatal situation: “I am fallen or standing; mom is far/near; nipple is hidden/found/latched.”

Initialization (Runner)

At runner startup, interactive_loop(...) calls a helper:

ctx.body_world, ctx.body_ids = init_body_world()

init_body_world():

creates a new WorldGraph() for the BodyMap,

seeds four bindings: root, posture, mom, nipple,

tags them with the default neonatal state:

posture: pred:posture:fallen

mom: pred:proximity:mom:far

nipple: pred:nipple:hidden

These are body-side defaults before any environment step runs.

Update from EnvObservation

Every time the environment produces a new observation (via HybridEnvironment.step(...)), the runner calls:

inject_obs_into_world(world, ctx, env_obs) update_body_world_from_obs(ctx, env_obs)

update_body_world_from_obs(...) mirrors discrete predicates from EnvObservation.predicates into the BodyMap slots:

If posture:standing appears in env_obs.predicates, BodyMap’s posture node’s tags are rewritten to include pred:posture:standing (and drop old posture tags).

If posture:fallen appears, it becomes pred:posture:fallen.

If resting appears, BodyMap marks pred:resting.

proximity:mom:close / proximity:mom:far update the mom slot.

nipple:found / nipple:latched / milk:drinking update the nipple slot accordingly (with pred:milk:drinking added when latched+feeding).

So on every env step we have:

EnvState → PerceptionAdapter → EnvObservation │ ├─→ main WorldGraph (pred:* / cue:*) └─→ BodyMap (posture / mom / nipple slots)

Snapshot output includes a compact BODYMAP panel:

BODYMAP (body + near-world): (different map than the larger WorldGraph) (same binding ids e.g., 'b1','b2', etc. but different map) root : b1: [anchor:BODY_ROOT] posture: b2: [pred:posture:fallen] mom : b3: [pred:proximity:mom:far] nipple : b4: [pred:nipple:hidden]

Note: binding ids (b1, b2, …) in BodyMap are separate from the main WorldGraph; each graph instance has its own bN space.

Reading BodyMap like a register (controller helpers)

To make BodyMap feel like simple fields, the controller exposes three helpers:

body_posture(ctx) -> "fallen" | "standing" | "resting" | None body_mom_distance(ctx) -> "far" | "near" | None body_nipple_state(ctx) -> "hidden" | "found" | "latched" | None

Internally they:

look up ctx.body_world and ctx.body_ids["posture" / "mom" / "nipple"],

read tags on those bindings,

return a simple string label so policies don’t need to know anything about the BodyMap’s internal structure.

The runner also prints a small BodyMap summary on each environment step:

[body] posture='fallen' mom_distance='far' nipple_state='hidden'

This line comes directly from body_posture, body_mom_distance, body_nipple_state and is a quick check that BodyMap is tracking the environment.

BodyMap is the preferred source of body state for gating policies:

StandUp gate (BodyMap-first):

bp = body_posture(ctx) if bp is not None: fallen = (bp == "fallen") standing = (bp == "standing") else: fallen = has_pred_near_now(world, "posture:fallen") standing = has_pred_near_now(world, "posture:standing")

stand_intent = has_pred_near_now(world, "stand") trigger = fallen or (stand_intent and not standing)

So when BodyMap posture flips from "fallen" to "standing", the StandUp gate naturally stops firing (except for the separate safety override, which will be updated in a future phase to also consult BodyMap).

SeekNipple gate (BodyMap posture + nipple state):

hunger = drives.hunger bp = body_posture(ctx) ns = body_nipple_state(ctx)

roughly: trigger = ( hunger > HUNGER_HIGH and bp == "standing" and ns != "latched" and not has_pred_near_now(world, "seeking_mom") )

Once BodyMap’s nipple slot reaches "latched" and milk:drinking is present, body_nipple_state(ctx) == "latched" and SeekNipple stops firing — a simple but realistic “don’t keep seeking when you’re already latched and drinking” rule.

This pattern will extend naturally to future BodyMap fields (e.g., a “balance” or “contact” slot, or limb-specific posture) without forcing policies to change their call sites.

WorldGraph: big, episode-level map over what happened (states, actions, cues, transitions). It accumulates all the posture:fallen and posture:standing bindings over time and is used for planning and discrepancy diagnostics.

BodyMap: tiny, always-on body-centered map for what is true of my body right now (plus very small near-world: mom, nipple). It is updated from the latest EnvObservation, independent of how messy the episode graph has become.

You can think of it as:

WorldGraph = “story of my life” BodyMap = “how my body is configured right now (and where mom/nipple are relative to me)”

Later phases will expand BodyMap and add a PeripersonalMap, but this v1 gives us a proper place for sensor-fused body state while keeping the main WorldGraph small and semantic.

Q: Why use a separate WorldGraph for BodyMap instead of just tags in Ctx?

A: Two reasons: (1) Conceptual honesty — BodyMap really is a tiny map, not just a flat struct, and we want that structure available when we’re ready to grow it (e.g., split posture into limbs, add contact nodes). (2) Uniform tools — by using WorldGraph again, we can reuse invariants, snapshot logic, and future graph tools (FOA, queries) without inventing a new mini-DSL.

Q: Do BodyMap binding ids collide with the main WorldGraph ids?

A: No. Each WorldGraph instance has its own bN counter. b3 in BodyMap is not the same as b3 in the main world. Snapshot clearly separates them: BODYMAP shows ctx.body_world, the BINDINGS/EDGES sections show the main world.

Q: What is the relationship between BodyMap and EnvObservation?

A: BodyMap is updated directly from EnvObservation.predicates via update_body_world_from_obs(ctx, env_obs). So at each env step, BodyMap mirrors the latest sensed posture/mom/nipple state. It is a per-step state estimate, not a long-term history; history lives in the main WorldGraph.

Q: Which policies read BodyMap today?

A: The StandUp and SeekNipple gates (via body_posture(ctx) and body_nipple_state(ctx)) prefer BodyMap when it’s available and only fall back to scanning the main WorldGraph when BodyMap is missing. This makes basic posture and latch decisions depend on the body schema, which is closer to how real animals (and robots with a state estimator) behave.

Q: Does BodyMap affect planning or just gating?

A: Today it affects policy gating and diagnostics, not planning: BFS/Dijkstra still operate over the main WorldGraph. In the future, we may add small queries over BodyMap (e.g., “which body parts are in contact?”) and integrate that into path selection or spatial reasoning, but the fast episode planner remains graph over the main world.

In addition to posture, mom-distance, and nipple state, BodyMap at this time of writing tracks two extra near-world slots that matter for survival:

• shelter – distance to a safe resting niche (pred:proximity:shelter:far / pred:proximity:shelter:near).

• cliff – proximity of a dangerous drop (pred:hazard:cliff:far / pred:hazard:cliff:near).

The BodyMap graph is extended accordingly:

BODY_ROOT --body_state--> POSTURE BODY_ROOT --body_relation--> MOM BODY_ROOT --body_relation--> SHELTER BODY_ROOT --body_danger--> CLIFF MOM --body_part--> NIPPLE

These slots are kept deliberately simple at the newborn stage:

shelter_distance is “far” early in the story and becomes “near” when the kid has moved into a sheltered resting position near mom.

cliff_distance is “near” during early struggle/first-stand (exposed terrain) and “far” once the kid is in a safer sheltered niche.

The Environment module (EnvState + FsmBackend + PerceptionAdapter) drives these slots:

EnvState.shelter_distance / cliff_distance are updated as part of the newborn storyboard (birth → struggle → first_stand → first_latch → rest).

PerceptionAdapter.observe(...) emits proximity:shelter:* and hazard:cliff:* predicates.

update_body_world_from_obs(ctx, env_obs) mirrors those predicates into the BodyMap shelter and cliff nodes (just like posture/mom/nipple).

Controller helpers make these easy to read:

body_shelter_distance(ctx) -> "near" | "far" | None

body_cliff_distance(ctx) -> "near" | "far" | None

These helpers are used in gates and policies when deciding whether it is safe to rest or which actions are appropriate in the current geometry.

When this README talks about the geometry of the environment, it is not referring to school-style angles and triangles. Instead, “environment geometry” means the spatial configuration of the scene: where, for example, the kid, mom, shelter, and cliff are, and how they are related (near, far, under shelter, near a drop, etc.).

In CCA8 there are three closely related layers that together define this geometry:

1. EnvState (God’s-eye world)
   The Environment module keeps a canonical EnvState with fields such as kid_posture, mom_distance, nipple_state, kid_position, mom_position, and high-level scenario_stage (birth → struggle → first_stand → first_latch → rest). This is the environment’s own notion of “where everything is and what is happening right now.” :contentReference[oaicite:0]{index=0}

2. BodyMap (body-centred near space)
   BodyMap is a tiny, separate WorldGraph that tracks the geometry as experienced by the body: posture (fallen/standing/resting), mom’s proximity (far/near/touching), nipple state (hidden/found/latched/milk:drinking), and safety-relevant slots for shelter and cliff (shelter near/far, cliff near/far). From BodyMap you can ask, “Is it safe to lie down here?” or “Is mom close enough to seek the nipple?” without scanning the full episode history.

3. WorldGraph spatial overlay (episode-level geometry)
   The main WorldGraph stores episodic traces of geometry using predicates and a small scene-graph overlay. For example, when the kid is resting safely, the runner writes edges like
   NOW --near--> b_mom_close and NOW --near--> b_shelter_near,
   where the target bindings carry tags such as pred:proximity:mom:close and pred:proximity:shelter:near. These edges say, “in this episode moment, SELF (NOW) is near mom and near shelter,” and can be inspected later via the snapshot, Pyvis export, or the spatial scene demo menu.

Hazard-aware Rest: “don’t lie down at the cliff edge”

Resting is now BodyMap-aware in a simple but important way:

When fatigue is high, policy:rest may be considered by the Action Center.

Before it actually changes anything, Rest.execute(...) consults BodyMap:

cliff = body_cliff_distance(ctx) shelter = body_shelter_distance(ctx) if cliff == "near" and shelter != "near": return self._fail("unsafe to rest (cliff near, shelter not near)")

In that case, Rest fails fast:

no change to drives (fatigue is not reduced),

no pred:resting binding is written.

Only when BodyMap says the geometry is safe:

shelter_distance == "near" and

cliff_distance == "far"

does Rest.execute(...) succeed, reduce fatigue, and assert a resting state.

This matches the ethological intuition:

The kid may attempt to rest near a drop, but the architecture refuses to actually lie down until it is in a sheltered, safer position.

Spatial overlay on the WorldGraph: NOW-near edges

BodyMap is the live, body-centred map. The main WorldGraph now carries a tiny scene-graph overlay derived from BodyMap and the environment:

At resting times, the runner inspects the current EnvObservation:

if it contains resting,

plus proximity:mom:close and/or proximity:shelter:near,

it writes small spatial edges out of the NOW anchor:

NOW --near--> b_mom_close NOW --near--> b_shelter_near

The destination bindings already carry their own tags:

pred:proximity:mom:close

pred:proximity:shelter:near

and any other metadata (e.g., temporal context, provenance).

The result is a very small spatial layer in the main episode graph:

The edge label vocabulary is kept minimal: near only (with inside and supports stubbed in code for future use).

Nodes still carry all semantics via their tags; the near edges just say “SELF (NOW) is currently near this mom-near / shelter-near node.”

In snapshot output, you will see entries like:

b1 --near--> b183 b183: [pred:proximity:mom:close]

b1 --near--> b184 b184: [pred:proximity:shelter:near]

interpreted as:

“At this resting moment, NOW (SELF) is near mom and near shelter.”

Spatial queries and menu demos

To make this spatial structure easy to inspect, the runner provides a couple of small query helpers and a menu demo.

Helpers (in cca8_run.py):

neighbors_near_self(world) -> list[str]

Returns all binding ids reachable via NOW --near--> *. Useful when you want to know “what is SELF currently near?” without scrolling the whole edge list.

resting_scenes_in_shelter(world) -> dict[str, Any]

Returns a summary dict like:

{ "rest_near_now": True/False, # is any 'resting' near NOW? "shelter_near_now": True/False, # is NOW near shelter-near bindings? "shelter_bids": [...], # the shelter-near binding ids "hazard_cliff_far_near_now": True/False, # is any 'hazard:cliff:far' near NOW? }

This is a convenience wrapper for the “resting in shelter, cliff far” situation.

Menu 39 – Spatial scene demo

The runner adds a small TUI demo:

“Spatial scene demo (NOW-near + resting-in-shelter?)” (menu 39).

It prints:

all NOW-near neighbors, showing their tags:

NOW-near neighbors: b183: [pred:proximity:mom:close] b184: [pred:proximity:shelter:near] ...

a one-line summary of the resting-in-shelter pattern:

Resting-in-shelter scene summary (around NOW): rest_near_now: True shelter_near_now: True hazard_cliff_far_near_now: True shelter_bids (NOW --near--> ...): b184: [pred:proximity:shelter:near] ...

Together with the BODYMAP summary line and the BodyMap Inspect menu, this gives a compact, readable picture of:

current posture,

near-space geometry (mom / shelter / cliff),

and where, in the episode graph, REST is happening (or being refused) as a function of that geometry.

In CCA8, valence is a simple notion:

how good or bad a configuration feels to the agent, in a way that can guide future approach/avoid decisions.

It is not just a one-off reward at a single time step, but a small, symbolic marker that says:

• “being in this kind of situation tends to be good for me”, or
• “being in this kind of situation tends to be bad for me”.

In biological brains, valence is closely tied to:

• Body state (hunger relief, warmth, pain).
• Near-space geometry (safe shelter vs exposed cliff).
• Social relations (comfort near mom vs separation).

CCA8 deliberately mirrors this by letting valence sit on top of the same spatial maps that drive behaviour:

• BodyMap tells the agent how its body is configured and what is nearby (posture, mom distance, shelter, cliff).
• The main WorldGraph records episodes with posture / proximity / hazard facts.
• Spatial edges (like NOW --near--> mom_near and NOW --near--> shelter_near) mark which nodes are currently near SELF.

Valence connects directly to these:

• We do not treat “like/hate” as a separate channel or a mysterious scalar floating around; instead we attach valence to specific bindings in the WorldGraph (and, later, potentially to BodyMap configurations).
• That way, the system is able to learn regularities like:
  • “When I am near mom and latched I tend to like this configuration.”
  • “When I am resting in shelter with the cliff far away this is usually safe and desirable.”

This matters pragmatically because:

• Planning and policy selection can be biased toward liked regions of the world graph (states and trajectories that were tagged as good), and away from strongly disliked regions.
• Spatial queries and the scene-graph overlay can be extended to ask not only “what am I near?” but also “what am I near that I historically like?”

The current Phase V implementation stops at representing a tiny amount of valence; using it for learning and policy bias is left to a future, more explicit RL/learning phase.

Valence in CCA8 is implemented as a small, explicit predicate vocabulary plus a couple of helpers and a minimal newborn wiring.

1. Valence tokens in the lexicon

The tag lexicon (TagLexicon.BASE) defines two canonical valence predicates:

• valence:like
• valence:hate

These live in the predicate family (pred:valence:like, pred:valence:hate) and are available starting at the neonate stage. That means any stage (neonate → juvenile → adult) can attach simple “like/hate” markers to its episodes without fighting the tag policy.

2. Node-level valence tags

Valence is represented as an extra tag on specific bindings in the WorldGraph. A typical example after the Phase V work is:

b143: [pred:proximity:mom:close, pred:valence:like] This says:

“Binding b143 represents a state where mom is close, and the agent tags this configuration as liked.”

Crucially:

Valence is attached to a relational configuration, not a mysterious global “mom is always good” or “cliff is always bad”.

The same object (e.g., cliffs) could later be tagged positively in other contexts (e.g., a safe refuge from predators). The representation does not hard-code “hate cliff”.

3. Minimal newborn wiring: ‘like mom’

In the current newborn goat scenario, we make one small but concrete choice:

When an EnvObservation simultaneously reports:

nipple:latched, and

proximity:mom:close

The runner identifies the binding created for proximity:mom:close in that step, and adds:

text Copy code pred:valence:like to its tags.

This is implemented as a tiny helper in the runner:

It uses the token_to_bid map from inject_obs_into_world(...) to find the mom-near binding for that observation.

It adds pred:valence:like to that binding’s tag set.

Over time, the WorldGraph accumulates a series of bindings like:

text Copy code b103: [pred:proximity:mom:close, pred:valence:like] b113: [pred:proximity:mom:close, pred:valence:like] b123: [pred:proximity:mom:close, pred:valence:like] ... These are precisely those moments when the kid was near mom and nursing. They are then connected to NOW via NOW --near--> * edges at resting times, so spatial queries like “what is NOW near?” will often list mom-close-liked bindings in safe resting configurations.

4. Future extensions: valence nodes and strengths (stubs)

The controller also provides a stub helper:

add_valence_binding(world, ctx, polarity, *, target=None, strength=1.0)

which, when used, will create a separate valence binding carrying:

pred:valence:like or pred:valence:hate,

plus meta fields:

python Copy code { "valence_polarity": "like" or "hate", "valence_target": "mom" / "cliff" / "shelter" / "research:direction_A" / ..., "valence_strength": float, ... } The current newborn implementation does not use this helper yet; it is provided as a structured way to represent more abstract or longer-lasting valence in future phases (e.g., research strategies, complex environments), without scattering ad-hoc meta fields through the code.

5. Where valence will plug in later

In the present Phase V work, valence is entirely representational:

No gate or planner reads pred:valence:like or pred:valence:hate yet.

No edge weights or policy scores are adjusted based on valence.

This is intentional: Phase V focuses on getting the wiring and structure right (BodyMap, spatial overlay, safety logic, valence tags). In a future learning/RL phase, these valence predicates can be used to:

bias planning toward “liked” trajectories in the WorldGraph,

modulate policy selection (e.g., prefer actions that preserve mom-close-liked configurations),

and serve as a structured target for RL-style value functions that are grounded in the same spatial/episodic maps the rest of CCA8 uses.

In summary:

Valence in CCA8 is a small, explicit symbolic layer sitting on top of the same spatial and episodic machinery as posture, shelter, and cliffs. Today it records “like mom when close and feeding”; tomorrow it can help the agent decide where to go and what to do.

Q: Why put shelter and cliff into BodyMap instead of a separate PeripersonalMap?

A: BodyMap already mixes body and very-near world (posture, mom distance, nipple state).

Adding shelter and cliff slots simply makes that explicit: BodyMap is a body-centred near-space map. If we created a separate PeripersonalMap, we would have to keep two sources of truth for “is shelter near me?” and “is cliff near me?”, which is error-prone. With the current design:

• BodyMap owns posture + mom + nipple + shelter + cliff.
• Policies ask one authority (body_* helpers) for this information.
• The main WorldGraph stores episodes over time, not a second near-space map.

This keeps the architecture simple: WorldGraph = story over time; BodyMap = body + immediate near world.

Q: What exactly happens when Rest is blocked near a cliff?

*A:When fatigue is high, the controller may select policy:rest based on drives. However, Rest.execute(...) now checks BodyMap:

cliff = body_cliff_distance(ctx) shelter = body_shelter_distance(ctx) if cliff == "near" and shelter != "near": return self._fail("unsafe to rest (cliff near, shelter not near)")

In this situation:

Rest returns fail (status "fail", reward 0.0).

Fatigue is not reduced.

No pred:resting predicate is written.

So the goat may “try” to rest, but the architecture refuses to actually lie down at the edge. Once BodyMap says shelter=near and cliff=far, Rest is allowed to succeed and assert a resting state.

Q: How do the NOW-near edges relate to BodyMap? Aren’t they redundant?

A: BodyMap is a live register (one posture/mom/shelter/cliff configuration at a time).

The NOW --near--> * edges are a thin episodic overlay written into the main WorldGraph at important moments (currently at resting times):

BodyMap says: “right now, mom is near, shelter is near, cliff is far.”

The runner writes: NOW --near--> b_mom_close and NOW --near--> b_shelter_near into the WorldGraph.

Those bindings (b_mom_close, b_shelter_near) already carry their own tags, including provenance and temporal fingerprint.

This lets you later inspect or analyze where resting happened in the episode graph (e.g., “rest near mom and shelter”) without re-running the environment or looking at BodyMap snapshots.

Q: Do spatial near edges change planning behavior today?

A: No. Today, spatial edges are purely descriptive:

They don’t affect BFS/Dijkstra correctness.

They’re not used as weights or filters yet.

They exist so humans (and future algorithms) can see and query simple scene-graph structure.

In the future, the same near label could be mapped to costs or constraints (e.g., prefer paths through near shelter states, avoid risky near cliff states), but Phase V keeps planning semantics unchanged. The edges are a no-regrets addition: useful for inspection now, available for planning later.