HOLO-Invariant：保留修正而非隐藏修正的 AI 连续性框架

AI continuity that preserves corrections instead of hiding them.

pip install -e .
holo demo

One command creates disposable evidence, retains an original observation, links a correction and revalidation, and opens the verified topology. It does not modify an existing chain or grant truth, acceptance, write, or execution authority.

Benchmark any continuity system

Export a system-neutral condition document, then score it against the exact committed fixture:

holo benchmark continuity --condition candidate.json

The public fixture fixes the target before results are observed. The condition schema is closed so undeclared fields cannot alter the scoring contract.

The CI-verified reference result is regenerated from the same committed fixture and condition on every change.

HOLO-Invariant is a Python framework for preserving, reconstructing, and checking state across sessions, models, tools, and execution environments. It externalizes continuity into inspectable artifacts instead of assuming that a model's context, memory, output, or confidence is authoritative.

Store what happened. Preserve where it came from. Recheck what still applies. Grant no authority merely because a record exists.

HOLO is not a model, agent, vector database, or autonomous authority. It is a set of deterministic boundaries for evidence, identity, replay, correction, branching, validation, authorization, and bounded software work.

Architectural authority hierarchy

The kernel governs; continuity carries; research tests.

HOLO-Invariant separates three layers with a one-way authority boundary:

1. Executable invariant layer Verifies supplied evidence under declared contracts: identity, correction, contradiction, reconstruction, currentness, authorization, and transitions. This is the only layer that can confer or reject bounded operational status under those contracts.

2. Continuity protocol Spine, IDX, handoff, recovery, absence, environment episodes, and reopening preserve and transfer verifiable relationships across observers, sessions, environments, and time. These artifacts can carry evidence into invariant checks; they cannot independently establish truth, currentness, acceptance, persistence of identity, or operational authority.

3. Research layer Functional-consciousness and observer experiments test explicit, falsifiable hypotheses. Research artifacts may produce evidence for later checks, but they are not runtime authority and are not claims of subjective experience.

The dependency direction is deliberate:

research / continuity
        |
        v
supplied evidence + declared contract
        |
        v
executable invariant verification
        |
        v
bounded status
        |
        v
separate authorization where an effect requires it

Never:

research / continuity -> truth, currentness, or authority

Currentness is computed, not declared. Given supplied evidence and a declared contract, the applicable verifier or gate determines the bounded status it is designed to check. HOLO does not independently discover the authoritative state of the world when the required evidence has not been supplied.

Identity is not authority. Hashes and receipts establish bounded identity and lineage under their declared encodings and schemas. They do not by themselves establish truth, authorship, relevance, acceptance, permission, or execution authority.

Higher layers cannot promote themselves. A Spine may carry a relationship. An experiment may produce evidence. A later observation may satisfy a declared condition. None of those facts alone grants permission to accept, mutate, execute, promote, or reopen anything.

Continuity artifacts preserve verifiable relationships between states; they do not establish persistence of a mind, consciousness, identity, truth, or authority.

Verification is not authorization. Persistence is not truth. Continuity is not identity. Research is not authority.

Generated public status

CLI: append, benchmark, check-spines, demo, doctor, health, idx-check, index, local-converge, lucidity, operator-summary, replay, resume, review, serve, service-status, test, verify

Schemas: continuity-condition.schema.json, idx-check-receipt.schema.json, idx-spine-packet.schema.json

MCP tools: idx_check

MCP resources: holo://schemas/idx-check-receipt, holo://schemas/idx-spine-packet

EnvPath workspace

Open the local chat, evidence search, and proposal-drafting interface:

python -m holosim.envpath

Search and draft export work without a model. Chat uses an already-installed, tool-capable Ollama model; select it with --model NAME. EnvPath does not change the retained chain or grant authority. See EnvPath setup and limits.

The continuity path

flowchart LR
    A[Append evidence] --> B[Verify identity]
    B --> C[Reconstruct state]
    C --> D[Bind current head]
    D --> E{Current?}
    E -->|Yes| F[Continue]
    E -->|No| G[Block or reopen]
    G --> A

Loading

The minimal spine is:

append -> verify -> reconstruct -> bind -> gate -> continue or reopen

Each stage answers a different question. A stored event may be historically present without being true. A valid receipt may be internally consistent without being current. A current observation may still lack permission to write or execute.

Verified correction lifecycle

HOLO's distinction is not merely that it retains history—Git, event logs, and audit trails already do that. It keeps correction lineage, verification, currentness, authorization, persistence, and truth as separately checkable boundaries.

propose -> verify evidence -> bind exact transition -> authorize exact target -> persist -> re-observe

Verification is not authorization. Persistence records an exact transition without establishing truth. Re-observation can confirm recurrence, detect change, or remain unresolved without rewriting the original or acquiring write or execution authority.

What the code guarantees

Within each module's declared boundary, HOLO can verify properties such as:

