@objectstack/objectql 9.0.0 → 9.1.0

package/dist/index.d.mts

@@ -358,6 +358,81 @@ declare class SchemaRegistry {
     reset(): void;
 }
 
+/** One runtime-verification finding (ADR-0038 BuildIssue, layer 'runtime'). */
+interface RuntimeBuildIssue {
+    layer: 'runtime';
+    severity: 'error' | 'warning';
+    /** The artifact whose runtime behaviour is broken. */
+    artifact: {
+        type: string;
+        name: string;
+    };
+    /** What it exercised, when narrower than the artifact (e.g. a widget). */
+    ref?: {
+        type: string;
+        name: string;
+        member?: string;
+    };
+    /** 'seed_not_applied' | 'view_read_failed' | 'empty_query' | 'widget_query_failed' | 'probes_unavailable' */
+    code: string;
+    message: string;
+    fix?: string;
+}
+/** Aggregate result of one post-publish probe pass. */
+interface BuildProbeReport {
+    /** Findings, empty when every probe passed. */
+    issues: RuntimeBuildIssue[];
+    /** How many probes actually ran, per plane (0s mean nothing to probe). */
+    checked: {
+        seeds: number;
+        views: number;
+        widgets: number;
+    };
+}
+/** The single read the probes need from the data engine. */
+interface ProbeEngine {
+    find(objectName: string, query: unknown): Promise<Array<Record<string, unknown>>>;
+}
+/** Optional analytics surface — when absent, widget probes degrade to a warning. */
+interface ProbeAnalytics {
+    queryDataset(dataset: unknown, selection: unknown, context?: unknown): Promise<unknown>;
+}
+interface RunBuildProbesOptions {
+    engine: ProbeEngine;
+    /** Read an ACTIVE (published) item body by type+name; undefined when absent. */
+    getItem: (type: string, name: string) => Promise<unknown | undefined>;
+    /** The just-published artifact set (publishPackageDrafts' `published`). */
+    published: Array<{
+        type: string;
+        name: string;
+    }>;
+    /**
+     * The kernel's analytics service, when one is mounted. Widget probes run
+     * the SAME `queryDataset` path the dashboard renderer hits — absent
+     * service means widgets can't be probed (one aggregate warning, not
+     * per-widget noise).
+     */
+    analytics?: ProbeAnalytics;
+    /** Threaded into engine/analytics reads (tenant scoping). */
+    organizationId?: string | null;
+}
+/**
+ * Run the L3 runtime probes over a just-published artifact set:
+ *
+ *  • per published `seed` — its target object must have rows now
+ *    (`seed_not_applied`: the rows were promised but never materialized);
+ *  • per published `view` — a limit-1 read through the same engine the
+ *    renderer uses must not throw (`view_read_failed`);
+ *  • per published `dashboard` widget — its real dataset selection must
+ *    execute (`widget_query_failed`) and must not return empty on an object
+ *    that HAS rows (`empty_query` — the four-layer staging incident class).
+ *
+ * All probes are reads (limit-1 / single aggregate); a probe crash is
+ * reported, never thrown — verification must not break the publish it
+ * verifies.
+ */
+declare function runBuildProbes(opts: RunBuildProbesOptions): Promise<BuildProbeReport>;
+
 /**
  * Re-export the canonical validation-result type so callers in this
  * package don't need to dual-import from `@objectstack/spec/kernel`.
@@ -1340,6 +1415,15 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
             error?: string;
             errors?: unknown[];
         };
+        /**
+         * ADR-0038 L3 — post-publish runtime probe report (absent when nothing
+         * was publishable). One real read per published artifact: seeded
+         * objects must have rows, views must be readable, dashboard widgets'
+         * dataset selections must execute and return data. `issues` carries
+         * BuildIssue-shaped findings (layer 'runtime') for the agent / chat
+         * health surfaces; probes never fail the publish itself.
+         */
+        probes?: BuildProbeReport;
     }>;
     /**
      * Discard every pending DRAFT bound to a package — the NON-destructive
@@ -3195,4 +3279,4 @@ declare class SeedLoaderService implements ISeedLoaderService {
     private buildResult;
 }
 
-export { type BindHooksOptions, type BindHooksResult, DEFAULT_EXTENDER_PRIORITY, DEFAULT_OWNER_PRIORITY, type EngineMiddleware, type EvaluateRulesOptions, type FieldValidationError, type HookEntry, type HookHandler, type HookMetricLabel, type HookMetricOutcome, type HookMetricsRecorder, type HookSkipReason, InMemoryHookMetricsRecorder, type IntrospectedColumn, type IntrospectedForeignKey, type IntrospectedSchema, type IntrospectedTable, MetadataFacade, type ObjectContributor, ObjectQL, type ObjectQLHostContext, type ObjectQLKernelOptions, ObjectQLPlugin, ObjectRepository, ObjectStackProtocolImplementation, type OperationContext, RESERVED_NAMESPACES, SECRET_MASK, SECRET_REF_PREFIX, SchemaRegistry, type SchemaRegistryOptions, ScopedContext, SeedLoaderService, type SysMetadataEngine, SysMetadataRepository, type SysMetadataRepositoryOptions, ValidationError, type WrapDeclarativeOptions, applyInMemoryAggregation, applySystemFields, bindHooksToEngine, bucketDateValue, collectSecretFields, computeFQN, convertIntrospectedSchemaToObjects, createObjectQLKernel, evaluateValidationRules, isSecretRef, legalNextStates, makeSecretRef, needsPriorRecord, noopHookMetricsRecorder, parseFQN, parseSecretRef, toTitleCase, validateRecord, wrapDeclarativeHook };
+export { type BindHooksOptions, type BindHooksResult, type BuildProbeReport, DEFAULT_EXTENDER_PRIORITY, DEFAULT_OWNER_PRIORITY, type EngineMiddleware, type EvaluateRulesOptions, type FieldValidationError, type HookEntry, type HookHandler, type HookMetricLabel, type HookMetricOutcome, type HookMetricsRecorder, type HookSkipReason, InMemoryHookMetricsRecorder, type IntrospectedColumn, type IntrospectedForeignKey, type IntrospectedSchema, type IntrospectedTable, MetadataFacade, type ObjectContributor, ObjectQL, type ObjectQLHostContext, type ObjectQLKernelOptions, ObjectQLPlugin, ObjectRepository, ObjectStackProtocolImplementation, type OperationContext, RESERVED_NAMESPACES, type RunBuildProbesOptions, type RuntimeBuildIssue, SECRET_MASK, SECRET_REF_PREFIX, SchemaRegistry, type SchemaRegistryOptions, ScopedContext, SeedLoaderService, type SysMetadataEngine, SysMetadataRepository, type SysMetadataRepositoryOptions, ValidationError, type WrapDeclarativeOptions, applyInMemoryAggregation, applySystemFields, bindHooksToEngine, bucketDateValue, collectSecretFields, computeFQN, convertIntrospectedSchemaToObjects, createObjectQLKernel, evaluateValidationRules, isSecretRef, legalNextStates, makeSecretRef, needsPriorRecord, noopHookMetricsRecorder, parseFQN, parseSecretRef, runBuildProbes, toTitleCase, validateRecord, wrapDeclarativeHook };

package/dist/index.d.ts

@@ -358,6 +358,81 @@ declare class SchemaRegistry {
     reset(): void;
 }
 
+/** One runtime-verification finding (ADR-0038 BuildIssue, layer 'runtime'). */
+interface RuntimeBuildIssue {
+    layer: 'runtime';
+    severity: 'error' | 'warning';
+    /** The artifact whose runtime behaviour is broken. */
+    artifact: {
+        type: string;
+        name: string;
+    };
+    /** What it exercised, when narrower than the artifact (e.g. a widget). */
+    ref?: {
+        type: string;
+        name: string;
+        member?: string;
+    };
+    /** 'seed_not_applied' | 'view_read_failed' | 'empty_query' | 'widget_query_failed' | 'probes_unavailable' */
+    code: string;
+    message: string;
+    fix?: string;
+}
+/** Aggregate result of one post-publish probe pass. */
+interface BuildProbeReport {
+    /** Findings, empty when every probe passed. */
+    issues: RuntimeBuildIssue[];
+    /** How many probes actually ran, per plane (0s mean nothing to probe). */
+    checked: {
+        seeds: number;
+        views: number;
+        widgets: number;
+    };
+}
+/** The single read the probes need from the data engine. */
+interface ProbeEngine {
+    find(objectName: string, query: unknown): Promise<Array<Record<string, unknown>>>;
+}
+/** Optional analytics surface — when absent, widget probes degrade to a warning. */
+interface ProbeAnalytics {
+    queryDataset(dataset: unknown, selection: unknown, context?: unknown): Promise<unknown>;
+}
+interface RunBuildProbesOptions {
+    engine: ProbeEngine;
+    /** Read an ACTIVE (published) item body by type+name; undefined when absent. */
+    getItem: (type: string, name: string) => Promise<unknown | undefined>;
+    /** The just-published artifact set (publishPackageDrafts' `published`). */
+    published: Array<{
+        type: string;
+        name: string;
+    }>;
+    /**
+     * The kernel's analytics service, when one is mounted. Widget probes run
+     * the SAME `queryDataset` path the dashboard renderer hits — absent
+     * service means widgets can't be probed (one aggregate warning, not
+     * per-widget noise).
+     */
+    analytics?: ProbeAnalytics;
+    /** Threaded into engine/analytics reads (tenant scoping). */
+    organizationId?: string | null;
+}
+/**
+ * Run the L3 runtime probes over a just-published artifact set:
+ *
+ *  • per published `seed` — its target object must have rows now
+ *    (`seed_not_applied`: the rows were promised but never materialized);
+ *  • per published `view` — a limit-1 read through the same engine the
+ *    renderer uses must not throw (`view_read_failed`);
+ *  • per published `dashboard` widget — its real dataset selection must
+ *    execute (`widget_query_failed`) and must not return empty on an object
+ *    that HAS rows (`empty_query` — the four-layer staging incident class).
+ *
+ * All probes are reads (limit-1 / single aggregate); a probe crash is
+ * reported, never thrown — verification must not break the publish it
+ * verifies.
+ */
+declare function runBuildProbes(opts: RunBuildProbesOptions): Promise<BuildProbeReport>;
+
 /**
  * Re-export the canonical validation-result type so callers in this
  * package don't need to dual-import from `@objectstack/spec/kernel`.
@@ -1340,6 +1415,15 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
             error?: string;
             errors?: unknown[];
         };
+        /**
+         * ADR-0038 L3 — post-publish runtime probe report (absent when nothing
+         * was publishable). One real read per published artifact: seeded
+         * objects must have rows, views must be readable, dashboard widgets'
+         * dataset selections must execute and return data. `issues` carries
+         * BuildIssue-shaped findings (layer 'runtime') for the agent / chat
+         * health surfaces; probes never fail the publish itself.
+         */
+        probes?: BuildProbeReport;
     }>;
     /**
      * Discard every pending DRAFT bound to a package — the NON-destructive
@@ -3195,4 +3279,4 @@ declare class SeedLoaderService implements ISeedLoaderService {
     private buildResult;
 }
 
-export { type BindHooksOptions, type BindHooksResult, DEFAULT_EXTENDER_PRIORITY, DEFAULT_OWNER_PRIORITY, type EngineMiddleware, type EvaluateRulesOptions, type FieldValidationError, type HookEntry, type HookHandler, type HookMetricLabel, type HookMetricOutcome, type HookMetricsRecorder, type HookSkipReason, InMemoryHookMetricsRecorder, type IntrospectedColumn, type IntrospectedForeignKey, type IntrospectedSchema, type IntrospectedTable, MetadataFacade, type ObjectContributor, ObjectQL, type ObjectQLHostContext, type ObjectQLKernelOptions, ObjectQLPlugin, ObjectRepository, ObjectStackProtocolImplementation, type OperationContext, RESERVED_NAMESPACES, SECRET_MASK, SECRET_REF_PREFIX, SchemaRegistry, type SchemaRegistryOptions, ScopedContext, SeedLoaderService, type SysMetadataEngine, SysMetadataRepository, type SysMetadataRepositoryOptions, ValidationError, type WrapDeclarativeOptions, applyInMemoryAggregation, applySystemFields, bindHooksToEngine, bucketDateValue, collectSecretFields, computeFQN, convertIntrospectedSchemaToObjects, createObjectQLKernel, evaluateValidationRules, isSecretRef, legalNextStates, makeSecretRef, needsPriorRecord, noopHookMetricsRecorder, parseFQN, parseSecretRef, toTitleCase, validateRecord, wrapDeclarativeHook };
+export { type BindHooksOptions, type BindHooksResult, type BuildProbeReport, DEFAULT_EXTENDER_PRIORITY, DEFAULT_OWNER_PRIORITY, type EngineMiddleware, type EvaluateRulesOptions, type FieldValidationError, type HookEntry, type HookHandler, type HookMetricLabel, type HookMetricOutcome, type HookMetricsRecorder, type HookSkipReason, InMemoryHookMetricsRecorder, type IntrospectedColumn, type IntrospectedForeignKey, type IntrospectedSchema, type IntrospectedTable, MetadataFacade, type ObjectContributor, ObjectQL, type ObjectQLHostContext, type ObjectQLKernelOptions, ObjectQLPlugin, ObjectRepository, ObjectStackProtocolImplementation, type OperationContext, RESERVED_NAMESPACES, type RunBuildProbesOptions, type RuntimeBuildIssue, SECRET_MASK, SECRET_REF_PREFIX, SchemaRegistry, type SchemaRegistryOptions, ScopedContext, SeedLoaderService, type SysMetadataEngine, SysMetadataRepository, type SysMetadataRepositoryOptions, ValidationError, type WrapDeclarativeOptions, applyInMemoryAggregation, applySystemFields, bindHooksToEngine, bucketDateValue, collectSecretFields, computeFQN, convertIntrospectedSchemaToObjects, createObjectQLKernel, evaluateValidationRules, isSecretRef, legalNextStates, makeSecretRef, needsPriorRecord, noopHookMetricsRecorder, parseFQN, parseSecretRef, runBuildProbes, toTitleCase, validateRecord, wrapDeclarativeHook };

package/dist/index.js

@@ -633,6 +633,172 @@ var init_seed_loader = __esm({
   }
 });
 
+// src/build-probes.ts
+var build_probes_exports = {};
+__export(build_probes_exports, {
+  runBuildProbes: () => runBuildProbes
+});
+function asRec(v) {
+  return v && typeof v === "object" && !Array.isArray(v) ? v : void 0;
+}
+function asArr(v) {
+  return Array.isArray(v) ? v : [];
+}
+function resultRows(result) {
+  if (Array.isArray(result)) return result;
+  const r = asRec(result);
+  if (!r) return [];
+  if (Array.isArray(r.rows)) return r.rows;
+  if (Array.isArray(r.data)) return r.data;
+  return [];
+}
+async function hasRows(engine, objectName, organizationId) {
+  const rows = await engine.find(objectName, {
+    fields: ["id"],
+    limit: 1,
+    ...organizationId ? { where: { organization_id: organizationId } } : {},
+    context: { isSystem: true }
+  });
+  return Array.isArray(rows) && rows.length > 0;
+}
+async function runBuildProbes(opts) {
+  const issues = [];
+  const checked = { seeds: 0, views: 0, widgets: 0 };
+  const { engine, getItem, published, analytics, organizationId } = opts;
+  const itemCache = /* @__PURE__ */ new Map();
+  const readItem = async (type, name) => {
+    const key = `${type} ${name}`;
+    if (itemCache.has(key)) return itemCache.get(key);
+    let item;
+    try {
+      item = await getItem(type, name);
+    } catch {
+      item = void 0;
+    }
+    itemCache.set(key, item);
+    return item;
+  };
+  for (const p of published.filter((x) => x.type === "seed")) {
+    const body = asRec(await readItem("seed", p.name));
+    const objectName = typeof body?.object === "string" ? body.object : void 0;
+    if (!objectName) continue;
+    checked.seeds += 1;
+    try {
+      if (!await hasRows(engine, objectName, organizationId)) {
+        issues.push({
+          layer: "runtime",
+          severity: "error",
+          artifact: { type: "seed", name: p.name },
+          ref: { type: "object", name: objectName },
+          code: "seed_not_applied",
+          message: `Seed "${p.name}" was published but object "${objectName}" has no rows \u2014 the sample data never materialized.`,
+          fix: `Check the publish response's seedApplied for the load error, fix the seed rows (field names/types), and republish the seed.`
+        });
+      }
+    } catch (e) {
+      issues.push({
+        layer: "runtime",
+        severity: "error",
+        artifact: { type: "seed", name: p.name },
+        ref: { type: "object", name: objectName },
+        code: "seed_not_applied",
+        message: `Seed "${p.name}" probe could not read object "${objectName}": ${String(e?.message ?? e)}`
+      });
+    }
+  }
+  for (const p of published.filter((x) => x.type === "view")) {
+    const body = asRec(await readItem("view", p.name));
+    const config = asRec(body?.config);
+    const dataObj = asRec(config?.data)?.object;
+    const objectName = typeof body?.object === "string" ? body.object : typeof dataObj === "string" ? dataObj : void 0;
+    if (!objectName) continue;
+    checked.views += 1;
+    try {
+      await engine.find(objectName, {
+        fields: ["id"],
+        limit: 1,
+        ...organizationId ? { where: { organization_id: organizationId } } : {},
+        context: { isSystem: true }
+      });
+    } catch (e) {
+      issues.push({
+        layer: "runtime",
+        severity: "error",
+        artifact: { type: "view", name: p.name },
+        ref: { type: "object", name: objectName },
+        code: "view_read_failed",
+        message: `View "${p.name}" cannot read object "${objectName}": ${String(e?.message ?? e)} \u2014 it will render as an error for every user.`,
+        fix: `Verify object "${objectName}" published successfully (its table must exist) and that the view's binding is correct.`
+      });
+    }
+  }
+  const dashboards = published.filter((x) => x.type === "dashboard");
+  let widgetsToProbe = 0;
+  for (const p of dashboards) {
+    const body = asRec(await readItem("dashboard", p.name));
+    const widgets = asArr(body?.widgets).map(asRec).filter((w) => !!w);
+    const datasetBound = widgets.filter((w) => typeof w.dataset === "string" && w.dataset);
+    widgetsToProbe += datasetBound.length;
+    if (!analytics || typeof analytics.queryDataset !== "function") continue;
+    for (const w of datasetBound) {
+      const widgetId = String(w.id ?? w.title ?? "?");
+      const dsName = w.dataset;
+      const dataset = asRec(await readItem("dataset", dsName));
+      if (!dataset) continue;
+      checked.widgets += 1;
+      const measures = asArr(w.values).filter((v) => typeof v === "string" && v.length > 0);
+      const firstMeasure = asRec(asArr(dataset.measures)[0])?.name;
+      const selection = {
+        measures: measures.length ? measures : typeof firstMeasure === "string" ? [firstMeasure] : [],
+        dimensions: [],
+        limit: 1
+      };
+      if (selection.measures.length === 0) continue;
+      const objectName = typeof dataset.object === "string" ? dataset.object : void 0;
+      try {
+        const result = await analytics.queryDataset(dataset, selection, void 0);
+        const rows = resultRows(result);
+        if (rows.length === 0 && objectName && await hasRows(engine, objectName, organizationId)) {
+          issues.push({
+            layer: "runtime",
+            severity: "error",
+            artifact: { type: "dashboard", name: p.name },
+            ref: { type: "dataset", name: dsName, member: widgetId },
+            code: "empty_query",
+            message: `Dashboard "${p.name}" widget "${widgetId}" returns NO data from dataset "${dsName}" although object "${objectName}" has rows \u2014 the widget will render empty for every user.`,
+            fix: `Run the dataset query directly to see the compiled strategy/SQL; check the dataset's measure/dimension field bindings against object "${objectName}".`
+          });
+        }
+      } catch (e) {
+        issues.push({
+          layer: "runtime",
+          severity: "error",
+          artifact: { type: "dashboard", name: p.name },
+          ref: { type: "dataset", name: dsName, member: widgetId },
+          code: "widget_query_failed",
+          message: `Dashboard "${p.name}" widget "${widgetId}" query against dataset "${dsName}" failed: ${String(e?.message ?? e)}`,
+          fix: `Fix the dataset definition (or the widget's values/dimensions) so the query compiles, then republish.`
+        });
+      }
+    }
+  }
+  if (widgetsToProbe > 0 && (!analytics || typeof analytics.queryDataset !== "function")) {
+    issues.push({
+      layer: "runtime",
+      severity: "warning",
+      artifact: { type: "dashboard", name: dashboards.map((d) => d.name).join(", ") },
+      code: "probes_unavailable",
+      message: `${widgetsToProbe} dashboard widget(s) could not be probed: no analytics service is mounted on this kernel.`
+    });
+  }
+  return { issues, checked };
+}
+var init_build_probes = __esm({
+  "src/build-probes.ts"() {
+    "use strict";
+  }
+});
+
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
@@ -668,6 +834,7 @@ __export(index_exports, {
   noopHookMetricsRecorder: () => noopHookMetricsRecorder,
   parseFQN: () => parseFQN,
   parseSecretRef: () => parseSecretRef,
+  runBuildProbes: () => runBuildProbes,
   toTitleCase: () => toTitleCase,
   validateRecord: () => validateRecord,
   wrapDeclarativeHook: () => wrapDeclarativeHook
@@ -5025,13 +5192,38 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
         });
       }
     }
