@lssm/lib.contracts-runtime-core 3.0.1

package/dist/native/engine/maintenance.js

@@ -0,0 +1,36 @@
+// src/engine/maintenance.ts
+function createMaintenance(deps) {
+  return {
+    async collectGarbage() {
+      const ts = deps.now();
+      let evicted = 0;
+      for (const entry of await deps.cache.entries()) {
+        if (entry.expiresAt !== undefined && ts >= entry.expiresAt) {
+          await deps.cache.remove(entry.key);
+          evicted += 1;
+        }
+      }
+      deps.events.emit({ type: "gc-collected", evicted });
+      return evicted;
+    },
+    async revalidateStale() {
+      const revalidate = deps.revalidate;
+      if (revalidate === undefined)
+        return 0;
+      const ts = deps.now();
+      let count = 0;
+      for (const entry of await deps.cache.entries()) {
+        const stale = entry.staleAt !== undefined && ts >= entry.staleAt;
+        if (!stale || entry.envelope === undefined)
+          continue;
+        await revalidate(entry.envelope);
+        deps.events.emit({ type: "revalidated", key: entry.key });
+        count += 1;
+      }
+      return count;
+    }
+  };
+}
+export {
+  createMaintenance
+};

package/dist/native/engine/mutation-engine.js

@@ -0,0 +1,360 @@
+// src/engine/mutation-engine.ts
+import {
+  mergeSafeEconomicEvidenceRefIds,
+  parseSafeEconomicEvidenceRefId
+} from "@lssm/lib.contracts-spec/operations";
+import { defaultConflictPolicy as defaultConflictPolicy2 } from "@lssm/lib.contracts-spec/query/conflict-policy";
+
+// src/reachability.ts
+function isNetworkAllowed(signal) {
+  return signal !== "offline";
+}
+function createStaticReachabilitySource(signal = "online") {
+  const snapshot = { signal, since: Date.now() };
+  return {
+    getSnapshot: () => snapshot,
+    subscribe: () => () => {}
+  };
+}
+var reachabilityPortDoc = {
+  id: "docs.contracts-runtime-core.reachability",
+  title: "Reachability input port (tri-state)",
+  summary: "Engine-owned reachability input port; integrations feed it, the engine never imports them.",
+  kind: "reference",
+  visibility: "internal",
+  route: "/docs/contracts-runtime-core/reachability",
+  domain: "contracts-runtime-core",
+  owners: ["@contractspec-core"],
+  tags: ["contracts-runtime-core", "reachability", "offline", "port"],
+  body: "Tri-state OnlineSignal ('online' | 'restricted' | 'offline'). 'online' allows normal fetch + queue drain. 'restricted' is online-degraded: the engine fetches and drains the queue as if online but may mark results stale-eligible; it never suspends network nor activates the offline queue. Only 'offline' suspends outbound network and activates the durable offline mutation queue. The engine reads reachability solely through ReachabilitySource and MUST NOT import integrations/* — concrete sources (runtime-local networkReachability) are wired via an integration→port adapter (plan §2.3/§4.2, Architect finding 1). isNetworkAllowed mirrors runtime-local's outboundNetworkAllowed = reachability !== 'offline'. createStaticReachabilitySource('online') is the B1a default and online test fixture."
+};
+
+// src/engine/backoff.ts
+var DEFAULT_BASE_MS = 200;
+var DEFAULT_FACTOR = 2;
+var DEFAULT_MAX_MS = 30000;
+function backoffDelayMs(attempt, options = {}) {
+  const base = options.baseMs ?? DEFAULT_BASE_MS;
+  const factor = options.factor ?? DEFAULT_FACTOR;
+  const max = options.maxMs ?? DEFAULT_MAX_MS;
+  const jitter = options.jitter ?? Math.random;
+  const exponent = Math.max(0, attempt - 1);
+  const raw = Math.min(max, base * factor ** exponent);
+  return Math.round(raw * (0.5 + jitter() * 0.5));
+}
+
+// src/engine/conflict-resolution.ts
+import { defaultConflictPolicy } from "@lssm/lib.contracts-spec/query/conflict-policy";
+async function restoreSnapshots(snapshots, cache) {
+  for (const snapshot of snapshots) {
+    if (snapshot.previous === undefined)
+      await cache.remove(snapshot.key);
+    else
+      await cache.write(snapshot.previous);
+  }
+}
+async function resolveQueuedConflict(entry, problem, deps) {
+  const policy = entry.conflictPolicy ?? defaultConflictPolicy();
+  const primaryKey = entry.rollback[0]?.key;
+  const localEntry = primaryKey === undefined ? undefined : await deps.cache.read(primaryKey);
+  const serverData = problem.metadata?.serverData;
+  const resolution = await deps.resolvers.resolve({
+    strategy: policy.strategy,
+    policy,
+    localData: localEntry?.data,
+    serverData,
+    localVersion: entry.versionToken,
+    serverVersion: problem.versionToken,
+    mergeFields: policy.mergeFields
+  });
+  deps.events.emit({
+    type: "mutation-conflict",
+    id: entry.id,
+    strategy: policy.strategy,
+    outcome: resolution.outcome
+  });
+  switch (resolution.outcome) {
+    case "use-server": {
+      await restoreSnapshots(entry.rollback, deps.cache);
+      await deps.cache.invalidate(entry.tags, deps.now());
+      for (const snapshot of entry.rollback) {
+        await deps.queryEngine?.refresh(snapshot.key);
+      }
+      return "resolved";
+    }
+    case "use-client":
+      await deps.queue.update({
+        ...entry,
+        versionToken: problem.versionToken,
+        status: "pending"
+      });
+      return "re-enqueued";
+    case "merged": {
+      if (primaryKey !== undefined && localEntry !== undefined) {
+        await deps.cache.write({
+          ...localEntry,
+          data: resolution.data,
+          versionToken: problem.versionToken,
+          status: "warm",
+          storedAt: deps.now()
+        });
+        await deps.queryEngine?.refresh(primaryKey);
+      }
+      await deps.queue.update({
+        ...entry,
+        versionToken: problem.versionToken,
+        status: "pending"
+      });
+      return "re-enqueued";
+    }
+    default: {
+      if (primaryKey !== undefined) {
+        await deps.queryEngine?.emitConflict(primaryKey, {
+          versionToken: problem.versionToken,
+          serverData,
+          clientData: localEntry?.data,
+          strategy: policy.strategy
+        });
+      }
+      return "resolved";
+    }
+  }
+}
+
+// src/engine/mutation-engine.ts
+var DEFAULT_MAX_ATTEMPTS = 5;
+function mergeEconomicEvidenceRefs(...groups) {
+  return mergeSafeEconomicEvidenceRefIds(...groups);
+}
+function toRuntimeEconomicEvidenceRef(ref) {
+  const safeRef = parseSafeEconomicEvidenceRefId(ref);
+  if (!safeRef) {
+    throw new Error("EconomicEvidenceInvalidRef: unsafe or invalid economic evidence ref");
+  }
+  return safeRef;
+}
+function createMutationEngine(options) {
+  const { transport, cache, queue, reachability, resolvers, events } = options;
+  const now = options.now ?? (() => Date.now());
+  const maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+  const deps = {
+    cache,
+    queue,
+    resolvers,
+    events,
+    now,
+    queryEngine: options.queryEngine
+  };
+  let paused = false;
+  let seq = 0;
+  let draining = null;
+  const outcomes = new Map;
+  const toEnvelope = (entry, economicEvidenceRefs = entry.economicEvidenceRefs) => ({
+    operation: entry.operation,
+    input: entry.input,
+    tags: entry.tags,
+    economicEvidenceRefs
+  });
+  async function applyOptimistic(writes) {
+    const snapshots = [];
+    for (const write of writes) {
+      const previous = await cache.read(write.key);
+      snapshots.push({ key: write.key, previous });
+      await cache.write({
+        key: write.key,
+        data: write.data,
+        versionToken: write.versionToken ?? previous?.versionToken,
+        status: "warm",
+        tags: previous?.tags ?? [],
+        storedAt: now(),
+        staleAt: previous?.staleAt,
+        expiresAt: previous?.expiresAt
+      });
+      await options.queryEngine?.refresh(write.key);
+    }
+    return snapshots;
+  }
+  async function commitSuccess(entry, result) {
+    for (const snapshot of entry.rollback) {
+      const current = await cache.read(snapshot.key);
+      if (current !== undefined) {
+        await cache.write({
+          ...current,
+          versionToken: result.versionToken ?? current.versionToken,
+          status: "stale",
+          staleAt: now()
+        });
+      }
+      await options.queryEngine?.refresh(snapshot.key);
+    }
+    await cache.invalidate(entry.tags, now());
+  }
+  async function replayEntry(entry) {
+    let safeEntryEconomicEvidenceRefs;
+    try {
+      safeEntryEconomicEvidenceRefs = mergeEconomicEvidenceRefs(entry.economicEvidenceRefs);
+    } catch {
+      await restoreSnapshots(entry.rollback, cache);
+      for (const snapshot of entry.rollback) {
+        await options.queryEngine?.refresh(snapshot.key);
+      }
+      await queue.remove(entry.id);
+      events.emit({
+        type: "mutation-failed",
+        id: entry.id,
+        code: "ECONOMIC_EVIDENCE_INVALID_REF"
+      });
+      outcomes.set(entry.id, {
+        id: entry.id,
+        status: "failed",
+        problem: {
+          type: "about:blank",
+          title: "Economic evidence ref rejected",
+          status: 422,
+          code: "ECONOMIC_EVIDENCE_INVALID_REF",
+          category: "validation",
+          severity: "error",
+          retryable: false
+        }
+      });
+      return true;
+    }
+    const attempts = entry.attempts + 1;
+    await queue.update({ ...entry, status: "in-flight", attempts });
+    const result = await transport.execute(toEnvelope(entry, safeEntryEconomicEvidenceRefs), options.contextProvider?.());
+    if (result.ok) {
+      const economicEvidenceRefs = mergeEconomicEvidenceRefs(safeEntryEconomicEvidenceRefs, result.data.economicEvidenceRefs);
+      await commitSuccess(entry, result.data);
+      await queue.remove(entry.id);
+      events.emit({
+        type: "mutation-replayed",
+        id: entry.id,
+        queueDepth: await queue.depth()
+      });
+      if (economicEvidenceRefs.length > 0) {
+        events.emit({
+          type: "economic-evidence-attached",
+          operationKey: entry.operation.key,
+          evidenceRefs: economicEvidenceRefs.map(toRuntimeEconomicEvidenceRef)
+        });
+      }
+      outcomes.set(entry.id, {
+        id: entry.id,
+        status: "done",
+        data: result.data.data,
+        economicEvidenceRefs
+      });
+      return true;
+    }
+    const { problem } = result;
+    if (problem.category === "auth") {
+      paused = true;
+      await queue.update({ ...entry, status: "paused-auth", attempts });
+      events.emit({ type: "auth-expired", id: entry.id });
+      outcomes.set(entry.id, { id: entry.id, status: "paused-auth", problem });
+      if (options.refreshAuth !== undefined && await options.refreshAuth()) {
+        paused = false;
+        await queue.update({ ...entry, status: "pending", attempts });
+        return true;
+      }
+      return false;
+    }
+    if (problem.category === "conflict") {
+      const disposition = await resolveQueuedConflict(entry, problem, deps);
+      if (disposition === "resolved") {
+        await queue.remove(entry.id);
+        outcomes.set(entry.id, { id: entry.id, status: "done", problem });
+      }
+      return true;
+    }
+    if (problem.retryable && attempts < maxAttempts) {
+      const delayMs = backoffDelayMs(attempts, options.backoff);
+      await queue.update({ ...entry, status: "failed", attempts });
+      events.emit({
+        type: "mutation-retry",
+        id: entry.id,
+        attempt: attempts,
+        delayMs
+      });
+      outcomes.set(entry.id, { id: entry.id, status: "failed", problem });
+      options.schedule?.(() => {
+        drain();
+      }, delayMs);
+      return true;
+    }
+    await restoreSnapshots(entry.rollback, cache);
+    for (const snapshot of entry.rollback) {
+      await options.queryEngine?.refresh(snapshot.key);
+    }
+    await queue.remove(entry.id);
+    events.emit({ type: "mutation-failed", id: entry.id, code: result.code });
+    outcomes.set(entry.id, { id: entry.id, status: "failed", problem });
+    return true;
+  }
+  async function runDrain() {
+    if (paused)
+      return;
+    if (!isNetworkAllowed(reachability.getSnapshot().signal))
+      return;
+    for (const entry of await queue.list()) {
+      if (entry.status === "paused-auth")
+        continue;
+      if (!await replayEntry(entry))
+        return;
+    }
+    events.emit({ type: "queue-drained", remaining: await queue.depth() });
+  }
+  function drain() {
+    if (draining !== null)
+      return draining;
+    draining = runDrain().finally(() => {
+      draining = null;
+    });
+    return draining;
+  }
+  async function mutate(request, mutateOptions = {}) {
+    mergeEconomicEvidenceRefs(request.economicEvidenceRefs);
+    const enqueuedAt = now();
+    seq += 1;
+    const id = `${enqueuedAt}-${seq}`;
+    const rollback = mutateOptions.optimistic ? await applyOptimistic(mutateOptions.optimistic) : [];
+    await queue.enqueue({
+      ...request,
+      conflictPolicy: request.conflictPolicy ?? defaultConflictPolicy2(),
+      id,
+      enqueuedAt,
+      attempts: 0,
+      status: "pending",
+      rollback
+    });
+    events.emit({
+      type: "mutation-enqueued",
+      id,
+      queueDepth: await queue.depth()
+    });
+    if (!paused && isNetworkAllowed(reachability.getSnapshot().signal)) {
+      await drain();
+    }
+    return outcomes.get(id) ?? {
+      id,
+      status: "pending"
+    };
+  }
+  async function resume() {
+    paused = false;
+    for (const entry of await queue.list()) {
+      if (entry.status === "paused-auth") {
+        await queue.update({ ...entry, status: "pending" });
+      }
+    }
+    await drain();
+  }
+  const unsubscribe = reachability.subscribe((snapshot) => {
+    if (!paused && isNetworkAllowed(snapshot.signal))
+      drain();
+  });
+  return { mutate, drain, resume, dispose: unsubscribe };
+}
+export {
+  createMutationEngine
+};