• deterministic canonical JSON identity;
• append-only SHA-256-linked history;
• correction lineage that preserves the original record;
• exact-schema receipt validation;
• rejection of undeclared fields and rehashed forged bodies;
• deterministic replay and reconstruction measurements;
• current, stale, invalid, and unknown head classifications;
• immutable parent identity across branch and reopen relations;
• explicit separation between observation and authorization;
• independently signed, purpose-scoped, target-scoped, current, replay-protected execution permits;
• bounded workspace mutation followed by real verification and rechecking.

A passing verifier establishes only the property it checked.

What the code does not claim

Hash equality proves identity under the declared canonical encoding. By itself, it does not prove truth, authorship, relevance, completeness, acceptance, or permission.

Unless a narrower module explicitly establishes otherwise, observational outputs remain bounded as:

{
  "accepted": false,
  "truth_claimed": false,
  "write_authority": "NONE",
  "execution_authority": "NONE"
}

HOLO does not claim to:

• preserve a mind or internal model state;
• make model output true;
• turn memory into acceptance;
• authenticate origin using an unsigned hash alone;
• establish a SLSA level by emitting an unsigned statement;
• authorize external effects using an observational receipt;
• discover an authoritative current head without supplied evidence;
• guarantee general intelligence, consciousness, or autonomous judgment.

Why exact schemas matter

HOLO treats undeclared fields as a failed boundary, not harmless metadata.

declared field + valid semantics + valid identity = eligible for verification

Adding approval: "GRANTED" to a receipt and recomputing its hash does not make the receipt approved. The schema, semantics, lineage, and identity must all verify. Authority remains a separate object and a separate check.

This rule is enforced across transformation receipts, validator receipts, transition receipts, completion certificates, reopen receipts, framework adapters, memory proposals, and provenance attestations.

Situated reconstruction boundary

situated_reconstruction_packet.py builds a deterministic, model-independent reconstruction artifact from an active invariant projection and verified environment bindings. It carries the current objective, usable claims, excluded claims, unresolved questions, and required rechecks without requiring a full transcript replay or naming a model provider.

The packet does not automatically inject itself into a model. The dependency-injected provider_neutral_observer_transport.py presents one canonical packet byte string to caller-supplied observers and binds each JSON response to that unchanged packet in a separate non-authoritative receipt. Live vendor clients, credentials, network delivery, and provider identity attestation remain integration boundaries. Packet identity and upstream bindings are verified; successful transport does not establish that every capable model will interpret or apply the packet equivalently.

Cross-model continuity remains an empirical target. Repeated reconstruction by independent models and operators, using retained fixtures and checks, is needed to measure whether different systems recover and preserve the same bounded state. Public fixtures and CI make that evaluation reproducible; they do not replace external review.

Current integration boundaries

The adapters are dependency-free protocol boundaries. They accept ordinary Python mappings shaped like the external framework's data, then reuse HOLO's verification rules.

Every adapter is tested against the same hostile cases:

1. Undeclared fields cannot smuggle authority.
2. Rehashing a forged body does not make it valid.
3. Replay preserves artifact identity.
4. Branching preserves the parent.
5. External effects require separately verifiable authorization.

Environment episodes and change over time

Completion is scoped to an observed window, not declared forever. Historical completion remains valid for the window it actually describes; later evidence is evaluated against that exact boundary rather than silently rewriting it.

stateDiagram-v2
    [*] --> Observing
    Observing --> Complete: completion certificate
    Complete --> Complete: no verified difference
    Complete --> Compared: later observation
    Compared --> Complete: condition not satisfied
    Compared --> ReopenEligible: declared condition satisfied
    ReopenEligible --> Authorized: exact-target external authorization
    Authorized --> Reopened: separate reopen operation
    Reopened --> Observing: distinct successor episode

Loading

The current path separates each question:

bounded completion
  -> exact terminal boundary
  -> later snapshot comparison
  -> comparison identity
  -> completion/comparison binding
  -> declared reopen-condition evaluation
  -> immutable reopen receipt
  -> exact-target operational authorization
  -> authorized reopen binding

environment_completion_evaluator.py emits bounded completion certificates. environment_completion_comparison_binding.py requires the later comparison to begin at the completed episode's exact terminal snapshot and window_end. environment_reopen_condition.py evaluates a declared condition against that same comparison identity without authorizing a reopen. environment_episode_reopen_receipt.py preserves the completed parent while binding later trigger evidence to a distinct successor episode. authorized_environment_episode_reopen.py then binds a satisfied condition, the verified reopen receipt, and a separate external authorization for the exact reopen target.

Even the authorized binding does not execute the reopen or mutate canonical state. The current implementation records authorization_consumed: false, reopen_executed: false, accepted: false, write_authority: "NONE", and execution_authority: "NONE". Authorization and execution therefore remain separate boundaries.

Bounded software convergence

HOLO includes a real compare-build-verify-recompare loop:

