14 KiB
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 contracts, Array/optional
and the shared snapshot Cursor.
Types, construction and operations
The @sdk:collections module exports invariant ordinary generic set<T> and the
nominal contract Identity<T>:
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 | 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:
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:
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 reused by Map/Keyval. Its 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 and catalog consumer rules.