toilscript 0.1.58 → 0.1.60

package/std/assembly/toildb.ts

@@ -72,6 +72,151 @@ function __toildbTakeGrow(): Uint8Array {
   return buf.subarray(0, n);
 }
 
+/// A typed ToilDB failure, the `TDLnnn` diagnostic of spec 27.1. The host bridges
+/// one as `-(1000 + nnn)`; the two small sentinels are NOT failures (`-1` output
+/// buffer too small, `-2` absent), so both decode to `None`.
+///
+/// Only a SUBSET can ever reach guest code. A hard fault (budget/quota, storage,
+/// integrity, capability/schema) is indistinguishable from a benign outcome at the
+/// ABI, so returning it would silently drop the op; the host TRAPS the request
+/// instead and the guest never runs again (toil-backend `status_is_hard_fault`).
+/// The members below say which is which. Every code is still listed, because
+/// `Db.errorOf` decodes any raw status.
+///
+/// So after a read returns `null`, `Db.lastError()` is either `None` (the row is
+/// absent) or one of the four RETRYABLE availability signals. `AlreadyExists` and
+/// `Conflict` are write outcomes, not read ones.
+@global
+export enum DbError {
+  /// No failure: the operation succeeded, or the row was simply absent.
+  None = 0,
+  /// TDL001: the collection handle is not one the host issued. HARD FAULT: traps.
+  InvalidHandle = 1,
+  /// TDL002: wrong tenant, or the row's MAC did not verify. HARD FAULT: traps.
+  TenantMismatch = 2,
+  /// TDL003: a `create` found the key already present. A write outcome.
+  AlreadyExists = 3,
+  /// TDL004: a compare-and-set lost, or a `@unique` value is owned elsewhere. A
+  /// write outcome.
+  Conflict = 4,
+  /// TDL005: the operation is not supported here. HARD FAULT: traps.
+  Unsupported = 5,
+  /// TDL006: the value did not decode against its schema. HARD FAULT: traps.
+  Codec = 6,
+  /// TDL007: an internal storage failure. HARD FAULT: traps.
+  Backend = 7,
+  /// TDL010: the op does not exist for this collection family. HARD FAULT: traps.
+  OpNotAllowedForFamily = 10,
+  /// TDL011: the op is not allowed for this kind, or at this tier. HARD FAULT: traps.
+  OpNotAllowedInKind = 11,
+  /// TDL020: too many ops, or too many keys in one multi-op. HARD FAULT: traps.
+  OpBudget = 20,
+  /// TDL021: the request or its result exceeds the byte budget. HARD FAULT: traps.
+  ByteBudget = 21,
+  /// TDL022: the value nests too deeply. HARD FAULT: traps.
+  DepthBudget = 22,
+  /// TDL025: the tenant is over its plan quota. HARD FAULT: traps, so a guest can
+  /// never observe this. It is here only to decode a raw status.
+  QuotaExceeded = 25,
+  /// TDL030: a backfill is throttling this read. RETRYABLE.
+  FillThrottled = 30,
+  /// TDL031: the home region, or the data, is temporarily unavailable. RETRYABLE.
+  Unavailable = 31,
+  /// TDL040: this key is a hot partition. RETRYABLE.
+  HotPartition = 40,
+  /// TDL041: too many cold reads at once. RETRYABLE.
+  ColdStorm = 41,
+  /// TDL070: the schema is temporarily unavailable. HARD FAULT: traps.
+  SchemaUnavailable = 70,
+  /// TDL090: a catalog op outside an admin context. HARD FAULT: traps.
+  CatalogOutsideAdmin = 90,
+  /// A negative status that carries no known `TDLnnn`.
+  Unknown = -1,
+}
+
+/// The typed failure of the last read that returned `null`/empty. See `Db`.
+// @ts-ignore: decorator
+@lazy
+var __toildbLastError: DbError = DbError.None;
+
+/// Decode a raw host status into a typed failure. Non-negative, `-1` (buffer too
+/// small) and `-2` (absent) are all `None`: only the `<= -1000` band is a failure.
+function __toildbErrorOf(status: i32): DbError {
+  if (status >= -2) return DbError.None;
+  const code = -status - 1000;
+  if (code < 0) return DbError.Unknown;
+  switch (code) {
+    case 1: return DbError.InvalidHandle;
+    case 2: return DbError.TenantMismatch;
+    case 3: return DbError.AlreadyExists;
+    case 4: return DbError.Conflict;
+    case 5: return DbError.Unsupported;
+    case 6: return DbError.Codec;
+    case 7: return DbError.Backend;
+    case 10: return DbError.OpNotAllowedForFamily;
+    case 11: return DbError.OpNotAllowedInKind;
+    case 20: return DbError.OpBudget;
+    case 21: return DbError.ByteBudget;
+    case 22: return DbError.DepthBudget;
+    case 25: return DbError.QuotaExceeded;
+    case 30: return DbError.FillThrottled;
+    case 31: return DbError.Unavailable;
+    case 40: return DbError.HotPartition;
+    case 41: return DbError.ColdStorm;
+    case 70: return DbError.SchemaUnavailable;
+    case 90: return DbError.CatalogOutsideAdmin;
+    default: return DbError.Unknown;
+  }
+}
+
+/// Record the outcome of a read that is about to return `null`. An absent row
+/// records `None`, so `null` + `None` means "not found" and `null` + anything else
+/// means "failed".
+function __toildbMiss(status: i32): void {
+  __toildbLastError = __toildbErrorOf(status);
+}
+
+/// ToilDB diagnostics. Read `lastError()` immediately after a read returns `null`
+/// to tell an absent row from a failed one; the next read overwrites it.
+///
+/// ```ts
+/// const u = App.users.get(id);
+/// if (u == null && Db.isRetryable(Db.lastError())) {
+///   // The row may well exist: the store is briefly unavailable. Retry or 503.
+/// }
+/// ```
+///
+/// ONLY `Documents.get`, `Documents.getDelete`, `View.get` and `Unique.lookup`
+/// record into this. Every other ToilDB op either succeeds or traps. The `Analytics`
+/// reads also answer `null`, but on their own `-2 absent` / `-3 forbidden` statuses
+/// rather than a `TDLnnn`, so they leave `lastError()` untouched: do not consult it
+/// after one, or you will read a stale value from an earlier ToilDB read.
+@global
+export class Db {
+  /// The failure recorded by the most recent read that returned `null`. `None`
+  /// when that read simply found nothing.
+  static lastError(): DbError {
+    return __toildbLastError;
+  }
+
+  /// Decode a raw negative host status into its typed failure.
+  static errorOf(status: i32): DbError {
+    return __toildbErrorOf(status);
+  }
+
+  /// Whether `err` is a transient availability signal, so the same read may well
+  /// succeed later. These are the ONLY failures a read can hand back: everything
+  /// else traps the request before the guest resumes.
+  static isRetryable(err: DbError): bool {
+    return (
+      err == DbError.FillThrottled ||
+      err == DbError.Unavailable ||
+      err == DbError.HotPartition ||
+      err == DbError.ColdStorm
+    );
+  }
+}
+
 /// A mutable keyed-entity collection (spec 7.1). `V` is the `@data` value type,
 /// `K` the `@data` key type.
 @global
