toilscript 0.1.57 → 0.1.59

package/dist/web.js

@@ -1,8 +1,8 @@
-var ASSEMBLYSCRIPT_VERSION = "0.1.57";
+var ASSEMBLYSCRIPT_VERSION = "0.1.59";
   var ASSEMBLYSCRIPT_IMPORTMAP = {
   "imports": {
-    "toilscript": "https://cdn.jsdelivr.net/npm/toilscript@0.1.57/dist/toilscript.js",
-    "toilscript/cli": "https://cdn.jsdelivr.net/npm/toilscript@0.1.57/dist/cli.js",
+    "toilscript": "https://cdn.jsdelivr.net/npm/toilscript@0.1.59/dist/toilscript.js",
+    "toilscript/cli": "https://cdn.jsdelivr.net/npm/toilscript@0.1.59/dist/cli.js",
     "binaryen": "https://cdn.jsdelivr.net/npm/binaryen@130.0.0-nightly.20260609/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.57",
+  "version": "0.1.59",
   "author": "Daniel Wirtz <dcode+assemblyscript@dcode.io>",
   "license": "Apache-2.0",
   "homepage": "https://github.com/dacely-cloud/toilscript",

package/std/assembly/bindings/toildb.ts

@@ -71,6 +71,20 @@ export namespace toildbHost {
     idemPtr: usize
   ): i32;
 
+  // record.upsert -> 0 created | 1 updated | 2 @unique-conflict (not written) |
+  // negative error. A single blind last-writer-wins put: creates the row if
+  // absent, overwrites it if present, in ONE op (no create-then-patch round trip).
+  // @ts-ignore: decorator
+  @external("env", "data.upsert")
+  export declare function upsert(
+    handle: u32,
+    keyPtr: usize,
+    keyLen: i32,
+    valPtr: usize,
+    valLen: i32,
+    idemPtr: usize
+  ): i32;
+
   // record.delete -> 0 ok | negative error.
   // @ts-ignore: decorator
   @external("env", "data.delete")

package/std/assembly/toildb.ts

@@ -75,6 +75,18 @@ function __toildbTakeGrow(): Uint8Array {
 /// A mutable keyed-entity collection (spec 7.1). `V` is the `@data` value type,
 /// `K` the `@data` key type.
 @global
+/// The outcome of `Documents.upsert` (spec 8.3). The wire bytes are pinned in the
+/// host ABI (`data.upsert`): a non-negative tag the guest returns as-is.
+export enum UpsertResult {
+  /// The row did not exist and was created.
+  Created = 0,
+  /// The row already existed and was overwritten.
+  Updated = 1,
+  /// A `@unique` field value is already owned by a DIFFERENT record; nothing was
+  /// written (the only outcome an upsert cannot auto-resolve).
+  Conflict = 2,
+}
+
 export class Documents<K, V> {
   private __handle: u32;
 
@@ -158,6 +170,30 @@ export class Documents<K, V> {
     ) == 0;
   }
 
+  /// Create-or-overwrite in ONE op (spec 8.3): a blind last-writer-wins put that
+  /// creates the row if absent or overwrites it if present, replacing the two-op
+  /// `if (!create(k,v)) patch(k,v)` idiom. Returns `UpsertResult.Created` or
+  /// `.Updated`; on a `@unique` collection, `.Conflict` when the value's unique
+  /// field is already held by ANOTHER record (nothing is written).
+  ///
+  /// The write is blind: it stores `value` as-is, so concurrent upserts do not
+  /// conflict or retry - the later one wins and overwrites the earlier. Correct
+  /// for writing a whole value (a profile, a settings blob); wrong for a
+  /// read-modify-write of accumulating state (a balance, a like count), where a
+  /// concurrent write would be lost - use `counter.add` or version-checked
+  /// `patch` there. A lost write is a data-integrity concern, not a boundary one:
+  /// the key is tenant-scoped, so a race is only ever one tenant's own concurrent
+  /// writes, and `@unique` stays race-safe (claim-once at the value's home).
+  upsert(key: K, value: V): UpsertResult {
+    const kb = key.encode();
+    const vb = value.encode();
+    const status = toildbHost.upsert(
+      this.__handle, kb.dataStart, kb.byteLength, vb.dataStart, vb.byteLength, 0
+    );
+    if (status < 0) unreachable();
+    return <UpsertResult>status;
+  }
+
   /// Apply a write through the key's home cell; returns the stored record.
   patch(key: K, value: V): V {
     const kb = key.encode();
@@ -495,6 +531,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).
@@ -520,11 +564,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).
@@ -600,6 +647,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),
@@ -642,7 +696,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++) {
@@ -652,10 +706,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.
@@ -673,7 +727,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

@@ -229,6 +229,16 @@ declare function admin(target: Object, propertyKey: string | symbol, descriptor:
 // User>` and `App.users.get(...)`. Every handle is KEY-FIRST (`<K, V>`, matching
 // `Map`/`Record`). `K`/`V`/`M` are `@data` types (the codec the host marshals).
 
+/** The outcome of `Documents.upsert` (spec 8.3). */
+declare const enum UpsertResult {
+  /** The row did not exist and was created. */
+  Created = 0,
+  /** The row already existed and was overwritten. */
+  Updated = 1,
+  /** A `@unique` field value is already owned by another record; nothing written. */
+  Conflict = 2,
+}
+
 /** A mutable keyed-entity collection (spec 7.1): user profiles, items, sessions. */
 declare class Documents<K, V> {
   get(key: K): V | null;
@@ -237,6 +247,13 @@ declare class Documents<K, V> {
   getMany(keys: K[]): (V | null)[];
   create(key: K, value: V): bool;
   patch(key: K, value: V): V;
+  /** Create-or-overwrite in one op (blind last-writer-wins); replaces the two-op
+   *  `if (!create(k,v)) patch(k,v)` idiom. Right for writing a whole value; wrong
+   *  for read-modify-write of accumulating state (a balance/count), where a
+   *  concurrent write would be lost - use `counter.add` or version-checked
+   *  `patch` there. The key is tenant-scoped, so a race is only ever the same
+   *  tenant's own writes. See {@link UpsertResult}. */
+  upsert(key: K, value: V): UpsertResult;
   delete(key: K): void;
   getDelete(key: K): V | null;
 }
@@ -316,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;
@@ -368,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;