@open-mercato/core 0.8.1-develop.7296.1.2111d779db → 0.9.0

package/dist/modules/forms/schema/style-validators.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/forms/schema/style-validators.ts"],
+  "sourcesContent": ["/**\n * Strict validators for the forms custom-styling vocabulary\n * (`x-om-theme`, `OmSection.style`, `x-om-style`).\n *\n * Each validator returns the first violation message (a string) or `null` when\n * the value is valid \u2014 mirroring the existing `OM_ROOT_VALIDATORS` /\n * `OM_FIELD_VALIDATORS` contract in `jsonschema-extensions.ts`.\n *\n * Security keystone (D1/D3/R-CS-1): there is no value an author can persist\n * that becomes an executable/parsed CSS declaration or selector. Colors are\n * either a curated token or a strict hex literal \u2014 no `rgb()`, `hsl()`, named\n * colors, `url()`, `var()`, `expression()`, or functional syntax. Every object\n * rejects unknown keys (strict \u2014 no passthrough). All validators are pure (no\n * I/O) and narrow `unknown` without `any`.\n */\n\nimport {\n  OM_BACKGROUND_KINDS,\n  OM_BORDER_SCALE,\n  OM_COLOR_TOKENS,\n  OM_CONTENT_WIDTH,\n  OM_FONT_FAMILY,\n  OM_FONT_SCALE,\n  OM_HEX_COLOR,\n  OM_LOGO_SIZE,\n  OM_RADIUS_SCALE,\n  OM_SPACE_SCALE,\n  OM_TEXT_ALIGN,\n  OM_TEXT_WEIGHT,\n} from './style-extensions'\n\n/** Attachment ids are server-minted UUIDs \u2014 the only assetId shape we accept. */\nconst OM_ASSET_ID = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/\nconst LOGO_KEYS: ReadonlySet<string> = new Set(['assetId', 'alt', 'align', 'size'])\n\ntype UnknownRecord = Record<string, unknown>\n\nfunction isPlainObject(value: unknown): value is UnknownRecord {\n  return typeof value === 'object' && value !== null && !Array.isArray(value)\n}\n\nfunction unknownKey(candidate: UnknownRecord, allowed: ReadonlySet<string>, scope: string): string | null {\n  for (const key of Object.keys(candidate)) {\n    if (!allowed.has(key)) {\n      return `${scope} has an unknown key \"${key}\".`\n    }\n  }\n  return null\n}\n\n/**\n * A color is either a curated DS-role token OR a strict hex literal\n * (`#rgb`, `#rrggbb`, `#rrggbbaa`). Everything else \u2014 `rgb()`, `hsl()`, named\n * colors, `url()`, `var()`, `expression()`, any functional/parenthesised\n * syntax \u2014 is rejected (D3 / R-CS-1).\n */\nexport function validateOmColor(value: unknown): string | null {\n  if (typeof value !== 'string') {\n    return 'Color must be a curated token or a hex literal string.'\n  }\n  if (OM_COLOR_TOKENS.has(value as never)) return null\n  if (OM_HEX_COLOR.test(value)) return null\n  return 'Color must be a curated token or a strict hex literal (#rgb, #rrggbb, or #rrggbbaa) \u2014 no rgb()/hsl()/named/functional syntax.'\n}\n\nconst BACKGROUND_KEYS_BY_KIND: Record<string, ReadonlySet<string>> = {\n  none: new Set(['kind']),\n  color: new Set(['kind', 'color']),\n  gradient: new Set(['kind', 'from', 'to', 'angle']),\n}\n\nexport function validateOmBackground(value: unknown): string | null {\n  if (!isPlainObject(value)) {\n    return 'Background must be an object with a `kind` discriminator.'\n  }\n  const kind = value.kind\n  if (typeof kind !== 'string' || !OM_BACKGROUND_KINDS.has(kind as never)) {\n    return 'Background `kind` must be \"none\", \"color\", or \"gradient\".'\n  }\n  const unknown = unknownKey(value, BACKGROUND_KEYS_BY_KIND[kind], `Background (kind \"${kind}\")`)\n  if (unknown) return unknown\n\n  if (kind === 'none') {\n    return null\n  }\n  if (kind === 'color') {\n    const colorMessage = validateOmColor(value.color)\n    if (colorMessage) return `Background color: ${colorMessage}`\n    return null\n  }\n  // gradient\n  const fromMessage = validateOmColor(value.from)\n  if (fromMessage) return `Background gradient from: ${fromMessage}`\n  const toMessage = validateOmColor(value.to)\n  if (toMessage) return `Background gradient to: ${toMessage}`\n  const angle = value.angle\n  if (typeof angle !== 'number' || !Number.isInteger(angle) || angle < 0 || angle > 360) {\n    return 'Background gradient `angle` must be an integer in [0, 360].'\n  }\n  return null\n}\n\nfunction validateEnumMember(\n  candidate: UnknownRecord,\n  key: string,\n  allowed: ReadonlySet<string>,\n  label: string,\n): string | null {\n  if (candidate[key] === undefined) return null\n  const member = candidate[key]\n  if (typeof member !== 'string' || !allowed.has(member)) {\n    return `${label} must be one of ${[...allowed].map((entry) => `\"${entry}\"`).join(', ')}.`\n  }\n  return null\n}\n\nfunction validateColorMember(candidate: UnknownRecord, key: string, label: string): string | null {\n  if (candidate[key] === undefined) return null\n  const message = validateOmColor(candidate[key])\n  if (message) return `${label}: ${message}`\n  return null\n}\n\nfunction validateBackgroundMember(candidate: UnknownRecord, key: string, label: string): string | null {\n  if (candidate[key] === undefined) return null\n  const message = validateOmBackground(candidate[key])\n  if (message) return `${label}: ${message}`\n  return null\n}\n\nconst THEME_KEYS: ReadonlySet<string> = new Set([\n  'background',\n  'surface',\n  'foreground',\n  'inputText',\n  'labelColor',\n  'labelWeight',\n  'accent',\n  'border',\n  'fontFamily',\n  'fontScale',\n  'radius',\n  'contentWidth',\n  'logo',\n])\n\n/**\n * `logo` carries only an attachment id + display hints \u2014 never a URL or raw\n * text that reaches the DOM unescaped. `assetId` must be a UUID (a server-minted\n * attachment id); `alt` is a bounded plain string; `align`/`size` are fixed\n * enums; unknown keys are rejected (D4 / R-CS-1).\n */\nexport function validateOmThemeLogo(value: unknown): string | null {\n  if (!isPlainObject(value)) {\n    return 'x-om-theme.logo must be an object.'\n  }\n  const unknown = unknownKey(value, LOGO_KEYS, 'x-om-theme.logo')\n  if (unknown) return unknown\n  if (typeof value.assetId !== 'string' || !OM_ASSET_ID.test(value.assetId)) {\n    return 'x-om-theme.logo.assetId must be an uploaded image id (UUID).'\n  }\n  if (value.alt !== undefined && (typeof value.alt !== 'string' || value.alt.length > 300)) {\n    return 'x-om-theme.logo.alt must be a string of at most 300 characters.'\n  }\n  return (\n    validateEnumMember(value, 'align', OM_TEXT_ALIGN, 'x-om-theme.logo.align')\n    || validateEnumMember(value, 'size', OM_LOGO_SIZE, 'x-om-theme.logo.size')\n  )\n}\n\nexport function validateOmTheme(value: unknown): string | null {\n  if (!isPlainObject(value)) {\n    return 'x-om-theme must be an object.'\n  }\n  const unknown = unknownKey(value, THEME_KEYS, 'x-om-theme')\n  if (unknown) return unknown\n\n  return (\n    validateBackgroundMember(value, 'background', 'x-om-theme.background')\n    || validateColorMember(value, 'surface', 'x-om-theme.surface')\n    || validateColorMember(value, 'foreground', 'x-om-theme.foreground')\n    || validateColorMember(value, 'inputText', 'x-om-theme.inputText')\n    || validateColorMember(value, 'labelColor', 'x-om-theme.labelColor')\n    || validateEnumMember(value, 'labelWeight', OM_TEXT_WEIGHT, 'x-om-theme.labelWeight')\n    || validateColorMember(value, 'accent', 'x-om-theme.accent')\n    || validateColorMember(value, 'border', 'x-om-theme.border')\n    || validateEnumMember(value, 'fontFamily', OM_FONT_FAMILY, 'x-om-theme.fontFamily')\n    || validateEnumMember(value, 'fontScale', OM_FONT_SCALE, 'x-om-theme.fontScale')\n    || validateEnumMember(value, 'radius', OM_RADIUS_SCALE, 'x-om-theme.radius')\n    || validateEnumMember(value, 'contentWidth', OM_CONTENT_WIDTH, 'x-om-theme.contentWidth')\n    || (value.logo !== undefined ? validateOmThemeLogo(value.logo) : null)\n  )\n}\n\nconst SECTION_STYLE_KEYS: ReadonlySet<string> = new Set([\n  'background',\n  'foreground',\n  'padding',\n  'border',\n  'radius',\n  'card',\n  'align',\n])\n\nexport function validateOmSectionStyle(value: unknown): string | null {\n  if (!isPlainObject(value)) {\n    return 'Section `style` must be an object.'\n  }\n  const unknown = unknownKey(value, SECTION_STYLE_KEYS, 'Section `style`')\n  if (unknown) return unknown\n\n  const backgroundMessage = validateBackgroundMember(value, 'background', 'Section style.background')\n  if (backgroundMessage) return backgroundMessage\n  const foregroundMessage = validateColorMember(value, 'foreground', 'Section style.foreground')\n  if (foregroundMessage) return foregroundMessage\n  const paddingMessage = validateEnumMember(value, 'padding', OM_SPACE_SCALE, 'Section style.padding')\n  if (paddingMessage) return paddingMessage\n  const borderMessage = validateEnumMember(value, 'border', OM_BORDER_SCALE, 'Section style.border')\n  if (borderMessage) return borderMessage\n  const radiusMessage = validateEnumMember(value, 'radius', OM_RADIUS_SCALE, 'Section style.radius')\n  if (radiusMessage) return radiusMessage\n  if (value.card !== undefined && typeof value.card !== 'boolean') {\n    return 'Section style.card must be a boolean when present.'\n  }\n  const alignMessage = validateEnumMember(value, 'align', OM_TEXT_ALIGN, 'Section style.align')\n  if (alignMessage) return alignMessage\n  return null\n}\n\nconst FIELD_STYLE_KEYS: ReadonlySet<string> = new Set([\n  'labelWeight',\n  'labelColor',\n  'textColor',\n  'accent',\n  'align',\n])\n\nexport function validateOmFieldStyle(value: unknown): string | null {\n  if (!isPlainObject(value)) {\n    return 'x-om-style must be an object.'\n  }\n  const unknown = unknownKey(value, FIELD_STYLE_KEYS, 'x-om-style')\n  if (unknown) return unknown\n\n  return (\n    validateEnumMember(value, 'labelWeight', OM_TEXT_WEIGHT, 'x-om-style.labelWeight')\n    || validateColorMember(value, 'labelColor', 'x-om-style.labelColor')\n    || validateColorMember(value, 'textColor', 'x-om-style.textColor')\n    || validateColorMember(value, 'accent', 'x-om-style.accent')\n    || validateEnumMember(value, 'align', OM_TEXT_ALIGN, 'x-om-style.align')\n  )\n}\n"],
+  "mappings": "AAgBA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAGP,MAAM,cAAc;AACpB,MAAM,YAAiC,oBAAI,IAAI,CAAC,WAAW,OAAO,SAAS,MAAM,CAAC;AAIlF,SAAS,cAAc,OAAwC;AAC7D,SAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC5E;AAEA,SAAS,WAAW,WAA0B,SAA8B,OAA8B;AACxG,aAAW,OAAO,OAAO,KAAK,SAAS,GAAG;AACxC,QAAI,CAAC,QAAQ,IAAI,GAAG,GAAG;AACrB,aAAO,GAAG,KAAK,wBAAwB,GAAG;AAAA,IAC5C;AAAA,EACF;AACA,SAAO;AACT;AAQO,SAAS,gBAAgB,OAA+B;AAC7D,MAAI,OAAO,UAAU,UAAU;AAC7B,WAAO;AAAA,EACT;AACA,MAAI,gBAAgB,IAAI,KAAc,EAAG,QAAO;AAChD,MAAI,aAAa,KAAK,KAAK,EAAG,QAAO;AACrC,SAAO;AACT;AAEA,MAAM,0BAA+D;AAAA,EACnE,MAAM,oBAAI,IAAI,CAAC,MAAM,CAAC;AAAA,EACtB,OAAO,oBAAI,IAAI,CAAC,QAAQ,OAAO,CAAC;AAAA,EAChC,UAAU,oBAAI,IAAI,CAAC,QAAQ,QAAQ,MAAM,OAAO,CAAC;AACnD;AAEO,SAAS,qBAAqB,OAA+B;AAClE,MAAI,CAAC,cAAc,KAAK,GAAG;AACzB,WAAO;AAAA,EACT;AACA,QAAM,OAAO,MAAM;AACnB,MAAI,OAAO,SAAS,YAAY,CAAC,oBAAoB,IAAI,IAAa,GAAG;AACvE,WAAO;AAAA,EACT;AACA,QAAM,UAAU,WAAW,OAAO,wBAAwB,IAAI,GAAG,qBAAqB,IAAI,IAAI;AAC9F,MAAI,QAAS,QAAO;AAEpB,MAAI,SAAS,QAAQ;AACnB,WAAO;AAAA,EACT;AACA,MAAI,SAAS,SAAS;AACpB,UAAM,eAAe,gBAAgB,MAAM,KAAK;AAChD,QAAI,aAAc,QAAO,qBAAqB,YAAY;AAC1D,WAAO;AAAA,EACT;AAEA,QAAM,cAAc,gBAAgB,MAAM,IAAI;AAC9C,MAAI,YAAa,QAAO,6BAA6B,WAAW;AAChE,QAAM,YAAY,gBAAgB,MAAM,EAAE;AAC1C,MAAI,UAAW,QAAO,2BAA2B,SAAS;AAC1D,QAAM,QAAQ,MAAM;AACpB,MAAI,OAAO,UAAU,YAAY,CAAC,OAAO,UAAU,KAAK,KAAK,QAAQ,KAAK,QAAQ,KAAK;AACrF,WAAO;AAAA,EACT;AACA,SAAO;AACT;AAEA,SAAS,mBACP,WACA,KACA,SACA,OACe;AACf,MAAI,UAAU,GAAG,MAAM,OAAW,QAAO;AACzC,QAAM,SAAS,UAAU,GAAG;AAC5B,MAAI,OAAO,WAAW,YAAY,CAAC,QAAQ,IAAI,MAAM,GAAG;AACtD,WAAO,GAAG,KAAK,mBAAmB,CAAC,GAAG,OAAO,EAAE,IAAI,CAAC,UAAU,IAAI,KAAK,GAAG,EAAE,KAAK,IAAI,CAAC;AAAA,EACxF;AACA,SAAO;AACT;AAEA,SAAS,oBAAoB,WAA0B,KAAa,OAA8B;AAChG,MAAI,UAAU,GAAG,MAAM,OAAW,QAAO;AACzC,QAAM,UAAU,gBAAgB,UAAU,GAAG,CAAC;AAC9C,MAAI,QAAS,QAAO,GAAG,KAAK,KAAK,OAAO;AACxC,SAAO;AACT;AAEA,SAAS,yBAAyB,WAA0B,KAAa,OAA8B;AACrG,MAAI,UAAU,GAAG,MAAM,OAAW,QAAO;AACzC,QAAM,UAAU,qBAAqB,UAAU,GAAG,CAAC;AACnD,MAAI,QAAS,QAAO,GAAG,KAAK,KAAK,OAAO;AACxC,SAAO;AACT;AAEA,MAAM,aAAkC,oBAAI,IAAI;AAAA,EAC9C;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAQM,SAAS,oBAAoB,OAA+B;AACjE,MAAI,CAAC,cAAc,KAAK,GAAG;AACzB,WAAO;AAAA,EACT;AACA,QAAM,UAAU,WAAW,OAAO,WAAW,iBAAiB;AAC9D,MAAI,QAAS,QAAO;AACpB,MAAI,OAAO,MAAM,YAAY,YAAY,CAAC,YAAY,KAAK,MAAM,OAAO,GAAG;AACzE,WAAO;AAAA,EACT;AACA,MAAI,MAAM,QAAQ,WAAc,OAAO,MAAM,QAAQ,YAAY,MAAM,IAAI,SAAS,MAAM;AACxF,WAAO;AAAA,EACT;AACA,SACE,mBAAmB,OAAO,SAAS,eAAe,uBAAuB,KACtE,mBAAmB,OAAO,QAAQ,cAAc,sBAAsB;AAE7E;AAEO,SAAS,gBAAgB,OAA+B;AAC7D,MAAI,CAAC,cAAc,KAAK,GAAG;AACzB,WAAO;AAAA,EACT;AACA,QAAM,UAAU,WAAW,OAAO,YAAY,YAAY;AAC1D,MAAI,QAAS,QAAO;AAEpB,SACE,yBAAyB,OAAO,cAAc,uBAAuB,KAClE,oBAAoB,OAAO,WAAW,oBAAoB,KAC1D,oBAAoB,OAAO,cAAc,uBAAuB,KAChE,oBAAoB,OAAO,aAAa,sBAAsB,KAC9D,oBAAoB,OAAO,cAAc,uBAAuB,KAChE,mBAAmB,OAAO,eAAe,gBAAgB,wBAAwB,KACjF,oBAAoB,OAAO,UAAU,mBAAmB,KACxD,oBAAoB,OAAO,UAAU,mBAAmB,KACxD,mBAAmB,OAAO,cAAc,gBAAgB,uBAAuB,KAC/E,mBAAmB,OAAO,aAAa,eAAe,sBAAsB,KAC5E,mBAAmB,OAAO,UAAU,iBAAiB,mBAAmB,KACxE,mBAAmB,OAAO,gBAAgB,kBAAkB,yBAAyB,MACpF,MAAM,SAAS,SAAY,oBAAoB,MAAM,IAAI,IAAI;AAErE;AAEA,MAAM,qBAA0C,oBAAI,IAAI;AAAA,EACtD;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAEM,SAAS,uBAAuB,OAA+B;AACpE,MAAI,CAAC,cAAc,KAAK,GAAG;AACzB,WAAO;AAAA,EACT;AACA,QAAM,UAAU,WAAW,OAAO,oBAAoB,iBAAiB;AACvE,MAAI,QAAS,QAAO;AAEpB,QAAM,oBAAoB,yBAAyB,OAAO,cAAc,0BAA0B;AAClG,MAAI,kBAAmB,QAAO;AAC9B,QAAM,oBAAoB,oBAAoB,OAAO,cAAc,0BAA0B;AAC7F,MAAI,kBAAmB,QAAO;AAC9B,QAAM,iBAAiB,mBAAmB,OAAO,WAAW,gBAAgB,uBAAuB;AACnG,MAAI,eAAgB,QAAO;AAC3B,QAAM,gBAAgB,mBAAmB,OAAO,UAAU,iBAAiB,sBAAsB;AACjG,MAAI,cAAe,QAAO;AAC1B,QAAM,gBAAgB,mBAAmB,OAAO,UAAU,iBAAiB,sBAAsB;AACjG,MAAI,cAAe,QAAO;AAC1B,MAAI,MAAM,SAAS,UAAa,OAAO,MAAM,SAAS,WAAW;AAC/D,WAAO;AAAA,EACT;AACA,QAAM,eAAe,mBAAmB,OAAO,SAAS,eAAe,qBAAqB;AAC5F,MAAI,aAAc,QAAO;AACzB,SAAO;AACT;AAEA,MAAM,mBAAwC,oBAAI,IAAI;AAAA,EACpD;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAEM,SAAS,qBAAqB,OAA+B;AAClE,MAAI,CAAC,cAAc,KAAK,GAAG;AACzB,WAAO;AAAA,EACT;AACA,QAAM,UAAU,WAAW,OAAO,kBAAkB,YAAY;AAChE,MAAI,QAAS,QAAO;AAEpB,SACE,mBAAmB,OAAO,eAAe,gBAAgB,wBAAwB,KAC9E,oBAAoB,OAAO,cAAc,uBAAuB,KAChE,oBAAoB,OAAO,aAAa,sBAAsB,KAC9D,oBAAoB,OAAO,UAAU,mBAAmB,KACxD,mBAAmB,OAAO,SAAS,eAAe,kBAAkB;AAE3E;",
+  "names": []
+}

