Skip to main content

11_Tag_Matrix.md

Manual — Database-backed causal tagging for O-Tags, R-Tags, and V-Pols

This chapter extends The Tag Trinity with the database shape behind the tags. The important design decision is simple: tags should be boring database identifiers and relationships, not clever encoded strings.

1) Why a matrix exists​

Traditional systems are good at answering what changed. The Brainframe needs to answer:

  • what changed;
  • what caused it;
  • which decision branch produced it;
  • which policy, authority, or precedent allowed it;
  • what downstream effects followed.

The tag matrix is the structure that makes those answers queryable. It treats operations as a causal graph: one event can cause many events, one event can have more than one cause, and any affected row or card should be traceable back to its origin.

2) The design choice: IDs, not encoded strings​

The early tag idea used compact self-describing strings. That is useful in theory, but it creates avoidable complexity in production.

The preferred Brainframe model is:

NeedPreferred mechanism
unique tag identitydatabase sequence / BIGINT ID
chronologydatabase timestamp
cause/effect linksparent-child edge row
explanationevent payload, reason log, policy reference
compact operational payloadO/R/V IDs

This keeps tags copy/paste safe, easy to query, and effectively unlimited for RABS purposes.

3) The two-layer model​

Event/action log​

The event log records that something happened.

Typical fields:

  • event ID;
  • created timestamp;
  • actor or source (system, human, reggie, henry, webhook, job, script);
  • bucket or domain (Comms, Billing, Scheduling, Transport, Incident);
  • event type;
  • compact description or payload reference;
  • optional O/R/V fields or related reason/policy references.

Causality matrix​

The matrix records only relationships.

parent_event_id -> child_event_id

It is intentionally small. It does not need names, descriptions, or long text. Those live on the event/action rows. The matrix's job is to say "this caused that."

4) How O/R/V uses the matrix​

The O/R/V triplet gives operational meaning to the graph.

TagMeaningMatrix role
O-Tagroot catalystthe upstream anchor for a chain
R-Tagmeaningful decision brancha decision event linked to its parent cause
V-Polvalidation policy / authoritythe trust basis attached to the decision

The matrix does not replace O/R/V. It connects them.

An O-Tag may have many child R-Tags. An R-Tag may have many downstream effects. A downstream event can also have more than one parent if two causes converge.

5) Baseline versus deviation​

RABS is built on repeating operational templates. If everyone attends, the bus runs normally, staff work the expected shifts, and billing follows the blueprint, the system does not need to invent reasons all day.

The baseline rule:

A normal template execution does not need a new R-Tag.

The deviation rule:

An R-Tag is minted when reality collides with the plan and a meaningful human, agent, or programmatic decision is made.

This keeps the Brainframe from turning every routine action into noise.

6) Worked example: cancellation to vehicle change​

Step 1 — root catalyst​

Susan sends an SMS saying Larry cannot attend.

  • O-Tag: SMS received.
  • Event bucket: Comms.
  • This is the root catalyst.

Step 2 — cancellation decision​

An agent or authorised user validates the cancellation.

  • New R-Tag: cancellation decision.
  • V-Pol: guardian cancellation policy or human approval.
  • Matrix edge: SMS event -> cancellation decision.

Attendance and billing effects inherit this decision context unless they make a new decision.

Step 3 — programmatic vehicle decision​

The attendance change drops passenger count below the bus threshold. A capacity script downgrades the vehicle to a sedan.

  • Same O-Tag: Susan's SMS is still the root catalyst.
  • New R-Tag if the vehicle downgrade is a meaningful decision branch.
  • New V-Pol: fleet optimisation rule.
  • Matrix edge: cancellation decision -> vehicle downgrade decision.

The driver assignment and route rows inherit the vehicle decision context.

7) The upstream "why" query​

The frontline question is usually not "what are all effects of Susan's SMS?"

It is:

"Why am I driving a sedan instead of the bus?"

The answer should be obtained by walking upstream from the affected vehicle/route card:

  1. vehicle card points to the vehicle-change event or R-Tag;
  2. matrix parent is the cancellation decision;
  3. matrix parent is the original SMS;
  4. V-Pol explains why the vehicle change was allowed.

Human explanation:

The vehicle changed because passenger count dropped after Larry's cancellation. That cancellation came from Susan's SMS. The downgrade was allowed by the fleet optimisation rule.

8) Downstream impact query​

The same matrix also supports the opposite question:

"What did Susan's SMS affect?"

Walking downstream from the O-Tag can show attendance, billing, route, shift notes, staff notifications, participant messages, and incident/compliance follow-ups.

This is useful for review and analytics, but it is a secondary benefit. The primary purpose is live operational clarity for the people dealing with the change.

9) Deterministic inheritance​

Not every effect gets a new reason.

If code is simply carrying out the known consequences of a decision, it inherits the parent O/R/V context.

Examples:

  • attendance row flips to cancelled after a validated cancellation;
  • standard confirmation SMS is queued from the cancellation;
  • billing is set to zero by a direct rule;
  • route membership removes the participant as a direct consequence.

Create a new R-Tag only when the system reaches a new meaningful branch, such as:

  • retain billing under a short-notice rule;
  • downgrade vehicle based on a fleet rule;
  • human manually reorders route stops;
  • agent chooses message wording beyond a fixed template;
  • HAL routes an escalation because no matching V-Pol exists.