package/dist/native/engine/mutation-queue.js

@@ -0,0 +1,26 @@
+// src/engine/mutation-queue.ts
+var QUEUE_PREFIX = "queue:";
+function createMutationQueue(storage) {
+  const storageKey = (id) => `${QUEUE_PREFIX}${id}`;
+  async function readAll() {
+    const keys = await storage.keys(QUEUE_PREFIX);
+    const entries = [];
+    for (const key of keys) {
+      const entry = await storage.get(key);
+      if (entry !== undefined)
+        entries.push(entry);
+    }
+    entries.sort((a, b) => a.enqueuedAt === b.enqueuedAt ? a.id.localeCompare(b.id) : a.enqueuedAt - b.enqueuedAt);
+    return entries;
+  }
+  return {
+    enqueue: (entry) => storage.set(storageKey(entry.id), entry),
+    update: (entry) => storage.set(storageKey(entry.id), entry),
+    remove: (id) => storage.remove(storageKey(id)),
+    list: () => readAll(),
+    depth: async () => (await storage.keys(QUEUE_PREFIX)).length
+  };
+}
+export {
+  createMutationQueue
+};

package/dist/native/engine/no-cache-store.js

@@ -0,0 +1,15 @@
+// src/engine/no-cache-store.ts
+function createNoCacheStore() {
+  return {
+    read: async (_key) => {
+      return;
+    },
+    write: async () => {},
+    remove: async () => {},
+    entries: async () => [],
+    invalidate: async (_tags, _now) => []
+  };
+}
+export {
+  createNoCacheStore
+};