@forgezero/runtime 0.1.8 → 0.1.10

package/dist/audit.d.ts

@@ -74,6 +74,8 @@ export interface AuditRecord extends AuditEntry {
     /** The previous record's `digest`, or `GENESIS_DIGEST` for the first. */
     previousDigest: string;
     digest: string;
+    /** Explicit because one realm may span locked (plain) and unlocked (sealed) periods. */
+    digestMode?: 'sha256' | 'hmac-sha256-v1';
 }
 /**
  * The bytes that get hashed.
@@ -111,6 +113,7 @@ export interface AuditStore {
 }
 export interface AppendOptions {
     digester?: Digester;
+    digestMode?: AuditRecord['digestMode'];
     now?: () => number;
 }
 /**
@@ -137,6 +140,12 @@ export interface ChainVerdict {
     reason?: AuditChainError['code'];
     message?: string;
 }
+export type AuditDigesterResolver = (record: AuditRecord) => Digester | Promise<Digester>;
+export interface AuditVerifyOptions {
+    digester?: Digester;
+    digesterForRecord?: AuditDigesterResolver;
+    expectGenesis?: boolean;
+}
 /**
  * Walk a chain and report the FIRST break.
  *
@@ -150,10 +159,7 @@ export interface ChainVerdict {
  * predecessor; a full chain that does not start at genesis has been truncated
  * from the front, which is exactly the deletion this is meant to catch.
  */
-export declare function verifyChain(records: readonly AuditRecord[], options?: {
-    digester?: Digester;
-    expectGenesis?: boolean;
-}): Promise<ChainVerdict>;
+export declare function verifyChain(records: readonly AuditRecord[], options?: AuditVerifyOptions): Promise<ChainVerdict>;
 export interface AuditExport {
     realm?: string;
     fromSequence: number;
@@ -181,7 +187,7 @@ export declare function exportRange(store: AuditStore, args: {
     realm?: string;
     fromSequence: number;
     toSequence: number;
-}, options?: AppendOptions): Promise<AuditExport>;
+}, options?: AppendOptions & Pick<AuditVerifyOptions, 'digesterForRecord'>): Promise<AuditExport>;
 /**
  * Check an export against the anchor somebody kept.
  *
@@ -192,6 +198,7 @@ export declare function exportRange(store: AuditStore, args: {
  */
 export declare function verifyExport(slice: AuditExport, options?: {
     digester?: Digester;
+    digesterForRecord?: AuditDigesterResolver;
     expectSealDigest?: string;
 }): Promise<ChainVerdict>;
 /**
@@ -215,6 +222,15 @@ export interface EffectAuditRecord {
 }
 export interface AuditChainOptions extends AppendOptions {
     store: AuditStore;
+    /** Selects a digest at append time, allowing locked/plain and unlocked/sealed records in one chain. */
+    digesterForEntry?: (entry: AuditEntry) => Promise<Required<Pick<AppendOptions, 'digester' | 'digestMode'>>>;
+    /** Selects the verifier from the record's authenticated mode marker. */
+    digesterForRecord?: AuditDigesterResolver;
+    /** Retry only a store-declared optimistic sequence collision, never arbitrary failures. */
+    retryAppend?: {
+        attempts: number;
+        conflict(error: unknown): boolean;
+    };
     /** Called when an append fails. Silence here is how a trail dies unnoticed. */
     onError?: (error: unknown, entry: AuditEntry) => void;
 }

package/dist/audit.js