10) Multi-cause events​

Real operations can converge. The matrix must allow one child to have multiple parents.

Example:

  • event A: participant cancellation;
  • event B: vehicle fault;
  • event C: route replacement decision.

The route replacement can link to both A and B. A string tag would struggle to represent that cleanly; a matrix only needs two edge rows.

11) ChainCode export format​

The database should remain boring and relational. ChainCode is an export/debug format generated from the event log and matrix, not the canonical truth.

Its purpose is to make bulk audits visually scannable. For example, when reviewing 24 billing rows that were blanked or changed, a ChainCode column lets a person quickly see which rows share an origin, which rows split across different reason branches, and which rows reused the same validation policy.

ChainCode v1 grammar​

A{actor}[O-{origin_id}][R-{reason_id}][V-{vpol_id}]-B{bucket_id}-T{time_code}{suffix}

Example:

AR[O-14][R-10][V-216]-B3-Tl(8^-->x

Decoded:

  • AR — actor is Reggie.
  • [O-14] — origin/catalyst ID 14.
  • [R-10] — reason/decision branch ID 10.
  • [V-216] — validation policy/authority ID 216.
  • B3 — context bucket 3, such as Finance/Billing.
  • Tl(8^ — compressed timestamp code.
  • -->x — this is the chain start and it spawned another decision branch.

The app can decode the same ChainCode into plain language: who acted, what started the chain, what decision was made, what authority allowed it, which bucket it belongs to, when it happened, and whether anything followed.

Why O/R/V order​

ChainCode uses O/R/V order because origin is the broadest and longest-lived grouping.

[O-14][R-10][V-216]

This makes bulk exports easier to scan:

  • same O-Tag, different R-Tags = one catalyst caused multiple decision branches;
  • same O-Tag and R-Tag, different V-Pols = same decision branch used different authorities;
  • same V-Pol across different R-Tags = the same authority was reused across separate decisions.

Fixed suffix zone​

Every ChainCode ends with a fixed 4-character suffix so rows align vertically, even when the compressed time code contains noisy symbols.

--->  chain start
---<  chain end / leaf
---x  connector / spawned another decision branch
-->x  chain start + connector
--><  single-event chain: start + end
----  middle / ordinary link

Examples:

AR[O-14][R-10][V-216]-B3-Tl(8^--->
AS[O-14][R-10][V-216]-B3-Tl(9@----
AS[O-14][R-22][V-216]-B5-Tl(A2---<
AU[O-99][R-31][V-400]-B3-Tk#7--><

Storage rule​

Store the normal database columns and matrix links. Generate ChainCode on request for:

  • selected-row exports;
  • audit packs;
  • debug panels;
  • "copy chain" tools;
  • bulk comparison tables.

If performance later requires caching, cache ChainCode as a derived artifact that can be regenerated from the canonical event and matrix data.

12) Brainframe memory and decay​

The matrix preserves full history. Brainframe active memory decides what remains in focus.

Useful pattern:

current_score = initial_score + frequency_bump - (decay_rate * time_passed)

Low-severity routine events can decay out of active context while staying queryable forever. High-severity events, such as emergency HELP actions, should spike into active attention and decay slowly or not at all until explicitly resolved.

This lets Reggie and Henry keep a finite working set without losing long-term lineage.

13) Prompt assembly​

When an agent needs to make a decision, the prompt should be assembled from structured context rather than a giant unfiltered log.

Recommended retrieval order:

  1. root O-Tag context;
  2. current R-Tag branch and upstream parents;
  3. active V-Pol constraints;
  4. relevant un-decayed context bucket rows;
  5. current operational card state.

If the agent makes a new meaningful decision, it mints a new R-Tag and links it into the matrix.

14) HAL and V-Pol creation​

HAL is the Human Assist Layer. It is not only login or authentication.

When Brainframe cannot find a valid V-Pol:

  1. Brainframe proposes an action and marks the missing authority.
  2. HAL packages the O/R context into a human review link or dashboard.
  3. The human approves, modifies, or rejects.
  4. That intervention becomes the authority for this action.
  5. Repeated approved patterns may become future V-Pol precedent.

This is how RABS can start safely with human-in-the-loop decisions and gradually build validated operational margins.

15) Implementation contract​

For developers:

  • Prefer relational IDs and edge tables over encoded tag strings.
  • Generate ChainCode as an export/debug/audit view, not as canonical storage.
  • Keep ChainCode suffixes fixed-width for visual alignment.
  • Treat O/R/V as causal trace, not decorative metadata.
  • Do not mint R-Tags for routine template execution.
  • Agent decisions require a V-Pol or HAL escalation.
  • Human material changes require a reason.
  • Deterministic cascades inherit O/R/V.
  • New discretionary branches mint new R-Tags.
  • Operational rows do not all need hard O/R/V columns on day one; they only need reliable traceability to the event/reason chain.
  • Unknown or unlinked changes should be surfaced as trace gaps, not silently ignored.

Adapted from admin/agentSPACE/agentDUMP/chatdump.pdf, reviewed 2026-05-27.

End of chapter