@@ -98,7 +243,7 @@ export class Documents<K, V> {
   get(key: K): V | null {
     const kb = key.encode();
     const status = toildbHost.get(this.__handle, kb.dataStart, kb.byteLength);
-    if (status < 0) return null;
+    if (status < 0) { __toildbMiss(status); return null; }
     __toildbResetMigrated();
     const v = instantiate<V>();
     v.decodeInto(__toildbTake(status));
@@ -226,7 +371,7 @@ export class Documents<K, V> {
   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;
+    if (status < 0) { __toildbMiss(status); return null; }
     const v = instantiate<V>();
     v.decodeInto(__toildbTake(status));
     return v;
@@ -249,7 +394,7 @@ export class View<K, V> {
   get(key: K): V | null {
     const kb = key.encode();
     const status = toildbHost.viewGet(this.__handle, kb.dataStart, kb.byteLength);
-    if (status < 0) return null;
+    if (status < 0) { __toildbMiss(status); return null; }
     const v = instantiate<V>();
     v.decodeInto(__toildbTake(status));
     return v;
@@ -295,7 +440,7 @@ export class Unique<K, V> {
   lookup(key: K): V | null {
     const kb = key.encode();
     const status = toildbHost.uniqueLookup(this.__handle, kb.dataStart, kb.byteLength);
-    if (status < 0) return null;
+    if (status < 0) { __toildbMiss(status); return null; }
     const v = instantiate<V>();
     v.decodeInto(__toildbTake(status));
     return v;
@@ -531,6 +676,14 @@ export enum MetricId {
 /// section.
 export const METRIC_COUNTERS: i32 = 42;
 
+/// The sustained-rate window (seconds): requests are metered over a 3-minute ROLLING window. A plan's
+/// sustained request rate `X` (rps) permits `X * BURST_WINDOW_SECS` requests across it. Instantaneous
+/// spikes ABOVE the sustained rate are NOT tier-capped (only the box firewall's global pps ceiling, the
+/// DDoS backstop, applies); throttling (HTTP 429) begins only once the window's allowance is spent.
+/// The window slides continuously rather than resetting on a boundary, so a spend does not become free
+/// all at once: it ages out gradually over the following 3 minutes.
+export const BURST_WINDOW_SECS: i32 = 180;
+
 /// A dashboard time range for `Analytics.series`. Short ranges (1h/6h) read the per-MINUTE ring; the long
 /// ranges (60d/90d) read the per-DAY ring (90-day retention); the rest read the per-HOUR ring (30-day).
 /// Append-only: never renumber (D60/D90 were added after D30, keeping the wire ids stable).
@@ -556,11 +709,14 @@ export class TenantStats {
   /// Live gauges (current level, not a total).
   connectedStreams: u64 = 0;
   committedMemory: u64 = 0;
-  /// Request windows: current bucket usage + plan cap (0 = unlimited).
-  reqMinuteUsed: u64 = 0;
-  reqMinuteCap: u64 = 0;
-  reqDayUsed: u64 = 0;
-  reqDayCap: u64 = 0;
+  /// Request meters (fleet-global, across every edge location) against the plan (cap 0 = unmetered).
+  /// Burst: requests in the trailing 3-minute ROLLING window vs its allowance
+  /// (`sustained_rps * BURST_WINDOW_SECS`). 30d: requests in the current 30-day bucket vs the quota
+  /// (the quota still tumbles: it is a billing period, not a rate).
+  reqBurstUsed: u64 = 0;
+  reqBurstCap: u64 = 0;
+  req30dUsed: u64 = 0;
+  req30dCap: u64 = 0;
   /// LIVE per-second gauges (rates), computed edge-side from the last completed minute bucket so the
   /// guest is STATELESS (no client diffing of two snapshots). Idle -> 0.0. `f64` (a rate is fractional
   /// and bounded; f64 cannot overflow for any real value).
@@ -636,6 +792,13 @@ export class TenantStats {
     const total = hits + this.cacheMisses;
     return total > 0 ? <f64>hits / <f64>total : 0.0;
   }
+
+  /// The plan's SUSTAINED request rate (requests/second), derived from the 3-minute burst cap
+  /// (`reqBurstCap / BURST_WINDOW_SECS`). 0.0 means unmetered. Spikes above this rate are allowed;
+  /// throttling only starts once `reqBurstUsed` passes `reqBurstCap` in the current bucket.
+  get sustainedRpsCap(): f64 {
+    return this.reqBurstCap == 0 ? 0.0 : <f64>this.reqBurstCap / <f64>BURST_WINDOW_SECS;
+  }
 }
 
 /// One metric's time series for a range: `points` oldest→newest (per-bucket totals, `u64` — non-negative),
@@ -678,7 +841,7 @@ export class Analytics {
     const r = new DataReader(buf);
     const stats = new TenantStats();
     const version = r.readU16();
-    if (version < 2) return stats; // pre-v2 edge: refuse rather than mis-decode
+    if (version < 3) return stats; // pre-v3 edge: refuse rather than mis-decode (clean break, no v2)
     stats.nowMs = r.readU64();
     const count = <i32>r.readU32();
     for (let i: i32 = 0; i < count && r.ok; i++) {
@@ -688,10 +851,10 @@ export class Analytics {
     }
     stats.connectedStreams = r.readU64();
     stats.committedMemory = r.readU64();
-    stats.reqMinuteUsed = r.readU64();
-    stats.reqMinuteCap = r.readU64();
-    stats.reqDayUsed = r.readU64();
-    stats.reqDayCap = r.readU64();
+    stats.reqBurstUsed = r.readU64();
+    stats.reqBurstCap = r.readU64();
+    stats.req30dUsed = r.readU64();
+    stats.req30dCap = r.readU64();
     // LIVE per-second rates (f64), appended after the windows. VERSION-GATE by LENGTH: a pre-rates
     // (shorter) frame from an older edge exhausts the buffer here, so `readF64` returns 0.0 for each
     // missing rate (DataReader is bounds-checked). No frame-version bump needed.
@@ -709,7 +872,7 @@ export class Analytics {
     const r = new DataReader(buf);
     const out = new Series();
     const version = r.readU16();
-    if (version < 2) return out;
+    if (version < 3) return out; // pre-v3 edge: refuse rather than mis-decode (clean break, no v2)
     out.metric = <MetricId>r.readU16();
     out.bucketSecs = r.readU32();
     out.headMs = r.readU64();

package/std/assembly/toilscript.d.ts

@@ -333,9 +333,14 @@ declare const enum AnalyticsRange {
   H1 = 0, H6 = 1, H12 = 2, H24 = 3, D3 = 4, D7 = 5, D14 = 6, D30 = 7, D60 = 8, D90 = 9,
 }
 
+/** The sustained-rate window (seconds): requests are metered over a 3-minute ROLLING window, so a plan's
+ *  sustained rate `X` (rps) permits `X * BURST_WINDOW_SECS` requests across it. */
+declare const BURST_WINDOW_SECS: i32;
+
 /** One tenant's analytics snapshot: lifetime totals (indexed by `MetricId`, no string keys), the two
- *  live gauge levels, and the request windows (current usage + plan cap; cap 0 = unlimited). Read a
- *  value by typed getter (`stats.requests`) or by id (`stats.metric(MetricId.Requests)`). */
+ *  live gauge levels, and the request meters (burst 3-min bucket + 30-day quota, each with its cap;
+ *  cap 0 = unmetered). Read a value by typed getter (`stats.requests`) or by id
+ *  (`stats.metric(MetricId.Requests)`). */
 declare class TenantStats {
   metric(id: MetricId): u64;
   readonly requests: u64;
@@ -385,10 +390,15 @@ declare class TenantStats {
   readonly cacheRatio: f64;
   connectedStreams: u64;
   committedMemory: u64;
-  reqMinuteUsed: u64;
-  reqMinuteCap: u64;
-  reqDayUsed: u64;
-  reqDayCap: u64;
+  /** Fleet-global requests in the trailing 3-minute ROLLING window, and its allowance
+   *  (`sustained_rps * BURST_WINDOW_SECS`; 0 = unmetered). Spikes are NOT tier-capped. */
+  reqBurstUsed: u64;
+  reqBurstCap: u64;
+  /** Fleet-global requests in the current 30-day tumbling bucket, and the 30-day quota (0 = unmetered). */
+  req30dUsed: u64;
+  req30dCap: u64;
+  /** Derived: the plan's SUSTAINED request rate (`reqBurstCap / BURST_WINDOW_SECS`), 0.0 when unmetered. */
+  readonly sustainedRpsCap: f64;
   /** LIVE per-second gauges (rates), computed edge-side from the last completed minute bucket (idle 0.0),
    *  so no client diffing is needed. `f64` cannot overflow for any real value. */
   readonly rps: f64;
@@ -431,6 +441,120 @@ declare class Analytics {
   static listSites(cursor?: string, limit?: i32): SiteList;
 }
 
+/**
+ * A typed ToilDB failure (`TDLnnn`, spec 27.1). A read that returns `null` either
+ * found nothing (`Db.lastError() == DbError.None`) or hit one of the four RETRYABLE
+ * availability signals. A HARD FAULT never reaches guest code: the host traps the
+ * request rather than hand back a status the ABI would mistake for a benign result.
+ */
+declare const enum DbError {
+  None = 0,
+  /** TDL001. Hard fault: traps. */ InvalidHandle = 1,
+  /** TDL002. Hard fault: traps. */ TenantMismatch = 2,
+  /** TDL003. A write outcome. */ AlreadyExists = 3,
+  /** TDL004. A write outcome. */ Conflict = 4,
+  /** TDL005. Hard fault: traps. */ Unsupported = 5,
+  /** TDL006. Hard fault: traps. */ Codec = 6,
+  /** TDL007. Hard fault: traps. */ Backend = 7,
+  /** TDL010. Hard fault: traps. */ OpNotAllowedForFamily = 10,
+  /** TDL011. Hard fault: traps. */ OpNotAllowedInKind = 11,
+  /** TDL020. Hard fault: traps. */ OpBudget = 20,
+  /** TDL021. Hard fault: traps. */ ByteBudget = 21,
+  /** TDL022. Hard fault: traps. */ DepthBudget = 22,
+  /** TDL025. Hard fault: traps, so a guest never observes it. */ QuotaExceeded = 25,
+  /** TDL030. Retryable. */ FillThrottled = 30,
+  /** TDL031. Retryable. */ Unavailable = 31,
+  /** TDL040. Retryable. */ HotPartition = 40,
+  /** TDL041. Retryable. */ ColdStorm = 41,
+  /** TDL070. Hard fault: traps. */ SchemaUnavailable = 70,
+  /** TDL090. Hard fault: traps. */ CatalogOutsideAdmin = 90,
+  /** A negative status carrying no known `TDLnnn`. */ Unknown = -1,
+}
+
+/** ToilDB diagnostics: tell an absent row from a failed read. */
+declare class Db {
+  /** The failure recorded by the most recent read that returned `null`. */
+  static lastError(): DbError;
+  /** Decode a raw negative host status into its typed failure. */
+  static errorOf(status: i32): DbError;
+  /** Whether `err` is a transient availability signal worth retrying. */
+  static isRetryable(err: DbError): bool;
+}
+
+// The daemon (L4 cold box) scheduler surface is an ambient global, like the
+// ToilDB handles above (`std/assembly/daemon`). It resolves ONLY inside a
+// `@daemon` cold box: its host imports live in the `daemon` wasm module, which a
+// request handler's module does not get.
+
+/** A typed daemon failure. Positive values are the host's u16 subsystem codes. */
+declare const enum DaemonError {
+  None = 0,
+  /** This node does not hold the lease; the host refused without acting. */
+  NotLeader = 0x0401,
+  /** The lease was lost while the call was in flight. */
+  LeaseLost = 0x0402,
+  /** The outbound request did not complete (SSRF guard, timeout, transport). */
+  CallFailed = 0x0405,
+  /** The response did not fit the buffer. The call ALREADY happened: do not retry. */
+  ResponseTooLarge = -1,
+  /** A request over a host cap (nothing sent), or a malformed response envelope. */
+  BadEnvelope = -2,
+  /** A negative status outside every band above. */
+  Unknown = -3,
+}
+
+/** One `name: value` header of an outbound request or an inbound response. */
+declare class DaemonHttpHeader {
+  name: string;
+  value: string;
+  constructor(name: string, value: string);
+}
+
+/** An outbound HTTP request. `url` must be an absolute `http(s)` URL. */
+declare class DaemonHttpRequest {
+  method: string;
+  url: string;
+  headers: DaemonHttpHeader[];
+  body: Uint8Array;
+  constructor(method?: string, url?: string);
+  /** Append a header. Returns `this` so calls chain. */
+  header(name: string, value: string): DaemonHttpRequest;
+  /** The wire envelope, or `null` when a field breaks a host cap. */
+  encode(): Uint8Array | null;
+}
+
+/** An inbound HTTP response. `status` is 0 when the host failed before a reply. */
+declare class DaemonHttpResponse {
+  status: u16;
+  headers: DaemonHttpHeader[];
+  body: Uint8Array;
+  /** A header's value (case-sensitive, first match), or `null`. */
+  header(name: string): string | null;
+  /** The body decoded as UTF-8. */
+  text(): string;
+  static decode(buf: Uint8Array, len: i32): DaemonHttpResponse | null;
+}
+
+/** The daemon scheduler surface, available inside a `@daemon` class. */
+declare class Daemon {
+  /** Whether THIS node currently holds the lease. A snapshot: re-check it. */
+  static isLeader(): bool;
+  /** The monotonic fencing token, or -1 when this node does not hold the lease. */
+  static epoch(): i64;
+  /** The number of registered `@scheduled` tasks. */
+  static taskCount(): i32;
+  /** The next fire time for `taskId` in epoch ms, or -1 when it never fires. */
+  static nextFireMs(taskId: i32): i64;
+  /** Let the host observe a lost lease. `None` means still leader. */
+  static yieldNow(): DaemonError;
+  /** Park for `ms` (host-clamped to 3s). `LeaseLost` means the task should stop. */
+  static sleep(ms: i64): DaemonError;
+  /** Make an outbound HTTP request, or `null` on failure (see `lastError()`). */
+  static httpCall(request: DaemonHttpRequest, responseCap?: i32): DaemonHttpResponse | null;
+  /** The failure recorded by the most recent `Daemon` call. */
+  static lastError(): DaemonError;
+}
+
 // Big integers, native globals implemented in std/assembly/bignum. The
 // arithmetic/bitwise/comparison operators
 // (+ - * / % & | ^ << >> == != < > <= >=) are operator overloads resolved by