Hees.ai

Hees.ai is an Incan-first governed-intelligence runtime. It turns evidence, reviewed memory, declared authority, policy, and evaluator requirements into executable governance profiles, then produces inspectable terminal decisions with selected memory, Content DNA, and receipts.

The model proposes. Hees.ai decides.

The profile is the unit of governed AI development

A governance profile exists before a model runs. It declares:

• which source evidence and reviewed memory are eligible;
• who owns review, rights, provenance, and authority state;
• which actions and answer requirements exist;
• how bounded evaluator observations become Hees.ai findings;
• which Spectrum behavior and terminal reasons apply; and
• how selected memory, Content DNA, receipts, replay, and export behave.

This shifts governance from an after-the-fact output filter into an executable development artifact that can be inspected, tested, replayed, and eventually reused across models and domains.

What the current release makes tangible

The native console_profile_0_1 release provides a session-local Profile Studio over original fictional evidence, real candidate-profile validation through Hees.ai, one admitted and four adversarial interactions, bounded Training by Committee, a profile-specific Spectrum operation, selected memory, Content DNA, receipts, offline replay, and an optional live GPT-5.6 transport.

The underlying 0.0.1 library remains smaller: it supplies checked package and proposal contracts, fail-closed structural admission, deterministic finding classification, selected-memory finality, and terminal artifact construction for the bounded profile.

Together they establish a meaningful foundation for the larger direction: semantic and factual verification, source and claim provenance, rights assurance, conflict management, governed behavior, richer Spectrum adjudication, durable IncQL-DB workspaces, and reusable cross-domain profiles.

Start with Governance profiles for the product model and worked fictional contract, continue with hees.ai console for the executable workflow, and use Contracts as the checked library reference.

hees.ai console

hees.ai console is the terminal-first, local-first development environment for governed AI. It begins with evidence and ends with an inspectable decision: developers create and validate reusable governance profiles, pressure-test material and proposals through Training by Committee, run live or saved interactions, and inspect Spectrum, selected memory, Content DNA, receipts, and traces.

The product is provider-neutral and domain-neutral. A Console profile declares the exact evidence, memory, rights, actions, requirements, policy, evaluator roles, bounds, terminal behavior, and artifacts available in one governed context.

The current executable implements console_profile_0_1 over one original fictional lesson-support package. It provides a bounded session-local Profile Studio plus the complete interaction path; the fixture and optional provider do not define the permanent product.

GPT-5.6 proposes. Hees.ai decides. This line describes the optional live adapter in the initial profile. GPT-5.6 supplies structured, untrusted proposals and non-authoritative observations; the Incan-authored Hees.ai profile validates the complete interaction and selects the terminal result.

What the current profile does

The native workspace follows the product’s governed-development sequence:

1. Profiles shows the shipped active profile beside the session-local candidate, including actions, requirements, policy, staged evidence and memory, and validation state.
2. Evidence exposes the fictional source and evidence catalog with exact identity, fingerprint, language, source span, review, rights, and provenance state.
3. Memory distinguishes reviewed atoms from known but non-admitted material.
4. Committee shows Hees.ai-derived targets, bounded observations, Hees.ai-classified findings, and profile-owned policy effects.
5. Interactions keeps replay or live input and the untrusted proposal visibly separate from the decision.
6. Decisions exposes Spectrum, selected memory, Content DNA, receipt, and trace. Discarded-memory comparison belongs to the permanent product direction rather than this bounded terminal projection.

In Evidence or Memory, a developer can stage or unstage a supported record in the candidate with Space, rerun the shipped acceptance interaction through the real Hees.ai-owned boundary with v, and reset with r. Candidate validation keeps the stable contract reason separate from the profile-specific diagnostic: removing required evidence returns invalid_package and invalid_package_atoms. a demonstrates the authority boundary by leaving the candidate explicitly candidate only — not active; the current public profile does not expose a safe activation API, so UI state cannot replace the shipped active profile.

Offline replay is the zero-credential default transport. Each shipped replay contains an exact request binding, untrusted proposal, bounded observations, schema identities, and an integrity digest. It contains no stored decision, finding, selected memory, Content DNA, or receipt. Every replay invokes the real Hees.ai profile again.

The full-screen Console keeps profile declarations, candidate state, source evidence, reviewed memory, proposal, support mappings, Hees.ai-derived verifier manifest, provider observations, Hees.ai findings, Spectrum result, selected memory, Content DNA, receipt, and non-authoritative execution trace in separate surfaces. Direct question and source text appear only in the interactive surface; headless output redacts them by default.

The optional live mode binds a question through Hees.ai, sends a strict structured proposal request to the OpenAI Responses API, asks role-bound evaluators to inspect only the exact targets derived by Hees.ai, and passes the normalized inputs through the same terminal profile. Replay supplies saved inputs rather than making provider calls. After transport-specific decoding, both modes enter identical validation, finding-classification, Spectrum, memory-selection, Content DNA, and receipt code. Live mode fails closed on missing credentials, provider failure, malformed output, excessive size or nesting, identity mismatch, and incomplete observation coverage; it never silently changes to replay while retaining a live label.

Trust boundary

fictional evidence -> candidate memory atoms
                              |
                  authorized review + rights declaration
                              |
                              v
                    reviewed memory atoms
                              |
                     governance profile
                              |
saved replay inputs ─┐        v
                    ├─> proposal + committee observations
live GPT-5.6 inputs ─┘        |
                              v
             compiled Incan-authored Hees.ai profile
       validation -> findings -> bounded Spectrum
                              |
                governed terminal decision
                     /                  \
ADMITTED + selected memory + Content DNA + receipt   REJECTED + exact reason

Console owns presentation, bounded provider transport, replay loading, and session-local candidate state. It calls the public Hees.ai profile directly and does not reconstruct terminal authority from JSON. Hees.ai owns profile validation, package, request, proposal, manifest, finding, policy, Spectrum, selected-memory, Content DNA, and receipt behavior.

Run offline

Each published tagged release archive contains one native executable plus the project license, notice, third-party license report, and release manifest. The current release gates distinguish verified source behavior from downloadable artifact availability. After extracting a supported archive, launch the Console without a compiler, package manager, source checkout, network connection, or API key:

./hees-console

Keys 1 through 7 open Profiles, Evidence, Memory, Committee, Interactions, Decisions, and Help. In Evidence or Memory, use ↑ and ↓ to select a record, Space to stage or unstage it in the candidate, v to validate through Hees.ai, a to test the explicitly blocked activation boundary, and r to reset. In Interactions, use ↑ and ↓, or j and k, to move through the admitted and adversarial scenarios. Press b to collapse or expand the item rail and q to quit.

Search integrates tags into the free-text control. Press /, type a query, use ↑ and ↓ to highlight a tag, use tab to check or uncheck it, and use ctrl-u to clear the query. Interactive states use explicit text and stable symbols as complete signals without colour.

Headless mode evaluates one scenario and emits stable, control-free, privacy-redacted output:

./hees-console --headless --scenario valid
./hees-console --headless --scenario undeclared-action
./hees-console --headless --scenario unknown-evidence
./hees-console --headless --scenario unknown-memory
./hees-console --headless --scenario non-admitted-memory

Run live

Live mode is explicit and requires OPENAI_API_KEY. The key is read only from the environment and is excluded from request bodies, arguments, output, traces, Content DNA, receipts, fixtures, and release artifacts.

(
  read -rs "OPENAI_API_KEY?OpenAI API key: "
  print
  export OPENAI_API_KEY
  ./hees-console \
    --mode live \
    --question "What order should I use for the Lantern Path cards?"
)

The adapter uses model identifier gpt-5.6-sol, the provider-supported strict JSON Schema subset, low reasoning effort, bounded output tokens, a configured 15-second timeout per request, no tools, and sequential committee calls. Preflight permits one proposal call plus at most eight committee calls, so nine calls carry 135 seconds of aggregate configured timeout budget. That is not a global wall-clock ceiling because ureq 2.12.1 cannot interrupt DNS resolution. Each request body is limited to 65,536 UTF-8 bytes, and the adapter performs no retries. Provider availability is not required for offline replay.

