105 lines
5.9 KiB
Markdown
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.
|