@jarenjs/contract 0.72.2 → 0.73.0

package/docs/CONTRACT-FORMAT.md

@@ -998,7 +998,9 @@ The `ref` a `new` claim hands back is `{ id, generation }` — the
 record's id and the **generation** the claim minted for it — and is
 portable: it names the record across processes rather than holding it.
 A settlement is fenced by both: `commit`/`fail` settle the record whose
-`id` AND `generation` the ref names while it is still `started`, and a
+`id` AND `generation` the ref names while it is still `started` and its
+`expiresAt` is greater than the settlement instant. Expiry is checked by
+the settlement itself, without waiting for a lookup or sweep. A
 ref whose record expired, was reclaimed under a newer generation, or was
 settled already is refused with `JC1011` (thrown or rejected) — the
 binding reports it to `onError` and the response still goes out, so a
@@ -1114,8 +1116,8 @@ export function createSqliteLedger(path, { ttlMs = 86_400_000, now: clock = Date
   const put = db.prepare("INSERT INTO ledger (id, generation, op, scope, key, hash, status, createdAt, updatedAt, expiresAt) VALUES (?, ?, ?, ?, ?, ?, 'started', ?, ?, ?)");
   const drop = db.prepare('DELETE FROM ledger WHERE id = ?');
   // the fence: a settlement names the id AND the generation of the claim
-  // that started the record, so a ref of an earlier claim matches no row
-  const settle = db.prepare("UPDATE ledger SET status = ?, response = ?, retryable = ?, updatedAt = ? WHERE id = ? AND generation = ? AND status = 'started'");
+  // that started the record, and the record must still be unexpired
+  const settle = db.prepare("UPDATE ledger SET status = ?, response = ?, retryable = ?, updatedAt = ? WHERE id = ? AND generation = ? AND status = 'started' AND expiresAt > ?");
   const reap = db.prepare('DELETE FROM ledger WHERE expiresAt <= ?');
   const stored = (row) => (row.response === null ? null : JSON.parse(row.response));
   const at = (now) => (typeof now === 'number' ? now : clock());
@@ -1147,10 +1149,12 @@ export function createSqliteLedger(path, { ttlMs = 86_400_000, now: clock = Date
       }
     },
     commit(ref, response, now) {
-      settled(ref, settle.run('committed', JSON.stringify(response), null, at(now), (ref)?.id ?? '', (ref)?.generation ?? '').changes);
+      const time = at(now);
+      settled(ref, settle.run('committed', JSON.stringify(response), null, time, (ref)?.id ?? '', (ref)?.generation ?? '', time).changes);
     },
     fail(ref, retryable, response, now) {
-      settled(ref, settle.run('failed', response === undefined ? null : JSON.stringify(response), retryable === true ? 1 : 0, at(now), (ref)?.id ?? '', (ref)?.generation ?? '').changes);
+      const time = at(now);
+      settled(ref, settle.run('failed', response === undefined ? null : JSON.stringify(response), retryable === true ? 1 : 0, time, (ref)?.id ?? '', (ref)?.generation ?? '', time).changes);
     },
     lookup({ op, scope, key, now }) {
       const row = (one.get(ledgerId(op, scope, key)));
@@ -2395,7 +2399,7 @@ no-store`, `x-jaren-trace`. Events, in order:
 - `end` — data `{ "reason": "closed" | "server-shutdown" }`.
 
 `seq` is strictly increasing per stream; a violation is the client's
-`JC2092`. An emission whose serialized patch exceeds
+`JC2092`. An emission whose serialized patch's UTF-8 byte length exceeds
 `policy.stream.maxPatchBytes` is replaced by a fresh `snapshot` event
 at that emission's seq — the consumer swaps its document instead of
 patching it; nothing is dropped.
@@ -2423,10 +2427,11 @@ informational, never an outcome).
 **Bounds.** `serveHttp`/`servePort` take `streamLimits: { replay: {
 limit, maxBytes }, queue: { events, bytes } }` (defaults 256 / 1 MiB
 for both): a replay page asks for at most `replay.limit` emissions and
-`replay.maxBytes` serialized patch bytes; the undelivered queue — the
-events that arrived while a carrier write was pending or a page was
+`replay.maxBytes` serialized patch bytes, measured in UTF-8; the undelivered
+queue — the events that arrived while a carrier write was pending or a page was
 loading, the SSE text or port frame as it will go on the wire — holds
-at most `queue.events` frames and `queue.bytes` bytes, each charged
+at most `queue.events` frames and `queue.bytes` UTF-8 bytes (the JSON
+encoding of a port frame), each charged
 until its write settled. When the next event would cross either bound
 the stream ends with the terminal `error` event `JC2096` (`kind:
 network`, retryable — the consumer reads slower than the source

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/contract",
   "private": false,
-  "version": "0.72.2",
+  "version": "0.73.0",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -102,9 +102,9 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.72.2",
-    "@jarenjs/json": "^0.72.2",
-    "@jarenjs/validate": "^0.72.2",
-    "@jarenjs/emit": "^0.72.2"
+    "@jarenjs/core": "^0.73.0",
+    "@jarenjs/json": "^0.73.0",
+    "@jarenjs/validate": "^0.73.0",
+    "@jarenjs/emit": "^0.73.0"
   }
 }

package/src/ledger.js

@@ -162,12 +162,14 @@ export function createMemoryLedger(options = {}) {
   /**
    * The started record a ref settles, or the `JC1011` refusal.
    * @param {unknown} ref
+   * @param {number} at - The settlement instant, also used for updatedAt
    * @returns {LedgerRecord}
    */
-  function settling(ref) {
+  function settling(ref, at) {
     const r = /** @type {any} */ (ref);
     const record = r !== null && typeof r === 'object' && typeof r.id === 'string' ? records.get(r.id) : undefined;
-    if (record === undefined || record.generation !== r.generation || record.status !== 'started') throw staleSettlement(ref);
+    if (record === undefined || record.generation !== r.generation || record.status !== 'started'
+      || record.expiresAt <= at) throw staleSettlement(ref);
     return record;
   }
 
@@ -194,18 +196,20 @@ export function createMemoryLedger(options = {}) {
       return { state: 'new', ref: Object.freeze({ id, generation }) };
     },
     commit(ref, response, now = undefined) {
-      const record = settling(ref);
+      const at = instant(now);
+      const record = settling(ref, at);
       record.status = 'committed';
       record.response = response;
       record.retryable = null;
-      record.updatedAt = instant(now);
+      record.updatedAt = at;
     },
     fail(ref, retryable, response, now = undefined) {
-      const record = settling(ref);
+      const at = instant(now);
+      const record = settling(ref, at);
       record.status = 'failed';
       record.retryable = retryable === true;
       record.response = response === undefined ? null : response;
-      record.updatedAt = instant(now);
+      record.updatedAt = at;
     },
     lookup({ op, scope, key, now = undefined }) {
       const record = records.get(ledgerId(op, scope, key));

package/src/port/serve.js

@@ -21,6 +21,7 @@
  */
 
 import { compileMessageCatalog } from '@jarenjs/core/message';
+import { utf8ByteLength } from '@jarenjs/core/string';
 
 import { ContractHostError, ContractFailure } from '../errors.js';
 import { validateOperationInput, settleOperation, safeTrace, PORT_LOCAL_ERRORS, classifyDeclared } from '../pipeline.js';
@@ -503,8 +504,8 @@ export function servePort(contract, handlers, options) {
           return pushFrame(id, 'error', seq, wireError(code, renderMessage(catalog, row.msgid, { op: opId }), trace, undefined, row.retryable));
         },
         end: (reason, seq) => pushFrame(id, 'end', seq, { reason }),
-        // the byte account is the frame as posted: its JSON text
-        size: (frame) => JSON.stringify(frame).length,
+        // Account for the UTF-8 encoding of the posted frame's JSON text.
+        size: (frame) => utf8ByteLength(JSON.stringify(frame)),
         write: (frame) => post(frame, pushCtx),
         done: () => {
           streams.delete(id);

package/src/stream/server.js

@@ -53,6 +53,7 @@
 import { toPromise, isThenable } from '@jarenjs/core/function';
 import { createAwaitedSink } from '@jarenjs/core/async';
 import { isJsonValue } from '@jarenjs/core/object';
+import { utf8ByteLength } from '@jarenjs/core/string';
 
 import { verdict } from '../http/wire.js';
 
@@ -337,7 +338,7 @@ function pageFault(page, after, bounds) {
       if (item.kind !== 'patch') return `replay item ${i} is not { patch, seq }`;
       if (item.seq <= last) return `replay item ${i} does not advance the seq (${item.seq} after ${last})`;
       last = item.seq;
-      bytes += JSON.stringify(item.patch).length;
+      bytes += utf8ByteLength(JSON.stringify(item.patch));
       if (bytes > bounds.maxBytes) return `a replay page holds ${bytes} patch bytes over the ${bounds.maxBytes} asked for`;
     }
     if (p.next !== undefined && p.items.length > 0 && p.next < last) return 'a replay page\'s next is below its last item';
@@ -617,7 +618,7 @@ export function runSubscription(route, sub, hooks, options) {
       return;
     }
     if (item.seq <= lastSeq && lastSeq !== 0) return; // already delivered, or reflected by a snapshot
-    if (maxPatchBytes !== null && JSON.stringify(item.patch).length > maxPatchBytes) {
+    if (maxPatchBytes !== null && utf8ByteLength(JSON.stringify(item.patch)) > maxPatchBytes) {
       // the consumer swaps its document instead of patching it (§18.1)
       emitSnapshot(item.seq, { reset: false, earliestAvailable: null, highWatermark: null });
       return;