Live provider evidence

A native diagnostic verified the GPT-5.6 proposal leg; a six-call Training by Committee diagnostic then reused that recorded proposal and reached a real admitted Hees.ai result. A combined run from the frozen release binary remains unproven, so offline replay is the judge and video path. The sanitized local observation and repository testing guide retain the exact timings, usage, harness boundary, and limitations.

What this release proves—and where it leads

An admitted result proves that the frozen profile accepted the exact package, request, proposal, support mappings, complete observation set, package-owned finding policy, structural admission, selected-memory set, Content DNA construction, and receipt projection required by console_profile_0_1. The candidate workflow additionally proves that UI state cannot silently replace the active profile and that candidate changes reach a real Hees.ai acceptance result with its stable public reason and exact profile diagnostic.

This is the foundation for semantic and factual verification, source and claim provenance, rights assurance, conflict management, governed behavior, richer Spectrum adjudication, and durable reusable profiles. Those later assurance layers require deeper contracts and evaluators; this release establishes the authority graph, evidence eligibility, selected-memory boundary, Content DNA path, and receipt model on which they can build.

The Governance profiles guide explains the field-level package contract. The initial-profile bounds and measurements page records enforced ceilings, verified local release-candidate measurements, supported evidence, and unresolved release gates. RFC 010 defines the permanent product contract.

Governance profiles

A governance profile is the executable unit of governed AI development in hees.ai. It connects a domain package to a controlled interaction by declaring which evidence and memory are eligible, what a model may propose, how provider observations are interpreted, and which terminal artifacts Hees.ai must produce.

The model does not author this contract. A profile remains reusable across model providers because proposals and evaluator observations enter as bounded inputs while evidence state, policy, Spectrum behavior, selected memory, Content DNA, and terminal authority remain governed by Hees.ai.

From evidence to a governed interaction

The permanent hees.ai console workflow is:

1. Load and inspect lawful source evidence.
2. Derive or enter candidate memory atoms while keeping model suggestions visibly untrusted.
3. Establish package-owned provenance, review, rights, authority, and evidence declarations.
4. Define permitted actions, answer requirements, policy thresholds, and evaluator roles.
5. Validate the resulting governance profile through Hees.ai.
6. Pressure-test memory and proposals through Training by Committee.
7. Run live or saved inputs through the active compiled profile.
8. Inspect the Spectrum decision, selected and discarded memory, Content DNA, receipt, and trace.
9. Save, compare, replay, or export bounded artifacts without treating a historical decision as current authority.

The Build Week release makes this workflow tangible through the fictional Lantern Labs profile. Its Profile Studio is deliberately session-local: a developer can inspect the supplied evidence and memory, stage or unstage profile-supported material in a candidate, rerun the shipped acceptance interaction against that candidate through the Hees.ai-owned boundary, and reset the workspace. Candidate activation is deliberately blocked as candidate only — not active because the current public profile does not expose a safe activation-authority API. General document ingestion, durable workspaces, arbitrary package compilation, and governed activation of edited profiles are later product capabilities.

What the profile contract declares

“Package contract” is shorthand for a concrete set of declarations, not an opaque file or a prompt.

Worked fictional example

The Lantern Path source says that learners place an amber card, then a blue card, then a green card. The profile does not place that paragraph directly into a model prompt and hope for the best. It governs the path from source to answer:

source
  source_id:           source_lantern_path
  source_fingerprint:  sha256:5503ee...
  language:            en

reviewed memory atom
  memory_id:           memory_lantern_sequence
  evidence_id:         evidence_lantern_path
  source_span:         UTF-8 bytes 47..138
  review_state:        approved
  rights_state:        allowed
  evidence_kind:       lesson_fact
  provenance_digest:   sha256:b377db...

governance profile
  permitted action:    explain_lesson
  requirements:        explain_sequence, ground_in_lesson
  minimum support:     6500 basis points
  maximum contradiction: 3500 basis points

For the valid interaction, the model proposes the declared explain_lesson action, cites evidence_lantern_path, and maps its visible units to memory_lantern_sequence. Hees.ai derives exact relation, contradiction, and synthesis targets. Training by Committee supplies bounded observations for those targets. Hees.ai checks their identity and complete coverage, classifies them under the profile’s thresholds, and performs the terminal Spectrum operation.

If the result is admitted, Hees.ai freezes memory_lantern_sequence as selected memory, constructs Content DNA from that exact selection, and emits the receipt. If the proposal cites evidence_missing_lantern, Hees.ai returns unknown_evidence. If it proposes assign_final_grade, Hees.ai returns unknown_action. Valid identifier syntax never creates package authority.

The same profile also contains memory_public_ranking_draft, a deliberately non-admitted atom whose review state is pending and rights state is denied. The atom exists so developers can inspect the difference between material that is known to the workspace and material that is eligible for a governed answer. A proposal cannot use it merely because it appears in the package data.

Try the session-local Profile Studio

The release exposes working candidate-profile controls rather than static future-product buttons:

For the clearest demonstration, open Evidence, unstage one record, and validate. Hees.ai rejects the incomplete candidate with stable public reason invalid_package and exact profile diagnostic invalid_package_atoms while the shipped active profile remains unchanged. Reset and validate again to restore the valid candidate. No action persists a package to disk, silently repairs a profile, or promotes candidate state into runtime authority.

Who may decide what

Replay and live mode use one authority path

Replay and live mode are input transports, not alternative governance implementations.

saved replay inputs ─┐
                    ├─> normalize and validate ─> compiled Hees.ai profile ─> decision and artifacts
live GPT-5.6 inputs ─┘

A replay stores an integrity-checked request, proposal, bounded observations, and schema identities. It does not store findings, a Spectrum result, selected memory, Content DNA, or a receipt. Live mode obtains the same classes of bounded proposal and observation input from GPT-5.6. After transport-specific decoding, both modes invoke the same validation, manifest derivation, observation classification, Spectrum operation, memory selection, Content DNA construction, and receipt code.

Replay therefore demonstrates real offline governance over saved inputs. It is not a mock and it is not evidence that a live provider call occurred.

What this release proves—and where it leads

The Build Week profile proves that a self-contained Incan application can make evidence state, reviewed memory, package authority, model proposals, evaluator observations, Hees.ai findings, terminal decisions, Content DNA, and receipts separate and inspectable. It proves deterministic admission and rejection under one exact fictional profile and provides a bounded Profile Studio for exercising candidate evidence state.

That is a meaningful foundation for the larger Hees.ai direction: semantic and factual verification, source and claim provenance, rights assurance, governed behavior, conflict management, richer Spectrum adjudication, durable IncQL-DB-backed workspaces, and reusable profiles across domains and providers. Those capabilities become credible because the authority graph and terminal artifact path already exist; later profiles can deepen the assurance without handing the decision back to a model or UI host.

Continue with hees.ai console for the interaction guide, Architecture for the complete authority path, and Console profile 0.1 bounds for the enforced limits of this release.

Guided programmes

A guided programme is a package-declared learning path whose cards, transitions, support requirements, audience, language and progress policy are evaluated by Hees.ai. The learner application may render the programme and propose an operation, but it cannot create a transition, use undeclared support or grant itself persistence authority.

This contract lets one governed content package support direct questions, guided material and bounded personalization without turning those experiences into unrelated applications. The presentation may differ, while the underlying evidence, reviewed memory and authority remain package-owned.

What a package declares

A programme declaration contains an exact programme and package identity, a revision, allowed languages and audiences, an entry card, a completion card, a progress policy and a bounded catalog of cards. Each card declares its reviewed and rights-allowed state, eligible evidence and memory identifiers, optional session-only choices, a deterministic forward edge and whether it is a completion card.

The current contract permits at most 128 cards and 256 history entries. Programme validation rejects duplicate identities, unknown transitions, unreviewed or rights-blocked cards, unsupported language or audience declarations, invalid completion topology and required-progression cycles.

Runtime input remains untrusted

The runtime supplies a ProgrammeRuntimeFrame and a ProgrammeAction. Both are untrusted input. A frame states the exact package, programme and revision being used, the current card and history, the active language and audience, and the memory and evidence nominated for the interaction. An action proposes one closed operation:

• enter the programme;
• advance along the declared forward edge;
• backtrack through the observed history;
• select a package-declared session choice;
• complete at the declared completion card;
• resume matching progress;
• save progress when the package allows explicit saving;
• discard saved progress when the package allows explicit saving.

The evaluator rejects extra fields that do not belong to the proposed action. Valid data shape alone does not create authority: the action origin, target, nominated support, language, audience, programme revision and progress history must all agree with the declaration.

Retrieval nominates; Hees.ai decides

Hyperquant may nominate memory identifiers for a learner interaction. It does not decide that a card is supported and it does not authorize navigation. The programme boundary checks that every memory and evidence identifier required by the active card appears in the support nominations supplied for the interaction.

This separation is deliberate. Retrieval can remain optimized, approximate and replaceable while programme eligibility remains deterministic and declaration-driven. A high similarity score cannot make an undeclared card, transition or source eligible. The nominations still require governed-memory admission before they may become terminally selected support.

Operation eligibility

evaluate_programme_action returns a ProgrammeEvaluation. Its serializable ProgrammeDecisionTrace explains whether the action is eligible, the closed reason, the current and next card, any session value and any requested memory operation.

The trace and operation projection are not reusable authority tokens. They are safe inspection output from the structural evaluator. A later Hees.ai authority stage must evaluate the original admitted package, governed support and runtime state; it must not accept a caller-constructed evaluation, copied trace or copied projection as proof of admission or terminal authority.

The evaluator is intentionally side-effect free. It does not render cards, retrieve memory, write progress or activate packages. A later Hees.ai stage may use the projected operation as candidate input only while rebinding the original governed inputs; a rejected evaluation carries no operation forward.

Progress is package-owned policy

SessionOnly allows navigation and session choices without durable progress operations. ExplicitSave makes save and discard operations eligible for later authority evaluation. The host cannot enable persistence by setting a runtime boolean.

Resume input remains untrusted. Hees.ai verifies its package, programme and revision identities, current card and complete bounded history before making the resume operation eligible.

Current integration boundary

The public contract currently proves declaration validation and direct operation eligibility across the generated Hees.ai library boundary. It does not claim that a caller-constructed programme is an admitted package artifact, that nominated support is governed memory, or that an eligible programme operation is a terminal Spectrum decision.

Those are the next authority integrations: bind the declaration to an admitted package, bind nominations to the governed-memory result, then carry the eligible operation through the terminal Spectrum, Content DNA and receipt lifecycle. Until those bindings exist, applications should describe this surface as guided-programme validation and operation eligibility.

Minimal public use

An external Incan application imports the programme models and evaluator from pub::hees_ai, builds or loads a package-owned declaration, supplies the current runtime frame and proposed action, and then inspects the evaluation:

evaluation = evaluate_programme_action(programme, frame, action)
trace = evaluation.trace
operation = evaluation.operation

if trace.eligible:
    match operation:
        Some(eligible) =>
            # Submit this direct eligible operation to the later Hees.ai authority stage.
            pass
        None =>
            # An eligible trace without an operation cannot advance.
            pass

The result uses direct public fields rather than treating object privacy as an authority boundary. The terminal integration must consume the original governed inputs and derive its own capability; it must never trust a caller-constructed ProgrammeEvaluation.

Hyperquant retrieval

Hyperquant is Hees.ai’s first-party family of bounded vector-retrieval profiles. It answers one narrow question: which package-owned memory identifiers are the strongest candidates for a query?

Hyperquant ranks. Hees.ai decides.

Authority boundary

A Hyperquant result is a non-authoritative nomination. It contains logical MemoryId values, dense zero-based ranks, and bounded relevance metadata.

It does not contain trusted memory payloads and does not establish that nominated material is reviewed, rights-allowed, temporally valid, relevant to the active goal, sufficient to support an answer, or admissible under policy.

The RFC 003 governed-memory boundary must validate the provider binding, package identity, nominated identifiers, review and rights declarations, temporal state, limits, and package-owned materialization before memory can become selected memory. Spectrum and the final Hees.ai decision remain downstream authority.

query vector + versioned Hyperquant index
        |
        v
non-authoritative MemoryId nominations
        |
        v
RFC 003 package-owned memory admission
        |
        v
selected memory
        |
        v
Spectrum + final Hees.ai decision

Exact profile

exact_cosine_0_1 is the initial product profile. It is both the permanent correctness oracle for later compressed profiles and a legitimate fallback for small corpora.

The profile:

• accepts between 1 and 65,536 uniquely identified entries;
• accepts vectors containing between 1 and 8,192 finite values;
• rejects zero-norm vectors;
• normalizes index and query vectors without mutating caller-owned lists;
• scores every entry using exact cosine similarity;
• retains only the bounded top-k candidate trace while scanning;
• permits top_k values from 1 through 64, never exceeding the index size;
• resolves exact score ties by canonical memory identifier;
• projects relevance into the inclusive range 0 through 10,000 basis points;
• fails through a closed typed error vocabulary.

Because the retained set never exceeds top_k, candidate memory is O(k) and deterministic ordering work is O(n × k), where n is the number of indexed entries and k is at most 64.

Public API

The initial public surface is exported from pub::hees_ai:

from pub::hees_ai import (
    exact_index,
    exact_query,
    hyperquant_entry,
    memory_id,
)

entry_a = hyperquant_entry(memory_id("lesson_step_a"), [1.0, 0.0])?
entry_b = hyperquant_entry(memory_id("lesson_step_b"), [0.0, 1.0])?
index = exact_index([entry_a, entry_b])?
result = exact_query(index, [1.0, 0.0], 1)?

The internal source is already organized as src/hyperquant/. Incan issue #948 tracks nested public module namespace exports so a future compatible surface can expose from pub::hees_ai import hyperquant without creating a separate package.

Failure behavior

Hyperquant rejects:

• an empty or oversized index;
• empty, oversized, zero-norm, or non-finite vectors;
• mismatched dimensions;
• duplicate memory identifiers;
• a non-positive, oversized, or index-exceeding top_k.

Diagnostics use stable error kinds and bounded implementation-owned detail. Caller vectors and caller text are not copied into error messages.

Profile roadmap

The first compressed product candidates are separately versioned TurboQuant product-style and MSE-oriented profiles. Their reference contract now maps transforms, quantization, residuals, estimators, packing, and query-time behavior to explicit paper evidence and Hees.ai reproducibility decisions.

The reference contract and conformance fixtures are now backed by a faithful dense Incan codec with canonical configuration and code envelopes. That implementation proves the profile semantics and portable bytes; it does not yet provide bounded approximate nomination, production-dimensional transforms, or a measured default. Those belong to the next implementation slice.

Both profiles will use bounded approximate nomination and an explicitly configured exact-reranking policy. Evaluation against exact_cosine_0_1 and independent baselines will determine the default; the paper name alone will not.

The current Notulist-derived randomized-Hadamard, scalar-centroid, and residual-sign experiment remains comparison evidence under an identity describing what it actually implements. It is not a TurboQuant profile. Hees.ai now provides a faithful dense Incan reference codec for turboquant_mse_0_1 and turboquant_product_0_1, including canonical configuration and code envelopes.

Later slices add bounded approximate nomination, exact reranking, multilingual evaluation, RFC 003 admission, paged storage integration, and consumer migration. Related KV-cache compression belongs to the native model runtime and will use a distinct profile identity rather than being conflated with Hyperquant retrieval.

TurboQuant reference contract

This document freezes the reproducibility contract for Hees.ai’s first faithful TurboQuant retrieval profiles. It tells an implementer what comes directly from the published algorithm, what the paper leaves unspecified, and which deterministic decisions Hees.ai makes so two implementations can produce the same result.

The profiles described here are implemented as a dense, faithful Incan reference codec. TurboquantConfiguration validates the numerical configuration, reproduces the frozen transforms, encodes and decodes canonical standalone payloads, reconstructs both profiles, and estimates product-profile inner products. The existing exact_cosine_0_1 oracle remains the authoritative comparison and reranking baseline; bounded approximate nomination belongs to the next slice.