package/dist/modules/forms/services/access-audit-logger.js

@@ -0,0 +1,179 @@
+import { FormAccessAudit } from "../data/entities.js";
+const DEFAULT_MAX_BUFFER_SIZE = 100;
+class BatchingAccessAuditLogger {
+  static {
+    this.buffer = [];
+  }
+  static {
+    this.timer = null;
+  }
+  static {
+    this.flushing = null;
+  }
+  static {
+    this.activeEmFactory = null;
+  }
+  constructor(options) {
+    this.emFactory = options.emFactory;
+    this.batchMs = Number.isFinite(options.batchMs) && options.batchMs > 0 ? Math.floor(options.batchMs) : 0;
+    this.maxBufferSize = options.maxBufferSize && options.maxBufferSize > 0 ? Math.floor(options.maxBufferSize) : DEFAULT_MAX_BUFFER_SIZE;
+    this.logger = options.logger;
+    this.now = options.now ?? (() => /* @__PURE__ */ new Date());
+  }
+  async log(em, event) {
+    if (this.batchMs === 0) {
+      await this.writeSync(em, event);
+      return;
+    }
+    this.enqueue(event);
+  }
+  /** Buffers a single event (non-blocking) and arms the flush timer. */
+  enqueue(event) {
+    BatchingAccessAuditLogger.activeEmFactory = this.emFactory;
+    BatchingAccessAuditLogger.activeLogger = this.logger;
+    BatchingAccessAuditLogger.buffer.push({ ...event, accessedAt: this.now() });
+    if (BatchingAccessAuditLogger.buffer.length >= this.maxBufferSize) {
+      void this.flush();
+      return;
+    }
+    if (BatchingAccessAuditLogger.timer === null) {
+      BatchingAccessAuditLogger.timer = setTimeout(() => {
+        void this.flush();
+      }, this.batchMs);
+      const timer = BatchingAccessAuditLogger.timer;
+      timer.unref?.();
+    }
+  }
+  /**
+   * Drains the shared buffer and persists it as a single bulk insert on a fresh
+   * EM. Idempotent w.r.t. concurrent callers: a single in-flight flush is shared.
+   * Fail-soft — a failed insert is logged and the events are dropped (audit is
+   * best-effort; correctness never blocks a read).
+   */
+  async flush() {
+    if (BatchingAccessAuditLogger.timer !== null) {
+      clearTimeout(BatchingAccessAuditLogger.timer);
+      BatchingAccessAuditLogger.timer = null;
+    }
+    if (BatchingAccessAuditLogger.flushing) {
+      await BatchingAccessAuditLogger.flushing;
+      if (BatchingAccessAuditLogger.buffer.length === 0) return;
+    }
+    const run = this.drain();
+    BatchingAccessAuditLogger.flushing = run;
+    try {
+      await run;
+    } finally {
+      if (BatchingAccessAuditLogger.flushing === run) {
+        BatchingAccessAuditLogger.flushing = null;
+      }
+    }
+  }
+  async drain() {
+    const batch = BatchingAccessAuditLogger.buffer.splice(0, BatchingAccessAuditLogger.buffer.length);
+    if (batch.length === 0) return;
+    const factory = BatchingAccessAuditLogger.activeEmFactory ?? this.emFactory;
+    try {
+      const em = await factory();
+      for (const event of batch) {
+        em.persist(
+          em.create(FormAccessAudit, {
+            organizationId: event.organizationId,
+            submissionId: event.submissionId,
+            accessedBy: event.accessedBy,
+            accessPurpose: event.accessPurpose,
+            ip: event.ip ?? null,
+            ua: event.ua ?? null,
+            revisionId: event.revisionId ?? null,
+            accessedAt: event.accessedAt
+          })
+        );
+      }
+      await em.flush();
+    } catch (error) {
+      const logger = BatchingAccessAuditLogger.activeLogger ?? this.logger;
+      logger?.warn?.(
+        {
+          event: "forms.access_audit.flush_failed",
+          dropped: batch.length,
+          message: error instanceof Error ? error.message : "Unknown audit flush error"
+        },
+        "forms access-audit batch flush failed (events dropped)"
+      );
+    }
+  }
+  async writeSync(em, event) {
+    try {
+      const row = em.create(FormAccessAudit, {
+        organizationId: event.organizationId,
+        submissionId: event.submissionId,
+        accessedBy: event.accessedBy,
+        accessPurpose: event.accessPurpose,
+        ip: event.ip ?? null,
+        ua: event.ua ?? null,
+        revisionId: event.revisionId ?? null,
+        accessedAt: this.now()
+      });
+      em.persist(row);
+      await em.flush();
+    } catch (error) {
+      this.logger?.warn?.(
+        {
+          event: "forms.access_audit.write_failed",
+          submissionId: event.submissionId,
+          message: error instanceof Error ? error.message : "Unknown audit write error"
+        },
+        "forms access-audit synchronous write failed (swallowed)"
+      );
+    }
+  }
+  /** Test-only: number of events currently buffered (shared singleton). */
+  static get bufferedCount() {
+    return BatchingAccessAuditLogger.buffer.length;
+  }
+  /** Test-only: drop buffered events + timer without persisting. */
+  static reset() {
+    if (BatchingAccessAuditLogger.timer !== null) {
+      clearTimeout(BatchingAccessAuditLogger.timer);
+      BatchingAccessAuditLogger.timer = null;
+    }
+    BatchingAccessAuditLogger.buffer = [];
+    BatchingAccessAuditLogger.flushing = null;
+    BatchingAccessAuditLogger.activeEmFactory = null;
+    BatchingAccessAuditLogger.activeLogger = void 0;
+  }
+}
+class FormsAccessAuditLogger {
+  async log(em, event) {
+    const row = em.create(FormAccessAudit, {
+      organizationId: event.organizationId,
+      submissionId: event.submissionId,
+      accessedBy: event.accessedBy,
+      accessPurpose: event.accessPurpose,
+      ip: event.ip ?? null,
+      ua: event.ua ?? null,
+      revisionId: event.revisionId ?? null,
+      accessedAt: /* @__PURE__ */ new Date()
+    });
+    em.persist(row);
+    await em.flush();
+  }
+}
+class NoopAccessAuditLogger {
+  async log() {
+  }
+}
+function resolveAccessAuditBatchMs(env = process.env) {
+  const raw = env.FORMS_ACCESS_AUDIT_BATCH_MS;
+  if (raw == null || raw.trim() === "") return 0;
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed < 0) return 0;
+  return parsed;
+}
+export {
+  BatchingAccessAuditLogger,
+  FormsAccessAuditLogger,
+  NoopAccessAuditLogger,
+  resolveAccessAuditBatchMs
+};
+//# sourceMappingURL=access-audit-logger.js.map

