feat(pbs): add Set and reusable identity hashing

This commit is contained in:
2026-10-25 12:15:13 +00:00
parent 632ba6d0d6
commit 8105604f92
59 changed files with 4190 additions and 34 deletions
+1 -1
View File
@@ -1,6 +1,6 @@
# PBS Generic Contracts
Owner: `compiler/pbs`. This specification extends nominal contracts with explicit type parameters. Registry, PBX, instruction, ownership and resource contracts remain governed by the runtime provider. Collections and object-identity hashing are separate consumers.
Owner: `compiler/pbs`. This specification extends nominal contracts with explicit type parameters. Registry, PBX, instruction, ownership and resource contracts remain governed by the runtime provider. [Set, SDK Identity and hashing](sdk-set-and-identity.md) are consumers with their own public policy; the examples below illustrate generic language syntax, not the SDK Identity declaration.
## Declaration and application
@@ -177,10 +177,11 @@ faults. List itself rejects directly optional elements.
The shared implementation is independent of List representation.
[Linked](sdk-linked-and-cursor.md) uses Cursor<T> for forward and reverse captures.
Future Set<T> producers use Cursor<T>; Map<K,V> uses Cursor<keyval<K,V>>. Set/Map gain
no ordering guarantee between captures. A captured keyval association is read-only
[Set](sdk-set-and-identity.md) produces Cursor<T>; future Map<K,V> uses
Cursor<keyval<K,V>>. Set/Map gain no ordering guarantee between captures.
A captured keyval association is read-only
and does not follow later association replacement; referenced objects stay shared.
Set/Map and keyval are separate deliveries.
Map and keyval remain separate deliveries.
For n logical List positions and k present occurrences, capture takes O(n) work
and O(k) additional nodes; next follows one link in O(1). Each node costs allocation,
@@ -0,0 +1,242 @@
# SDK Set, Identity and hashing
Owner: `compiler/pbs`. Set algorithms belong to executable PBS SDK source. Typed
reference queries, storage, admission, faults and resource limits are generic
compiler/provider mechanisms. This contract builds on [generic structs](generic-structs-and-free-functions.md),
[generic contracts](generic-contracts.md), [Array/optional](typed-arrays-and-optional-execution.md)
and the [shared snapshot Cursor](sdk-list-and-cursor.md#cursor-protocol).
## Types, construction and operations
The `@sdk:collections` module exports invariant ordinary generic `set<T>` and the
nominal contract `Identity<T>`:
```pbs
declare contract Identity<T> {
fn hash(value: T) -> long;
fn equals(left: T, right: T) -> bool;
}
```
Import the SDK declarations with `import {set, Identity, Cursor} from @sdk:collections;`.
Another user contract named Identity does not become the SDK contract through its spelling.
`new set<T>()` selects the SDK default for T. `new set<T>(identity)` takes an
explicit `Identity<T>` service/struct value. Contextual `new set()` and diamond
construction require an existing expected application; argument values do not infer
T. Type applications and strategies are invariant. Associated members such as
Enemy.identity, blanket implementations and generic reflection are not introduced.
No-strategy construction for T without a default is a localized source error.
Explicit-strategy construction remains valid for otherwise supported grouped/native
T, even though the generic owner also declares a no-argument constructor. Direct
optional T, including grouped optional, is invalid with either constructor.
`optional (set<T>)` and elements with optional fields remain valid.
| Operation | Result | Behavior |
| --- | --- | --- |
| add(value) | bool | True on inclusion; false for an equal existing element |
| contains(value) | bool | Membership under the selected policy |
| remove(value) | bool | True only when an equal element was removed |
| clear() | unit | Release table/nodes and reset size to zero |
| size() | long | Number of elements |
| isEmpty() | bool | size equals zero |
| cursor() | Cursor<T> | Complete independent snapshot |
Set has stable reference identity: aliases observe the same collection. A duplicate
add preserves the original stored reference and does not grow the table. Removing
an absent value is false. There is no positional indexer, tryGet, capacity argument,
capacity/reserve/trim API or public node. Insertion/iteration order is not guaranteed.
Receiver and arguments evaluate once in source order, including named application.
An unrelated user declaration named set gains none of the SDK-specific rules.
## Equality policy and obligations
| T | Default policy |
| --- | --- |
| int / long | Value equality in the static domain of T; int widens exactly to Int64 for hashing |
| bool | Value equality; false/true map to Int64 0/1 for hashing |
| str | Exact resident UTF-8 content, without normalization or case folding |
| float | Finite Float equality; +0 and -0 are equal and hash equally |
| Source structs, arrays, Fn and Random | Instance identity, independent of mutable fields/elements, code/captures or generator state |
| contracts | Identity of the fully validated receiver, independent of view/ImplementationId |
| Tuples and other native values | Explicit Identity required; no automatic composition |
Services represented as ordinary singleton references retain the same instance
semantics when they are valid element types. There is no public Dynamic, universal
cross-numeric equality, structural fallback or equality based on private value
carrier identity. Hash collisions do not imply equality. All signed long digest
bits, including negative values, are retained.
Two distinct gameplay objects with equal fields remain distinct under defaults.
An explicit strategy may define content equality and collapse such instances.
Actual stored references remain shared; no deep freezing/copying occurs. Identity
must define a stable equivalence relation while stored and satisfy
`equals(a,b) => hash(a) == hash(b)`. The converse is not required. Strategy
configuration and relevant content must remain coherent. Remove from every affected
collection before changing content used by equality/hash, then reinsert. A cached
old hash does not stabilize mutable equality. The SDK cannot prove these obligations
and does not introduce purity, readonly or effect-system requirements.
Every value preserves its complete logical group and reference aliases through
callbacks, nodes, calls, allocations, rehash and capture. A tuple's private storage
carrier is not that tuple's source identity. Groups/native owners retain ordinary
storage packing and quota costs.
## Private representation and growth
Set uses a private array of buckets with private chained nodes. Each node stores
the complete cached long hash, full T and its next link. It does not depend on the
public linked collection or a universal Element. Hash selects candidates and
equals resolves collisions, including deliberately identical hashes.
Empty construction has no nonempty bucket table. First successful inclusion uses
8 buckets. For current capacity c and next size r, grow when r exceeds
`floor(3*c/4)`; new capacity is `min(2*c, 4294967295)`. Arithmetic uses long and
must not overflow. At the maximum Array capacity, chaining can continue within
checked signed-long size and provider quotas, accepting increased occupancy.
Array's u32 structural bound limits buckets, not the count of chained elements.
An unrepresentable next size is rejected before addition/mutation.
For positive capacity, select the bucket with signed remainder and correction:
```text
bucket = hash % capacity
if bucket < 0: bucket += capacity
```
Do not abs the digest, narrow to int, or assume every capacity is a power of two.
Removal does not shrink. Clear releases table/node references and returns to lazy
empty state. Discarded objects and old storage follow normal tracing and other
owners; immediate collection or quota recovery is not guaranteed.
Rehash prepares independent buckets/nodes/topology from cached hashes. It preserves
published links until installation and preserves payload reference identities.
It does not invoke hash/equals. Old and candidate structures coexist under ordinary
quotas; private carriers can add allocation/ownership work. Installation uses
ordinary typed stores. Whole-table reconstruction on every mutation is not the
algorithm, and preparing a candidate does not make later source instructions atomic.
Search cost depends on hash distribution, occupancy and callback cost; the worst
case is O(N). Growing rehash costs O(new buckets + N) work and additional nodes/table.
String hashing additionally costs work proportional to content. Expected lookup
or amortized growth claims do not promise constant instruction cost, no allocation,
adversarial resistance or allocation-free optional carriers.
## Guard, mutation phases and faults
Operations calling Identity use a private guard. A callback cannot reenter
add/remove/clear/contains on the same Set, including aliases; reject before
structural changes through the private terminal TRAP_EXPLICIT path. During callback
preparation the original structure is consistent: size/isEmpty/cursor may read it
without invoking Identity. Capturing a Cursor may still fail resources.
Validation, hashing/equality/search, next sizes, nodes/tables and value/return
carriers are prepared before structural writes. No user callback or explicit
suspension occurs in the sequence that applies structural changes. Rehash/capture
never call strategies. The guard is released on successful return, including
ordinary false results.
| Outcome | Guarantee |
| --- | --- |
| Refusal before the first structural write | Prior elements/topology are unchanged; external argument/callback effects and provisional allocations are not undone |
| Successful return | Size, topology, buckets, groups, identity, cleanup and guard invariants hold |
| Internal/resource fault after structural mutation starts | Earlier writes may remain and invariants may be incomplete; no rollback, safe reuse, retry or automatic recovery |
Installing the guard is already a write. Callback fault can leave it active while
elements remain unchanged. Structural preservation is not bit-for-bit preservation
of the whole Set object. No catch/finally, poison flag or recovery API is added;
permitted callback reads do not establish post-fault safe reuse. Mutations of other
Sets/objects are not rolled back, and the guard does not prove strategy stability.
Faults are never translated into false/none.
Per-instruction refusal preserves that instruction's applicable entry state, not
earlier successful instructions. BudgetExhausted/debugger pauses are resumable
instruction boundaries; execution resumes at its PC. A source method is not an
atomic observation region for host/debugger inspection.
## Snapshot Cursor
Cursor uses the existing shared implementation and full state table. A nonempty
snapshot begins on the first captured element; hasNext tests a successor; next
without a successor keeps the final value. Only an empty-born Cursor reports
current absent. Consume current before deciding whether to advance:
```pbs
let snapshot = values.cursor();
while true {
if let value = snapshot.current() {
// Use value.
} else { break; }
if snapshot.hasNext() { snapshot.next(); }
else { break; }
}
```
Capture allocates one private immutable singly linked node per element and completes
before returning. Failure returns no partial Cursor and preserves source structure.
Snapshot nodes retain payload values, not editable Set nodes/bucket positions.
Later inclusion/removal/clear/growth cannot rewrite the capture. Referenced objects
remain shared and later field mutation remains visible; iteration order between
captures is not guaranteed. There is no live/fail-fast iterator, reset, removal
through Cursor or new for-in protocol.
For B buckets and N elements, capture is O(B+N) work/O(N) extra nodes and next O(1).
Consumed prefixes can become unreachable; final current node/value stays retained
until the Cursor releases it. Ordinary allocations, carriers, owners, GC and quotas
apply without relaxation.
## Hash facade and typed query boundary
`@sdk:hash` exports `hash.i64(long)->long`, `hash.f64(float)->long`,
`hash.text(str)->long`, `referenceHash<T>(T)->long` and
`referenceEquals<T>(T,T)->bool`. Generic reference wrappers require explicit type
arguments and accept exactly eligible reference categories; grouped/optional value
carriers and arbitrary scalar/Dynamic values do not become references.
The reference wrappers lower complete groups to REF_IDENTITY_HASH 0x0097 and
REF_IDENTITY_EQ 0x0098. Contracts validate receiver and ImplementationId, including
valid zero, before querying receiver identity. Concrete and valid trait views agree.
Both sides of equality validate left-to-right; an absent/different left cannot
suppress an invalid right. Invalid handles/groups remain faults. TypeIds are static
program metadata, not guest selectors. Reference hashes do not root objects or
provide persistent cross-session IDs.
Scalar wrappers use hash.i64@1 0x4100, hash.float@1 0x4101 and hash.string@1 0x4102.
Hash-v1 preserves the provider's XXH64 seed-zero digest bits. Numeric hashes cost
8 cycles; String costs 8 plus UTF-8 bytes. Finite Float bit hashing normalizes both
zeros, never converts numerically to integer, and rejects non-finite inputs.
Provider-level canonical null String hashes to zero and differs from empty text;
PBS adds no public null syntax or optional-element admission. Reference hash costs
8+w(T), equality 4+w(left)+w(right). Valid queries have bounded borrowed execution
without guest/scratch allocation or user callbacks; wrapper/call costs are separate.
Compiler verification, emission and optimization must preserve complete groups,
provenance/null admission, fault order, attempt costs, zero-budget/overshoot and
unused-result effects. Defaults are resolved by private trusted bindings at
concrete logical types, not by enabling == on unconstrained T. Existing user
contracts named Identity retain their own nominal identity and signatures.
## Qualification, distribution and related consumers
Qualify the hash facade from real PBS through PBX into the production VM before
Set algorithms. Test ordinary/optimized source and neutral producers, independent
provider vectors, negative hashes, complete contract groups, Float boundaries,
String owners, aliases/mutation, GC/stale handles and malformed/dead instructions.
Strategy counters and deliberate collisions must demonstrate callback-free
rehash/capture and alias-safe reentrancy. Observe measured old/candidate memory
peaks and instruction-prefix refusal state, separating guard effects and structural
writes. Controlled test-only fault injection must be identified separately from
natural production quota cases.
Ship this English specification, SDK source and executable examples in installed
knowledge; compile actual installed examples outside the checkout and execute their
PBX. Normal compilation uses versioned Studio catalogs/resources without a sibling
checkout. Runtime ownership, limits and semantics remain the provider contract;
Set adds no VM collection instruction/syscall or provider source change.
Identity/hash are reusable by future Map. Map/keyval API, representation and
implementation are separate consumers; sharing policy does not impose a shared
physical table or universal entry type. See the
[common typed Registry contract](../../general/specs/typed-registry-and-pbx-v0.md)
and [catalog consumer rules](../../general/specs/runtime-catalog-support.md).