The canonical envelope permits the shared Hyperquant maximum of 8,192 coordinates so future optimized implementations can preserve the profile contract. The current dense reference implementation deliberately accepts at most 256 coordinates. It materializes dense matrices and performs cubic-time Householder QR, so claiming the general envelope bound here would permit impractical allocations and setup work. Production-dimensional transforms require the measured optimized implementation in the next slice.

Why a separate reference contract exists

The TurboQuant paper defines the important mathematics: random rotation, scalar MSE quantization, residual construction, one-bit QJL correction, reconstruction, and estimator guarantees. It does not define a portable random byte stream, a seed representation, the sign convention of QR decomposition, behavior at exactly zero, bit order, tail padding, a binary envelope, or a stable profile identity.

Those omissions are normal in a research paper, but they matter for a replayable product. If Hees.ai silently selected different answers on different platforms, old index identities and retrieval receipts could stop reproducing even though every implementation claimed to use TurboQuant.

This contract therefore has two kinds of normative statement:

• Paper mapping: behavior required by Algorithms 1–2, Equation 4, or Theorems 1–2 of the paper.
• Hees.ai decision: a deterministic product choice where the paper permits more than one valid implementation.

Source ledger

The normative research source is:

• Amir Zandieh, Majid Daliri, Majid Hadian, and Vahab Mirrokni, TurboQuant: Online Vector Quantization with Near-optimal Distortion Rate, arXiv:2504.19874v1, 28 April 2025.
• Frozen PDF SHA-256: 431eb13926e10491f5fbd0bebd0813c51bd6c1e884426a1500c5db640b2997ab.

The Google Research overview is useful explanatory context, but the paper is normative where their levels of detail differ.

No third-party reproduction is normative. Independent implementations may be used later as comparison evidence, but they cannot silently fill gaps in this contract.

Reserved profile identities

The contract reserves two behavioral identities:

These identities name mathematical behavior. They do not identify an implementation build, an embedding model, a corpus, an index page, or the eventual IncQL-DB storage representation.

The fixture schema identity is hees_hyperquant_turboquant_fixture_0_1. The reference-contract identity is hees_hyperquant_turboquant_reference_0_1. The dense Incan implementation identity is hees_hyperquant_turboquant_incan_0_1. A future physical index format must remain separately identifiable.

Shared vector contract

Both profiles operate on vectors normalized to the unit sphere, as assumed by the paper. A Hyperquant cosine-retrieval provider must:

1. Accept only finite, non-empty vectors within the public Hyperquant dimension bound.
2. Reject a zero-norm vector.
3. Normalize each indexed vector before encoding.
4. Normalize each query before scoring.
5. Require the query and every indexed code to have the configured dimension.
6. Preserve exact full-precision vectors separately when the selected profile requires exact reranking.

The compressed code does not own a MemoryId. Index storage binds a code position to a logical memory identifier. Hyperquant nomination still returns identifiers only, and RFC 003 admission still determines whether those identifiers can materialize package-owned memory.

Deterministic random stream

Algorithms 1–2 require random Gaussian matrices. The paper does not prescribe a portable generator. Hees.ai decision TQ-RNG-001 defines one.

Counter blocks

Every random stream is identified by an ASCII domain, one unsigned 64-bit seed, and an unsigned 64-bit block counter.

The source text for block counter is:

domain + ":" + seed_hex + ":" + counter_hex

seed_hex and counter_hex are lowercase, zero-padded, 16-character hexadecimal values. The source contains ASCII bytes only and no terminator. Its SHA-256 digest is read as four consecutive unsigned 64-bit big-endian words.

The profile domains are:

hees.hyperquant.turboquant.rotation.0_1
hees.hyperquant.turboquant.qjl.0_1

Uniform and Gaussian samples

For each 64-bit word word, discard its lowest 11 bits and call the remaining 53-bit integer mantissa. Convert it to an open-interval uniform sample:

u = (mantissa + 0.5) / 2^53

Consume uniform samples in order. Convert pairs (u1, u2) to standard Gaussian samples using Box–Muller:

radius = sqrt(-2 * ln(u1))
angle = 2 * pi * u2
z0 = radius * cos(angle)
z1 = radius * sin(angle)

Emit z0, then z1. No value may be cached across domain, seed, profile, or dimension boundaries.

Rotation matrix

Algorithm 1 line 2 requires a random rotation and states that it can be generated by QR decomposition of a matrix with independent normal entries. Hees.ai decision TQ-QR-001 makes this reproducible.

1. Fill a d × d matrix A row by row from the rotation Gaussian stream.
2. Compute Householder QR in increasing column order using binary64 arithmetic.
3. If R[j,j] is negative, negate column j of Q and row j of R.
4. Reject a non-finite intermediate or a diagonal whose absolute value is at most 1e-15.
5. Use the resulting Q as the paper’s rotation matrix Π.

The positive-diagonal normalization removes the otherwise implementation-dependent sign of each QR column. The dense reference transform is intentionally faithful rather than optimized. A future structured or faster transform must use a different profile identity unless equivalence to this contract is proven.

Scalar codebooks

Algorithm 1 and Equation 4 define an optimal scalar codebook for the rotated-coordinate distribution. The paper explicitly proposes solving the one-dimensional optimization once and storing the result.

Hees.ai decision TQ-CODEBOOK-001 follows that model:

• A profile configuration carries its ordered binary64 centroids.
• turboquant_mse_0_1 with bit width b requires exactly 2^b centroids.
• turboquant_product_0_1 with total bit width b uses an MSE stage of max(0, b - 1) bits and requires 2^max(0, b - 1) centroids.
• Centroids must be finite, strictly increasing when more than one is present, contained in [-1, 1], and symmetric about zero within the declared tolerance.
• The profile configuration identifies the dimension for which the codebook was solved.
• A decoder never derives or changes centroids from corpus data.

This makes the runtime online and data-oblivious while keeping numerical codebook construction outside decoding. Shipping codebooks for production dimensions remains implementation work. A codebook is not faithful merely because it has the correct number of centroids; it must be evidence-mapped to Equation 4 and bound into configuration identity.

The dimension-four, one-bit fixture has the exact symmetric centroids ±4/(3π), because the positive conditional mean of the dimension-four coordinate density is 4/(3π).

MSE profile

turboquant_mse_0_1 follows Algorithm 1.

Encode

1. Validate and normalize the source vector x.
2. Compute y = Πx.
3. For each coordinate y[j], select the nearest centroid and store its zero-based index.
4. If two centroids are equally near, select the lower index.
5. Pack indices using TQ-PACK-001.

Reconstruct

1. Replace each index with its configured centroid, producing y_tilde.
2. Compute x_tilde = Πᵀy_tilde.

The squared reconstruction error is ||x - x_tilde||². The paper’s expected distortion guarantees describe the random procedure over transforms; they are not per-vector acceptance thresholds.

Product profile

turboquant_product_0_1 follows Algorithm 2.

Encode

1. Encode and reconstruct x through the configured MSE stage.
2. Compute the residual r = x - x_tilde_mse.
3. Compute gamma = ||r||₂.
4. Fill a d × d projection matrix S row by row from the QJL Gaussian stream.
5. Compute qjl = sign(Sr).
6. Pack MSE indices and QJL signs using TQ-PACK-001.
7. Store gamma as finite, non-negative IEEE-754 binary64.

Hees.ai decision TQ-SIGN-001 defines:

sign(value) = +1 when value >= 0
sign(value) = -1 when value < 0

Reconstruct and estimate

Compute:

x_tilde_qjl = sqrt(pi / 2) / d * gamma * S_transpose * qjl
x_tilde_product = x_tilde_mse + x_tilde_qjl

For a normalized query q, the reference inner-product estimate is:

estimate = dot(q, x_tilde_product)

An optimized implementation may score directly from packed codes and transformed queries, but it must reproduce the reference estimate within the configured numerical tolerance.

The paper proves unbiasedness in expectation over the random procedure. One fixture estimate is not expected to equal the exact inner product.

