ZNAK ORIENT

Inspiration

Long project histories often preserve every sentence while losing the decisions, constraints, risks, and unknowns that determine what should happen next. We wanted minimum sufficient memory: enough to restore direction safely without loading the whole project “city,” and without allowing a newer or louder claim to silently replace supported state.

What it does

ZNAK ORIENT imports a strict JSON evidence package and evaluates it under a closed, deterministic local policy. It rejects duplicate keys, unsupported shapes, stale or unauthorized changes, evidence that arrives after the change it supposedly supports, and unsupported completion claims.

Material contradictions are preserved as disputes instead of being overwritten. Critical unknowns remain visible. Imported instruction-like text is treated as inert data. The result contains a source-backed current position, exactly one corrective next step, a closed machine-evaluable success condition, a canonical checkpoint, and a compact Recovery Card that cannot write back into canonical state.

The responsive local interface presents Noise Intake, Current Position, Conflicts and Unknowns, Recovery Card, Source Evidence, and Validation Receipt. A small animated ZNAK assistant maps deterministic voltage states to the one canonical next step. It does not call a model or invent another action.

How we built it

The runtime uses Python 3.11 and the standard library for strict contracts, duplicate-key-rejecting JSON parsing, canonical JSON, SHA-256 content sealing, deterministic reduction, checkpoint fallback, atomic CLI output replacement, unit tests, and a loopback HTTP server.

The interface is code-native HTML, CSS, and JavaScript. Imported values are rendered with textContent. The local server uses a Content Security Policy, exact route and media-type checks, request-size limits, and loopback-only binding by default.

Codex for Windows with gpt-5.6-sol accelerated repository discovery, contract and reducer implementation, test generation, browser verification, accessibility refinement, diagnosis of a Windows rejected-response failure, and preparation of the evidence ledger. Human decisions kept the engine deterministic, separated fact confidence from decision authority, preserved disputes instead of overwriting them, made the Recovery Card non-authoritative, and kept external calls and publication behind explicit approval gates.

The repository’s 121-test suite and deterministic demo run in GitHub Actions with Python 3.11 on Windows, Ubuntu, and macOS.

Challenges we ran into

The hardest challenge was preventing different kinds of confidence from collapsing into a single status. Source recency is not truth, fact verification is not decision authority, and a newer claim is not automatically a correction.

We also had to retain receipt identity across compact checkpoints and fallback without silently rolling back meaning or requiring all earlier raw receipts. A Windows HTTP edge case exposed another useful boundary: rejecting a request without draining its bounded body could cause a connection abort before the client received the intended response. We fixed the scoped failure, added a regression test and 25 additional stress probes, and retained the pre-fix observations in the validation record.

On the interface side, the challenge was making conflicts, unknowns, evidence, and one canonical action readable on desktop and mobile while supporting keyboard focus, forced colors, reduced motion, long tokens, and persistent import errors.

Accomplishments that we are proud of

• A deterministic orientation transform with exact checkpoint integrity for the tested evidence packages.
• Explicit dispositions for duplicate, stale, unauthorized, unsupported, disputed, and derived inputs.
• Safe fallback from a corrupt or semantically invalid primary checkpoint.
• Immutable receipt identity and lineage checks that fail closed when rollback meaning becomes unknowable.
• Exactly one source-linked corrective next step with a closed success-condition evaluator.
• A non-authoritative Recovery Card that cannot contaminate canonical state.
• A judge-safe synthetic instruction-injection fixture that remains inert by construction.
• A responsive code-native interface and animated guide with 39/39 retained Chromium workflow checks.
• A 121-test automated suite and public CI on Windows, Ubuntu, and macOS.
• A public MIT-licensed repository that judges can clone and run without credentials, a build step, or a model service.

What we learned

Good project memory is not maximum recall. It is traceable selection: retain meaningful state changes, preserve disputes, expose unknowns, carry source and receipt identity forward, and refuse to turn a convenient output summary back into authoritative evidence.

What’s next

Next steps include an authenticated authority registry, cryptographically bound validator receipts, an append-only transactional store, and larger regression corpora.

Only after separate evidence exists, we would run a preregistered controlled evaluation of whether compact checkpoints restore project direction better than raw notes. The current repository proves scoped recovery equivalence for tested fixtures; it does not claim that broader comparison has already been won.

Built With

• actions
• chromium
• codex
• css
• github
• gpt-5.6
• html
• javascript
• python