@objectstack/objectql 7.3.0 → 7.4.1

package/dist/index.js

@@ -29,6 +29,8 @@ __export(index_exports, {
   ObjectRepository: () => ObjectRepository,
   ObjectStackProtocolImplementation: () => ObjectStackProtocolImplementation,
   RESERVED_NAMESPACES: () => RESERVED_NAMESPACES,
+  SECRET_MASK: () => SECRET_MASK,
+  SECRET_REF_PREFIX: () => SECRET_REF_PREFIX,
   SchemaRegistry: () => SchemaRegistry,
   ScopedContext: () => ScopedContext,
   SysMetadataRepository: () => SysMetadataRepository,
@@ -37,11 +39,18 @@ __export(index_exports, {
   applySystemFields: () => applySystemFields,
   bindHooksToEngine: () => bindHooksToEngine,
   bucketDateValue: () => bucketDateValue,
+  collectSecretFields: () => collectSecretFields,
   computeFQN: () => computeFQN,
   convertIntrospectedSchemaToObjects: () => convertIntrospectedSchemaToObjects,
   createObjectQLKernel: () => createObjectQLKernel,
+  evaluateValidationRules: () => evaluateValidationRules,
+  isSecretRef: () => isSecretRef,
+  legalNextStates: () => legalNextStates,
+  makeSecretRef: () => makeSecretRef,
+  needsPriorRecord: () => needsPriorRecord,
   noopHookMetricsRecorder: () => noopHookMetricsRecorder,
   parseFQN: () => parseFQN,
+  parseSecretRef: () => parseSecretRef,
   toTitleCase: () => toTitleCase,
   validateRecord: () => validateRecord,
   wrapDeclarativeHook: () => wrapDeclarativeHook
@@ -178,6 +187,14 @@ var SchemaRegistry = class {
     // ==========================================
     /** Type → Name/ID → MetadataItem */
     this.metadata = /* @__PURE__ */ new Map();
+    /**
+     * App name → navigation contributions (ADR-0029 D7).
+     *
+     * Lets packages inject nav items into apps they do not own (the UI analog
+     * of object extenders). Merged into the owning app's `navigation` tree on
+     * read in {@link getApp} / {@link getAllApps} by group id + priority.
+     */
+    this.appNavContributions = /* @__PURE__ */ new Map();
     /**
      * Package ids that must be installed in a DISABLED state. Seeded once at
      * boot (from persisted state) BEFORE any package registration so that every
@@ -405,6 +422,47 @@ var SchemaRegistry = class {
     const contributors = this.objectContributors.get(fqn);
     return contributors?.find((c) => c.ownership === "own");
   }
+  /**
+   * ADR-0029 K0 — assert every registered object resolves to exactly one
+   * owner.
+   *
+   * A second `own` from a different package is already rejected eagerly in
+   * {@link registerObject} (it throws). This is the install-time backstop
+   * called once all packages are registered (kernel bootstrap complete),
+   * and it additionally catches the case `registerObject` cannot: an object
+   * that has only `extend` contributions and **no owner** — which would
+   * otherwise resolve to nothing. Surfacing it here turns a silent
+   * "extend a non-existent object" into a clear bootstrap error.
+   *
+   * This is the invariant the kernel-decomposition (ADR-0029) relies on:
+   * the `sys` namespace is shared across many first-party plugins, but each
+   * object name has exactly one owner.
+   *
+   * @throws Error listing every object whose owner count is not exactly 1.
+   */
+  assertSingleOwnerPerObject() {
+    const violations = [];
+    for (const [fqn, contributors] of this.objectContributors.entries()) {
+      const owners = contributors.filter((c) => c.ownership === "own");
+      if (owners.length === 0) {
+        const extenders = contributors.map((c) => c.packageId).join(", ") || "(none)";
+        violations.push(
+          `Object "${fqn}" has no owner \u2014 only extend contributions from [${extenders}]. Exactly one package must register it with ownership 'own'.`
+        );
+      } else if (owners.length > 1) {
+        const names = owners.map((c) => c.packageId).join(", ");
+        violations.push(
+          `Object "${fqn}" has ${owners.length} owners [${names}] \u2014 exactly one is allowed.`
+        );
+      }
+    }
+    if (violations.length > 0) {
+      throw new Error(
+        `[Registry] single-owner-per-object check failed (ADR-0029):
+  ` + violations.join("\n  ")
+      );
+    }
+  }
   /**
    * Unregister all objects contributed by a package.
    * 
@@ -646,10 +704,88 @@ var SchemaRegistry = class {
     this.registerItem("app", app, "name", packageId);
   }
   getApp(name) {
-    return this.getItem("app", name);
+    const app = this.getItem("app", name);
+    if (!app) return app;
+    return this.applyNavContributions(app);
   }
   getAllApps() {
-    return this.listItems("app");
+    return this.listItems("app").map((app) => this.applyNavContributions(app));
+  }
+  // ==========================================
+  // App navigation contributions (ADR-0029 D7)
+  // ==========================================
+  /**
+   * Register a navigation contribution — a package injecting nav items into
+   * an app it does not own (the UI-layer analog of object `extend`).
+   *
+   * Contributions are merged into the target app's `navigation` tree lazily
+   * on read ({@link getApp} / {@link getAllApps}) by group id + priority, so
+   * registration order does not matter and the owning app can be registered
+   * before or after its contributors.
+   */
+  registerAppNavContribution(contribution, packageId) {
+    if (!contribution || !contribution.app) return;
+    const list = this.appNavContributions.get(contribution.app) ?? [];
+    list.push({
+      packageId,
+      group: contribution.group,
+      priority: contribution.priority ?? 200,
+      items: Array.isArray(contribution.items) ? contribution.items : []
+    });
+    this.appNavContributions.set(contribution.app, list);
+    this.log(
+      `[Registry] Navigation contribution: ${packageId ?? "(unknown)"} -> ${contribution.app}` + (contribution.group ? `/${contribution.group}` : "") + ` (${list[list.length - 1].items.length} items)`
+    );
+  }
+  /** Contributions registered for an app (empty array when none). */
+  getAppNavContributions(appName) {
+    return this.appNavContributions.get(appName) ?? [];
+  }
+  /**
+   * Return a copy of `app` with all registered navigation contributions
+   * merged into its `navigation` tree. The stored app is never mutated, so
+   * repeated reads stay idempotent.
+   *
+   * Public so the protocol serving path (`getMetaItems` / `getMetaItem` for
+   * `app`) can merge contributions the same way `getApp` / `getAllApps` do —
+   * the REST app endpoints read through the protocol, not these helpers, so
+   * the merge must be reachable from there too (ADR-0029 D7).
+   */
+  applyNavContributions(app) {
+    const contributions = this.appNavContributions.get(app?.name);
+    if (!contributions || contributions.length === 0) return app;
+    const cloned = structuredClone(app);
+    const nav = Array.isArray(cloned.navigation) ? cloned.navigation : cloned.navigation = [];
+    const sorted = [...contributions].sort((a, b) => a.priority - b.priority);
+    for (const c of sorted) {
+      if (!c.items.length) continue;
+      if (c.group) {
+        const group = this.findNavGroup(nav, c.group);
+        if (group) {
+          if (!Array.isArray(group.children)) group.children = [];
+          group.children.push(...c.items);
+        } else {
+          this.log(
+            `[Registry] Navigation contribution from "${c.packageId ?? "(unknown)"}" targets missing group "${c.group}" in app "${app.name}" \u2014 appending at top level.`
+          );
+          nav.push(...c.items);
+        }
+      } else {
+        nav.push(...c.items);
+      }
+    }
+    return cloned;
+  }
+  /** Depth-first search for a `type: 'group'` nav item by id. */
+  findNavGroup(items, groupId) {
+    for (const item of items) {
+      if (item && item.id === groupId && item.type === "group") return item;
+      if (item && Array.isArray(item.children)) {
+        const found = this.findNavGroup(item.children, groupId);
+        if (found) return found;
+      }
+    }
+    return void 0;
   }
   // ==========================================
   // Plugin Helpers
@@ -708,6 +844,7 @@ var SchemaRegistry = class {
     this.mergedObjectCache.clear();
     this.namespaceRegistry.clear();
     this.metadata.clear();
+    this.appNavContributions.clear();
     this.log("[Registry] Reset complete");
   }
 };
@@ -1399,6 +1536,7 @@ var SysMetadataRepository = class {
 var import_metadata_core2 = require("@objectstack/metadata-core");
 var import_data2 = require("@objectstack/spec/data");
 var import_shared4 = require("@objectstack/spec/shared");
+var import_ui2 = require("@objectstack/spec/ui");
 var import_system = require("@objectstack/spec/system");
 var import_kernel4 = require("@objectstack/spec/kernel");
 var import_kernel5 = require("@objectstack/spec/kernel");
@@ -2093,6 +2231,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       const zodSchema = (0, import_kernel4.getMetadataTypeSchema)(singular);
       const schema = (zodSchema ? toJsonSchemaSafe(zodSchema) : void 0) ?? HAND_CRAFTED_SCHEMAS[singular];
       const form = TYPE_TO_FORM[singular];
+      const typeActions = (0, import_kernel4.getMetadataTypeActions)(singular);
       const base = registryByType.get(singular);
       if (base) {
         const isEnvOverridden = writableOverrides.has(singular);
@@ -2104,7 +2243,11 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
           allowOrgOverride: base.allowOrgOverride || isEnvOverridden,
           overrideSource: isEnvOverridden && !base.allowOrgOverride ? "env" : "registry",
           schema,
-          form
+          form,
+          // Override the spread `base.actions` with the merged view
+          // (declarative + plugin-registered). Omit when empty to
+          // preserve the prior "no actions key" response shape.
+          ...typeActions.length ? { actions: typeActions } : {}
         };
       }
       return {
@@ -2123,7 +2266,9 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
         domain: "system",
         overrideSource: writableOverrides.has(singular) ? "env" : "registry",
         schema,
-        form
+        form,
+        // Plugin-registered actions on a type with no registry entry.
+        ...typeActions.length ? { actions: typeActions } : {}
       };
     }).sort((a, b) => {
       if (a.domain !== b.domain) return a.domain.localeCompare(b.domain);
@@ -2298,6 +2443,12 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
         (it) => !this.engine.registry.isPackageDisabled(it?._packageId)
       );
     }
+    if (request.type === "view" || request.type === "views") {
+      items = items.filter((it) => !(0, import_ui2.isAggregatedViewContainer)(it));
+    }
+    if (request.type === "app" || request.type === "apps") {
+      items = items.map((app) => this.engine.registry.applyNavContributions(app));
+    }
     return {
       type: request.type,
       items: decorateMetadataItems(
@@ -2387,6 +2538,9 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
         if (alt) item = this.engine.registry.getItem(alt, request.name);
       }
     }
+    if ((request.type === "app" || request.type === "apps") && item) {
+      item = this.engine.registry.applyNavContributions(item);
+    }
     const artifactItem = this.lookupArtifactItem(request.type, request.name);
     const decorated = decorateMetadataItem(
       request.type,
@@ -3145,7 +3299,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
         throw new Error(`Metadata item ${request.type}/${request.name} not found`);
       }
       const content = JSON.stringify(item);
-      const hash = simpleHash(content);
+      const hash = simpleHash(request.locale ? `${request.locale}\0${content}` : content);
       const etag = { value: hash, weak: false };
       if (request.cacheRequest?.ifNoneMatch) {
         const clientEtag = request.cacheRequest.ifNoneMatch.replace(/^"(.*)"$/, "$1").replace(/^W\/"(.*)"$/, "$1");
@@ -4597,8 +4751,33 @@ var ObjectStackProtocolImplementation = _ObjectStackProtocolImplementation;
 var import_kernel6 = require("@objectstack/spec/kernel");
 var import_core = require("@objectstack/core");
 var import_system2 = require("@objectstack/spec/system");
+
+// src/secret-fields.ts
+var SECRET_REF_PREFIX = "secret:";
+var SECRET_MASK = "\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022";
+function makeSecretRef(handleId) {
+  return `${SECRET_REF_PREFIX}${handleId}`;
+}
+function isSecretRef(value) {
+  return typeof value === "string" && value.startsWith(SECRET_REF_PREFIX);
+}
+function parseSecretRef(value) {
+  return isSecretRef(value) ? value.slice(SECRET_REF_PREFIX.length) : null;
+}
+function collectSecretFields(schema) {
+  const fields = schema?.fields;
+  if (!fields) return [];
+  const out = [];
+  for (const [name, def] of Object.entries(fields)) {
+    if (def && def.type === "secret") out.push(name);
+  }
+  return out;
+}
+
+// src/engine.ts
 var import_shared5 = require("@objectstack/spec/shared");
-var import_formula2 = require("@objectstack/formula");
+var import_formula3 = require("@objectstack/formula");
+var import_spec = require("@objectstack/spec");
 
 // src/hook-wrappers.ts
 var import_formula = require("@objectstack/formula");
@@ -5152,6 +5331,101 @@ function validateRecord(objectSchema, data, mode) {
   if (errors.length > 0) throw new ValidationError(errors);
 }
 
+// src/validation/rule-validator.ts
+var import_formula2 = require("@objectstack/formula");
+function needsPriorRecord(objectSchema) {
+  const rules = objectSchema?.validations;
+  if (!Array.isArray(rules)) return false;
+  return rules.some(
+    (r) => r != null && typeof r === "object" && (r.type === "state_machine" || r.type === "cross_field" || r.type === "script")
+  );
+}
+function toExpression(cond) {
+  return typeof cond === "string" ? { dialect: "cel", source: cond } : cond;
+}
+function evaluateValidationRules(objectSchema, data, mode, opts = {}) {
+  const rules = objectSchema?.validations;
+  if (!Array.isArray(rules) || rules.length === 0 || !data) return;
+  const previous = opts.previous ?? void 0;
+  const merged = { ...previous ?? {}, ...data };
+  const errors = [];
+  const ordered = rules.filter((r) => r != null && typeof r === "object").filter((r) => r.active !== false).filter((r) => {
+    const events = r.events ?? ["insert", "update"];
+    return events.includes(mode);
+  }).sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100));
+  for (const rule of ordered) {
+    let violation = null;
+    try {
+      if (rule.type === "state_machine") {
+        violation = checkStateMachine(rule, mode, data, previous);
+      } else if (rule.type === "script" || rule.type === "cross_field") {
+        violation = checkPredicate(rule, merged, previous, opts.logger);
+      }
+    } catch (err) {
+      opts.logger?.warn?.(`Validation rule '${rule.name}' threw \u2014 skipped`, err);
+      continue;
+    }
+    if (!violation) continue;
+    const severity = rule.severity ?? "error";
+    if (severity === "error") {
+      errors.push(violation);
+    } else {
+      opts.logger?.warn?.(
+        `Validation rule '${rule.name}' (${severity}): ${violation.message}`
+      );
+    }
+  }
+  if (errors.length > 0) throw new ValidationError(errors);
+}
+function checkStateMachine(rule, mode, data, previous) {
+  if (mode === "insert" || !previous) return null;
+  if (!(rule.field in data)) return null;
+  const from = previous[rule.field];
+  const to = data[rule.field];
+  if (from === to || to === void 0 || to === null) return null;
+  const fromKey = String(from);
+  const allowed = rule.transitions[fromKey];
+  if (!Array.isArray(allowed)) return null;
+  if (!allowed.includes(String(to))) {
+    return {
+      field: rule.field,
+      code: "invalid_transition",
+      message: rule.message || `Invalid transition for ${rule.field}: ${fromKey} \u2192 ${String(to)}`
+    };
+  }
+  return null;
+}
+function checkPredicate(rule, record, previous, logger) {
+  const expr = toExpression(rule.condition);
+  const result = import_formula2.ExpressionEngine.evaluate(expr, {
+    record,
+    previous: previous ?? void 0
+  });
+  if (!result.ok) {
+    logger?.warn?.(
+      `Validation rule '${rule.name}' predicate failed to evaluate (${result.error.kind}: ${result.error.message}) \u2014 skipped`
+    );
+    return null;
+  }
+  if (result.value === true) {
+    return {
+      field: rule.fields?.[0] ?? "_record",
+      code: "rule_violation",
+      message: rule.message
+    };
+  }
+  return null;
+}
+function legalNextStates(objectSchema, field, currentState) {
+  const rules = objectSchema?.validations;
+  if (!Array.isArray(rules)) return null;
+  const rule = rules.find(
+    (r) => r != null && typeof r === "object" && r.type === "state_machine" && r.field === field
+  );
+  if (!rule) return null;
+  return rule.transitions[currentState] ?? [];
+}
+
 // src/in-memory-aggregation.ts
 function applyInMemoryAggregation(rows, ast) {
   const groupBy = ast.groupBy ?? [];
@@ -5309,7 +5583,7 @@ function planFormulaProjection(schema, requestedFields) {
     if (def?.type === "formula" && def.expression) {
       const expr = typeof def.expression === "string" ? { dialect: "cel", source: def.expression } : def.expression;
       plan.push({ name: f, expression: expr });
-      import_formula2.ExpressionEngine.compile(expr);
+      import_formula3.ExpressionEngine.compile(expr);
     } else if (Array.isArray(requestedFields) && requestedFields.length > 0) {
       projected.add(f);
     }
@@ -5331,7 +5605,7 @@ function applyFormulaPlan(plan, records) {
   for (const rec of records) {
     if (rec == null) continue;
     for (const fp of plan) {
-      const r = import_formula2.ExpressionEngine.evaluate(fp.expression, { record: rec });
+      const r = import_formula3.ExpressionEngine.evaluate(fp.expression, { record: rec });
       rec[fp.name] = r.ok ? r.value : null;
     }
   }
@@ -5341,7 +5615,7 @@ function resolveMetadataItemName(key, item) {
   if (item.name) return item.name;
   if (item.id) return item.id;
   if (key === "views") {
-    return item?.list?.data?.object || item?.form?.data?.object || void 0;
+    return item?.object || item?.list?.data?.object || item?.form?.data?.object || void 0;
   }
   return void 0;
 }
@@ -5353,6 +5627,11 @@ var _ObjectQL = class _ObjectQL {
     this.datasourceMapping = [];
     // Package manifests registry (for defaultDatasource lookup)
     this.manifests = /* @__PURE__ */ new Map();
+    // Datasource definitions by name (ADR-0015): carries schemaMode +
+    // external.allowWrites so the write gate (Gate 3) can enforce federation
+    // ownership. Populated from manifests in registerApp and via
+    // registerDatasourceDef. Absent entry ⇒ treated as managed (default DB).
+    this.datasourceDefs = /* @__PURE__ */ new Map();
     // Per-object hooks with priority support
     this.hooks = /* @__PURE__ */ new Map([
       ["beforeFind", []],
@@ -5735,7 +6014,7 @@ var _ObjectQL = class _ObjectQL {
       if (f.defaultValue == null) continue;
       const dv = f.defaultValue;
       if (typeof dv === "object" && dv !== null && dv.dialect && typeof dv.source === "string") {
-        const result = import_formula2.ExpressionEngine.evaluate(dv, {
+        const result = import_formula3.ExpressionEngine.evaluate(dv, {
           now,
           user: execCtx?.userId ? { id: String(execCtx.userId), role: execCtx?.roles?.[0] } : void 0,
           org: execCtx?.tenantId ? { id: String(execCtx.tenantId) } : void 0,
@@ -5775,6 +6054,12 @@ var _ObjectQL = class _ObjectQL {
     if (id) {
       this.manifests.set(id, manifest);
     }
+    if (manifest.datasources) {
+      const dsList = Array.isArray(manifest.datasources) ? manifest.datasources : Object.entries(manifest.datasources).map(([name, def]) => ({ name, ...def }));
+      for (const ds of dsList) {
+        if (ds?.name) this.registerDatasourceDef(ds);
+      }
+    }
     this._registry.installPackage(manifest);
     this.logger.debug("Installed Package", { id: manifest.id, name: manifest.name, namespace });
     if (manifest.objects) {
@@ -5828,6 +6113,15 @@ var _ObjectQL = class _ObjectQL {
       this._registry.registerApp(resolved, id);
       this.logger.debug("Registered manifest-as-app", { app: manifest.name, from: id });
     }
+    if (Array.isArray(manifest.navigationContributions) && manifest.navigationContributions.length > 0) {
+      for (const contribution of manifest.navigationContributions) {
+        this._registry.registerAppNavContribution(contribution, id);
+      }
+      this.logger.debug("Registered navigation contributions", {
+        from: id,
+        count: manifest.navigationContributions.length
+      });
+    }
     const metadataArrayKeys = [
       // UI Protocol
       "actions",
@@ -5871,6 +6165,11 @@ var _ObjectQL = class _ObjectQL {
           if (itemName) {
             const toRegister = item.name === itemName ? item : { ...item, name: itemName };
             this._registry.registerItem((0, import_shared5.pluralToSingular)(key), toRegister, "name", id);
+            if (key === "views" && (0, import_spec.isAggregatedViewContainer)(toRegister)) {
+              for (const vi of (0, import_spec.expandViewContainer)(itemName, toRegister)) {
+                this._registry.registerItem("view", vi, "name", id);
+              }
+            }
           } else {
             this.logger.warn(`Skipping ${(0, import_shared5.pluralToSingular)(key)} without a derivable name`, { id });
           }
@@ -6023,6 +6322,41 @@ var _ObjectQL = class _ObjectQL {
       this.logger.info("Set default driver", { driverName: driver.name });
     }
   }
+  /**
+   * Register a Datasource *definition* (ADR-0015).
+   *
+   * Distinct from {@link registerDriver}, which registers a live connection.
+   * This captures the declarative `schemaMode` + `external.allowWrites` so the
+   * write gate ({@link assertWriteAllowed}) can enforce external-datasource
+   * ownership. Safe to call repeatedly; last write wins.
+   */
+  registerDatasourceDef(def) {
+    if (!def?.name) return;
+    this.datasourceDefs.set(def.name, { schemaMode: def.schemaMode, external: def.external });
+  }
+  /**
+   * Write gate — Gate 3 of ADR-0015 §5.3.
+   *
+   * Blocks insert/update/delete against a federated datasource
+   * (`schemaMode !== 'managed'`) unless BOTH the datasource opts in
+   * (`external.allowWrites`) AND the object opts in (`external.writable`).
+   * Managed datasources (the common case, including the absence of any
+   * definition) are unaffected.
+   */
+  assertWriteAllowed(objectName, operation) {
+    const object = this._registry.getObject(objectName);
+    const dsName = object?.datasource;
+    if (!dsName || dsName === "default") return;
+    const ds = this.datasourceDefs.get(dsName);
+    if (!ds || !ds.schemaMode || ds.schemaMode === "managed") return;
+    const dsAllows = ds.external?.allowWrites ?? false;
+    const objAllows = object?.external?.writable ?? false;
+    if (!(dsAllows && objAllows)) {
+      throw new import_shared5.ExternalWriteForbiddenError(
+        `Write '${operation}' blocked on object '${objectName}': datasource '${dsName}' is external (schemaMode=${ds.schemaMode}). Requires datasource.external.allowWrites=true (got ${dsAllows}) AND object.external.writable=true (got ${objAllows}).`
+      );
+    }
+  }
   /**
    * Set the realtime service for publishing data change events.
    * Should be called after kernel resolves the realtime service.
@@ -6033,6 +6367,141 @@ var _ObjectQL = class _ObjectQL {
     this.realtimeService = service;
     this.logger.info("RealtimeService configured for data events");
   }
+  /**
+   * Register the crypto provider that backs `secret`-typed fields.
+   *
+   * When set, the engine encrypts secret fields on write (storing ciphertext in
+   * `sys_secret` and only an opaque ref on the business row) and masks them on
+   * read. When NOT set, writing to an object that declares a secret field is
+   * **fail-closed** — the write throws rather than persist cleartext.
+   *
+   * Mirrors the Settings subsystem's ICryptoProvider wiring; the host (e.g.
+   * `serve`) injects `InMemoryCryptoProvider` in dev and a KMS/Vault-backed
+   * provider in production.
+   */
+  setCryptoProvider(provider) {
+    this.cryptoProvider = provider;
+    this.logger.info("CryptoProvider configured for secret fields");
+  }
+  /**
+   * Encrypt any `secret`-typed fields on `row` in place before it reaches the
+   * driver. Each plaintext is wrapped by the ICryptoProvider, persisted as a
+   * `sys_secret` row, and replaced on `row` by an opaque ref. Cleartext never
+   * reaches the business table.
+   *
+   * Rules:
+   *  - No secret fields on the object ⇒ no-op (fast path, no crypto cost).
+   *  - `null`/`undefined` value ⇒ left as-is (clears the secret).
+   *  - Value already a ref (re-save of an unchanged ref) ⇒ left as-is.
+   *  - Value equal to the read mask ⇒ dropped, so a form round-trip that
+   *    echoes the mask does not overwrite the stored secret.
+   *  - **Fail-closed:** any other value with no CryptoProvider registered, or
+   *    no reachable `sys_secret` store, THROWS — never persists cleartext.
+   */
+  async encryptSecretFields(object, row, context, driverOptions) {
+    if (!row || typeof row !== "object") return;
+    const schema = this._registry.getObject(object);
+    const secretFields = collectSecretFields(schema);
+    if (secretFields.length === 0) return;
+    for (const field of secretFields) {
+      if (!(field in row)) continue;
+      const value = row[field];
+      if (value === null || typeof value === "undefined") continue;
+      if (isSecretRef(value)) continue;
+      if (value === SECRET_MASK) {
+        delete row[field];
+        continue;
+      }
+      if (!this.cryptoProvider) {
+        throw new Error(
+          `Cannot persist secret field "${object}.${field}": no CryptoProvider is registered. Wire one via engine.setCryptoProvider(...) (e.g. InMemoryCryptoProvider in dev, a KMS/Vault provider in production). Refusing to store cleartext (fail-closed).`
+        );
+      }
+      const plain = typeof value === "string" ? value : JSON.stringify(value);
+      const handle = await this.cryptoProvider.encrypt(plain, {
+        namespace: object,
+        key: field,
+        tenantId: context?.tenantId
+      });
+      let secretDriver;
+      try {
+        secretDriver = this.getDriver("sys_secret");
+      } catch {
+        throw new Error(
+          `Cannot persist secret field "${object}.${field}": the sys_secret store is not available. Ensure the platform-objects (sys_secret) are registered before writing secret fields (fail-closed).`
+        );
+      }
+      await secretDriver.create(
+        "sys_secret",
+        {
+          id: handle.id,
+          namespace: object,
+          key: field,
+          kms_key_id: handle.kmsKeyId,
+          alg: handle.alg,
+          version: handle.version,
+          ciphertext: handle.ciphertext,
+          created_at: (/* @__PURE__ */ new Date()).toISOString()
+        },
+        driverOptions
+      );
+      row[field] = makeSecretRef(handle.id);
+    }
+  }
+  /**
+   * Mask `secret`-typed fields on read so plaintext never leaves the engine
+   * through the normal query path. A set secret becomes {@link SECRET_MASK};
+   * an unset one stays `null`. Privileged callers that genuinely need the
+   * plaintext use {@link resolveSecret} against the stored ref.
+   */
+  maskSecretFields(object, rows) {
+    if (!rows) return;
+    const schema = this._registry.getObject(object);
+    const secretFields = collectSecretFields(schema);
+    if (secretFields.length === 0) return;
+    const list = Array.isArray(rows) ? rows : [rows];
+    for (const row of list) {
+      if (!row || typeof row !== "object") continue;
+      for (const field of secretFields) {
+        if (!(field in row)) continue;
+        row[field] = row[field] == null ? null : SECRET_MASK;
+      }
+    }
+  }
+  /**
+   * Dereference a stored secret ref back to its plaintext. Intended for
+   * privileged, server-side consumers (e.g. a datasource connection-pool
+   * binder) — NOT exposed through the generic read path, which only ever
+   * returns the mask.
+   *
+   * Fail-closed: throws when no CryptoProvider is registered or the
+   * `sys_secret` row is missing. Returns `null` when `ref` is not a secret ref.
+   */
+  async resolveSecret(ref, opts) {
+    const id = parseSecretRef(ref);
+    if (!id) return null;
+    if (!this.cryptoProvider) {
+      throw new Error("Cannot resolve secret: no CryptoProvider is registered (fail-closed).");
+    }
+    const secretDriver = this.getDriver("sys_secret");
+    const found = await secretDriver.find("sys_secret", { object: "sys_secret", where: { id } });
+    const secret = Array.isArray(found) ? found[0] : found;
+    if (!secret) {
+      throw new Error(`Cannot resolve secret: sys_secret row "${id}" not found (fail-closed).`);
+    }
+    const handle = {
+      id: secret.id,
+      kmsKeyId: secret.kms_key_id,
+      alg: secret.alg,
+      version: secret.version,
+      ciphertext: secret.ciphertext
+    };
+    return this.cryptoProvider.decrypt(handle, {
+      namespace: secret.namespace,
+      key: secret.key,
+      tenantId: opts?.tenantId
+    });
+  }
   /**
    * Helper to get object definition
    */
@@ -6325,6 +6794,7 @@ var _ObjectQL = class _ObjectQL {
         hookContext.event = "afterFind";
         hookContext.result = result;
         await this.triggerHooks("afterFind", hookContext);
+        this.maskSecretFields(object, hookContext.result);
         return hookContext.result;
       } catch (e) {
         this.logger.error("Find operation failed", e, { object });
@@ -6366,6 +6836,7 @@ var _ObjectQL = class _ObjectQL {
         const expanded = await this.expandRelatedRecords(objectName, [result], ast.expand, 0, opCtx.context);
         result = expanded[0];
       }
+      this.maskSecretFields(objectName, result);
       return result;
     });
     return opCtx.result;
@@ -6373,6 +6844,7 @@ var _ObjectQL = class _ObjectQL {
   async insert(object, data, options) {
     object = this.resolveObjectName(object);
     this.logger.debug("Insert operation starting", { object, isBatch: Array.isArray(data) });
+    this.assertWriteAllowed(object, "insert");
     const driver = this.getDriver(object);
     const opCtx = {
       object,
@@ -6401,7 +6873,13 @@ var _ObjectQL = class _ObjectQL {
           const rows = hookContext.input.data.map(
             (row) => this.applyFieldDefaults(object, row, opCtx.context, nowSnap)
           );
-          for (const r of rows) validateRecord(schemaForValidation, r, "insert");
+          for (const r of rows) {
+            await this.encryptSecretFields(object, r, opCtx.context, hookContext.input.options);
+          }
+          for (const r of rows) {
+            validateRecord(schemaForValidation, r, "insert");
+            evaluateValidationRules(schemaForValidation, r, "insert", { logger: this.logger });
+          }
           if (driver.bulkCreate) {
             result = await driver.bulkCreate(object, rows, hookContext.input.options);
           } else {
@@ -6414,7 +6892,9 @@ var _ObjectQL = class _ObjectQL {
             opCtx.context,
             nowSnap
           );
+          await this.encryptSecretFields(object, row, opCtx.context, hookContext.input.options);
           validateRecord(schemaForValidation, row, "insert");
+          evaluateValidationRules(schemaForValidation, row, "insert", { logger: this.logger });
           result = await driver.create(object, row, hookContext.input.options);
         }
         hookContext.event = "afterInsert";
@@ -6464,6 +6944,7 @@ var _ObjectQL = class _ObjectQL {
   async update(object, data, options) {
     object = this.resolveObjectName(object);
     this.logger.debug("Update operation starting", { object });
+    this.assertWriteAllowed(object, "update");
     const driver = this.getDriver(object);
     let id = data.id;
     if (!id && options?.where && typeof options.where === "object" && "id" in options.where) {
@@ -6490,11 +6971,23 @@ var _ObjectQL = class _ObjectQL {
       hookContext.input.options = this.buildDriverOptions(opCtx.context, hookContext.input.options);
       try {
         let result;
+        let priorRecord = null;
+        const updateSchema = this._registry.getObject(object);
         if (hookContext.input.id) {
-          validateRecord(this._registry.getObject(object), hookContext.input.data, "update");
+          await this.encryptSecretFields(object, hookContext.input.data, opCtx.context, hookContext.input.options);
+          validateRecord(updateSchema, hookContext.input.data, "update");
+          if (needsPriorRecord(updateSchema) || (this.hooks.get("afterUpdate")?.length ?? 0) > 0) {
+            const priorAst = { object, where: { id: hookContext.input.id }, limit: 1 };
+            priorRecord = await driver.findOne(object, priorAst, hookContext.input.options);
+          }
+          evaluateValidationRules(updateSchema, hookContext.input.data, "update", { previous: priorRecord, logger: this.logger });
           result = await driver.update(object, hookContext.input.id, hookContext.input.data, hookContext.input.options);
         } else if (options?.multi && driver.updateMany) {
-          validateRecord(this._registry.getObject(object), hookContext.input.data, "update");
+          await this.encryptSecretFields(object, hookContext.input.data, opCtx.context, hookContext.input.options);
+          validateRecord(updateSchema, hookContext.input.data, "update");
+          if (needsPriorRecord(updateSchema)) {
+            this.logger.warn("Object-level validation rules (state_machine/cross_field/script) are not enforced on multi-row updates", { object });
+          }
           const ast = { object, where: options.where };
           result = await driver.updateMany(object, ast, hookContext.input.data, hookContext.input.options);
         } else {
@@ -6502,6 +6995,7 @@ var _ObjectQL = class _ObjectQL {
         }
         hookContext.event = "afterUpdate";
         hookContext.result = result;
+        if (priorRecord) hookContext.previous = priorRecord;
         await this.triggerHooks("afterUpdate", hookContext);
         if (this.realtimeService) {
           try {
@@ -6534,6 +7028,7 @@ var _ObjectQL = class _ObjectQL {
   async delete(object, options) {
     object = this.resolveObjectName(object);
     this.logger.debug("Delete operation starting", { object });
+    this.assertWriteAllowed(object, "delete");
     const driver = this.getDriver(object);
     let id = void 0;
     if (options?.where && typeof options.where === "object" && "id" in options.where) {
@@ -6793,6 +7288,26 @@ var _ObjectQL = class _ObjectQL {
   getDriverByName(name) {
     return this.drivers.get(name);
   }
+  /**
+   * Introspect a datasource's live remote schema (ADR-0015).
+   *
+   * Resolves the driver registered under `datasource` and delegates to its
+   * `introspectSchema()` capability. Used by the external-datasource service
+   * (and CLI/REST) to list remote tables and validate federated objects.
+   *
+   * @throws if the datasource has no registered driver, or the driver does
+   *   not support introspection.
+   */
+  async introspectDatasource(datasource) {
+    const driver = this.drivers.get(datasource);
+    if (!driver) {
+      throw new Error(`[ObjectQL] Datasource '${datasource}' has no registered driver to introspect.`);
+    }
+    if (typeof driver.introspectSchema !== "function") {
+      throw new Error(`[ObjectQL] Driver for datasource '${datasource}' does not support introspectSchema().`);
+    }
+    return driver.introspectSchema();
+  }
   /**
    * Get the driver responsible for the given object.
    *
@@ -7726,7 +8241,7 @@ var ObjectQLPlugin = class {
    */
   async loadMetadataFromService(metadataService, ctx) {
     ctx.logger.info("Syncing metadata from external service into ObjectQL registry...");
-    const metadataTypes = ["object", "view", "app", "flow", "workflow", "function", "hook"];
+    const metadataTypes = ["object", "view", "app", "flow", "function", "hook"];
     let totalLoaded = 0;
     for (const type of metadataTypes) {
       try {
@@ -7877,6 +8392,8 @@ function convertIntrospectedSchemaToObjects(introspectedSchema, options) {
   ObjectRepository,
   ObjectStackProtocolImplementation,
   RESERVED_NAMESPACES,
+  SECRET_MASK,
+  SECRET_REF_PREFIX,
   SchemaRegistry,
   ScopedContext,
   SysMetadataRepository,
@@ -7885,11 +8402,18 @@ function convertIntrospectedSchemaToObjects(introspectedSchema, options) {
   applySystemFields,
   bindHooksToEngine,
   bucketDateValue,
+  collectSecretFields,
   computeFQN,
   convertIntrospectedSchemaToObjects,
   createObjectQLKernel,
+  evaluateValidationRules,
+  isSecretRef,
+  legalNextStates,
+  makeSecretRef,
+  needsPriorRecord,
   noopHookMetricsRecorder,
   parseFQN,
+  parseSecretRef,
   toTitleCase,
   validateRecord,
   wrapDeclarativeHook