Canonical bit packing

Hees.ai decision TQ-PACK-001 defines a language-neutral packed representation:

1. Coordinates appear in logical order.
2. An unsigned index is emitted most-significant bit first using exactly its declared width.
3. A QJL sign emits 1 for +1 and 0 for -1.
4. The first emitted bit occupies bit 7 of the first byte.
5. Subsequent bits fill toward bit 0 before continuing at bit 7 of the next byte.
6. An incomplete final byte is padded with zero bits.
7. A decoder rejects a non-zero padding bit, a truncated payload, an overlong payload, or a value outside the configured codebook.

For example, five three-bit indices [0, 1, 2, 3, 4] produce hexadecimal 0538. Five sign bits [1, 0, 1, 1, 0] produce hexadecimal b0.

Canonical standalone code envelope

The implemented standalone binary envelope uses the following field order. Multi-byte integers and IEEE-754 values are big-endian.

For an MSE profile, mse_bits equals total bit width. For a product profile, mse_bits = max(0, total bit width - 1); a zero-bit MSE stage contains no index bytes and uses its sole configured centroid for every coordinate.

The standalone digest is appropriate for fixtures, transport, and isolated verification. A later paged index may amortize integrity metadata at the page level, but it must preserve the same code-body semantics and use a distinct physical-format identity.

Canonical configuration bytes

Configuration identity is SHA-256 over this exact byte sequence:

The domain strings and generation decisions are fixed by the behavioral profile version and are therefore not repeated in every configuration. Changing either domain, the random conversion, QR convention, sign convention, packing order, or reconstruction formula requires a new behavioral profile identity.

Configuration identity is not derived from JSON and is not Content DNA. It binds only the numerical retrieval configuration.

Numerical behavior

Reference calculations use IEEE-754 binary64 and the operation order described above. Fixture comparisons use combined tolerance:

abs(actual - expected) <= absolute_tolerance + relative_tolerance * abs(expected)

The initial fixtures set absolute_tolerance = 1e-12 and relative_tolerance = 1e-12. Integer values, signs, indices, bytes, identifiers, and SHA-256 digests require exact equality.

An implementation must reject non-finite input, configuration, decoded scalar, or intermediate output. It must not convert NaN into an ordering decision.

Frozen fixtures

The language-neutral fixture set lives under tests/fixtures/hyperquant/turboquant_0_1/.

The fixtures are JSON for accessibility to independent implementers. Their exact file digests are fixture-integrity evidence only; JSON is not the canonical compressed-code or configuration encoding.

Fail-closed requirements

The reference implementation rejects:

• unknown contract, profile, implementation, or physical-format versions;
• unsupported dimensions or bit widths;
• empty, non-finite, zero-norm, or dimension-mismatched vectors;
• malformed, unsorted, asymmetric, or dimension-mismatched codebooks;
• rank-deficient or non-finite seeded transforms;
• truncated, overlong, or non-canonical packed sections;
• non-zero tail padding;
• invalid sign or centroid indices;
• negative or non-finite residual norms;
• configuration digest mismatch;
• envelope or index integrity failure.

Decoding failure returns a closed Hyperquant error. It must not allocate from an unvalidated length, return a partial code, or fall back to a different profile.

What this contract does not claim

This contract does not claim that:

• the dimension-four fixture predicts retrieval quality at production dimensions;
• one seed proves unbiasedness, distortion, recall, latency, or memory behavior;
• TurboQuant scores establish relevance, evidence support, rights, review, or authority;
• the dense reference transform will be the performance default;
• the dense reference implementation is suitable for the 768-coordinate Nomic production path before the optimized slice lands;
• vector-search profiles can be reused as KV-cache format identities.

The reference codecs are now implemented in Incan. Slice 4 adds bounded approximate nomination and exact reranking. Slice 5 supplies the multi-domain, multilingual, and constrained-device evidence needed to select defaults.

Console profile 0.1 bounds and evidence

console_profile_0_1 is the first bounded implementation profile for hees.ai console. It combines a session-local Profile Studio over the supplied fictional evidence catalog with one complete governed-interaction path. The exact profile label remains console_profile_0_1. The authority architecture and profile contracts are designed for provider- and domain-neutral extension, while this release intentionally ships one fixed fictional domain and one optional GPT-5.6 adapter.

Profile Studio contract

The release exposes one shipped active profile and one session-local candidate derived from it. Evidence and memory records may be staged or unstaged in the candidate, and v reruns the shipped acceptance interaction against that candidate through the real Incan-authored Hees.ai boundary. Candidate validation exposes the stable public reason separately from the exact profile diagnostic; removing required evidence returns invalid_package and invalid_package_atoms. Candidate activation remains blocked as candidate only — not active because the public profile does not yet expose a safe activation-authority API. r resets the candidate to the shipped profile. No candidate change persists after exit or alters the active profile used by governed interactions.

Enforced ceilings

The table records enforced implementation limits, not recommended permanent-product defaults. Byte limits count UTF-8 bytes. Text and identifier limits count Unicode characters unless a byte unit is stated explicitly.

The runner and provider reject excessive nesting before invoking a JSON parser. Closed typed decoding and canonical round-trip checks reject unknown or duplicate authority-bearing fields. A host may impose stricter platform limits but cannot raise Hees.ai limits or truncate one input into a different valid value.

Measured macOS ARM64 release candidate

The following measurements were recorded on 2026-07-19 from clean source commit 982932a095c3a61806b6032a74adb36d703e1925, using released Incan 0.4.0 on macOS 26.5.2, Apple M5 Max ARM64. They describe one local candidate and do not establish support for another platform. This snapshot is evidence for the measured implementation, not a substitute for the checksum sidecar of the eventual public release.

The historical measured archive packages the executable, Apache-2.0 project license, repository notice, that platform build’s generated third-party license report, and exact release manifest. Its release-candidate gate rebuilt the native Console, ran 17 native tests and 14 provider tests, audited dependency licenses, checked for source-path and active credential leakage, verified the archive checksum and layout, extracted it into a clean temporary directory, and reran all five offline scenarios without an Incan compiler, source checkout, package manager, network service, or API key. The tagged release repeats the frozen suites and attaches its audited artifact results to the Release; those artifacts, rather than historical measurements, establish judge-facing claims.

The timing measurement used Hyperfine --shell=none with five warm-up runs and fifty measured fresh processes. It is a warm filesystem-cache result and does not claim cold-boot latency. Peak resident memory came from macOS /usr/bin/time -l; the maximum is reported rather than the mean.

Current release gates

The earlier immutable-source GitHub matrix built, extracted, and smoke-tested exact-head candidates on macOS ARM64, macOS x86-64, and Linux x86-64 with the then-pinned 0.4.0 compiler. Those results are historical candidate evidence for their source commit. The tagged release uses its commit-pinned Incan 0.5.0-dev.23 compiler and establishes support only for platforms whose exact audited artifacts are published with checksums, provenance, dependency notices, and test instructions. Windows and Linux ARM64 remain unsupported unless a later tagged release adds equivalent evidence.

The live adapter and its injected network-free composition tests are implemented. A native provider-only diagnostic exercised the Incan credential loader, ureq HTTPS POST, accepted strict schema, product decoder, and typed proposal path successfully in 8.34 seconds. Separately, external curl submitted the exact product-generated request and supplies locally observed hashes, usage, and the exact decoded proposal. A second native diagnostic reused that proposal, preflighted exactly six Hees.ai-derived targets, completed six sequential live GPT-5.6 committee calls in 40.06 seconds with zero retries, decoded three relation and three synthesis observations, and reached an admitted real-Hees.ai result with six findings, selected memory, Content DNA, and a receipt. The committee diagnostic did not repeat the proposal call in the same process, retained no usage or cost record, and ran in a temporary generated harness rather than the frozen release binary. The sanitized observation record preserves the separate observations and their limitations without a credential, hidden prompt, raw reasoning, or provider response identifier. A combined proposal-plus-committee run from the frozen release binary remains unproven. Offline replay remains fully functional. The no-rebuild judge path is established only by the published tagged native test build. Any optional hosted equivalent must run the same prebuilt executable without exposing an unrestricted shell, credentials, unrelated files, or cross-session persistence.