@@ -323,7 +323,7 @@ class AuditChainError extends Error {
 var GENESIS_DIGEST = "0".repeat(64);
 function canonicalise(record) {
   const detail = record.detail ? Object.keys(record.detail).sort().map((key) => `${key}=${String(record.detail[key])}`).join("\x1F") : "";
-  return [
+  const fields = [
     record.sequence,
     record.previousDigest,
     record.atMs,
@@ -335,7 +335,10 @@ function canonicalise(record) {
     record.targetKey ?? "",
     record.reason ?? "",
     detail
-  ].join("\x1E");
+  ];
+  if (record.digestMode !== undefined)
+    fields.push(record.digestMode);
+  return fields.join("\x1E");
 }
 var hashDigester = (input) => sha256(input);
 var sealedDigester = (key) => {
@@ -351,7 +354,8 @@ async function appendRecord(store, entry, options = {}) {
     ...entry,
     sequence: (previous?.sequence ?? 0) + 1,
     atMs: (options.now ?? Date.now)(),
-    previousDigest: previous?.digest ?? GENESIS_DIGEST
+    previousDigest: previous?.digest ?? GENESIS_DIGEST,
+    ...options.digestMode ? { digestMode: options.digestMode } : {}
   };
   const record = { ...unsigned, digest: await digester(canonicalise(unsigned)) };
   await store.append(record);
@@ -393,7 +397,8 @@ async function verifyChain(records, options = {}) {
         };
       }
     }
-    const expected = await digester(canonicalise(record));
+    const recordDigester = options.digesterForRecord ? await options.digesterForRecord(record) : digester;
+    const expected = await recordDigester(canonicalise(record));
     if (!timingSafeEqual(expected, record.digest)) {
       return {
         ok: false,
@@ -418,6 +423,7 @@ async function exportRange(store, args, options = {}) {
   }
   const verdict = await verifyChain(records, {
     digester,
+    digesterForRecord: options.digesterForRecord,
     expectGenesis: args.fromSequence <= 1
   });
   if (!verdict.ok) {
@@ -437,6 +443,7 @@ async function verifyExport(slice, options = {}) {
   const digester = options.digester ?? hashDigester;
   const verdict = await verifyChain(slice.records, {
     digester,
+    digesterForRecord: options.digesterForRecord,
     expectGenesis: slice.anchorDigest === GENESIS_DIGEST
   });
   if (!verdict.ok)
@@ -475,13 +482,30 @@ function createAuditChain(options) {
   const digester = options.digester ?? hashDigester;
   const queue = createQueue();
   const enqueue = (realm, run) => queue.run(realm ?? "\x00platform", run).result;
+  const append = (entry) => enqueue(entry.realm, async () => {
+    const attempts = Math.max(1, Math.min(options.retryAppend?.attempts ?? 1, 32));
+    for (let attempt = 0;attempt < attempts; attempt += 1) {
+      const selected = options.digesterForEntry ? await options.digesterForEntry(entry) : { digester, digestMode: options.digestMode };
+      try {
+        return await appendRecord(options.store, entry, { ...options, ...selected });
+      } catch (error) {
+        if (attempt + 1 >= attempts || !options.retryAppend?.conflict(error))
+          throw error;
+      }
+    }
+    throw new Error("audit: append retry exhausted");
+  });
   return {
-    append: (entry) => enqueue(entry.realm, () => appendRecord(options.store, entry, { ...options, digester })),
+    append,
     verify: async (realm, fromSequence = 1, toSequence = Number.MAX_SAFE_INTEGER) => {
       const records = await options.store.range(realm, fromSequence, toSequence);
-      return verifyChain(records, { digester, expectGenesis: fromSequence <= 1 });
+      return verifyChain(records, {
+        digester,
+        digesterForRecord: options.digesterForRecord,
+        expectGenesis: fromSequence <= 1
+      });
     },
-    export: (args) => exportRange(options.store, args, { ...options, digester }),
+    export: (args) => exportRange(options.store, args, { ...options, digester, digesterForRecord: options.digesterForRecord }),
     sink: {
       write(record) {
         const entry = {
@@ -498,7 +522,7 @@ function createAuditChain(options) {
           },
           ...record.outcome === "denied" && record.code ? { reason: record.code } : {}
         };
-        enqueue(record.realm, () => appendRecord(options.store, entry, { ...options, digester })).catch((error) => options.onError?.(error, entry));
+        append(entry).catch((error) => options.onError?.(error, entry));
       }
     }
   };

package/dist/jobs.d.ts

@@ -85,6 +85,13 @@ export interface JobContext {
     holdsLock(): Promise<boolean>;
     log(message: string, detail?: Record<string, unknown>): void;
 }
+export declare class JobFenceLostError extends Error {
+    constructor();
+}
+/** Check/renew the distributed fence immediately before one mutation. */
+export declare function withJobFence<T>(context: JobContext, mutate: () => Promise<T>): Promise<T>;
+/** Sequential mutation helper; a lost fence stops before the next item is touched. */
+export declare function forEachFenced<T>(context: JobContext, items: Iterable<T>, mutate: (item: T, index: number) => Promise<void>): Promise<void>;
 export interface JobResult {
     /** A resolved run may still report an operational failure without throwing. */
     ok?: boolean;

package/dist/jobs.js

@@ -410,6 +410,27 @@ function storeLock(store, clock = systemClock) {
     release: (key, fence) => store.clear(key, fence)
   };
 }
+
+class JobFenceLostError extends Error {
+  constructor() {
+    super("job: distributed lease was lost; refusing further mutation");
+    this.name = "JobFenceLostError";
+  }
+}
+async function withJobFence(context, mutate) {
+  if (context.signal.aborted)
+    throw context.signal.reason ?? new Error("job: aborted");
+  if (!await context.holdsLock())
+    throw new JobFenceLostError;
+  return mutate();
+}
+async function forEachFenced(context, items, mutate) {
+  let index = 0;
+  for (const item of items) {
+    await withJobFence(context, () => mutate(item, index));
+    index += 1;
+  }
+}
 function defineJob(spec) {
   if (!spec.key.trim())
     throw new Error("A job needs a key — it is the lock key and the report key.");
@@ -460,12 +481,29 @@ function createScheduler(options) {
     const report = reports.get(job.key);
     const leaseMs = job.leaseMs ?? (job.every ? everyMs(job.every) * 4 : 60000);
     let lease;
+    let leaseHeld = true;
+    let renewTimer;
     if (!job.unlocked) {
       lease = await lock.acquire(job.key, leaseMs);
       if (!lease) {
         report.skippedLocked += 1;
         return;
       }
+      const renewEveryMs = Math.max(1, Math.floor(leaseMs / 3));
+      const scheduleRenewal = () => {
+        renewTimer = setTimeout(async () => {
+          if (!lease || !leaseHeld)
+            return;
+          try {
+            leaseHeld = await lock.renew(job.key, lease.fence, leaseMs);
+          } catch {
+            leaseHeld = false;
+          }
+          if (leaseHeld)
+            scheduleRenewal();
+        }, renewEveryMs);
+      };
+      scheduleRenewal();
     }
     report.state = "running";
     report.lastStartedAtMs = clock.now();
@@ -473,7 +511,18 @@ function createScheduler(options) {
     try {
       const result = await job.run({
         signal: controller.signal,
-        holdsLock: async () => lease ? lock.renew(job.key, lease.fence, leaseMs) : true,
+        holdsLock: async () => {
+          if (!lease)
+            return true;
+          if (!leaseHeld)
+            return false;
+          try {
+            leaseHeld = await lock.renew(job.key, lease.fence, leaseMs);
+          } catch {
+            leaseHeld = false;
+          }
+          return leaseHeld;
+        },
         log: (message, detail) => options.onLog?.(job.key, message, detail)
       });
       report.lastResult = result ?? undefined;
@@ -491,6 +540,8 @@ function createScheduler(options) {
       report.consecutiveFailures += 1;
       options.onError?.(job.key, error);
     } finally {
+      if (renewTimer)
+        clearTimeout(renewTimer);
       report.runs += 1;
       report.lastFinishedAtMs = clock.now();
       report.lastDurationMs = clock.now() - startedAt;
@@ -644,13 +695,16 @@ function cursorJob(spec) {
 }
 var VERSION = "0.1.0";
 export {
+  withJobFence,
   systemClock,
   storeLock,
   nextWallClockAt,
   memoryLock,
+  forEachFenced,
   everyMs,
   defineJob,
   cursorJob,
   createScheduler,
-  VERSION
+  VERSION,
+  JobFenceLostError
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgezero/runtime",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "type": "module",
   "publishConfig": {
     "access": "public",
@@ -190,7 +190,7 @@
     "prepublishOnly": "bun ../tools/package-task.ts prepublish runtime"
   },
   "dependencies": {
-    "@forgezero/access": "^0.1.4"
+    "@forgezero/access": "^0.1.6"
   },
   "peerDependencies": {
     "@noble/ciphers": "^2.2.0",