toilscript 0.1.26 → 0.1.28

package/dist/web.js

@@ -1,8 +1,8 @@
-var ASSEMBLYSCRIPT_VERSION = "0.1.26";
+var ASSEMBLYSCRIPT_VERSION = "0.1.28";
   var ASSEMBLYSCRIPT_IMPORTMAP = {
   "imports": {
-    "toilscript": "https://cdn.jsdelivr.net/npm/toilscript@0.1.26/dist/toilscript.js",
-    "toilscript/cli": "https://cdn.jsdelivr.net/npm/toilscript@0.1.26/dist/cli.js",
+    "toilscript": "https://cdn.jsdelivr.net/npm/toilscript@0.1.28/dist/toilscript.js",
+    "toilscript/cli": "https://cdn.jsdelivr.net/npm/toilscript@0.1.28/dist/cli.js",
     "binaryen": "https://cdn.jsdelivr.net/npm/binaryen@129.0.0-nightly.20260428/index.js",
     "long": "https://cdn.jsdelivr.net/npm/long@5.3.2/index.js"
   }

package/package.json

@@ -8,7 +8,7 @@
     "toilscript",
     "wasm"
   ],
-  "version": "0.1.26",
+  "version": "0.1.28",
   "author": "Daniel Wirtz <dcode+assemblyscript@dcode.io>",
   "license": "Apache-2.0",
   "homepage": "https://github.com/dacely-cloud/toilscript",

package/std/assembly/bindings/toildb.ts