package/dist/modules/forms/services/access-audit-logger.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/forms/services/access-audit-logger.ts"],
+  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/postgresql'\nimport { FormAccessAudit, type FormAccessAuditPurpose } from '../data/entities'\n\n/**\n * Phase 2b \u2014 admin-surface access audit (T7 compliance polish).\n *\n * Writes one row per admin read or audit-bearing mutation against a\n * submission. Runtime (patient) reads of one's own submission do NOT call\n * this logger (R1 posture per phase 1c spec).\n *\n * Two write postures, selected by `FORMS_ACCESS_AUDIT_BATCH_MS`:\n *\n *   - `0` (default for tests / deterministic admin reads) \u21D2 synchronous mode:\n *     each `log(em, event)` inserts + flushes immediately on the request's own\n *     EntityManager (the original phase 2b behaviour, preserved verbatim).\n *\n *   - `> 0` \u21D2 async-batched mode: events are buffered in a module-level\n *     singleton queue and flushed as a single bulk insert on a timer (every\n *     `FORMS_ACCESS_AUDIT_BATCH_MS`) or when the buffer hits a size cap. The\n *     request `em` is request-scoped and likely gone by flush time, so the\n *     flusher forks a FRESH EntityManager from a captured factory. Every scope\n *     field needed to write the row is captured on the buffered event at\n *     enqueue time \u2014 nothing is read back from the (possibly disposed) request\n *     context at flush time.\n *\n * Fail-soft everywhere: a failed insert (sync or batched) is logged and\n * swallowed. An audit write MUST NEVER break the read it accompanies.\n */\nexport type AccessAuditEvent = {\n  organizationId: string\n  submissionId: string\n  accessedBy: string\n  accessPurpose: FormAccessAuditPurpose\n  ip?: string | null\n  ua?: string | null\n  revisionId?: string | null\n}\n\nexport interface AccessAuditLogger {\n  log(em: EntityManager, event: AccessAuditEvent): Promise<void>\n}\n\ntype BufferedAuditEvent = AccessAuditEvent & { accessedAt: Date }\n\ntype AuditLoggerLogger = {\n  warn?: (data: Record<string, unknown>, message: string) => void\n}\n\nexport type BatchingAccessAuditLoggerOptions = {\n  /**\n   * Forks a fresh EntityManager for the deferred bulk insert. MUST return an\n   * EM bound to the same ORM the request used (e.g. `(await getOrm()).em.fork()`).\n   * Synchronous mode never calls this.\n   */\n  emFactory: () => Promise<EntityManager> | EntityManager\n  /** Flush interval in ms. `0` \u21D2 synchronous mode (no buffering, no timer). */\n  batchMs: number\n  /** Flush early once the buffer reaches this many events. Default 100. */\n  maxBufferSize?: number\n  /** Optional structured logger for fail-soft diagnostics. */\n  logger?: AuditLoggerLogger\n  /** Override the clock for tests. */\n  now?: () => Date\n}\n\nconst DEFAULT_MAX_BUFFER_SIZE = 100\n\n/**\n * Async-batched access audit logger.\n *\n * Architectural note: the DI container is request-scoped, so this logger is\n * registered once per request. To make batching span requests it is backed by\n * a MODULE-LEVEL singleton buffer + timer (the static members below). All\n * request-scoped instances share that buffer and the fresh-EM factory captured\n * by the first instance, so events from many requests coalesce into one bulk\n * insert. In synchronous mode (`batchMs === 0`) the singleton is never touched.\n */\nexport class BatchingAccessAuditLogger implements AccessAuditLogger {\n  private static buffer: BufferedAuditEvent[] = []\n  private static timer: ReturnType<typeof setTimeout> | null = null\n  private static flushing: Promise<void> | null = null\n  private static activeEmFactory: BatchingAccessAuditLoggerOptions['emFactory'] | null = null\n  private static activeLogger: AuditLoggerLogger | undefined\n\n  private readonly emFactory: BatchingAccessAuditLoggerOptions['emFactory']\n  private readonly batchMs: number\n  private readonly maxBufferSize: number\n  private readonly logger?: AuditLoggerLogger\n  private readonly now: () => Date\n\n  constructor(options: BatchingAccessAuditLoggerOptions) {\n    this.emFactory = options.emFactory\n    this.batchMs = Number.isFinite(options.batchMs) && options.batchMs > 0 ? Math.floor(options.batchMs) : 0\n    this.maxBufferSize =\n      options.maxBufferSize && options.maxBufferSize > 0 ? Math.floor(options.maxBufferSize) : DEFAULT_MAX_BUFFER_SIZE\n    this.logger = options.logger\n    this.now = options.now ?? (() => new Date())\n  }\n\n  async log(em: EntityManager, event: AccessAuditEvent): Promise<void> {\n    if (this.batchMs === 0) {\n      await this.writeSync(em, event)\n      return\n    }\n    this.enqueue(event)\n  }\n\n  /** Buffers a single event (non-blocking) and arms the flush timer. */\n  private enqueue(event: AccessAuditEvent): void {\n    BatchingAccessAuditLogger.activeEmFactory = this.emFactory\n    BatchingAccessAuditLogger.activeLogger = this.logger\n    BatchingAccessAuditLogger.buffer.push({ ...event, accessedAt: this.now() })\n\n    if (BatchingAccessAuditLogger.buffer.length >= this.maxBufferSize) {\n      void this.flush()\n      return\n    }\n    if (BatchingAccessAuditLogger.timer === null) {\n      BatchingAccessAuditLogger.timer = setTimeout(() => {\n        void this.flush()\n      }, this.batchMs)\n      // Never keep the process alive for a pending audit flush.\n      const timer = BatchingAccessAuditLogger.timer as unknown as { unref?: () => void }\n      timer.unref?.()\n    }\n  }\n\n  /**\n   * Drains the shared buffer and persists it as a single bulk insert on a fresh\n   * EM. Idempotent w.r.t. concurrent callers: a single in-flight flush is shared.\n   * Fail-soft \u2014 a failed insert is logged and the events are dropped (audit is\n   * best-effort; correctness never blocks a read).\n   */\n  async flush(): Promise<void> {\n    if (BatchingAccessAuditLogger.timer !== null) {\n      clearTimeout(BatchingAccessAuditLogger.timer)\n      BatchingAccessAuditLogger.timer = null\n    }\n    if (BatchingAccessAuditLogger.flushing) {\n      await BatchingAccessAuditLogger.flushing\n      // A second drain in case events landed during the awaited flush.\n      if (BatchingAccessAuditLogger.buffer.length === 0) return\n    }\n\n    const run = this.drain()\n    BatchingAccessAuditLogger.flushing = run\n    try {\n      await run\n    } finally {\n      if (BatchingAccessAuditLogger.flushing === run) {\n        BatchingAccessAuditLogger.flushing = null\n      }\n    }\n  }\n\n  private async drain(): Promise<void> {\n    const batch = BatchingAccessAuditLogger.buffer.splice(0, BatchingAccessAuditLogger.buffer.length)\n    if (batch.length === 0) return\n\n    const factory = BatchingAccessAuditLogger.activeEmFactory ?? this.emFactory\n    try {\n      const em = await factory()\n      for (const event of batch) {\n        em.persist(\n          em.create(FormAccessAudit, {\n            organizationId: event.organizationId,\n            submissionId: event.submissionId,\n            accessedBy: event.accessedBy,\n            accessPurpose: event.accessPurpose,\n            ip: event.ip ?? null,\n            ua: event.ua ?? null,\n            revisionId: event.revisionId ?? null,\n            accessedAt: event.accessedAt,\n          }),\n        )\n      }\n      await em.flush()\n    } catch (error) {\n      const logger = BatchingAccessAuditLogger.activeLogger ?? this.logger\n      logger?.warn?.(\n        {\n          event: 'forms.access_audit.flush_failed',\n          dropped: batch.length,\n          message: error instanceof Error ? error.message : 'Unknown audit flush error',\n        },\n        'forms access-audit batch flush failed (events dropped)',\n      )\n    }\n  }\n\n  private async writeSync(em: EntityManager, event: AccessAuditEvent): Promise<void> {\n    try {\n      const row = em.create(FormAccessAudit, {\n        organizationId: event.organizationId,\n        submissionId: event.submissionId,\n        accessedBy: event.accessedBy,\n        accessPurpose: event.accessPurpose,\n        ip: event.ip ?? null,\n        ua: event.ua ?? null,\n        revisionId: event.revisionId ?? null,\n        accessedAt: this.now(),\n      })\n      em.persist(row)\n      await em.flush()\n    } catch (error) {\n      this.logger?.warn?.(\n        {\n          event: 'forms.access_audit.write_failed',\n          submissionId: event.submissionId,\n          message: error instanceof Error ? error.message : 'Unknown audit write error',\n        },\n        'forms access-audit synchronous write failed (swallowed)',\n      )\n    }\n  }\n\n  /** Test-only: number of events currently buffered (shared singleton). */\n  static get bufferedCount(): number {\n    return BatchingAccessAuditLogger.buffer.length\n  }\n\n  /** Test-only: drop buffered events + timer without persisting. */\n  static reset(): void {\n    if (BatchingAccessAuditLogger.timer !== null) {\n      clearTimeout(BatchingAccessAuditLogger.timer)\n      BatchingAccessAuditLogger.timer = null\n    }\n    BatchingAccessAuditLogger.buffer = []\n    BatchingAccessAuditLogger.flushing = null\n    BatchingAccessAuditLogger.activeEmFactory = null\n    BatchingAccessAuditLogger.activeLogger = undefined\n  }\n}\n\n/**\n * Synchronous access audit logger (legacy / `FORMS_ACCESS_AUDIT_BATCH_MS=0`).\n * Each call inserts + flushes immediately on the request's own EntityManager.\n * Retained as a standalone implementation so callers/tests can opt into\n * deterministic synchronous behaviour without constructing the batching logger.\n */\nexport class FormsAccessAuditLogger implements AccessAuditLogger {\n  async log(em: EntityManager, event: AccessAuditEvent): Promise<void> {\n    const row = em.create(FormAccessAudit, {\n      organizationId: event.organizationId,\n      submissionId: event.submissionId,\n      accessedBy: event.accessedBy,\n      accessPurpose: event.accessPurpose,\n      ip: event.ip ?? null,\n      ua: event.ua ?? null,\n      revisionId: event.revisionId ?? null,\n      accessedAt: new Date(),\n    })\n    em.persist(row)\n    await em.flush()\n  }\n}\n\nexport class NoopAccessAuditLogger implements AccessAuditLogger {\n  async log(): Promise<void> {\n    /* no-op \u2014 used in tests and contexts where audit is intentionally suppressed */\n  }\n}\n\n/**\n * Resolves `FORMS_ACCESS_AUDIT_BATCH_MS` from env. Default `0` (synchronous) so\n * existing tests and deterministic admin reads keep today's behaviour. Any\n * positive integer enables async-batched writes with that flush interval.\n */\nexport function resolveAccessAuditBatchMs(env: NodeJS.ProcessEnv = process.env): number {\n  const raw = env.FORMS_ACCESS_AUDIT_BATCH_MS\n  if (raw == null || raw.trim() === '') return 0\n  const parsed = Number.parseInt(raw, 10)\n  if (!Number.isFinite(parsed) || parsed < 0) return 0\n  return parsed\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/modules/forms/services/analytics-service.js

@@ -0,0 +1,306 @@
+import {
+  FormSubmission,
+  FormSubmissionRevision,
+  FormVersion
+} from "../data/entities.js";
+import { resolveSectionViews } from "./form-version-compiler.js";
+const ENUMERABLE_FIELD_TYPES = ["select_one", "select_many", "boolean", "scale"];
+const DEFAULT_ANALYTICS_SCAN_LIMIT = 1e3;
+const MAX_ANALYTICS_SCAN_LIMIT = 5e3;
+const ALL_STATUSES = ["draft", "submitted", "reopened", "archived"];
+class AnalyticsService {
+  constructor(options) {
+    this.emFactory = options.emFactory;
+    this.compiler = options.compiler;
+    this.encryption = options.encryption;
+  }
+  async computeFormAnalytics(args) {
+    const em = this.emFactory();
+    const limit = clampLimit(args.limit);
+    const versions = await em.find(FormVersion, {
+      formId: args.formId,
+      organizationId: args.organizationId,
+      tenantId: args.tenantId
+    });
+    if (versions.length === 0) {
+      return emptyAnalytics(args, limit);
+    }
+    const versionById = /* @__PURE__ */ new Map();
+    for (const version of versions) versionById.set(version.id, version);
+    const versionIds = versions.map((version) => version.id);
+    const where = {
+      organizationId: args.organizationId,
+      tenantId: args.tenantId,
+      deletedAt: null,
+      formVersionId: { $in: versionIds }
+    };
+    const firstSavedAtFilter = buildRangeFilter(args.from ?? null, args.to ?? null);
+    if (firstSavedAtFilter) where.firstSavedAt = firstSavedAtFilter;
+    const submissions = await em.find(FormSubmission, where, {
+      orderBy: { firstSavedAt: "desc" },
+      limit
+    });
+    const capped = submissions.length >= limit;
+    const funnel = buildFunnel(submissions);
+    const volume = buildVolume(submissions);
+    const timeToComplete = buildTimeToComplete(submissions);
+    const compiledByVersion = /* @__PURE__ */ new Map();
+    const sectionsByVersion = /* @__PURE__ */ new Map();
+    for (const version of versions) {
+      const compiled = this.compiler.compile({
+        id: version.id,
+        updatedAt: version.updatedAt,
+        schema: version.schema,
+        uiSchema: version.uiSchema
+      });
+      compiledByVersion.set(version.id, compiled);
+      sectionsByVersion.set(version.id, resolveSectionViews(version.schema));
+    }
+    const fieldAccumulator = new FieldStatsAccumulator();
+    const dropOffAccumulator = /* @__PURE__ */ new Map();
+    for (const submission of submissions) {
+      const compiled = compiledByVersion.get(submission.formVersionId);
+      if (!compiled) continue;
+      const revision = submission.currentRevisionId ? await em.findOne(FormSubmissionRevision, {
+        id: submission.currentRevisionId,
+        submissionId: submission.id,
+        organizationId: args.organizationId
+      }) : null;
+      const decoded = revision ? await this.decodeRevision(args.organizationId, revision) : {};
+      fieldAccumulator.tally(compiled.fieldIndex, decoded);
+      const isDraft = submission.status === "draft" || submission.status === "reopened";
+      if (isDraft) {
+        const sections = sectionsByVersion.get(submission.formVersionId) ?? [];
+        const reached = furthestSectionReached(sections, compiled.fieldIndex, decoded);
+        if (reached) dropOffAccumulator.set(reached, (dropOffAccumulator.get(reached) ?? 0) + 1);
+      }
+    }
+    const dropOff = Array.from(dropOffAccumulator.entries()).map(([sectionKey, count]) => ({ sectionKey, count })).sort((a, b) => b.count - a.count);
+    return {
+      formId: args.formId,
+      window: {
+        from: args.from ? args.from.toISOString() : null,
+        to: args.to ? args.to.toISOString() : null
+      },
+      scan: { limit, scanned: submissions.length, capped },
+      funnel,
+      volume,
+      timeToComplete,
+      fields: fieldAccumulator.toStats(),
+      dropOff
+    };
+  }
+  async decodeRevision(organizationId, revision) {
+    const ciphertext = ensureBuffer(revision.data);
+    if (ciphertext.length === 0) return {};
+    const plain = await this.encryption.decrypt(organizationId, ciphertext);
+    if (plain.length === 0) return {};
+    try {
+      const parsed = JSON.parse(plain.toString("utf8"));
+      return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+    } catch {
+      return {};
+    }
+  }
+}
+class FieldStatsAccumulator {
+  constructor() {
+    this.entries = /* @__PURE__ */ new Map();
+  }
+  tally(fieldIndex, decoded) {
+    for (const descriptor of Object.values(fieldIndex)) {
+      if (descriptor.type === "info_block") continue;
+      const entry = this.ensure(descriptor);
+      const value = decoded[descriptor.key];
+      if (isBlank(value)) {
+        entry.blank += 1;
+        continue;
+      }
+      entry.answered += 1;
+      if (!entry.enumerable || entry.sensitive) continue;
+      for (const token of enumerableTokens(value)) {
+        entry.choices.set(token, (entry.choices.get(token) ?? 0) + 1);
+      }
+    }
+  }
+  ensure(descriptor) {
+    const existing = this.entries.get(descriptor.key);
+    if (existing) return existing;
+    const entry = {
+      type: descriptor.type,
+      sensitive: descriptor.sensitive,
+      enumerable: ENUMERABLE_FIELD_TYPES.includes(descriptor.type),
+      answered: 0,
+      blank: 0,
+      choices: /* @__PURE__ */ new Map()
+    };
+    this.entries.set(descriptor.key, entry);
+    return entry;
+  }
+  toStats() {
+    const stats = [];
+    for (const [fieldKey, entry] of this.entries.entries()) {
+      const stat = {
+        fieldKey,
+        type: entry.type,
+        sensitive: entry.sensitive,
+        answered: entry.answered,
+        blank: entry.blank
+      };
+      if (entry.enumerable && !entry.sensitive) {
+        stat.choices = Array.from(entry.choices.entries()).map(([value, count]) => ({ value, count })).sort((a, b) => b.count - a.count);
+      }
+      stats.push(stat);
+    }
+    return stats;
+  }
+}
+function buildFunnel(submissions) {
+  const byStatus = {
+    draft: 0,
+    submitted: 0,
+    reopened: 0,
+    archived: 0,
+    anonymized: 0
+  };
+  let started = 0;
+  let submitted = 0;
+  for (const submission of submissions) {
+    started += 1;
+    if (submission.anonymizedAt) byStatus.anonymized += 1;
+    const status = submission.status;
+    if (ALL_STATUSES.includes(status)) byStatus[status] += 1;
+    if (submission.submittedAt) submitted += 1;
+  }
+  const completionRate = started > 0 ? roundTo(submitted / started, 4) : 0;
+  return { started, submitted, completionRate, byStatus };
+}
+function buildVolume(submissions) {
+  const buckets = /* @__PURE__ */ new Map();
+  for (const submission of submissions) {
+    const startKey = dayKey(submission.firstSavedAt);
+    if (startKey) {
+      const bucket = buckets.get(startKey) ?? { started: 0, submitted: 0 };
+      bucket.started += 1;
+      buckets.set(startKey, bucket);
+    }
+    if (submission.submittedAt) {
+      const submitKey = dayKey(submission.submittedAt);
+      if (submitKey) {
+        const bucket = buckets.get(submitKey) ?? { started: 0, submitted: 0 };
+        bucket.submitted += 1;
+        buckets.set(submitKey, bucket);
+      }
+    }
+  }
+  return Array.from(buckets.entries()).map(([date, value]) => ({ date, started: value.started, submitted: value.submitted })).sort((a, b) => a.date.localeCompare(b.date));
+}
+function buildTimeToComplete(submissions) {
+  const durations = [];
+  for (const submission of submissions) {
+    if (!submission.submittedAt || !submission.firstSavedAt) continue;
+    const seconds = (submission.submittedAt.getTime() - submission.firstSavedAt.getTime()) / 1e3;
+    if (Number.isFinite(seconds) && seconds >= 0) durations.push(seconds);
+  }
+  if (durations.length === 0) {
+    return { sampleSize: 0, medianSeconds: null, averageSeconds: null };
+  }
+  const sorted = [...durations].sort((a, b) => a - b);
+  const sum = sorted.reduce((acc, value) => acc + value, 0);
+  return {
+    sampleSize: sorted.length,
+    medianSeconds: roundTo(median(sorted), 2),
+    averageSeconds: roundTo(sum / sorted.length, 2)
+  };
+}
+function furthestSectionReached(sections, fieldIndex, decoded) {
+  let reached = null;
+  for (const section of sections) {
+    const hasAnswer = section.fieldKeys.some((fieldKey) => {
+      if (!fieldIndex[fieldKey]) return false;
+      return !isBlank(decoded[fieldKey]);
+    });
+    if (hasAnswer) reached = section.key;
+  }
+  return reached;
+}
+function emptyAnalytics(args, limit) {
+  return {
+    formId: args.formId,
+    window: {
+      from: args.from ? args.from.toISOString() : null,
+      to: args.to ? args.to.toISOString() : null
+    },
+    scan: { limit, scanned: 0, capped: false },
+    funnel: {
+      started: 0,
+      submitted: 0,
+      completionRate: 0,
+      byStatus: { draft: 0, submitted: 0, reopened: 0, archived: 0, anonymized: 0 }
+    },
+    volume: [],
+    timeToComplete: { sampleSize: 0, medianSeconds: null, averageSeconds: null },
+    fields: [],
+    dropOff: []
+  };
+}
+function clampLimit(limit) {
+  if (typeof limit !== "number" || !Number.isFinite(limit) || limit <= 0) {
+    return DEFAULT_ANALYTICS_SCAN_LIMIT;
+  }
+  return Math.min(Math.floor(limit), MAX_ANALYTICS_SCAN_LIMIT);
+}
+function buildRangeFilter(from, to) {
+  const filter = {};
+  if (from) filter.$gte = from;
+  if (to) filter.$lte = to;
+  return Object.keys(filter).length > 0 ? filter : null;
+}
+function isBlank(value) {
+  if (value === null || value === void 0) return true;
+  if (typeof value === "string") return value.trim().length === 0;
+  if (Array.isArray(value)) return value.length === 0;
+  return false;
+}
+function enumerableTokens(value) {
+  if (Array.isArray(value)) {
+    return value.filter((entry) => entry !== null && entry !== void 0).map((entry) => stringifyToken(entry));
+  }
+  return [stringifyToken(value)];
+}
+function stringifyToken(value) {
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number") return String(value);
+  if (typeof value === "string") return value;
+  return JSON.stringify(value);
+}
+function dayKey(date) {
+  if (!(date instanceof Date) || Number.isNaN(date.getTime())) return null;
+  return date.toISOString().slice(0, 10);
+}
+function median(sorted) {
+  const mid = Math.floor(sorted.length / 2);
+  if (sorted.length % 2 === 0) return (sorted[mid - 1] + sorted[mid]) / 2;
+  return sorted[mid];
+}
+function roundTo(value, decimals) {
+  const factor = 10 ** decimals;
+  return Math.round(value * factor) / factor;
+}
+function ensureBuffer(value) {
+  if (Buffer.isBuffer(value)) return value;
+  if (value instanceof Uint8Array) return Buffer.from(value);
+  if (typeof value === "string") return Buffer.from(value, "binary");
+  return Buffer.alloc(0);
+}
+export {
+  AnalyticsService,
+  DEFAULT_ANALYTICS_SCAN_LIMIT,
+  ENUMERABLE_FIELD_TYPES,
+  MAX_ANALYTICS_SCAN_LIMIT,
+  buildFunnel,
+  buildTimeToComplete,
+  buildVolume,
+  furthestSectionReached
+};
+//# sourceMappingURL=analytics-service.js.map

package/dist/modules/forms/services/analytics-service.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/forms/services/analytics-service.ts"],
+  "sourcesContent": ["/**\n * Phase 3 Track B \u2014 Form analytics.\n *\n * Computes AGGREGATE, PII-safe metrics across every version of a form's\n * submissions. The service is the only place that decrypts revision payloads,\n * and it does so exclusively to TALLY enumerable answers \u2014 it never returns a\n * decrypted value. The response carries counts only.\n *\n * PII-safety invariants (R-3-2 / R-3-5 mitigations):\n *  - Every read is scoped by `organizationId` + `tenantId`.\n *  - Per-field value distributions are emitted ONLY for non-sensitive,\n *    enumerable field types (`select_one`, `select_many`, `boolean`, `scale`).\n *  - Any field flagged `x-om-sensitive: true` is excluded from value\n *    distributions entirely \u2014 only its answered/blank counts are reported.\n *  - Free-text / non-enumerable fields never contribute raw values \u2014 only\n *    answered/blank counts.\n *  - Decryption happens server-side to count; decrypted values never leave\n *    this service and are never logged.\n *  - Aggregates are per-form / per-window \u2014 never broken down by subject.\n *\n * Cost control: the scan is capped at the most-recent N submissions\n * (`limit`, default 1000, max 5000). The cap and whether it was hit are echoed\n * in the response so callers can surface a \"partial\" indicator.\n */\n\nimport type { EntityManager } from '@mikro-orm/postgresql'\nimport {\n  FormSubmission,\n  FormSubmissionRevision,\n  FormVersion,\n  type FormSubmissionStatus,\n} from '../data/entities'\nimport type { EncryptionService } from './encryption-service'\nimport type { FormVersionCompiler, FieldDescriptor } from './form-version-compiler'\nimport { resolveSectionViews } from './form-version-compiler'\n\nexport const ENUMERABLE_FIELD_TYPES = ['select_one', 'select_many', 'boolean', 'scale'] as const\nexport type EnumerableFieldType = (typeof ENUMERABLE_FIELD_TYPES)[number]\n\nexport const DEFAULT_ANALYTICS_SCAN_LIMIT = 1000\nexport const MAX_ANALYTICS_SCAN_LIMIT = 5000\n\ntype Scope = {\n  organizationId: string\n  tenantId: string\n}\n\nexport type AnalyticsArgs = Scope & {\n  formId: string\n  /** Inclusive lower bound on `firstSavedAt`. */\n  from?: Date | null\n  /** Inclusive upper bound on `firstSavedAt`. */\n  to?: Date | null\n  /** Cap on the number of (most-recent) submissions scanned. */\n  limit?: number | null\n}\n\nexport type FunnelMetrics = {\n  started: number\n  submitted: number\n  /** `submitted / started`, rounded to 4 decimals. `0` when nothing started. */\n  completionRate: number\n  byStatus: Record<FormSubmissionStatus | 'anonymized', number>\n}\n\nexport type VolumePoint = {\n  /** UTC day bucket, `YYYY-MM-DD`. */\n  date: string\n  started: number\n  submitted: number\n}\n\nexport type TimeToCompleteMetrics = {\n  /** Number of submitted submissions with a measurable duration. */\n  sampleSize: number\n  /** Median seconds from `firstSavedAt` \u2192 `submittedAt`. `null` when no sample. */\n  medianSeconds: number | null\n  /** Average seconds from `firstSavedAt` \u2192 `submittedAt`. `null` when no sample. */\n  averageSeconds: number | null\n}\n\nexport type FieldChoiceCount = {\n  /** Stringified option value chosen. */\n  value: string\n  count: number\n}\n\nexport type FieldResponseStats = {\n  fieldKey: string\n  type: string\n  sensitive: boolean\n  /** Submissions whose current revision had a non-empty answer for this field. */\n  answered: number\n  /** Scanned submissions that left this field blank. */\n  blank: number\n  /**\n   * Count distribution of chosen option values. Present ONLY for non-sensitive\n   * enumerable types; `undefined` for free-text / sensitive / non-enumerable\n   * fields (which only carry answered/blank counts).\n   */\n  choices?: FieldChoiceCount[]\n}\n\nexport type DropOffPoint = {\n  sectionKey: string\n  /** Non-submitted drafts whose furthest-reached section is this one. */\n  count: number\n}\n\nexport type FormAnalytics = {\n  formId: string\n  window: { from: string | null; to: string | null }\n  /** Whether the scan hit the cap (response may be partial). */\n  scan: { limit: number; scanned: number; capped: boolean }\n  funnel: FunnelMetrics\n  volume: VolumePoint[]\n  timeToComplete: TimeToCompleteMetrics\n  fields: FieldResponseStats[]\n  dropOff: DropOffPoint[]\n}\n\nexport type AnalyticsServiceOptions = {\n  emFactory: () => EntityManager\n  compiler: FormVersionCompiler\n  encryption: EncryptionService\n}\n\nconst ALL_STATUSES: Array<FormSubmissionStatus> = ['draft', 'submitted', 'reopened', 'archived']\n\nexport class AnalyticsService {\n  private readonly emFactory: () => EntityManager\n  private readonly compiler: FormVersionCompiler\n  private readonly encryption: EncryptionService\n\n  constructor(options: AnalyticsServiceOptions) {\n    this.emFactory = options.emFactory\n    this.compiler = options.compiler\n    this.encryption = options.encryption\n  }\n\n  async computeFormAnalytics(args: AnalyticsArgs): Promise<FormAnalytics> {\n    const em = this.emFactory()\n    const limit = clampLimit(args.limit)\n\n    const versions = await em.find(FormVersion, {\n      formId: args.formId,\n      organizationId: args.organizationId,\n      tenantId: args.tenantId,\n    })\n\n    if (versions.length === 0) {\n      return emptyAnalytics(args, limit)\n    }\n\n    const versionById = new Map<string, FormVersion>()\n    for (const version of versions) versionById.set(version.id, version)\n    const versionIds = versions.map((version) => version.id)\n\n    const where: Record<string, unknown> = {\n      organizationId: args.organizationId,\n      tenantId: args.tenantId,\n      deletedAt: null,\n      formVersionId: { $in: versionIds },\n    }\n    const firstSavedAtFilter = buildRangeFilter(args.from ?? null, args.to ?? null)\n    if (firstSavedAtFilter) where.firstSavedAt = firstSavedAtFilter\n\n    const submissions = await em.find(FormSubmission, where as never, {\n      orderBy: { firstSavedAt: 'desc' },\n      limit,\n    })\n    const capped = submissions.length >= limit\n\n    const funnel = buildFunnel(submissions)\n    const volume = buildVolume(submissions)\n    const timeToComplete = buildTimeToComplete(submissions)\n\n    const compiledByVersion = new Map<string, ReturnType<FormVersionCompiler['compile']>>()\n    const sectionsByVersion = new Map<string, ReturnType<typeof resolveSectionViews>>()\n    for (const version of versions) {\n      const compiled = this.compiler.compile({\n        id: version.id,\n        updatedAt: version.updatedAt,\n        schema: version.schema,\n        uiSchema: version.uiSchema,\n      })\n      compiledByVersion.set(version.id, compiled)\n      sectionsByVersion.set(version.id, resolveSectionViews(version.schema))\n    }\n\n    const fieldAccumulator = new FieldStatsAccumulator()\n    const dropOffAccumulator = new Map<string, number>()\n\n    for (const submission of submissions) {\n      const compiled = compiledByVersion.get(submission.formVersionId)\n      if (!compiled) continue\n      const revision = submission.currentRevisionId\n        ? await em.findOne(FormSubmissionRevision, {\n            id: submission.currentRevisionId,\n            submissionId: submission.id,\n            organizationId: args.organizationId,\n          })\n        : null\n      const decoded = revision ? await this.decodeRevision(args.organizationId, revision) : {}\n\n      fieldAccumulator.tally(compiled.fieldIndex, decoded)\n\n      const isDraft = submission.status === 'draft' || submission.status === 'reopened'\n      if (isDraft) {\n        const sections = sectionsByVersion.get(submission.formVersionId) ?? []\n        const reached = furthestSectionReached(sections, compiled.fieldIndex, decoded)\n        if (reached) dropOffAccumulator.set(reached, (dropOffAccumulator.get(reached) ?? 0) + 1)\n      }\n    }\n\n    const dropOff: DropOffPoint[] = Array.from(dropOffAccumulator.entries())\n      .map(([sectionKey, count]) => ({ sectionKey, count }))\n      .sort((a, b) => b.count - a.count)\n\n    return {\n      formId: args.formId,\n      window: {\n        from: args.from ? args.from.toISOString() : null,\n        to: args.to ? args.to.toISOString() : null,\n      },\n      scan: { limit, scanned: submissions.length, capped },\n      funnel,\n      volume,\n      timeToComplete,\n      fields: fieldAccumulator.toStats(),\n      dropOff,\n    }\n  }\n\n  private async decodeRevision(\n    organizationId: string,\n    revision: FormSubmissionRevision,\n  ): Promise<Record<string, unknown>> {\n    const ciphertext = ensureBuffer(revision.data)\n    if (ciphertext.length === 0) return {}\n    const plain = await this.encryption.decrypt(organizationId, ciphertext)\n    if (plain.length === 0) return {}\n    try {\n      const parsed = JSON.parse(plain.toString('utf8'))\n      return parsed && typeof parsed === 'object' && !Array.isArray(parsed)\n        ? (parsed as Record<string, unknown>)\n        : {}\n    } catch {\n      return {}\n    }\n  }\n}\n\n// ============================================================================\n// Field stats accumulator\n// ============================================================================\n\ntype FieldAccumulatorEntry = {\n  type: string\n  sensitive: boolean\n  enumerable: boolean\n  answered: number\n  blank: number\n  choices: Map<string, number>\n}\n\nclass FieldStatsAccumulator {\n  private readonly entries = new Map<string, FieldAccumulatorEntry>()\n\n  tally(fieldIndex: Record<string, FieldDescriptor>, decoded: Record<string, unknown>): void {\n    for (const descriptor of Object.values(fieldIndex)) {\n      if (descriptor.type === 'info_block') continue\n      const entry = this.ensure(descriptor)\n      const value = decoded[descriptor.key]\n      if (isBlank(value)) {\n        entry.blank += 1\n        continue\n      }\n      entry.answered += 1\n      // Only non-sensitive enumerable fields contribute a value distribution.\n      if (!entry.enumerable || entry.sensitive) continue\n      for (const token of enumerableTokens(value)) {\n        entry.choices.set(token, (entry.choices.get(token) ?? 0) + 1)\n      }\n    }\n  }\n\n  private ensure(descriptor: FieldDescriptor): FieldAccumulatorEntry {\n    const existing = this.entries.get(descriptor.key)\n    if (existing) return existing\n    const entry: FieldAccumulatorEntry = {\n      type: descriptor.type,\n      sensitive: descriptor.sensitive,\n      enumerable: (ENUMERABLE_FIELD_TYPES as readonly string[]).includes(descriptor.type),\n      answered: 0,\n      blank: 0,\n      choices: new Map(),\n    }\n    this.entries.set(descriptor.key, entry)\n    return entry\n  }\n\n  toStats(): FieldResponseStats[] {\n    const stats: FieldResponseStats[] = []\n    for (const [fieldKey, entry] of this.entries.entries()) {\n      const stat: FieldResponseStats = {\n        fieldKey,\n        type: entry.type,\n        sensitive: entry.sensitive,\n        answered: entry.answered,\n        blank: entry.blank,\n      }\n      if (entry.enumerable && !entry.sensitive) {\n        stat.choices = Array.from(entry.choices.entries())\n          .map(([value, count]) => ({ value, count }))\n          .sort((a, b) => b.count - a.count)\n      }\n      stats.push(stat)\n    }\n    return stats\n  }\n}\n\n// ============================================================================\n// Pure metric builders\n// ============================================================================\n\nexport function buildFunnel(submissions: ReadonlyArray<FormSubmission>): FunnelMetrics {\n  const byStatus: Record<FormSubmissionStatus | 'anonymized', number> = {\n    draft: 0,\n    submitted: 0,\n    reopened: 0,\n    archived: 0,\n    anonymized: 0,\n  }\n  let started = 0\n  let submitted = 0\n  for (const submission of submissions) {\n    started += 1\n    if (submission.anonymizedAt) byStatus.anonymized += 1\n    const status = submission.status as FormSubmissionStatus\n    if (ALL_STATUSES.includes(status)) byStatus[status] += 1\n    if (submission.submittedAt) submitted += 1\n  }\n  const completionRate = started > 0 ? roundTo(submitted / started, 4) : 0\n  return { started, submitted, completionRate, byStatus }\n}\n\nexport function buildVolume(submissions: ReadonlyArray<FormSubmission>): VolumePoint[] {\n  const buckets = new Map<string, { started: number; submitted: number }>()\n  for (const submission of submissions) {\n    const startKey = dayKey(submission.firstSavedAt)\n    if (startKey) {\n      const bucket = buckets.get(startKey) ?? { started: 0, submitted: 0 }\n      bucket.started += 1\n      buckets.set(startKey, bucket)\n    }\n    if (submission.submittedAt) {\n      const submitKey = dayKey(submission.submittedAt)\n      if (submitKey) {\n        const bucket = buckets.get(submitKey) ?? { started: 0, submitted: 0 }\n        bucket.submitted += 1\n        buckets.set(submitKey, bucket)\n      }\n    }\n  }\n  return Array.from(buckets.entries())\n    .map(([date, value]) => ({ date, started: value.started, submitted: value.submitted }))\n    .sort((a, b) => a.date.localeCompare(b.date))\n}\n\nexport function buildTimeToComplete(\n  submissions: ReadonlyArray<FormSubmission>,\n): TimeToCompleteMetrics {\n  const durations: number[] = []\n  for (const submission of submissions) {\n    if (!submission.submittedAt || !submission.firstSavedAt) continue\n    const seconds = (submission.submittedAt.getTime() - submission.firstSavedAt.getTime()) / 1000\n    if (Number.isFinite(seconds) && seconds >= 0) durations.push(seconds)\n  }\n  if (durations.length === 0) {\n    return { sampleSize: 0, medianSeconds: null, averageSeconds: null }\n  }\n  const sorted = [...durations].sort((a, b) => a - b)\n  const sum = sorted.reduce((acc, value) => acc + value, 0)\n  return {\n    sampleSize: sorted.length,\n    medianSeconds: roundTo(median(sorted), 2),\n    averageSeconds: roundTo(sum / sorted.length, 2),\n  }\n}\n\n/**\n * Best-effort drop-off: the furthest section a draft reached, derived from\n * which fields carry a non-blank answer. Returns the last section (in\n * declaration order) that has at least one answered field, or `null` when no\n * answered field maps to a section.\n */\nexport function furthestSectionReached(\n  sections: ReadonlyArray<{ key: string; fieldKeys: string[] }>,\n  fieldIndex: Record<string, FieldDescriptor>,\n  decoded: Record<string, unknown>,\n): string | null {\n  let reached: string | null = null\n  for (const section of sections) {\n    const hasAnswer = section.fieldKeys.some((fieldKey) => {\n      if (!fieldIndex[fieldKey]) return false\n      return !isBlank(decoded[fieldKey])\n    })\n    if (hasAnswer) reached = section.key\n  }\n  return reached\n}\n\n// ============================================================================\n// Helpers\n// ============================================================================\n\nfunction emptyAnalytics(args: AnalyticsArgs, limit: number): FormAnalytics {\n  return {\n    formId: args.formId,\n    window: {\n      from: args.from ? args.from.toISOString() : null,\n      to: args.to ? args.to.toISOString() : null,\n    },\n    scan: { limit, scanned: 0, capped: false },\n    funnel: {\n      started: 0,\n      submitted: 0,\n      completionRate: 0,\n      byStatus: { draft: 0, submitted: 0, reopened: 0, archived: 0, anonymized: 0 },\n    },\n    volume: [],\n    timeToComplete: { sampleSize: 0, medianSeconds: null, averageSeconds: null },\n    fields: [],\n    dropOff: [],\n  }\n}\n\nfunction clampLimit(limit: number | null | undefined): number {\n  if (typeof limit !== 'number' || !Number.isFinite(limit) || limit <= 0) {\n    return DEFAULT_ANALYTICS_SCAN_LIMIT\n  }\n  return Math.min(Math.floor(limit), MAX_ANALYTICS_SCAN_LIMIT)\n}\n\nfunction buildRangeFilter(from: Date | null, to: Date | null): Record<string, Date> | null {\n  const filter: Record<string, Date> = {}\n  if (from) filter.$gte = from\n  if (to) filter.$lte = to\n  return Object.keys(filter).length > 0 ? filter : null\n}\n\nfunction isBlank(value: unknown): boolean {\n  if (value === null || value === undefined) return true\n  if (typeof value === 'string') return value.trim().length === 0\n  if (Array.isArray(value)) return value.length === 0\n  return false\n}\n\nfunction enumerableTokens(value: unknown): string[] {\n  if (Array.isArray(value)) {\n    return value\n      .filter((entry) => entry !== null && entry !== undefined)\n      .map((entry) => stringifyToken(entry))\n  }\n  return [stringifyToken(value)]\n}\n\nfunction stringifyToken(value: unknown): string {\n  if (typeof value === 'boolean') return value ? 'true' : 'false'\n  if (typeof value === 'number') return String(value)\n  if (typeof value === 'string') return value\n  return JSON.stringify(value)\n}\n\nfunction dayKey(date: Date): string | null {\n  if (!(date instanceof Date) || Number.isNaN(date.getTime())) return null\n  return date.toISOString().slice(0, 10)\n}\n\nfunction median(sorted: ReadonlyArray<number>): number {\n  const mid = Math.floor(sorted.length / 2)\n  if (sorted.length % 2 === 0) return (sorted[mid - 1] + sorted[mid]) / 2\n  return sorted[mid]\n}\n\nfunction roundTo(value: number, decimals: number): number {\n  const factor = 10 ** decimals\n  return Math.round(value * factor) / factor\n}\n\nfunction ensureBuffer(value: Buffer | Uint8Array | string): Buffer {\n  if (Buffer.isBuffer(value)) return value\n  if (value instanceof Uint8Array) return Buffer.from(value)\n  if (typeof value === 'string') return Buffer.from(value, 'binary')\n  return Buffer.alloc(0)\n}\n"],
+  "mappings": "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",
+  "names": []
+}