243 lines
14 KiB
Markdown
243 lines
14 KiB
Markdown
# 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 reused by [Map/Keyval](sdk-map-and-keyval.md). 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](../../general/specs/typed-registry-and-pbx-v0.md)
|
|
and [catalog consumer rules](../../general/specs/runtime-catalog-support.md).
|