@@ -0,0 +1,169 @@
+// Host-import declarations for the ToilDB data API. The production edge
+// (toil-backend `src/wasm/host/import_functions/db`) and the toiljs dev server
+// both provide these under the `env` namespace. All byte regions are passed as
+// a (pointer, length) pair into guest linear memory.
+//
+// Collections are resolved by name ONCE at module init (`resolveCollection`),
+// which returns an opaque numeric handle; request-time ops pass the handle.
+//
+// Return convention (see toildb/ABI.md):
+//   >= 0  success: a length (a value stashed for `takeResult`), a count, a
+//         boolean (0/1), a tag, or 0 (ok).
+//   -1    output buffer too small (retry `takeResult` with a bigger buffer).
+//   -2    absent (a normal null / not-found).
+//   <= -1000  a typed failure; the diagnostic is TDL(|v| - 1000).
+//
+// Variable-length results (a fetched value, a patched record, a claim owner)
+// use the two-step pull: the op returns the stashed length, then the guest
+// allocates a buffer and calls `takeResult` to copy the bytes out.
+//
+// `idemPtr` is 0 for none, otherwise a pointer to a 16-byte idempotency key.
+//
+// This is the guest half of the ABI contract; the byte framing of keys/values
+// is the `@data` binary codec (`DataWriter`/`DataReader`).
+
+export namespace toildbHost {
+  // Resolve a collection by its "<db>/<collection>" name; writes the u32 handle
+  // to outHandlePtr. Returns 0 on success or a negative TDL code.
+  // @ts-ignore: decorator
+  @external("env", "data.resolve_collection")
+  export declare function resolveCollection(namePtr: usize, nameLen: i32, outHandlePtr: usize): i32;
+
+  // record.get -> value length (stashed) | -2 absent | negative error.
+  // @ts-ignore: decorator
+  @external("env", "data.get")
+  export declare function get(handle: u32, keyPtr: usize, keyLen: i32): i32;
+
+  // record bounded multi-get. Input at keysPtr: u32 count + per key (u32 len +
+  // bytes). Result (stashed): u32 count + per item u8 present (+ u32 len + bytes
+  // when present), in request order. Returns the stashed length | negative error.
+  // @ts-ignore: decorator
+  @external("env", "data.get_many")
+  export declare function getMany(handle: u32, keysPtr: usize, keysLen: i32): i32;
+
+  // record.exists -> 1 | 0 | negative error.
+  // @ts-ignore: decorator
+  @external("env", "data.exists")
+  export declare function exists(handle: u32, keyPtr: usize, keyLen: i32): i32;
+
+  // record.create -> 0 ok | AlreadyExists/typed code.
+  // @ts-ignore: decorator
+  @external("env", "data.create")
+  export declare function create(
+    handle: u32,
+    keyPtr: usize,
+    keyLen: i32,
+    valPtr: usize,
+    valLen: i32,
+    idemPtr: usize
+  ): i32;
+
+  // record.patch -> length of the new record (stashed) | negative error.
+  // @ts-ignore: decorator
+  @external("env", "data.patch")
+  export declare function patch(
+    handle: u32,
+    keyPtr: usize,
+    keyLen: i32,
+    patchPtr: usize,
+    patchLen: i32,
+    idemPtr: usize
+  ): i32;
+
+  // record.delete -> 0 ok | negative error.
+  // @ts-ignore: decorator
+  @external("env", "data.delete")
+  export declare function del(handle: u32, keyPtr: usize, keyLen: i32, idemPtr: usize): i32;
+
+  // record consume-once fetch-and-delete -> prior value length (stashed) | -2.
+  // @ts-ignore: decorator
+  @external("env", "data.get_delete")
+  export declare function getDelete(handle: u32, keyPtr: usize, keyLen: i32, idemPtr: usize): i32;
+
+  // unique.lookup -> owner value length (stashed) | -2 absent.
+  // @ts-ignore: decorator
+  @external("env", "data.unique_lookup")
+  export declare function uniqueLookup(handle: u32, keyPtr: usize, keyLen: i32): i32;
+
+  // unique.claim -> 0 Claimed | 1 AlreadyClaimed (owner stashed) | 2 owned-by-caller | neg.
+  // @ts-ignore: decorator
+  @external("env", "data.unique_claim")
+  export declare function uniqueClaim(
+    handle: u32,
+    keyPtr: usize,
+    keyLen: i32,
+    valPtr: usize,
+    valLen: i32,
+    idemPtr: usize
+  ): i32;
+
+  // unique.release -> 0 ok | neg (Conflict if not the owner).
+  // @ts-ignore: decorator
+  @external("env", "data.unique_release")
+  export declare function uniqueRelease(
+    handle: u32,
+    keyPtr: usize,
+    keyLen: i32,
+    valPtr: usize,
+    valLen: i32,
+    idemPtr: usize
+  ): i32;
+
+  // view.get -> view value length (stashed) | -2 absent | negative error.
+  // @ts-ignore: decorator
+  @external("env", "data.view_get")
+  export declare function viewGet(handle: u32, keyPtr: usize, keyLen: i32): i32;
+
+  // view.publish -> 0 ok | negative error (derive/job only; the host gate enforces).
+  // @ts-ignore: decorator
+  @external("env", "data.view_publish")
+  export declare function viewPublish(
+    handle: u32,
+    keyPtr: usize,
+    keyLen: i32,
+    valPtr: usize,
+    valLen: i32,
+    idemPtr: usize
+  ): i32;
+
+  // counter.get -> 8 (the i64 sum stashed as 8 LE bytes) | negative error.
+  // @ts-ignore: decorator
+  @external("env", "data.counter_get")
+  export declare function counterGet(handle: u32, keyPtr: usize, keyLen: i32): i32;
+
+  // counter.add(delta: i64) -> 0 ok | negative error.
+  // @ts-ignore: decorator
+  @external("env", "data.counter_add")
+  export declare function counterAdd(
+    handle: u32,
+    keyPtr: usize,
+    keyLen: i32,
+    delta: i64,
+    idemPtr: usize
+  ): i32;
+
+  // events.append -> 0 ok | negative error.
+  // @ts-ignore: decorator
+  @external("env", "data.append")
+  export declare function append(
+    handle: u32,
+    keyPtr: usize,
+    keyLen: i32,
+    evPtr: usize,
+    evLen: i32,
+    idemPtr: usize
+  ): i32;
+
+  // events.latest(limit) -> framed-list length (stashed) | negative error.
+  // The blob is `u32 count` then per event `u32 len + bytes`, newest first.
+  // @ts-ignore: decorator
+  @external("env", "data.latest")
+  export declare function latest(handle: u32, keyPtr: usize, keyLen: i32, limit: i32): i32;
+
+  // Copy the last stashed variable-length result into outPtr (outLen must equal
+  // the length the producing op returned). Returns bytes written, or -1 if the
+  // buffer is too small.
+  // @ts-ignore: decorator
+  @external("env", "data.take_result")
+  export declare function takeResult(outPtr: usize, outLen: i32): i32;
+}

