@lssm/lib.contracts-runtime-core 3.0.1

package/dist/native/engine/index.js

@@ -0,0 +1,1189 @@
+// 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/cache-store.ts
+import { invalidationTagMatches } from "@lssm/lib.contracts-spec/query/invalidation";
+var CACHE_PREFIX = "cache:";
+function createCacheStore(storage) {
+  const tagIndex = new Map;
+  const storageKey = (key) => `${CACHE_PREFIX}${key}`;
+  return {
+    read: (key) => storage.get(storageKey(key)),
+    write: async (entry) => {
+      tagIndex.set(entry.key, entry.tags);
+      await storage.set(storageKey(entry.key), entry);
+    },
+    remove: async (key) => {
+      tagIndex.delete(key);
+      await storage.remove(storageKey(key));
+    },
+    entries: async () => {
+      const keys = await storage.keys(CACHE_PREFIX);
+      const all = [];
+      for (const key of keys) {
+        const entry = await storage.get(key);
+        if (entry !== undefined)
+          all.push(entry);
+      }
+      return all;
+    },
+    invalidate: async (tags, now) => {
+      const affected = [];
+      for (const [cacheKey, entryTags] of tagIndex.entries()) {
+        const matched = entryTags.some((subject) => tags.some((pattern) => invalidationTagMatches(subject, pattern)));
+        if (!matched)
+          continue;
+        const stored = await storage.get(storageKey(cacheKey));
+        if (stored === undefined)
+          continue;
+        await storage.set(storageKey(cacheKey), {
+          ...stored,
+          status: "stale",
+          staleAt: now
+        });
+        affected.push(cacheKey);
+      }
+      return affected;
+    }
+  };
+}
+// src/engine/conflict-registry.ts
+function fieldMerge(ctx) {
+  const server = ctx.serverData;
+  const local = ctx.localData;
+  const fields = ctx.mergeFields ?? [];
+  if (typeof server !== "object" || server === null || typeof local !== "object" || local === null) {
+    return { outcome: "surface" };
+  }
+  const merged = {
+    ...server
+  };
+  const localRecord = local;
+  for (const field of fields) {
+    if (field in localRecord)
+      merged[field] = localRecord[field];
+  }
+  return { outcome: "merged", data: merged };
+}
+function createConflictResolverRegistry() {
+  const resolvers = new Map;
+  return {
+    register(key, resolver) {
+      resolvers.set(key, resolver);
+    },
+    has(key) {
+      return resolvers.has(key);
+    },
+    async resolve(ctx) {
+      switch (ctx.strategy) {
+        case "server-wins":
+          return { outcome: "use-server", data: ctx.serverData };
+        case "client-wins":
+          return { outcome: "use-client", data: ctx.localData };
+        case "field-merge":
+          return fieldMerge(ctx);
+        case "surface":
+          return { outcome: "surface" };
+        default: {
+          const key = ctx.policy.resolver;
+          const resolver = key === undefined ? undefined : resolvers.get(key);
+          if (resolver === undefined)
+            return { outcome: "surface" };
+          return resolver(ctx);
+        }
+      }
+    }
+  };
+}
+// 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/local-offline.ts
+var MODES = new Set([
+  "online-only",
+  "memory-cache",
+  "offline-capable"
+]);
+var MODE_ALIASES = {
+  "online-only": "online-only",
+  online: "online-only",
+  disabled: "online-only",
+  false: "online-only",
+  off: "online-only",
+  "memory-cache": "memory-cache",
+  memory: "memory-cache",
+  cache: "memory-cache",
+  "offline-capable": "offline-capable",
+  offline: "offline-capable",
+  enabled: "offline-capable",
+  true: "offline-capable",
+  on: "offline-capable"
+};
+function isLocalOfflineMode(value) {
+  return typeof value === "string" && MODES.has(value);
+}
+function resolveLocalOfflinePolicy(options = {}) {
+  const fallback = options.defaultMode === undefined ? {
+    mode: "online-only",
+    source: "default",
+    reason: "No local/offline policy input was supplied."
+  } : normalizePolicy(options.defaultMode, "explicit") ?? {
+    mode: "online-only",
+    source: "explicit"
+  };
+  const env = normalizePolicy(readEnvValue(options.env), "env", {
+    allowUnknown: true
+  });
+  const flag = normalizePolicy(options.flag, "feature-flag");
+  return flag ?? env ?? fallback;
+}
+function readEnvValue(input) {
+  if (typeof input !== "object" || input === null)
+    return input;
+  if ("CONTRACTSPEC_LOCAL_OFFLINE" in input) {
+    return input.CONTRACTSPEC_LOCAL_OFFLINE;
+  }
+  if ("mode" in input)
+    return input;
+  return;
+}
+function normalizePolicy(input, source, options = {}) {
+  if (input === undefined || input === null || input === "")
+    return;
+  if (typeof input === "boolean") {
+    return { mode: input ? "offline-capable" : "online-only", source };
+  }
+  if (typeof input === "string") {
+    const mode = MODE_ALIASES[input.trim().toLowerCase()];
+    if (mode !== undefined)
+      return { mode, source };
+    if (options.allowUnknown)
+      return;
+  }
+  if (typeof input === "object" && input !== null && "mode" in input) {
+    const policy = input;
+    const mode = typeof policy.mode === "string" ? MODE_ALIASES[policy.mode.trim().toLowerCase()] : undefined;
+    if (mode !== undefined) {
+      return {
+        mode,
+        source,
+        ...typeof policy.reason === "string" ? { reason: policy.reason } : {}
+      };
+    }
+    if (options.allowUnknown)
+      return;
+  }
+  throw new Error(`Unsupported localOffline policy value: ${String(input)}`);
+}
+
+// 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/storage/memory.ts
+function createMemoryStorage() {
+  const store = new Map;
+  return {
+    get: async (key) => {
+      const value = store.get(key);
+      return value === undefined ? undefined : structuredClone(value);
+    },
+    set: async (key, value) => {
+      store.set(key, structuredClone(value));
+    },
+    remove: async (key) => {
+      store.delete(key);
+    },
+    keys: async (prefix) => {
+      const all = [...store.keys()];
+      return prefix === undefined ? all : all.filter((key) => key.startsWith(prefix));
+    },
+    clear: async () => {
+      store.clear();
+    }
+  };
+}
+
+// src/engine/events.ts
+function createEngineEvents() {
+  const listeners = new Set;
+  return {
+    emit(event) {
+      for (const listener of listeners)
+        listener(event);
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    }
+  };
+}
+
+// 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;
+    }
+  };
+}
+
+// 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";
+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 };
+}
+
+// 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
+  };
+}
+
+// src/engine/online-only-data-engine.ts
+import { createQueryKey } from "@lssm/lib.contracts-spec/query/key";
+
+// src/engine/state.ts
+function computeIsStale(entry, now) {
+  if (entry?.staleAt === undefined)
+    return false;
+  return now >= entry.staleAt;
+}
+function idleState() {
+  return {
+    status: "idle",
+    fetchStatus: "idle",
+    cacheStatus: "empty",
+    isStale: false,
+    isOffline: false
+  };
+}
+function loadingState(entry, now) {
+  if (entry === undefined) {
+    return {
+      status: "loading",
+      fetchStatus: "fetching",
+      cacheStatus: "empty",
+      isStale: false,
+      isOffline: false
+    };
+  }
+  const isStale = computeIsStale(entry, now);
+  return {
+    status: "success",
+    fetchStatus: "fetching",
+    data: entry.data,
+    cacheStatus: isStale ? "stale" : entry.status,
+    isStale,
+    isOffline: false,
+    versionToken: entry.versionToken,
+    dataUpdatedAt: entry.storedAt,
+    ...entry.pageInfo === undefined ? {} : { pageInfo: entry.pageInfo }
+  };
+}
+function successState(entry, now) {
+  const isStale = computeIsStale(entry, now);
+  return {
+    status: "success",
+    fetchStatus: "idle",
+    data: entry.data,
+    cacheStatus: isStale ? "stale" : entry.status,
+    isStale,
+    isOffline: false,
+    versionToken: entry.versionToken,
+    dataUpdatedAt: entry.storedAt,
+    ...entry.pageInfo === undefined ? {} : { pageInfo: entry.pageInfo }
+  };
+}
+function errorState(problem, entry, now) {
+  return {
+    status: "error",
+    fetchStatus: "idle",
+    data: entry?.data,
+    error: problem,
+    cacheStatus: entry === undefined ? "empty" : entry.status,
+    isStale: computeIsStale(entry, now),
+    isOffline: false,
+    versionToken: entry?.versionToken,
+    dataUpdatedAt: entry?.storedAt,
+    errorUpdatedAt: now
+  };
+}
+function authExpiredState(problem, entry, now) {
+  return {
+    status: "auth-expired",
+    fetchStatus: "idle",
+    data: entry?.data,
+    error: problem,
+    cacheStatus: entry === undefined ? "empty" : entry.status,
+    isStale: computeIsStale(entry, now),
+    isOffline: false,
+    versionToken: entry?.versionToken,
+    dataUpdatedAt: entry?.storedAt,
+    errorUpdatedAt: now
+  };
+}
+function conflictState(entry, conflict, now) {
+  return {
+    status: entry === undefined ? "idle" : "success",
+    fetchStatus: "idle",
+    data: entry?.data,
+    cacheStatus: "conflict",
+    isStale: computeIsStale(entry, now),
+    isOffline: false,
+    conflict,
+    versionToken: conflict.versionToken ?? entry?.versionToken,
+    dataUpdatedAt: entry?.storedAt
+  };
+}
+function offlineState(entry, now) {
+  return {
+    status: entry === undefined ? "idle" : "success",
+    fetchStatus: "idle",
+    data: entry?.data,
+    cacheStatus: "offline",
+    isStale: computeIsStale(entry, now),
+    isOffline: true,
+    versionToken: entry?.versionToken,
+    dataUpdatedAt: entry?.storedAt,
+    ...entry?.pageInfo === undefined ? {} : { pageInfo: entry.pageInfo }
+  };
+}
+
+// src/engine/online-only-data-engine.ts
+function createOnlineOnlyDataEngine(options, resolvedPolicy) {
+  const { transport } = options;
+  const advanced = options.advanced ?? {};
+  const now = advanced.now ?? (() => Date.now());
+  const reachability = advanced.reachability ?? createStaticReachabilitySource("online");
+  const events = advanced.events ?? createEngineEvents();
+  const resolvers = advanced.resolvers ?? createConflictResolverRegistry();
+  const localOffline = resolvedPolicy ?? resolveLocalOfflinePolicy({
+    defaultMode: options.localOffline,
+    env: options.env,
+    flag: options.flag
+  });
+  const states = new Map;
+  const listeners = new Map;
+  let seq = 0;
+  function emit(key, state) {
+    states.set(key, state);
+    for (const listener of listeners.get(key) ?? [])
+      listener(state);
+  }
+  const queryEngine = {
+    async query(envelope, ctx) {
+      const key = createQueryKey(envelope);
+      const signal = reachability.getSnapshot().signal;
+      if (!isNetworkAllowed(signal)) {
+        const state = offlineState(undefined, now());
+        emit(key, state);
+        return state;
+      }
+      emit(key, loadingState(undefined, now()));
+      const startedAt = now();
+      const result = await transport.execute(envelope, ctx);
+      const settledAt = now();
+      if (!result.ok) {
+        events.emit({
+          type: "fetch-error",
+          key,
+          code: result.code,
+          latencyMs: settledAt - startedAt
+        });
+        const state = result.problem.category === "auth" ? authExpiredState(result.problem, undefined, settledAt) : errorState(result.problem, undefined, settledAt);
+        emit(key, state);
+        return state;
+      }
+      events.emit({
+        type: "fetch-success",
+        key,
+        latencyMs: settledAt - startedAt
+      });
+      const entry = {
+        key,
+        data: result.data.data,
+        versionToken: result.data.versionToken ?? result.versionToken,
+        status: signal === "restricted" ? "warm" : "fresh",
+        tags: [],
+        storedAt: settledAt,
+        ...result.data.pageInfo === undefined ? {} : { pageInfo: result.data.pageInfo }
+      };
+      const state = successState(entry, settledAt);
+      emit(key, state);
+      return state;
+    },
+    getState(envelope) {
+      return states.get(createQueryKey(envelope)) ?? idleState();
+    },
+    subscribe(envelope, listener) {
+      const key = createQueryKey(envelope);
+      let set = listeners.get(key);
+      if (set === undefined) {
+        set = new Set;
+        listeners.set(key, set);
+      }
+      set.add(listener);
+      return () => set?.delete(listener);
+    },
+    async invalidateTags() {
+      return [];
+    },
+    async refresh(key) {
+      const state = states.get(key) ?? idleState();
+      emit(key, state);
+      return state;
+    },
+    async emitConflict(key, conflict) {
+      const state = conflictState(undefined, conflict, now());
+      emit(key, state);
+      return state;
+    }
+  };
+  const mutationEngine = {
+    async mutate(request, mutateOptions = {}) {
+      seq += 1;
+      const id = `${now()}-${seq}`;
+      if (!isNetworkAllowed(reachability.getSnapshot().signal)) {
+        return {
+          id,
+          status: "disabled-offline",
+          problem: offlineQueueDisabledProblem()
+        };
+      }
+      const result = await transport.execute({
+        operation: request.operation,
+        input: request.input,
+        tags: request.tags
+      }, mutateOptions.ctx ?? advanced.contextProvider?.());
+      if (result.ok)
+        return { id, status: "done", data: result.data.data };
+      if (result.problem.category === "auth") {
+        return { id, status: "paused-auth", problem: result.problem };
+      }
+      return { id, status: "failed", problem: result.problem };
+    },
+    async drain() {},
+    async resume() {},
+    dispose() {}
+  };
+  return {
+    ...queryEngine,
+    ...mutationEngine,
+    maintenance: {
+      collectGarbage: async () => 0,
+      revalidateStale: async () => 0
+    },
+    events,
+    resolvers,
+    localOffline
+  };
+}
+function offlineQueueDisabledProblem() {
+  return {
+    type: "about:blank",
+    title: "Offline mutation queue disabled",
+    status: 409,
+    code: "OFFLINE_QUEUE_DISABLED",
+    category: "conflict",
+    severity: "warning",
+    retryable: false,
+    detail: "localOffline=online-only does not cache local data or queue offline mutations."
+  };
+}
+
+// src/engine/query-engine.ts
+import { createQueryKey as createQueryKey2 } from "@lssm/lib.contracts-spec/query/key";
+
+// src/engine/dedup.ts
+function createInflightRegistry() {
+  const inflight = new Map;
+  return {
+    run(key, factory) {
+      const existing = inflight.get(key);
+      if (existing !== undefined)
+        return existing;
+      const promise = factory().finally(() => {
+        inflight.delete(key);
+      });
+      inflight.set(key, promise);
+      return promise;
+    },
+    size() {
+      return inflight.size;
+    }
+  };
+}
+
+// src/engine/query-engine.ts
+var DEFAULT_STALE_TIME_MS = 0;
+function createQueryEngine(options) {
+  const { transport } = options;
+  const storage = options.storage ?? createMemoryStorage();
+  const reachability = options.reachability ?? createStaticReachabilitySource("online");
+  const now = options.now ?? (() => Date.now());
+  const defaultStaleTimeMs = options.defaultStaleTimeMs ?? DEFAULT_STALE_TIME_MS;
+  const cache = options.cacheStore ?? createCacheStore(storage);
+  const events = options.events ?? createEngineEvents();
+  const inflight = createInflightRegistry();
+  const states = new Map;
+  const listeners = new Map;
+  function emit(key, state) {
+    states.set(key, state);
+    const set = listeners.get(key);
+    if (set === undefined)
+      return;
+    for (const listener of set)
+      listener(state);
+  }
+  async function query(envelope, ctx) {
+    const key = createQueryKey2(envelope);
+    const signal = reachability.getSnapshot().signal;
+    const entry = await cache.read(key);
+    if (!isNetworkAllowed(signal)) {
+      const state = offlineState(entry, now());
+      emit(key, state);
+      return state;
+    }
+    if (entry !== undefined && !computeIsStale(entry, now())) {
+      events.emit({ type: "cache-hit", key });
+      const state = successState(entry, now());
+      emit(key, state);
+      return state;
+    }
+    events.emit({ type: "cache-miss", key });
+    emit(key, loadingState(entry, now()));
+    const startedAt = now();
+    const result = await inflight.run(key, () => transport.execute(envelope, ctx));
+    const settledAt = now();
+    if (!result.ok) {
+      events.emit({
+        type: "fetch-error",
+        key,
+        code: result.code,
+        latencyMs: settledAt - startedAt
+      });
+      const state = result.problem.category === "auth" ? authExpiredState(result.problem, entry, settledAt) : errorState(result.problem, entry, settledAt);
+      emit(key, state);
+      return state;
+    }
+    events.emit({
+      type: "fetch-success",
+      key,
+      latencyMs: settledAt - startedAt
+    });
+    const staleTimeMs = envelope.cache?.staleTimeMs ?? defaultStaleTimeMs;
+    const cacheTimeMs = envelope.cache?.cacheTimeMs;
+    const written = {
+      key,
+      data: result.data.data,
+      versionToken: result.data.versionToken ?? result.versionToken,
+      status: signal === "restricted" ? "warm" : "fresh",
+      tags: envelope.tags ?? [],
+      storedAt: settledAt,
+      staleAt: settledAt + staleTimeMs,
+      envelope,
+      ...cacheTimeMs === undefined ? {} : { expiresAt: settledAt + cacheTimeMs },
+      ...result.data.pageInfo === undefined ? {} : { pageInfo: result.data.pageInfo }
+    };
+    await cache.write(written);
+    const state = successState(written, settledAt);
+    emit(key, state);
+    return state;
+  }
+  async function refresh(key) {
+    const entry = await cache.read(key);
+    const state = entry === undefined ? idleState() : successState(entry, now());
+    emit(key, state);
+    return state;
+  }
+  async function emitConflict(key, conflict) {
+    const entry = await cache.read(key);
+    const state = conflictState(entry, conflict, now());
+    emit(key, state);
+    return state;
+  }
+  function getState(envelope) {
+    const existing = states.get(createQueryKey2(envelope));
+    return existing ?? idleState();
+  }
+  function subscribe(envelope, listener) {
+    const key = createQueryKey2(envelope);
+    let set = listeners.get(key);
+    if (set === undefined) {
+      set = new Set;
+      listeners.set(key, set);
+    }
+    set.add(listener);
+    return () => {
+      listeners.get(key)?.delete(listener);
+    };
+  }
+  async function invalidateTags(tags) {
+    const affected = await cache.invalidate(tags, now());
+    for (const key of affected) {
+      const entry = await cache.read(key);
+      if (entry !== undefined)
+        emit(key, successState(entry, now()));
+    }
+    return affected;
+  }
+  return { query, getState, subscribe, invalidateTags, refresh, emitConflict };
+}
+
+// src/engine/data-engine.ts
+function createDataEngine(options) {
+  assertNoLegacyLowLevelOptions(options);
+  const advanced = options.advanced ?? {};
+  const policy = resolveLocalOfflinePolicy({
+    defaultMode: options.localOffline,
+    env: options.env,
+    flag: options.flag
+  });
+  assertModeCompatibleWithAdvanced(policy.mode, advanced);
+  if (policy.mode === "online-only")
+    return createOnlineOnlyDataEngine(options, policy);
+  const now = advanced.now ?? (() => Date.now());
+  const storage = advanced.storage ?? createMemoryStorage();
+  const events = advanced.events ?? createEngineEvents();
+  const cacheStore = advanced.cacheStore ?? createCacheStore(storage);
+  const reachability = advanced.reachability ?? createStaticReachabilitySource("online");
+  const resolvers = advanced.resolvers ?? createConflictResolverRegistry();
+  const queue = createMutationQueue(storage);
+  const queryEngine = createQueryEngine({
+    ...advanced,
+    transport: options.transport,
+    now,
+    storage,
+    events,
+    cacheStore,
+    reachability
+  });
+  const mutationEngine = createMutationEngine({
+    transport: options.transport,
+    cache: cacheStore,
+    queue,
+    reachability,
+    resolvers,
+    events,
+    now,
+    maxAttempts: advanced.maxAttempts,
+    queryEngine,
+    contextProvider: advanced.contextProvider,
+    refreshAuth: advanced.refreshAuth,
+    schedule: advanced.schedule,
+    backoff: advanced.backoff
+  });
+  const maintenance = createMaintenance({
+    cache: cacheStore,
+    events,
+    now,
+    revalidate: (envelope) => queryEngine.query(envelope)
+  });
+  return {
+    ...queryEngine,
+    ...mutationEngine,
+    maintenance,
+    events,
+    resolvers,
+    localOffline: policy
+  };
+}
+function assertModeCompatibleWithAdvanced(mode, advanced) {
+  if (mode === "offline-capable") {
+    if (advanced.storage === undefined) {
+      throw new Error("localOffline=offline-capable requires advanced.storage; pass a durable StoragePort or explicit platform storage adapter.");
+    }
+    return;
+  }
+  if (advanced.storage !== undefined) {
+    throw new Error(`localOffline=${mode} rejects advanced.storage; this mode must not use durable local persistence.`);
+  }
+  if (advanced.cacheStore !== undefined) {
+    throw new Error(`localOffline=${mode} rejects advanced.cacheStore; this mode owns cache semantics.`);
+  }
+}
+function assertNoLegacyLowLevelOptions(options) {
+  const legacy = options;
+  if (legacy.storage !== undefined) {
+    throw new Error("Use advanced.storage instead of top-level storage.");
+  }
+  if (legacy.cacheStore !== undefined) {
+    throw new Error("Use advanced.cacheStore instead of top-level cacheStore.");
+  }
+}
+// src/engine/data-engine-host.ts
+function readHostEnv() {
+  const proc = globalThis.process;
+  return proc?.env;
+}
+function createDataEngineFromEnv(options) {
+  return createDataEngine({
+    ...options,
+    env: options.env ?? readHostEnv()
+  });
+}
+// src/engine/no-cache-store.ts
+function createNoCacheStore() {
+  return {
+    read: async (_key) => {
+      return;
+    },
+    write: async () => {},
+    remove: async () => {},
+    entries: async () => [],
+    invalidate: async (_tags, _now) => []
+  };
+}
+// src/engine/online-only-mutation-engine.ts
+function offlineDisabledProblem() {
+  return {
+    type: "https://contractspec.io/problems/offline-queue-disabled",
+    title: "Offline mutation queue disabled",
+    status: 503,
+    code: "OFFLINE_QUEUE_DISABLED",
+    category: "policy",
+    severity: "warning",
+    retryable: true,
+    detail: "localOffline is online-only; offline mutations are not queued or replayed."
+  };
+}
+var toEnvelope = (request) => ({
+  operation: request.operation,
+  input: request.input,
+  tags: request.tags
+});
+function createOnlineOnlyMutationEngine(options) {
+  const now = options.now ?? (() => Date.now());
+  let seq = 0;
+  async function mutate(request, mutateOptions = {}) {
+    seq += 1;
+    const id = `${now()}-${seq}`;
+    if (!isNetworkAllowed(options.reachability.getSnapshot().signal)) {
+      return {
+        id,
+        status: "disabled-offline",
+        problem: offlineDisabledProblem()
+      };
+    }
+    const result = await options.transport.execute(toEnvelope(request), mutateOptions.ctx);
+    if (result.ok)
+      return { id, status: "done", data: result.data.data };
+    return { id, status: "failed", problem: result.problem };
+  }
+  return {
+    mutate,
+    drain: async () => {},
+    resume: async () => {},
+    dispose: () => {}
+  };
+}
+export {
+  authExpiredState,
+  backoffDelayMs,
+  computeIsStale,
+  conflictState,
+  createCacheStore,
+  createConflictResolverRegistry,
+  createDataEngine,
+  createDataEngineFromEnv,
+  createEngineEvents,
+  createInflightRegistry,
+  createMaintenance,
+  createMutationEngine,
+  createMutationQueue,
+  createNoCacheStore,
+  createOnlineOnlyMutationEngine,
+  createQueryEngine,
+  errorState,
+  idleState,
+  loadingState,
+  offlineState,
+  readHostEnv,
+  resolveQueuedConflict,
+  restoreSnapshots,
+  successState
+};