@lssm/lib.contracts-runtime-core 3.0.1

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

@@ -0,0 +1,360 @@
+// src/engine/query-engine.ts
+import { createQueryKey } from "@lssm/lib.contracts-spec/query/key";
+
+// 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/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/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/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/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 = createQueryKey(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(createQueryKey(envelope));
+    return existing ?? idleState();
+  }
+  function 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 () => {
+      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 };
+}
+export {
+  createQueryEngine
+};

package/dist/native/engine/state.js

@@ -0,0 +1,116 @@
+// 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 }
+  };
+}
+export {
+  authExpiredState,
+  computeIsStale,
+  conflictState,
+  errorState,
+  idleState,
+  loadingState,
+  offlineState,
+  successState
+};

package/dist/native/forms-platform-csv-columns.js

@@ -0,0 +1,31 @@
+// src/forms-platform-csv-columns.ts
+import { flattenPortableFormFields } from "@lssm/lib.contracts-spec/forms";
+function formCsvColumns(document) {
+  const questionNames = new Set(document.questions.map(({ name }) => name));
+  const questions = document.questions.map(questionColumn);
+  const portableSensitive = new Set(document.formSpec?.policy?.pii ?? []);
+  const allFields = flattenPortableFormFields(document.formSpec?.fields ?? []);
+  const portable = Object.entries(document.formSpec?.modelFields ?? {}).flatMap(([name, modelField]) => {
+    if (questionNames.has(name))
+      return [];
+    const field = allFields.find((candidate) => candidate.name === name);
+    return [
+      {
+        id: name,
+        labelKey: field?.labelI18n ?? name,
+        sensitive: portableSensitive.has(name) || [...portableSensitive].some((path) => path.startsWith(`${name}.`)) || field?.kind === "email" || field?.kind === "phone" || modelField.type === "email" || modelField.type === "phone"
+      }
+    ];
+  });
+  return [...questions, ...portable];
+}
+function questionColumn(question) {
+  return {
+    id: question.id,
+    labelKey: question.labelKey,
+    sensitive: question.sensitive === true || question.kind === "email" || question.kind === "phone"
+  };
+}
+export {
+  formCsvColumns
+};

package/dist/native/forms-platform-csv.js