package/std/assembly/crypto/subtle.ts

@@ -7,12 +7,11 @@ import { webcrypto } from "bindings/webcrypto";
 import { CryptoKey } from "crypto/key";
 import {
   AlgorithmParams,
-  algId,
-  formatId,
   cryptoError,
-  FMT_JWK,
+  FMT_RAW,
   FMT_PKCS8,
   FMT_SPKI,
+  FMT_JWK,
   ALG_AES_GCM,
   ALG_AES_CBC,
   ALG_AES_CTR,
@@ -43,26 +42,24 @@ function isSymmetricAlg(alg: i32): bool {
 }
 
 export class SubtleCrypto {
-  digest(algorithm: string, data: Uint8Array): Uint8Array {
-    let id = algId(algorithm);
-    if (id == 0) throw new Error("Unrecognized algorithm: " + algorithm);
-    return drain(webcrypto.digest(id, data.dataStart, data.byteLength));
+  // `algorithm` is a hash-id selector: an `ALG_SHA_*` const (NOT a magic string).
+  digest(algorithm: i32, data: Uint8Array): Uint8Array {
+    return drain(webcrypto.digest(algorithm, data.dataStart, data.byteLength));
   }
 
+  // `format` is an `FMT_*` selector const (FMT_RAW / FMT_PKCS8 / FMT_SPKI).
   importKey(
-    format: string,
+    format: i32,
     keyData: Uint8Array,
     algorithm: AlgorithmParams,
     extractable: bool,
     usages: i32
   ): CryptoKey {
-    let fmt = formatId(format);
-    if (fmt < 0) throw new Error("Unknown key format: " + format);
-    if (fmt == FMT_JWK) throw new Error("jwk key format is not supported");
+    if (format == FMT_JWK) throw new Error("jwk key format is not supported");
     let p = algorithm.pack();
     let alg = load<i32>(p.dataStart); // first packed field is the alg id
     let handle = webcrypto.importKey(
-      fmt,
+      format,
       keyData.dataStart,
       keyData.byteLength,
       p.dataStart,
@@ -73,18 +70,17 @@ export class SubtleCrypto {
     if (handle < 0) throw new Error(cryptoError(handle));
 
     let type: string;
-    if (fmt == FMT_PKCS8) type = "private";
-    else if (fmt == FMT_SPKI) type = "public";
+    if (format == FMT_PKCS8) type = "private";
+    else if (format == FMT_SPKI) type = "public";
     else type = isSymmetricAlg(alg) ? "secret" : "public";
 
     return new CryptoKey(handle, type, extractable, alg, usages);
   }
 
-  exportKey(format: string, key: CryptoKey): Uint8Array {
-    let fmt = formatId(format);
-    if (fmt < 0) throw new Error("Unknown key format: " + format);
-    if (fmt == FMT_JWK) throw new Error("jwk key format is not supported");
-    return drain(webcrypto.exportKey(fmt, key.handle));
+  // `format` is an `FMT_*` selector const (FMT_RAW / FMT_PKCS8 / FMT_SPKI).
+  exportKey(format: i32, key: CryptoKey): Uint8Array {
+    if (format == FMT_JWK) throw new Error("jwk key format is not supported");
+    return drain(webcrypto.exportKey(format, key.handle));
   }
 
   encrypt(algorithm: AlgorithmParams, key: CryptoKey, data: Uint8Array): Uint8Array {
@@ -146,6 +142,6 @@ export class SubtleCrypto {
     usages: i32
   ): CryptoKey {
     let bits = this.deriveBits(algorithm, baseKey, lengthBits);
-    return this.importKey("raw", bits, derivedKeyAlgorithm, extractable, usages);
+    return this.importKey(FMT_RAW, bits, derivedKeyAlgorithm, extractable, usages);
   }
 }

package/std/assembly/crypto.ts

@@ -11,7 +11,16 @@
 
 import { webcrypto } from "bindings/webcrypto";
 import { SubtleCrypto } from "crypto/subtle";
-import { HmacImportParams, HmacParams, ALG_SHA_256, USAGE_SIGN } from "crypto/algorithms";
+import {
+  HmacImportParams,
+  HmacParams,
+  ALG_SHA_1,
+  ALG_SHA_256,
+  ALG_SHA_384,
+  ALG_SHA_512,
+  FMT_RAW,
+  USAGE_SIGN,
+} from "crypto/algorithms";
 import { Encoding } from "encoding";
 
 // Re-export the public surface so guests can import everything from "crypto".
@@ -51,6 +60,13 @@ export {
   ALG_X25519,
   ALG_HKDF,
   ALG_PBKDF2,
+  ALG_SHA3_256,
+  ALG_SHA3_384,
+  ALG_SHA3_512,
+  FMT_RAW,
+  FMT_PKCS8,
+  FMT_SPKI,
+  FMT_JWK,
   CURVE_P256,
   CURVE_P384,
   USAGE_ENCRYPT,
@@ -101,16 +117,16 @@ export namespace crypto {
 
   // --- Ergonomic digest helpers (thin wrappers over subtle.digest) ----------
   export function sha1(data: Uint8Array): Uint8Array {
-    return subtle.digest("SHA-1", data);
+    return subtle.digest(ALG_SHA_1, data);
   }
   export function sha256(data: Uint8Array): Uint8Array {
-    return subtle.digest("SHA-256", data);
+    return subtle.digest(ALG_SHA_256, data);
   }
   export function sha384(data: Uint8Array): Uint8Array {
-    return subtle.digest("SHA-384", data);
+    return subtle.digest(ALG_SHA_384, data);
   }
   export function sha512(data: Uint8Array): Uint8Array {
-    return subtle.digest("SHA-512", data);
+    return subtle.digest(ALG_SHA_512, data);
   }
 
   // String-input variants (UTF-8 encode, then hash).
@@ -129,7 +145,7 @@ export namespace crypto {
 
   /// One-shot HMAC-SHA-256 over raw key + message bytes.
   export function hmacSha256(key: Uint8Array, msg: Uint8Array): Uint8Array {
-    let k = subtle.importKey("raw", key, new HmacImportParams(ALG_SHA_256), false, USAGE_SIGN);
+    let k = subtle.importKey(FMT_RAW, key, new HmacImportParams(ALG_SHA_256), false, USAGE_SIGN);
     return subtle.sign(new HmacParams(), k, msg);
   }
   export function hmacSha256Text(key: Uint8Array, msg: string): Uint8Array {

package/std/assembly/index.d.ts

@@ -2853,11 +2853,14 @@ declare class X25519ImportParams extends AlgorithmParams {}
 declare class EcdhParams extends AlgorithmParams {
   constructor(alg: i32, publicKeyHandle: i32);
 }
-/** Synchronous SubtleCrypto (no Promises). Returns values directly. */
+/** Synchronous SubtleCrypto (no Promises). Returns values directly. The hash and
+ *  key-format arguments are typed ABI ids (no magic strings): pass an `ALG_SHA_*`
+ *  const to `digest`, and an `FMT_*` const (`FMT_RAW` / `FMT_PKCS8` / `FMT_SPKI`)
+ *  to `importKey` / `exportKey`. */
 declare class SubtleCrypto {
-  digest(algorithm: string, data: Uint8Array): Uint8Array;
-  importKey(format: string, keyData: Uint8Array, algorithm: AlgorithmParams, extractable: bool, usages: i32): CryptoKey;
-  exportKey(format: string, key: CryptoKey): Uint8Array;
+  digest(algorithm: i32, data: Uint8Array): Uint8Array;
+  importKey(format: i32, keyData: Uint8Array, algorithm: AlgorithmParams, extractable: bool, usages: i32): CryptoKey;
+  exportKey(format: i32, key: CryptoKey): Uint8Array;
   encrypt(algorithm: AlgorithmParams, key: CryptoKey, data: Uint8Array): Uint8Array;
   decrypt(algorithm: AlgorithmParams, key: CryptoKey, data: Uint8Array): Uint8Array;
   sign(algorithm: AlgorithmParams, key: CryptoKey, data: Uint8Array): Uint8Array;
@@ -2868,6 +2871,8 @@ declare class SubtleCrypto {
 
 // Algorithm / format / curve / usage ids (the Web Crypto ABI contract).
 declare const ALG_SHA_1: i32, ALG_SHA_256: i32, ALG_SHA_384: i32, ALG_SHA_512: i32;
+declare const ALG_SHA3_256: i32, ALG_SHA3_384: i32, ALG_SHA3_512: i32;
+declare const FMT_RAW: i32, FMT_PKCS8: i32, FMT_SPKI: i32, FMT_JWK: i32;
 declare const ALG_AES_GCM: i32, ALG_AES_CBC: i32, ALG_AES_CTR: i32, ALG_AES_KW: i32;
 declare const ALG_HMAC: i32, ALG_ECDSA: i32, ALG_ED25519: i32, ALG_ECDH: i32, ALG_X25519: i32, ALG_HKDF: i32, ALG_PBKDF2: i32;
 declare const CURVE_P256: i32, CURVE_P384: i32;

package/std/assembly/toildb.ts

@@ -0,0 +1,311 @@
+// ToilDB: the developer-facing edge-database API.
+//
+// `@database class App { @collection(...) users!: Record<User, UserId>; ... }`
+// declares logical collections; the compiler (see parser `injectDatabaseBinding`)
+// synthesizes a `@global App` singleton whose fields are these typed handles,
+// resolved to numeric host handles once at module init.
+//
+// The handles marshal `@data` keys/values to the `env.data.*` host imports
+// (`bindings/toildb`). Keys and values are `@data` types (they have the injected
+// `encode(): Uint8Array` + `decodeInto(buf): void` instance methods). Both
+// encode and decode go through INSTANCE methods on the generic type parameter,
+// which AssemblyScript resolves at specialization (it cannot call the `decode`
+// static through a type parameter, but `instantiate<V>()` + `v.decodeInto(buf)`
+// works). Value types must be default-constructible.
+
+import { toildbHost } from "bindings/toildb";
+import { DataWriter } from "data";
+
+/// Resolve a `"<db>/<collection>"` name to its numeric host handle. Called once
+/// per collection at module init by the generated `App` binding.
+export function __toildbResolve(name: string): u32 {
+  const nb = Uint8Array.wrap(String.UTF8.encode(name));
+  const out = new Uint8Array(4);
+  toildbHost.resolveCollection(nb.dataStart, nb.byteLength, out.dataStart);
+  return load<u32>(out.dataStart);
+}
+
+/// Pull the last stashed variable-length result of `len` bytes into a buffer.
+function __toildbTake(len: i32): Uint8Array {
+  const buf = new Uint8Array(len);
+  toildbHost.takeResult(buf.dataStart, len);
+  return buf;
+}
+
+/// Pull a stashed result whose length is NOT known up front (e.g. the owner
+/// returned by a failed `claim`): grow the buffer until `take_result` fits.
+function __toildbTakeGrow(): Uint8Array {
+  let cap = 256;
+  let buf = new Uint8Array(cap);
+  let n = toildbHost.takeResult(buf.dataStart, cap);
+  while (n == -1) {
+    cap = cap * 2;
+    buf = new Uint8Array(cap);
+    n = toildbHost.takeResult(buf.dataStart, cap);
+  }
+  return buf.subarray(0, n);
+}
+
+/// A mutable keyed-entity collection (spec 7.1). `V` is the `@data` value type,
+/// `K` the `@data` key type.
+export class Record<V, K> {
+  private __handle: u32;
+
+  constructor(handle: u32) {
+    this.__handle = handle;
+  }
+
+  /// Return the record, or `null` if it does not exist.
+  get(key: K): V | null {
+    const kb = key.encode();
+    const status = toildbHost.get(this.__handle, kb.dataStart, kb.byteLength);
+    if (status < 0) return null;
+    const v = instantiate<V>();
+    v.decodeInto(__toildbTake(status));
+    return v;
+  }
+
+  /// Like `get`, but traps if the record is absent.
+  require(key: K): V {
+    const v = this.get(key);
+    if (v == null) unreachable();
+    return v!;
+  }
+
+  /// Bounded multi-get: one op, one result per key (in order), each the value
+  /// or `null` if absent. The key count is capped by the request budget.
+  getMany(keys: K[]): Array<V | null> {
+    const w = new DataWriter();
+    w.writeU32(<u32>keys.length);
+    for (let i = 0, n = keys.length; i < n; i++) {
+      w.writeBytes(keys[i].encode());
+    }
+    const blob = w.toBytes();
+    const status = toildbHost.getMany(this.__handle, blob.dataStart, blob.byteLength);
+    if (status < 0) unreachable();
+    const out = __toildbTake(status);
+    const results = new Array<V | null>();
+    let off: i32 = 0;
+    const count = load<u32>(out.dataStart + off);
+    off += 4;
+    for (let i: u32 = 0; i < count; i++) {
+      const present = load<u8>(out.dataStart + off);
+      off += 1;
+      if (present == 0) {
+        results.push(null);
+        continue;
+      }
+      const len = <i32>load<u32>(out.dataStart + off);
+      off += 4;
+      const v = instantiate<V>();
+      v.decodeInto(out.subarray(off, off + len));
+      off += len;
+      results.push(v);
+    }
+    return results;
+  }
+
+  /// Whether the record exists.
+  exists(key: K): bool {
+    const kb = key.encode();
+    return toildbHost.exists(this.__handle, kb.dataStart, kb.byteLength) == 1;
+  }
+
+  /// Create the record if absent. Returns false if it already existed.
+  create(key: K, value: V): bool {
+    const kb = key.encode();
+    const vb = value.encode();
+    return toildbHost.create(
+      this.__handle, kb.dataStart, kb.byteLength, vb.dataStart, vb.byteLength, 0
+    ) == 0;
+  }
+
+  /// Apply a write through the key's home cell; returns the stored record.
+  patch(key: K, value: V): V {
+    const kb = key.encode();
+    const vb = value.encode();
+    const status = toildbHost.patch(
+      this.__handle, kb.dataStart, kb.byteLength, vb.dataStart, vb.byteLength, 0
+    );
+    if (status < 0) unreachable();
+    const v = instantiate<V>();
+    v.decodeInto(__toildbTake(status));
+    return v;
+  }
+
+  /// Delete the record (idempotent).
+  delete(key: K): void {
+    const kb = key.encode();
+    toildbHost.del(this.__handle, kb.dataStart, kb.byteLength, 0);
+  }
+
+  /// Atomic fetch-and-delete (consume-once); returns the prior value or `null`.
+  getDelete(key: K): V | null {
+    const kb = key.encode();
+    const status = toildbHost.getDelete(this.__handle, kb.dataStart, kb.byteLength, 0);
+    if (status < 0) return null;
+    const v = instantiate<V>();
+    v.decodeInto(__toildbTake(status));
+    return v;
+  }
+}
+
+/// A precomputed, read-optimized projection (spec 7.2): home pages,
+/// leaderboards, rendered fragments. Read by any function kind; PUBLISHED only
+/// by a `@derive`/`@job` (the host kind gate enforces it). `V` is the `@data`
+/// value type, `K` the `@data` key type.
+export class View<V, K> {
+  private __handle: u32;
+
+  constructor(handle: u32) {
+    this.__handle = handle;
+  }
+
+  /// The published view for `key`, or `null` if none has been published.
+  get(key: K): V | null {
+    const kb = key.encode();
+    const status = toildbHost.viewGet(this.__handle, kb.dataStart, kb.byteLength);
+    if (status < 0) return null;
+    const v = instantiate<V>();
+    v.decodeInto(__toildbTake(status));
+    return v;
+  }
+
+  /// Like `get`, but traps if no view is published.
+  require(key: K): V {
+    const v = this.get(key);
+    if (v == null) unreachable();
+    return v!;
+  }
+
+  /// Publish (overwrite) the view for `key`. Derive/job only; the host assigns
+  /// the version so a later publish always supersedes an earlier one.
+  publish(key: K, value: V): void {
+    const kb = key.encode();
+    const vb = value.encode();
+    toildbHost.viewPublish(
+      this.__handle, kb.dataStart, kb.byteLength, vb.dataStart, vb.byteLength, 0
+    );
+  }
+}
+
+/// The result of a `unique.claim` (spec 8.6). `claimed` is true when the caller
+/// owns the key (a fresh claim or an idempotent re-claim of its own); when
+/// false, `owner` is the value that currently holds the key.
+export class ClaimResult<V> {
+  constructor(public claimed: bool, public owner: V | null) {}
+}
+
+/// A globally-unique claim collection (spec 7.6): username, email, slug, ...
+/// `V` is the `@data` OWNER value type, `K` the `@data` claim-key type.
+export class Unique<V, K> {
+  private __handle: u32;
+
+  constructor(handle: u32) {
+    this.__handle = handle;
+  }
+
+  /// The value that owns `key`, or `null` if unclaimed.
+  lookup(key: K): V | null {
+    const kb = key.encode();
+    const status = toildbHost.uniqueLookup(this.__handle, kb.dataStart, kb.byteLength);
+    if (status < 0) return null;
+    const v = instantiate<V>();
+    v.decodeInto(__toildbTake(status));
+    return v;
+  }
+
+  /// Claim `key` for `value`. Returns whether the caller owns it, and (when
+  /// another owns it) who.
+  claim(key: K, value: V): ClaimResult<V> {
+    const kb = key.encode();
+    const vb = value.encode();
+    const tag = toildbHost.uniqueClaim(
+      this.__handle, kb.dataStart, kb.byteLength, vb.dataStart, vb.byteLength, 0
+    );
+    if (tag < 0) unreachable();
+    if (tag == 1) {
+      // AlreadyClaimed: the current owner is stashed.
+      const owner = instantiate<V>();
+      owner.decodeInto(__toildbTakeGrow());
+      return new ClaimResult<V>(false, owner);
+    }
+    // 0 Claimed, 2 AlreadyOwnedByCaller -> the caller owns it.
+    return new ClaimResult<V>(true, null);
+  }
+
+  /// Release `key` (only the current owner may; a non-owner release traps).
+  release(key: K, value: V): void {
+    const kb = key.encode();
+    const vb = value.encode();
+    toildbHost.uniqueRelease(
+      this.__handle, kb.dataStart, kb.byteLength, vb.dataStart, vb.byteLength, 0
+    );
+  }
+}
+
+/// A commutative integer counter (spec 7.4): likes, view counts, inventory.
+/// `K` is the `@data` key type; the value is a host-aggregated i64 rollup (there
+/// is no `set`, only `add` and `get`, so concurrent deltas never lose writes).
+export class Counter<K> {
+  private __handle: u32;
+
+  constructor(handle: u32) {
+    this.__handle = handle;
+  }
+
+  /// The current sum (0 if no deltas have been applied).
+  get(key: K): i64 {
+    const kb = key.encode();
+    const status = toildbHost.counterGet(this.__handle, kb.dataStart, kb.byteLength);
+    if (status < 0) unreachable();
+    const buf = __toildbTake(status);
+    return load<i64>(buf.dataStart);
+  }
+
+  /// Apply a (possibly negative) delta; saturates at the i64 bounds.
+  add(key: K, delta: i64): void {
+    const kb = key.encode();
+    toildbHost.counterAdd(this.__handle, kb.dataStart, kb.byteLength, delta, 0);
+  }
+}
+
+/// An append-only event log (spec 7.5): activity feeds, audit trails, the
+/// fact stream a `@derive` consumes. `V` is the `@data` event type, `K` the
+/// `@data` stream-key type.
+export class Events<V, K> {
+  private __handle: u32;
+
+  constructor(handle: u32) {
+    this.__handle = handle;
+  }
+
+  /// Append an event to the stream.
+  append(key: K, event: V): void {
+    const kb = key.encode();
+    const eb = event.encode();
+    toildbHost.append(this.__handle, kb.dataStart, kb.byteLength, eb.dataStart, eb.byteLength, 0);
+  }
+
+  /// The newest `limit` events, newest first. Decodes each framed event into a
+  /// `V`. The host frames them as `u32 count` then per event `u32 len + bytes`.
+  latest(key: K, limit: i32): V[] {
+    const kb = key.encode();
+    const status = toildbHost.latest(this.__handle, kb.dataStart, kb.byteLength, limit);
+    if (status < 0) unreachable();
+    const blob = __toildbTake(status);
+    const out = new Array<V>();
+    let off: i32 = 0;
+    const count = load<u32>(blob.dataStart + off);
+    off += 4;
+    for (let i: u32 = 0; i < count; i++) {
+      const len = <i32>load<u32>(blob.dataStart + off);
+      off += 4;
+      const ev = instantiate<V>();
+      ev.decodeInto(blob.subarray(off, off + len));
+      out.push(ev);
+      off += len;
+    }
+    return out;
+  }
+}