+    const seedApplied = seedBodies.length > 0 ? await this.applySeedBodies(seedBodies, orgId) : void 0;
+    let probes;
+    if (published.length > 0) {
+      try {
+        const { runBuildProbes: runBuildProbes2 } = await Promise.resolve().then(() => (init_build_probes(), build_probes_exports));
+        const analytics = this.getServicesRegistry?.().get("analytics");
+        probes = await runBuildProbes2({
+          engine: this.engine,
+          getItem: async (type, name) => {
+            const wrapper = await this.getMetaItem({
+              type,
+              name,
+              ...orgId ? { organizationId: orgId } : {}
+            });
+            return wrapper?.item ?? wrapper ?? void 0;
+          },
+          published,
+          ...analytics && typeof analytics.queryDataset === "function" ? { analytics } : {},
+          organizationId: orgId
+        });
+      } catch {
+        probes = void 0;
+      }
+    }
     return {
       success: failed.length === 0 && published.length > 0,
       publishedCount: published.length,
       failedCount: failed.length,
       published,
       failed,
-      ...seedBodies.length > 0 ? { seedApplied: await this.applySeedBodies(seedBodies, orgId) } : {}
+      ...seedApplied ? { seedApplied } : {},
+      ...probes ? { probes } : {}
     };
   }
   /**
@@ -9893,6 +10085,7 @@ function convertIntrospectedSchemaToObjects(introspectedSchema, options) {
 
 // src/index.ts
 init_seed_loader();
+init_build_probes();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEFAULT_EXTENDER_PRIORITY,
@@ -9927,6 +10120,7 @@ init_seed_loader();
   noopHookMetricsRecorder,
   parseFQN,
   parseSecretRef,
+  runBuildProbes,
   toTitleCase,
   validateRecord,
   wrapDeclarativeHook