Files
prometeu-runtime/docs/vm-arch/identity-hashing-producer-handoff.md
T

105 lines
5.9 KiB
Markdown

# Identity and hashing producer handoff
The runtime provides the five operations in the
[identity/hash contract](../specs/runtime/02f-vm-identity-and-value-hashing.md).
The [catalog](INTRINSICS.csv) uses schema 2. Compiler/SDK integration is pending
consumer work; the neutral PBX corpus qualifies the provider independently of
any source language. No host, firmware, syscall or Lua frontend is required.
## Provider identity
The [qualification record](IDENTITY_HASHING_QUALIFICATION.md) identifies the
source base revision, source fingerprint, toolchain, catalog/constant/vector
SHA-256 values and executed commands. Pin the delivered runtime revision and
catalog digest together when importing this provider. A catalog-only copy does
not establish consumer compatibility. The hash contract version remains one;
schema version two changes metadata representation, not old intrinsic versions.
## Representation and emission
| Operation | Encoding | Complete input group(s) | Output | Cycles |
| --- | --- | --- | --- | --- |
| REF_IDENTITY_HASH | u16 0x0097, u32 source TypeId | source | Int64 | 8+w(source) |
| REF_IDENTITY_EQ | u16 0x0098, u32 left TypeId, u32 right TypeId | left then right | Bool | 4+w(left)+w(right) |
| hash.i64@1 | INTRINSIC u32 0x4100 | Int64 | Int64 | 8 |
| hash.float@1 | INTRINSIC u32 0x4101 | Float | Int64 | 8 |
| hash.string@1 | INTRINSIC u32 0x4102 | nullable String | Int64 | 8+UTF-8 bytes |
All fields are little-endian. TypeIds are program-local Registry indices.
Reference eligibility is exactly Struct/Array/Fn/Trait/Random; preserve complete
Trait pairs and source evaluation order. Valid trait views hash/compare their
receiver, including ImplementationId zero. Do not project String/Dynamic through
these opcodes or widen the older REF_* category rules.
For example, with TypeId 5 a Struct and TypeId 7 its Trait, emit:
```text
STRUCT_NEW 5
SET_LOCAL 0
GET_LOCAL 0
REF_IDENTITY_HASH 5
GET_LOCAL 0
REF_TO_TRAIT source=5,target=7
REF_IDENTITY_HASH 7
EQ
RET
```
The result is true. Trait conversion must have a coherent Registry implementation.
Hash values use signed Int64 carriers with unchanged digest bits; negative results
are valid. SDK code must define ordered component composition, optional/Dynamic
strategies, 32-bit folding, and coherent equality domains. Integer/Float equality
across domains requires explicit canonicalization; numerical Float-to-Int64
conversion is not the Float hashing algorithm.
## Metadata import and rejection
Import all 25 exact columns, including schema_version=2 on every row and ordered
arg_nullable booleans matching flattened argument slots. Preserve the existing
18 fields. Validate:
- borrowed_inline_v1/none/none is the hash profile; deterministic=true,
may_allocate=false and mutates_guest_state=false are separate claims.
- fixed numeric costs have no cost_arg_index and cost_per_byte=0.
- argument_utf8_bytes_v1 uses String slot zero, cost_per_byte=1 and base eight;
attempt_cost_cycles/max_attempts are zero.
- Old Host and VM-owned entries retain their explicit profiles and existing
contract; their metadata does not promise the bounded profile's execution model.
- Known null is admitted for hash.string only among String arguments; previous
String intrinsics and numeric hashes keep non-nullable admission. Random
nullable admission still allows runtime receiver precondition faults.
Reject unsupported schemas, profiles, cost models, capacities and inconsistent
layouts/nullable widths/indexes explicitly. Do not infer nullability, scratch,
context access or purity from names or deterministic alone. Preserve observable
faults and charged work when results are unused. Optimization must not skip
complete right-side validation because a left operand is null or differs.
## Studio consumer ownership and acceptance
The following targets belong to the Studio/compiler delivery, outside this
runtime implementation:
| Target | Required result and acceptance evidence |
| --- | --- |
| Manual IRVMIntrinsicDefinition and intrinsic registry | Represent/import schema, nullable mask, invocation/scratch/context and cost parameters; reject unknown or inconsistent entries. |
| IR, verifier, lowering and emitter | Represent both typed reference instructions, complete operand groups and exact IDs; admit nullable String per entry; preserve fault order and costs. |
| Catalog mirrors and runtime-catalog pin | Copy generated schema 2 artifacts, record runtime revision and SHA-256, retain all old IDs/versions/contracts and constant bytes. |
| Packaged compiler and SDK resources | Installed resources and generated code use the same pin, schema and definitions as development execution. |
| SDK equality/hash wrappers | Explicit domain policy, null handling, Float zero normalization, Int32 widening, Bool mapping, composition and 32-bit folding. No implicit object-content or universal Dynamic equality. |
| Normal and optimized source corpus | Execute emitted PBX against the runtime and compare result bits, faults, retained operands and cycles. Include the neutral cases below and packaged execution. |
Consumer corpus coverage must include signed Int64 extremes and negative digests;
finite Float subnormals/extremes/2^53, both zeros and injected non-finite faults;
UTF-8, NUL, empty/null and equal content with different owners; aliases versus
distinct objects/closures/generators; mutation and Random advancement; Trait
views and implementation zero; absent and malformed groups; stale handles after
GC/reuse; rejected right groups despite null/different left groups; zero fuel,
positive overshoot and discarded results. Reuse the
[reference vectors](../../crates/console/prometeu-vm/tests/fixtures/hash-conformance.tsv)
with their [independent oracle provenance](../../crates/console/prometeu-vm/tests/fixtures/hash-oracle.md).
Set/Map implementation, source frontend integration, general structural equality,
storage-publication integration and any future Lua frontend retain their own
scope and validation. This handoff does not report those consumers as delivered.