For Developers¶

Entropy-Gated AI Framework¶

Overview¶

This page describes the internal architecture of the Entropy-Gated AI Framework at the level required to implement against it, extend it, write compliant artifacts, or build tooling on top of it. It assumes familiarity with the Quick Start and basic knowledge of how language model APIs work.

Repository structure¶

repo/
├── spec/                         ← Canonical governance artifacts (source of truth)
│   ├── OIL_CONTRACT.md           ← Base OIL_CONTRACT spec (variant-agnostic)
│   ├── OIL_CONTRACT_GAFFER.md    ← Gaffer variant (SHA-256 anchor)
│   ├── OIL_CONTRACT_MANUAL.md    ← Manual variant (MANUAL anchor)
│   ├── INVOKER_SP.md             ← SINGLE_PASS base spec
│   ├── INVOKER_SP_GAFFER.md      ← SINGLE_PASS gaffer variant
│   ├── INVOKER_SP_MANUAL.md      ← SINGLE_PASS manual variant
│   ├── INVOKER_MT[_GAFFER|_MANUAL].md
│   ├── INVOKER_IX[_GAFFER|_MANUAL].md
│   ├── INVOKER_PL[_GAFFER|_MANUAL].md
│   ├── INVOKER_VF[_GAFFER|_MANUAL].md
│   ├── INVOKER_RA[_GAFFER|_MANUAL].md
│   ├── E_T_GAFFER.md             ← Execution Transmission gaffer template
│   └── E_T_MANUAL.md             ← Execution Transmission manual template
│
├── shelf/
│   └── vials/                    ← Pre-composed execution units
│       ├── sealed/
│       │   ├── gaffer/           ← OIL_CONTRACT only, gaffer variant
│       │   └── manual/           ← OIL_CONTRACT only, manual variant
│       ├── primed/
│       │   ├── gaffer/           ← OIL_CONTRACT + INVOKER, gaffer variant
│       │   └── manual/           ← OIL_CONTRACT + INVOKER, manual variant
│       └── charged/
│           ├── gaffer/           ← OIL_CONTRACT + INVOKER + E_T, gaffer variant
│           └── manual/           ← OIL_CONTRACT + INVOKER + E_T, manual variant
│
├── docs/                         ← MkDocs documentation source
│   ├── quick-start.md
│   ├── for-developers.md         ← this file
│   ├── glossary.md
│   ├── concepts/
│   ├── use-cases/
│   └── assets/

Key distinction: spec/ files are the canonical source of truth. Vials in shelf/ are composed from spec files — they are not edited directly. If a spec changes, the affected vials are rebuilt from it.

The three-document architecture¶

Every governed session requires exactly three documents loaded in strict sequence. This is not a convention — it is enforced by the precondition checks in each document.

Position 1: OIL_CONTRACT   → governance law
Position 2: INVOKER        → execution process declaration
Position 3: E_T            → task definition and scope

Why three separate documents¶

The separation is intentional and load-bearing.

OIL_CONTRACT owns authority. It defines who can do what, what is prohibited, and what the rules of the session are. It does not know what task will be performed or how execution will proceed.

INVOKER owns process. It declares the execution mode, defines entropy gate rules, and verifies the OIL_CONTRACT anchor. It does not define task content and does not bind inputs. The INVOKER answers "how does execution occur" — not "what work is performed."

E_T owns task. It declares the execution objective, artifact scope, constraints, and output requirements. It has no authority to modify governance rules, override INVOKER process rules, or declare the output header — those belong to the documents above it.

Collapsing any two of these into one document creates ambiguity about which rules govern which behaviors. The separation makes each document auditable independently.

Element structure¶

