@lssm/lib.contracts-runtime-core 3.0.1

package/dist/native/engine/online-only-data-engine.js

@@ -0,0 +1,422 @@
+// src/engine/online-only-data-engine.ts
+import { createQueryKey } from "@lssm/lib.contracts-spec/query/key";
+
+// 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/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/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/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."
+  };
+}
+export {
+  createOnlineOnlyDataEngine
+};

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

@@ -0,0 +1,70 @@
+// 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/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 {
+  createOnlineOnlyMutationEngine
+};