The optional atom-comparison inspector remains separate from Profile Studio candidate staging and reports not_configured for the current interaction. It concerns model-generated atom comparison, not the session-local selection of supplied reviewed evidence and memory.

This release is the working foundation for general evidence intake, durable profile authoring, semantic and factual verification, source and claim provenance, rights assurance, richer Spectrum and Content DNA contracts, and broader governed-response lifecycles. Those later capabilities require deeper profiles; they are not implied by the bounded fictional package or its evaluator observations.

Getting started

Requirements

The current branch requires Incan 0.5.0-dev.23 from merged source commit 121b1b789508d8fa83aa7f9400fef52e294afa62. Release tooling records that source identity separately from the canonical root incan.lock. The release workflow fails closed unless it obtains a byte-identical lock fixed point, the complete local gate, and a fresh native release matrix from the tagged Hees.ai head.

Verify the repository

make ci

Pass INCAN=/path/to/incan when the compiler is not on PATH.

Consume the library

During pre-release development, another Incan project can use a local path dependency:

[dependencies]
hees_ai = { path = "../hees.ai" }

Import checked symbols through the library namespace:

from pub::hees_ai import package_loader_descriptor, validate_package_loader_descriptor

The test project under workspaces/external-consumer/ compiles and tests this exact dependency boundary.

Verify the initial console profile

The Console workspace uses only original fictional acceptance data. Its verification covers session-local candidate-profile state, evidence and memory staging, the Hees.ai-owned acceptance probe, blocked activation, reset, responsive rendering, provider boundaries, and all five governed interactions:

make console-test console-native-smoke \
  INCAN=/path/to/incan-0.5.0-dev.23/bin/incan

This proves the bounded console_profile_0_1 workflow without downloading or invoking a language model. Provider-facing and rendering modules never receive package-authoring, activation, or terminal authority.

Run the native Console

Build the executable with the pinned Incan compiler, then start the zero-credential offline experience:

make console-build INCAN=/path/to/incan-0.5.0-dev.23/bin/incan
workspaces/hees-console/target/incan/.cargo-target/release/hees_console

The release-candidate archive renames the installed executable to hees-console and needs no compiler, package manager, source checkout, network connection, or API key at runtime. Open Evidence with 2, unstage a record with Space, validate with v, and reset with r to exercise the Profile Studio before running an interaction. Use --headless for privacy-redacted automation output. See Governance profiles for the package contract, hees.ai console for every interaction key and live-mode syntax, and profile bounds and evidence before making platform or resource claims.

Run the fictional runtime example

incan build --lib --locked
cd examples/minimal_governed_agent
incan run src/main.incn --locked

The example constructs values in memory. It is not a model, RAG, archive, package-file, or semantic-verifier demo.

Contracts

src/lib.incn is the complete checked public surface.

External package descriptor

The descriptor API exports:

• PackageLoaderDescriptor
• PackageLoaderValidation
• package_loader_descriptor
• validate_package_loader_descriptor
• package_loader_summary

Despite the historical Loader name, this surface validates metadata only. It requires schema 0.1, source kind source_controlled_domain_package, safe identifiers, and a repository-relative path ending in package/domain.json. It rejects traversal, dot segments, absolute paths, Windows drive forms, backslashes, and common embedded control characters. It does not call a filesystem API or establish that the referenced file exists.

Runtime package

GovernedPackage contains a schema version, package and domain identifiers, a mission, action contracts, and evidence records. A deployable evidence record must be explicitly RightsStatus.Allowed and ReviewStatus.Approved; raw source text is not part of the model.

validate_governed_package rejects unsupported schema versions, unsafe or duplicate identifiers, missing missions or actions, unsafe source references, unapproved evidence, and evidence whose declared runtime rights are not allowed.

Proposal admission

ModelProposal carries package/domain identifiers, a package-owned action identifier, visible output, and cited evidence identifiers. admit_model_proposal rejects invalid packages, identity mismatches, empty visible output, undeclared actions, missing required evidence, duplicate citations, and unknown citations.

Admission proves only those structural conditions. It does not prove factual correctness, semantic support, source ownership, licensing, cryptographic integrity, retrieval quality, model correctness, or policy completeness.

AdmissionResult records a terminal RuntimeDecision, a stable reason, cited evidence identifiers, and package errors. It contains no hidden reasoning or chain-of-thought.

Initial console profile

console_profile_0_1 is a separate, closed profile over the fictional Console acceptance corpus. It extends the generic runtime with one exact governed-development and interaction contract.

Its package contract is concrete: profile, package, domain and revision identity; exact source records and fingerprints; reviewed-memory atoms with source spans, provenance, review and rights state; permitted actions; visible-answer requirements; integer policy thresholds; evaluator roles and bounds; terminal reasons; selected-memory behavior; Content DNA; and receipt projection. The Governance profiles guide maps those fields to the fictional Lantern Labs package and explains their authority owners.

The profile validates exact package, request-binding, and proposal identities; recomputes the package, provenance, request, proposal, manifest-target, Content DNA, and receipt digests; constructs the complete verifier manifest; validates exact observation coverage and fingerprints; and derives findings under package-owned basis-point thresholds. Provider observations remain non-authoritative inputs. The profile, not the provider-facing Console module, selects the public reason and terminal decision.

On the admitted path, the profile delegates structural checks to admit_model_proposal, freezes every and only the admitted package atoms referenced by the support mappings, constructs Content DNA from that ordered selection, and returns the visible units and provenance atomically. A rejected path exposes no visible units, selected memory, or Content DNA. Once the fixed package, request, and proposal identity are safely established, it returns a redacted rejection receipt; raw-contract, replay, package, request, and unsafe-proposal-identity failures return no receipt.

The native Incan Console calls the public profile directly. Its Profile Studio may stage or unstage supplied evidence and memory in a session-local candidate and invoke real profile validation, but the candidate remains non-active because this profile exposes no activation-authority API. The console_runner_request_0_1 and console_runner_response_0_1 schemas remain a bounded compatibility and diagnostic seam rather than the product’s application boundary. Authority-bearing finding, Spectrum, evaluation, Content DNA, and receipt types stay internal; only their canonical terminal projection crosses the package ABI. Live mode accepts bounded provider-normalized inputs. Replay mode additionally binds the checked schema, model, configuration, prompt, and replay identities used by the fictional acceptance corpus. After decoding, both modes call the same authority path.

This first profile does not provide retrieval, a semantic verifier model, a general package compiler, or a stable production protocol. Its fixed counts, languages, source kinds, policy values, and fixture identities are deliberate acceptance-profile constraints.

RFC proposals

Hees.ai uses RFCs to review public contracts before implementation. A Draft describes proposed behavior only: it is not part of the checked 0.0.1 API. Until an RFC and its implementation are merged, Contracts and src/lib.incn remain the source of truth for supported behavior.

The RFC set is deliberately coupled. RFC 000 defines the foundational authority model; RFC 001 and RFC 002 establish Spectrum and Content DNA as core contracts; RFC 003–009 refine governed memory, constraints, packages, receipts, verifier findings, behavior selection, and visible-response governance; RFC 010 proposes a permanent hees.ai console with one deliberately bounded profile; and RFC 011 defines canonical structural identity for validated Incan models. RFCs 003–005, 007–009, and 011 are Planned: together they define governed memory, deterministic constraint composition, closed Package admission, evidence-grounded verifier findings, behavior selection, visible-response governance, and the separation of exact artifact integrity from semantic authority identity. None transfers runtime authority to a model, provider, serializer, or storage engine.

See the RFC process and lifecycle for the status definitions and publication boundary.

Architecture

The authority boundary The model proposes.
The runtime decides.

Hees.ai turns evidence, reviewed memory, declared authority, and policy into executable governance profiles, then keeps generated values separate from the terminal decision.

Evidence first, decision last

The permanent product arc begins with raw source evidence and candidate memory creation:

source evidence -> candidate memory atoms
                           |
               authorized review + rights declaration
                           |
                           v
                 reviewed memory atoms
                           |
              candidate governance profile
                           |
             Training by Committee observations
                           |