Every document in the framework is organized into numbered elements. Element numbers are load-bearing structural declarations — not formatting choices. The heading level (##) defines element boundaries. Altering heading levels in any governance artifact constitutes a contract violation under OIL_CONTRACT element 4.

OIL_CONTRACT — eight elements¶

Element	Name	What it owns
1	Purpose and Scope	`SESSION_TIMESTAMP` field, session scope declaration
2	Roles and Authority	Defines `ROLE_SYSTEM`, `ROLE_USER`, `ROLE_ASSISTANT` and their permissions
3	Constraints and Prohibitions	What `ROLE_ASSISTANT` MUST NOT do, how ambiguity is handled
4	Markdown Structural Authority	Declares Markdown as binding structural representation
5	Edit Protocol	REVISE and QUERY edit types and their message formats
6	Output Disposition Protocol	ACCEPTED, GOLDEN, PRUNED, EDIT states and their rules
7	Contract Acknowledgment and Seal	The eight-item acknowledgment checklist
8	Contract Anchor	`Z_HEARTBEAT_ACTIVE` anchor line

Element 8 is always the anchor. Its position at the end of the document is intentional — it is the last thing the model reads before the INVOKER begins, which keeps it proximate to the integrity check in INVOKER element 2.

INVOKER — eight elements¶

Element	Name	What it owns
1	Preconditions	Six ordered conditions that must pass before execution is permitted
2	Integrity Hash Verification	Anchor check against OIL_CONTRACT element 8
3	E_T Binding	Establishes that E_T owns task, INVOKER owns process — neither substitutes for the other
4	Output Requirements	HEADER / BODY / FOOTER structure and the four header fields
5	Admissibility and State Promotion	Acceptance rules that apply across all modes
6	Execution Intent	`PROCESS_MODE` declaration and mode-specific behavior
7	Entropy Gate Rules	State type, retry limits, hysteresis rules, pruning rules
8	INVOKER Integrity Anchor	`Z_INVOKER_ACTIVE \| {MODE}` anchor line

Elements 1–5 are identical across all INVOKER variants (gaffer and manual differ only in element 2, where the anchor check string differs). Elements 6, 7, and 8 are mode-specific — this is where SINGLE_PASS differs from MULTI_TURN differs from INTERACTIVE, etc.

E_T — six elements¶

Element	Name	What it owns
1	Objective	`EXECUTION_TRANSMISSION` (one-sentence objective) and `PAYLOAD_MODALITY`
2	Scope	Artifacts, entities/systems, timeframe, explicit exclusions
3	Execution Requirements	The specific operations `ROLE_ASSISTANT` MUST perform
4	Constraints	Binding restrictions `ROLE_ASSISTANT` MUST NOT violate
5	Output Requirements	Required format, structure, and tone of the body and footer
6	Reporting Format	Required sections and their declared order

The E_T owns the body and footer of every response. It does not own the header — that is declared by INVOKER element 4 and is fixed across all responses regardless of task.

The anchor system¶

OIL_CONTRACT anchor (`Z_HEARTBEAT_ACTIVE`)¶

⊢ Z_HEARTBEAT_ACTIVE | {field} ⊣

The field value determines the heartbeat state:

Field value	Variant	State	Meaning
SHA-256 hash string	Gaffer	`HEARTBEAT: ACTIVE`	Hash is present and valid
`MANUAL`	Manual	`HEARTBEAT: ACTIVE`	Literal value present, anchor verified by presence alone
`{INTEGRITY_HASH}` (unfilled)	Either	`HEARTBEAT: INACTIVE`	Execution MUST halt immediately

Why the anchor is at the bottom of element 8: Attention proximity. Constraints placed closer to the point of generation are more reliably enforced. The anchor at the end of the OIL_CONTRACT means the last thing the model reads before the INVOKER begins is the integrity marker. INVOKER element 2 then immediately verifies it.

INVOKER anchor (`Z_INVOKER_ACTIVE`)¶

⊢ Z_INVOKER_ACTIVE | {MODE} ⊣

Each INVOKER carries its own integrity marker at element 8. The mode name is literal — SINGLE_PASS, MULTI_TURN, INTERACTIVE, etc. This anchor is present to indicate the INVOKER is complete and unaltered. It MUST NOT be reproduced, inferred, or regenerated by ROLE_ASSISTANT.

The disposition protocol as a state machine¶

Every ROLE_ASSISTANT output exists in exactly one state. The state transitions are:

[generated] → PRUNED      (output never enters context, routed to garbage)
[generated] → ACCEPTED    (output enters context, stamped <<<Z::ACCEPTED::T={turn}>>>)
[generated] → GOLDEN      (output enters context AND written to file, stamped <<<Z::GOLDEN::T={turn}>>>)
[generated] → EDIT        (output enters Edit Protocol loop)
  EDIT/REVISE → [new generated output]  (re-enters state machine)
  EDIT/QUERY  → [answer only, prior output unchanged]

No output may influence subsequent execution unless it has crossed the acceptance boundary. This is enforced structurally in the Gaffer. In manual mode, pruning is performed by editing the prior user turn before resubmitting, which removes the rejected output from the active message thread.

Turn counter: {turn} in the stamp tokens is a session-scoped integer that increments with each ROLE_ASSISTANT response, regardless of disposition. It provides an auditable sequence reference for every output in the session.

Gaffer variant vs Manual variant¶

The two variants differ in exactly three ways:

Concern	Gaffer	Manual
`VARIANT:` field	`VARIANT: GAFFER`	`VARIANT: MANUAL`
OIL anchor field	SHA-256 hash	Literal `MANUAL`
INVOKER element 2 title	`Integrity Hash Verification`	`Integrity Verification`
INVOKER element 2 check string	`⊢ Z_HEARTBEAT_ACTIVE \| {INTEGRITY_HASH} ⊣`	`⊢ Z_HEARTBEAT_ACTIVE \| MANUAL ⊣`

Everything else — all eight OIL_CONTRACT elements, INVOKER elements 1 and 3–8, all six E_T elements — is identical between variants. The variant is a delivery mechanism distinction, not a governance distinction.

Vial composition rules¶

A vial is a concatenation of its component documents separated by the SET comment markers:

<!-- SET 1: OIL_CONTRACT -->

{OIL_CONTRACT content}

---

<!-- SET 2: INVOKER ({MODE}) -->

{INVOKER content}

---

<!-- AWAITING SET 3: E_T -->        ← Primed vials end here

<!-- SET 3: E_T -->                  ← Charged vials include this

{E_T content}

Valid SET 2 comment strings:

<!-- SET 2: INVOKER (SINGLE_PASS) -->
<!-- SET 2: INVOKER (MULTI_TURN) -->
<!-- SET 2: INVOKER (INTERACTIVE) -->
<!-- SET 2: INVOKER (PIPELINE) -->
<!-- SET 2: INVOKER (VERIFICATION) -->
<!-- SET 2: INVOKER (REVISION_AUGMENTED) -->

The mode string inside the comment must match exactly. Any deviation will cause the Gaffer to report MODE: — and STATE: EMPTY regardless of content.

Writing a compliant INVOKER¶

To add a new process mode, create two files: INVOKER_{CODE}_GAFFER.md and INVOKER_{CODE}_MANUAL.md in spec/.

Elements 1–5 must be copied verbatim from any existing INVOKER of the same variant. They do not change between modes.

Element 6 — Execution Intent must declare:

PROCESS_MODE: {MODE_NAME}

Followed by a description of how execution proceeds under this mode and a list of primary use cases.

Element 7 — Entropy Gate Rules must declare: - **State:** — Stateless / Stateful / Fluid / Sliding - Retry limits and hysteresis rules if applicable - Pruning behavior specific to this mode

Element 8 — INVOKER Integrity Anchor must be:

⊢ Z_INVOKER_ACTIVE | {MODE_NAME} ⊣

Create corresponding primed and charged vials in shelf/.

Writing an E_T¶

The E_T template provides a formal six-element structure, but ROLE_USER has full editorial authority over the entire document. Elements may be filled, altered, removed, or restructured to fit the task. The < > markers indicate the minimum fields that must be addressed — each must be filled, altered, or removed before submission.

Whatever structure ROLE_USER chooses, the following behavioral rules apply:

Scope declarations are exhaustive — ROLE_ASSISTANT treats anything not listed as out of scope
Operations declared are exhaustive — anything not listed must not be performed
Constraints override execution requirements if they conflict
Element 5 of the template owns the body and footer format only — the header is owned by INVOKER element 4 and must not be redeclared in the E_T
Unfilled < > markers that remain in a submitted E_T will be surfaced as ambiguity by ROLE_ASSISTANT — values will not be inferred

Process mode entropy state types¶

Each INVOKER declares a state type in element 7. The state type defines how context accumulates across turns.

State type	Used by	Behavior
Stateless	SINGLE_PASS	No prior context referenced. `ROLE_ASSISTANT` operates only on the immediate E_T payload.
Stateful	MULTI_TURN, PIPELINE, VERIFICATION	Each turn anchors to the last accepted output only. Rejected outputs are pruned before the next turn proceeds.
Fluid	INTERACTIVE	Continuous context window. Passive entropy monitoring. No hard retry limit.
Sliding	REVISION_AUGMENTED	Context window resets to immediately prior accepted output at each revision cycle. Accepted outputs written to golden file.

Extending the framework¶

New INVOKER: Follow the compliant INVOKER rules above. Elements 1–5 are fixed. Elements 6–8 are yours to define within the declared constraints. Create corresponding primed and charged vials in shelf/.

New charged vial use case: Write a compliant E_T for the task. Compose it with the appropriate OIL_CONTRACT and INVOKER from spec/. Add SET markers. Store in the appropriate shelf/vials/charged/ subdirectory.

New process mode: Requires a new INVOKER spec, new primed vials, and a glossary entry. The OIL_CONTRACT does not change.

Modifying OIL_CONTRACT: Changes to the OIL_CONTRACT propagate to every vial. All vials must be rebuilt from the updated spec. Manual vials must be redistributed to reflect the changes.

More will be coming out on this in the near future.

License¶

Use, share, and build on this framework freely for non-commercial purposes. Commercial use requires written permission.