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

5.9 KiB

Identity and hashing producer handoff

The runtime provides the five operations in the identity/hash contract. The catalog 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 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:

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 with their independent oracle provenance.

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.