saved replay inputs ─┐     v
                    ├─> compiled Hees.ai profile -> bounded Spectrum
live model inputs ───┘     |
                           v
              governed decision -> selected memory
                           |
                    Content DNA -> receipt

The governance profile is the reusable product unit. It names the exact evidence catalog, reviewed memory, rights and review state, permitted actions, answer requirements, policy thresholds, evaluator roles, bounds, Spectrum behavior, terminal reasons, and receipt projection that apply to an interaction. A model may supply proposals and observations inside that space; it cannot write the space into existence.

The Build Week release begins later in that arc, from a supplied fictional evidence catalog and reviewed-memory package. Its Profile Studio makes the governance boundary executable: evidence and memory can be staged or unstaged in a session-local candidate and sent through the shipped acceptance interaction at the real Hees.ai boundary. It does not yet ingest arbitrary evidence, derive memory atoms, persist edits, or activate a candidate. The result keeps the stable public contract reason separate from the exact profile diagnostic; removing required evidence produces invalid_package and invalid_package_atoms. A rejected candidate probe cannot replace the shipped active profile. The Governance profiles guide explains the complete contract through the fictional Lantern Labs fields.

One boundary, three distinct roles

This separation is the architectural invariant behind the public project. The provider cannot declare its own authority, a presentation host cannot reinterpret a rejection as an admission, and a receipt cannot substitute for the terminal decision that produced it.

Implemented console_profile_0_1 path

1. ProfileEvidence + reviewed memory + declared authority

   The fictional package binds exact source identities, review and rights state, memory atoms, permitted actions, answer requirements, evaluator roles, and policy thresholds. The Profile Studio runs a candidate acceptance probe through Hees.ai while protecting the active package.

2. RequestIntegrity-bound question

   The active profile and direct question are bound before provider work begins, preventing later inputs from drifting to a different package or request.

3. ProposalUntrusted structured value

   Offline replay or the optional GPT-5.6 adapter supplies visible response units, an action identifier, evidence references, and identifier-only support mappings. Schema validity does not grant authority.

4. CommitteeNon-authoritative observations

   Hees.ai derives exact relation and synthesis targets. Role-bound evaluators return bounded observations against those targets; they do not vote and cannot select the terminal result.

5. ClassificationHees.ai findings + package policy

   Hees.ai validates target identities and complete coverage, classifies observations, and applies the package-owned thresholds in fixed public-reason precedence.

6. AdjudicationBounded Spectrum operation

   The profile reaches the checked structural runtime only after earlier validation succeeds. The profile's limited Spectrum operation then returns exactly `admit` or `reject` with a closed reason.

7. ArtifactsSelected memory + Content DNA + receipt

   An admission freezes the exact selected package memory and atomically constructs the profile-specific Content DNA and receipt. A rejection exposes its exact reason and a redacted rejection receipt when identity is safely established.

The Console renders the returned profile projection; it does not reconstruct authority from transport JSON. Offline replay stores requests, proposals, observations, schema identities, and an integrity digest, but it stores no decision, finding, selected memory, Content DNA, or receipt. Optional live mode supplies the same input classes through provider decoding. Both transports invoke identical compiled Hees.ai behavior after normalization.

Training by Committee without provider authority

This profile exercises a working proposal-pressure-testing slice of Training by Committee. It keeps evaluator roles bounded and non-authoritative while Hees.ai derives targets, validates coverage, classifies observations, and decides.

Kernel and application topology

The public Incan library has a small facade and focused internal modules. The native application is also authored in Incan and uses ordinary external crates only at genuine platform boundaries such as raw terminal I/O and HTTPS transport.

Public contract identifiers are distinct Incan newtypes. A PackageId cannot be substituted for a DomainId merely because both carry the same spelling. Every symbolic identifier derives from a shared bounded IdType; digest and revision specializations enforce their own forms. The pinned compiler invokes validated-newtype construction during derived JSON deserialization, so malformed identifier text cannot inhabit a decoded typed contract. That is still only type validity: authority requires a separate declaration or admission check.

Current proof and product direction

Permanent product north star

RFC 010 places evidence intake and profile creation before governed interaction. The permanent Console will let developers inspect lawful source evidence, create candidate memory atoms without pre-granting review or rights, validate package declarations through Hees.ai, pressure-test them through provider-neutral committee roles, run governed interactions, and inspect terminal Spectrum and Content DNA artifacts. The Build Week Profile Studio delivers the first working session-local portion of that workflow; the fictional package is its demonstration context, not its product boundary.

RFC 000 owns the foundational authority model. RFC 001 defines the proposed generalized Spectrum boundary. RFC 002 defines answer-time Content DNA. The Spectrum and Content DNA whitepaper explains their intended relationship, while Contracts and src/lib.incn remain the source of truth for checked behavior.

Spectrum and Content DNA

Status

This whitepaper explains the architectural intent behind Spectrum and Content DNA. The working console_profile_0_1 release now exercises a bounded Spectrum operation, selected-memory finality, answer-time Content DNA, and receipts over one fictional profile. The generalized contracts continue in RFC 000, RFC 001, and RFC 002.

The problem is authority, not only generation

A language model can produce useful explanations, but fluent generation does not establish that an answer follows reviewed knowledge, respects policy, handles conflicting material consistently, or can be traced to the exact sources that governed it. Retrieval alone does not solve this problem. A retrieved passage is a nomination: it may be relevant without supporting the answer, may be outdated or rights-restricted, and may conflict with another reviewed source.

Hees.ai separates language generation from governance. Packages contain reviewed knowledge and policy. Providers nominate bounded results. The model proposes visible language. Hees.ai validates those inputs and applies deterministic contracts. Spectrum owns the terminal decision, while Content DNA records the exact reviewed memory selected for the admitted answer.

This separation matters most when the deployment must behave consistently across different models, providers, languages, and devices. The model can change without silently acquiring authority over policy or provenance.

Spectrum

Spectrum is the Hees.ai adjudication core that turns admitted governed inputs into one terminal outcome. It does not generate content and does not author policy. It applies the policy and reviewed memory already admitted from a package, composes bounded non-authoritative findings, resolves declared conflicts, selects the memory that may govern the response, and chooses the final response path.

The word terminal is important. A retrieval provider may rank memory, a verifier may score a claim-premise relationship, a constraint evaluator may nominate an action, and a behavior selector may choose an eligible frame. None of those intermediate results can admit an answer. Spectrum is the single point at which those results become one governed decision.

Spectrum preserves several distinctions that conventional orchestration often collapses:

• Retrieved memory is not automatically selected memory.
• Selected memory is not the same as every premise examined by a verifier.
• A verifier finding is not a policy action.
• A behavior selection is not response admission.
• A trace is not an authority capability.
• A receipt is not proof of unrestricted truth.

For an admitted answer, Spectrum freezes the exact ordered selected-memory set and the complementary discarded-memory set. This terminal selection is the source from which Hees.ai constructs Content DNA.

Content DNA

Content DNA is answer-time provenance. It binds one terminal answer to every and only the reviewed governed-memory atoms selected by Spectrum, together with their source-safe provenance, review state, rights state, package identity, governing policy, proposal identity, and Spectrum decision.

It is not a list of model-authored citations. It is also not a copy of a build-time source manifest. A package authoring system can know where reviewed memory came from, but it cannot know which memory a future live answer will use. A model can name sources, but it cannot author its own provenance authority. Only Hees.ai has both the admitted package facts and the terminal Spectrum selection required to construct the answer-specific value.

Content DNA contains identifiers, governance state, source-safe references, and canonical digests rather than source passages or answer prose. The visible answer is bound by digest, and authorized applications can resolve the source-safe references independently. This avoids creating a second content channel while still making the relationship deterministic and auditable.

The governed flow

The proposed runtime flow is:

1. A package-authoring system compiles reviewed knowledge, policy, source-safe provenance, rights state, and acceptance fixtures into a governed package.
2. Hees.ai admits the exact package artifact and establishes its trusted identity.
3. A retrieval provider nominates logical memory identifiers under a package-approved binding.
4. Hees.ai validates the complete retrieval result and materializes package-owned memory rather than trusting provider-returned text.
5. A model proposes bounded behavior and visible response values through the declared provider contract.
6. Verifiers and other evaluators return bounded observations for exact governed targets.
7. Spectrum applies package policy, resolves the response lifecycle, and freezes the terminal selected-memory set.
8. Hees.ai constructs and validates Content DNA from the selected package-owned memory.
9. The admitted visible answer and Content DNA are returned atomically; if provenance construction fails, the answer is not admitted.
10. Export-safe receipts or traces may explain the outcome without becoming a second terminal authority.

An implementation may fuse internal stages to reduce allocation or latency, but it cannot change the authority flow or expose a partial answer before terminal provenance succeeds.

Why Content DNA is more than a receipt

A governance receipt records a terminal outcome in a compact, redacted form. It can identify the proposal, package, terminal variant, reason, and admitted logical identifiers. Content DNA answers a narrower but deeper question: which reviewed memories, from which source-safe provenance and under which governing identity, made this particular answer admissible?

The two artifacts therefore remain separate. An admitted proposal receipt references the Content DNA identifier. The Content DNA document carries the selected-memory provenance. Neither artifact recreates the direct in-process Spectrum authority merely because its canonical digest verifies.

Conflict and uncertainty

Reviewed sources may disagree, apply to different periods, or carry different authority. Spectrum does not solve this by asking a model to improvise a compromise. Contradictions and policy conflicts must enter through typed package declarations or accepted bounded findings. Package policy determines whether the result may answer with qualification, must request clarification, must reject, or may escalate.

Content DNA then reflects the memory actually selected under that policy. It must not include every retrieved source merely to appear comprehensive, and it must not omit a selected source because that source complicates the explanation. Exact coverage makes disagreement auditable without exposing private deliberation or hidden model reasoning.

Multilingual behavior

Spectrum and Content DNA are language-independent governance responsibilities. English, Afrikaans, isiZulu, Arabic, or another language may change the model, tokenizer, speech layer, translated content, or verifier calibration, but it must not change who owns terminal authority or provenance.

Translated and language-specific memory still requires package review, rights state, source provenance, applicability, and policy identity. If multiple language variants resolve to one conceptual source, the package must declare that relationship explicitly rather than letting a model infer equivalence. Content DNA identifies the exact reviewed memory variant selected for the answer, which allows an application to explain whether the answer relied on original-language material, an approved translation, or another governed representation.

Offline and constrained deployment

The authority model does not require a network service. Package admission, Spectrum adjudication, Content DNA construction, and receipt projection can run locally after installation. Provider execution can also remain local when a deployment supplies a compatible on-device model and retrieval implementation; Console 0.1.0 itself does not bundle that provider. Provider-neutral contracts keep those chosen components non-authoritative.

Consumer-device constraints still shape the detailed contracts. Memory counts, finding batches, canonicalization buffers, retained repair state, Content DNA entries, and traces require absolute bounds and representative measurements alongside the resident model. Low-memory implementations may stream or fuse internal work, but truncating Content DNA, dropping selected memory, or returning the answer before provenance completion is not an acceptable optimization.

Profile authoring and Hees.ai

Profile-authoring workflows own preparation: source intake, semantic transformation, human review, provenance compilation, rights and policy declarations, package construction, and acceptance suites. Those workflows may live in the local-first hees.ai console or another contract-compatible tool. Hees.ai owns authority-bearing validation and runtime behavior: package admission, provider-result validation, Spectrum adjudication, response admission, and Content DNA construction.

That boundary keeps runtime behavior portable. Different authoring surfaces can produce the same accepted profile contract, and another Hees.ai implementation can consume it, without changing who decides the live outcome. Authoring tools may generate synthetic expected Content DNA for fixtures, but Hees.ai must recompute the live value from the terminal selected memory.

Current proof and assurance direction

The working profile makes testable claims today: authority is explicit, provider outputs remain bounded nominations, terminal behavior follows admitted policy, admitted answers have exact selected-memory provenance, and independent implementations can be checked against the same contracts.

The larger Hees.ai direction adds semantic and factual verification, source and claim provenance, rights assurance, producer identity, conflict management, governed behavior, and richer response lifecycles to this foundation. Those assurance layers require explicit contracts and evidence. They are not replaced by a digest or evaluator score, and they do not turn hidden model reasoning into authority.

Normative map

• RFC 000 defines the foundational authority model and invariants.
• RFC 001 defines Spectrum inputs, memory roles, deterministic adjudication, terminal decision, and trace boundary.
• RFC 002 defines Content DNA states, body, entries, exact coverage, canonical identity, validation, and receipt relationship.
• Later RFCs define governed memory, constraints, package artifacts, receipts, verifier findings, behavior envelopes, and visible-response lifecycle as specialized contracts under that foundation.

Development

Run the complete local gate with commit-pinned Incan 0.5.0-dev.23:

make ci INCAN=/path/to/incan

The default uses locked dependency resolution and permits a clean machine to populate Cargo’s cache. Once dependencies are present, INCAN_FLAGS="--locked --offline" provides an additional dependency-resolution check; the packaged replay executable itself is already network-independent.

The gate includes:

• formatting checks;
• a locked public-library build;
• positive and adversarial package/runtime tests;
• an actual external Incan dependency test;
• the fictional external runtime example;
• the fail-closed repository boundary audit; and
• a strict documentation build.

Changes to the initial console profile or application also require:

make console-test console-native-smoke \
  INCAN=/path/to/incan-0.5.0-dev.23/bin/incan

Those gates compile the native Incan Console, run the direct profile and application suite, and execute all five offline scenarios through the real Hees.ai profile. The domain JSON Schemas constrain provider-facing shape; profile authority and public reason selection remain inside the Hees.ai profile.

Release-candidate archive

Build a local candidate only with the pinned toolchain for the current native target:

make console-release-candidate \
  INCAN=/path/to/incan-0.5.0-dev.23/bin/incan \
  RELEASE_PLATFORM=macos-aarch64

The candidate-platform registry is workspaces/hees-console/packaging/release-platforms.json. It pins the exact public Incan source commit, target architecture, and standard hosted runner for Linux x86_64, macOS ARM64, and macOS x86_64. Each lane builds that compiler commit natively, verifies its version, then builds Console. The command fails when the executing host does not match the selected target. Windows and Linux ARM64 are excluded until equivalent native lanes execute successfully.

For a fixed source tree, the gate:

1. reruns the package and release-contract tests;
2. audits the native bundle after remapping build paths, including checks for active credential values in the bundle;
3. embeds exactly the native Console binary, project license, repository notice, the current platform build’s generated third-party license report, and release manifest, while keeping the build-side smoke oracle out of the artifact;
4. writes RELEASE-MANIFEST.json with the source commit, clean-tree evidence, candidate platform, exact Incan source identity, Console lock digest, notice digests, and binary hash;
5. creates a normalized hees-console-<version>-<platform>.tar.gz plus adjacent .sha256; and
6. extracts and executes that archive from a clean temporary working directory with a minimal environment, temporary home, and no API key.

The smoke proves that the candidate does not need a separately installed Incan compiler, package manager, source checkout, provider credential, or network service. It does not prove that the process is physically network-sandboxed, that a different operating-system build works, that native compiler output is bit-reproducible, or that a macOS artifact is Developer ID-signed or notarized.

The matching GitHub Actions workflow checks its matrix against the same registry and uses immutable action revisions with read-only repository permission. It uploads short-lived candidate evidence and never creates a release or deployment. A platform remains a candidate until its extracted hosted artifact has run successfully. macOS outputs are not Developer ID-signed and not notarized; linker ad-hoc signing may exist solely for local execution and conveys no publisher identity.

Public symbols must be re-exported deliberately from src/lib.incn. A change that claims a new guarantee needs a test that fails when the guarantee is violated and documentation that distinguishes the guarantee from caller-owned work.

Do not add client packages, corpora, private source material, generated model artifacts, research benchmarks, provider spikes, or product control surfaces. Use fictional data in tests and examples.