@@ -0,0 +1,150 @@
+// src/forms-platform-csv-columns.ts
+import { flattenPortableFormFields } from "@lssm/lib.contracts-spec/forms";
+function formCsvColumns(document) {
+  const questionNames = new Set(document.questions.map(({ name }) => name));
+  const questions = document.questions.map(questionColumn);
+  const portableSensitive = new Set(document.formSpec?.policy?.pii ?? []);
+  const allFields = flattenPortableFormFields(document.formSpec?.fields ?? []);
+  const portable = Object.entries(document.formSpec?.modelFields ?? {}).flatMap(([name, modelField]) => {
+    if (questionNames.has(name))
+      return [];
+    const field = allFields.find((candidate) => candidate.name === name);
+    return [
+      {
+        id: name,
+        labelKey: field?.labelI18n ?? name,
+        sensitive: portableSensitive.has(name) || [...portableSensitive].some((path) => path.startsWith(`${name}.`)) || field?.kind === "email" || field?.kind === "phone" || modelField.type === "email" || modelField.type === "phone"
+      }
+    ];
+  });
+  return [...questions, ...portable];
+}
+function questionColumn(question) {
+  return {
+    id: question.id,
+    labelKey: question.labelKey,
+    sensitive: question.sensitive === true || question.kind === "email" || question.kind === "phone"
+  };
+}
+
+// src/forms-platform-utils.ts
+import {
+  compileFormDocument,
+  validateFormDocument
+} from "@lssm/lib.contracts-spec/forms";
+
+// src/forms-platform-types.ts
+class FormsPlatformError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "FormsPlatformError";
+  }
+}
+
+// src/forms-platform-utils.ts
+function requireFormDefinition(definition, scope) {
+  const matches = definition?.owner.product === scope.product && definition.owner.tenantRef === scope.tenantRef && definition.owner.workspaceRef === scope.workspaceRef && definition.owner.ownerRef === scope.ownerRef;
+  if (!definition || !matches) {
+    throw new FormsPlatformError("FORM_NOT_FOUND", "Form definition was not found in the caller scope");
+  }
+  return definition;
+}
+function validateRuntimeFormDocument(document) {
+  const issues = validateFormDocument(document);
+  if (issues.length) {
+    throw new FormsPlatformError("INVALID_FORM_DOCUMENT", issues.map((issue) => issue.message).join("; "));
+  }
+  compileFormDocument(document);
+}
+function formAssuranceMeetsRequirement(assurance, requirement) {
+  if (requirement === "none")
+    return true;
+  if (requirement === "either")
+    return assurance !== "anonymous";
+  if (requirement === "both")
+    return assurance === "both";
+  return assurance === requirement || assurance === "both";
+}
+function resolveFormResponseStatus(document, assurance) {
+  if (formAssuranceMeetsRequirement(assurance, document.verification.requirement)) {
+    return "completed";
+  }
+  return document.verification.unverifiedDisposition === "pending-hidden" ? "pending-verification" : "completed-unverified";
+}
+function resolveFormLocale(document, candidates) {
+  const supported = new Set(document.content.enabledLocales.map((locale) => locale.toLowerCase()));
+  for (const candidate of candidates) {
+    if (!candidate)
+      continue;
+    const normalized = candidate.trim().toLowerCase();
+    const exact = document.content.enabledLocales.find((locale) => locale.toLowerCase() === normalized);
+    if (supported.has(normalized) && exact)
+      return exact;
+    const language = normalized.split("-")[0];
+    const match = document.content.enabledLocales.find((locale) => locale.toLowerCase().split("-")[0] === language);
+    if (match)
+      return match;
+  }
+  return document.content.defaultLocale;
+}
+
+// src/forms-platform-csv.ts
+var RESPONSE_EXTENSIONS_COLUMN = "response_extensions:AI follow-ups";
+function csvCell(value) {
+  const raw = Array.isArray(value) ? value.every((item) => typeof item !== "object") ? value.join(";") : JSON.stringify(value) : value == null ? "" : typeof value === "object" ? JSON.stringify(value) : String(value);
+  const protectedValue = /^[\s]*[=+\-@]/.test(raw) ? `'${raw}` : raw;
+  return `"${protectedValue.replaceAll('"', '""')}"`;
+}
+function csvRow(values) {
+  return `${values.map(csvCell).join(",")}\r
+`;
+}
+function responseRow(revision, response, options) {
+  if (response.revisionId !== revision.id) {
+    throw new Error("CSV responses must belong to the exported revision");
+  }
+  const columns = formCsvColumns(revision.document);
+  const baseIds = new Set(columns.map(({ id }) => id));
+  const extensions = Object.fromEntries(Object.entries(response.answers).filter(([id]) => !baseIds.has(id)));
+  return [
+    response.id,
+    response.status,
+    response.locale,
+    response.submittedAt ?? "",
+    ...columns.map((column) => {
+      const mayIncludeSensitive = options.includeSensitive && options.sensitiveGrant?.authorized;
+      if (!mayIncludeSensitive && column.sensitive) {
+        return "[REDACTED]";
+      }
+      return response.answers[column.id];
+    }),
+    options.includeSensitive && options.sensitiveGrant?.authorized ? extensions : "[REDACTED]"
+  ];
+}
+function csvHeaders(revision, locale) {
+  const resolved = resolveFormLocale(revision.document, [locale]);
+  const catalog = revision.document.content.catalogs[resolved] ?? {};
+  return [
+    "response_id",
+    "status",
+    "locale",
+    "submitted_at",
+    ...formCsvColumns(revision.document).map((column) => `${column.id}:${catalog[column.labelKey] ?? column.labelKey}`),
+    RESPONSE_EXTENSIONS_COLUMN
+  ];
+}
+function serializeFormResponsesCsv(revision, responses, options = {}) {
+  return `\uFEFF${csvRow(csvHeaders(revision, options.locale))}${responses.map((response) => csvRow(responseRow(revision, response, options))).join("")}`;
+}
+async function* streamFormResponsesCsv(revision, responses, options = {}) {
+  yield `\uFEFF${csvRow(csvHeaders(revision, options.locale))}`;
+  for await (const response of responses) {
+    yield csvRow(responseRow(revision, response, options));
+  }
+}
+export {
+  serializeFormResponsesCsv,
+  streamFormResponsesCsv
+};