flowchart TD
    A[Observe workspace] --> B{Relevant difference?}
    B -->|No| C[Stop]
    B -->|Yes| D[Propose bounded change]
    D --> E[Apply inside workspace]
    E --> F[Run verifier]
    F --> A

Loading

The software path includes capability decomposition, planning, proposal, bounded transformation, workspace verification, lineage reconstruction, convergence, and an optional local Ollama transport. Model output is treated as a proposal. The verifier and observed environment determine whether the requested behavior was actually reached.

Run the disposable example:

python examples/software_convergence.py

Run the continuity handoff example:

python examples/end_to_end_continuity.py

Installation

HOLO-Invariant requires Python 3.10 or newer and has no required runtime dependencies.

git clone https://github.com/Deathburgerz013/HOLO-Invariant.git
cd HOLO-Invariant
python -m pip install -e .

Install test tooling:

python -m pip install -e ".[dev]"

Optional collection and embedding tools:

python -m pip install -e ".[collect]"

The collect extra installs arxiv, sentence-transformers, and scikit-learn. These dependencies are optional and are not required for the continuity core.

Quick start

Append and verify a local chain

from holosim.core import HoloChain

chain = HoloChain("holo_memory.jsonl")
chain.append("Example continuity delta")

print(chain.health())

The chain file is local state. Git history or another independently retained checkpoint can provide an external comparison point; the internal hash chain alone establishes self-consistency, not independent authorship.

Command line

The canonical CLI implementation is holosim.holo_cli; holosim.cli is the compatibility entry point.

python -m holosim.cli health
python -m holosim.cli doctor
python -m holosim.cli verify
python -m holosim.cli replay --last 10
python -m holosim.cli test

Appending through HoloService requires an external reviewer identity and approval reference:

python -m holosim.cli append "Example delta" \
  --reviewer "reviewer-id" \
  --approval-reference "approval-record-id"

On Windows Command Prompt, enter the same command on one line.

Fixed-point evaluator

python -m holosim.Holo_Sim identity
python -m holosim.Holo_Sim verify
python -m holosim.Holo_Sim evaluate "Example delta"

The symbolic relation (C + I + E)^2 remains a project design mnemonic used by this evaluator. It is not presented as a derived scientific law. It is not proof of the repository's engineering guarantees.

Local Ollama convergence

With Ollama already running locally:

python -m holosim.cli local-converge \
  "implement the requested behavior" \
  ./workspace \
  --model qwen2.5-coder:7b

The default endpoint is http://127.0.0.1:11434/api/generate. Workspace changes remain bounded to the supplied directory and are evaluated through the software convergence path.

Architecture map

The package contains many small boundary modules rather than one monolithic agent. The groups below are the supported map; the source tree remains the complete inventory.

For detailed implementation history and review-bound evidence, see docs/HOLO_Invariant_Implementation_Map.md.

Verification

Run the complete test suite:

python -m pytest -q

Retained verification observations are commit-bound rather than treated as timeless repository claims. The latest locally observed full-suite result for the implementation commit immediately preceding this documentation update is:

3026 passed, 4 skipped
main commit: d398302

Retained historical post-merge observation:

Older verification evidence remains useful for the exact commits it names. For example, main-5ba72ed-pytest-receipt.json and its separately hashed main-5ba72ed-pytest.txt remain historical evidence for 5ba72ed; they are not silently promoted into evidence for later commits. Verification observations grant no acceptance, truth, write, or execution authority.

Run the integrated CLI self-test:

python -m holosim.cli test

Validate a rail-formatted Spine document:

python -m holosim.spine_protocol rail-validate path/to/document.md

Passing tests demonstrate the cases encoded by those tests. They do not grant acceptance, certify every deployment environment, or replace external review.

Development workflow

Repository changes follow a narrow, evidence-first loop:

current main
  -> one named branch
  -> one reproducible failure
  -> smallest supported correction
  -> focused tests
  -> full suite
  -> diff checks
  -> external review
  -> merge
  -> post-merge verification

Automated assistants must follow AGENTS.md. In particular:

• evaluation is not approval;
• raw evidence is not rewritten;
• changes begin from current main on a narrow branch;
• only the intended files are staged;
• merging requires explicit human direction;
• a passing check establishes only what it observed.

Project status

HOLO-Invariant is an active experimental engineering project. The repository is expected to evolve, but later additions remain subordinate to the same declared boundaries rather than retroactively changing what older evidence established.

Its strongest claims are executable and testable: exact schemas, deterministic identities, append-only lineage, correction and contradiction relations, fail-closed currentness gates, bounded completion windows, exact-boundary reopening, target-bound authorization, bounded mutations, replay resistance, and explicit separation of evidence, status, authority, and execution.

Long-horizon performance across different models, providers, machines, environments, and operators remains an empirical question. Historical commits, fixtures, receipts, and retained artifacts make those experiments comparable over time without requiring old observations to be rewritten.

License

MIT. See holosim/LICENSE.

Author

Canyon Brock Haney

Holo/Sim Continuity Engine conception: July 27, 2025.