feat(pbs): add Set and reusable identity hashing
This commit is contained in:
@@ -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).
|
||||
Reference in New Issue
Block a user