@objectstack/core 17.0.0 → 17.1.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { Logger, LifecycleEventName, IServiceRegistry, AudienceBindingSuggestionFilter, IObjectQLEngine } from '@objectstack/spec/contracts';
-export { EngineSchemaRegistryView, EngineTransactionInfo, EngineTransactionOptions, IDataDriver, IDataEngine, IHttpRequest, IHttpResponse, IHttpServer, IObjectQLEngine, Logger, Middleware, RouteHandler } from '@objectstack/spec/contracts';
+export { EngineSchemaRegistryView, EngineTransactionInfo, EngineTransactionOptions, HttpResponseObservation, HttpResponseObserver, IDataDriver, IDataEngine, IHttpRequest, IHttpResponse, IHttpServer, IObjectQLEngine, Logger, Middleware, RouteHandler, UNMATCHED_ROUTE_PATTERN } from '@objectstack/spec/contracts';
 import { z } from 'zod';
 import { LoggerConfig, MigrationOnCrashPolicy, MigrationJournalEvent } from '@objectstack/spec/system';
 import { ObjectLogger } from './logger.cjs';
@@ -7,7 +7,7 @@ export { createLogger } from './logger.cjs';
 import * as QA from '@objectstack/spec/qa';
 import { KeyObject } from 'node:crypto';
 import { PluginCapability, PluginPermissions as PluginPermissions$1, PluginPermissionSet, ResourceType, PermissionAction, PluginPermission, SandboxConfig, KernelSecurityScanResult, KernelSecurityVulnerability, ExecutionContext, PluginHealthCheckParsed, PluginHealthStatus as PluginHealthStatus$1, PluginHealthReport, HotReloadConfigParsed, VersionConstraint, DependencyConflict, SemanticVersion, CompatibilityLevel } from '@objectstack/spec/kernel';
-import { AuthzPosture } from '@objectstack/spec/security';
+import { TenancyPosture, AuthzPosture } from '@objectstack/spec/security';
 export { nextUtcCalendarDay, utcInstantMs } from '@objectstack/spec/data';
 
 /**
@@ -222,6 +222,14 @@ declare class ObjectKernel {
     constructor(config?: ObjectKernelConfig);
     /**
      * Register a plugin with enhanced validation
+     *
+     * Duplicate names OVERWRITE, with one `warn` naming both versions — the
+     * declared contract in `plugin-registration.ts`, applied identically by
+     * `LiteKernel.use()` (#9864, maintainer ruling 2026-08-19). The overwrite
+     * itself is unchanged: it is what lets an app config's `plugins` entry
+     * supersede a plugin the CLI auto-registered earlier in the same boot
+     * (#9863). What changes is that it is no longer silent, and no longer
+     * disagrees with the other kernel.
      */
     use(plugin: Plugin): Promise<this>;
     /**
@@ -811,6 +819,17 @@ declare class LiteKernel extends ObjectKernelBase {
     /**
      * Register a plugin
      * @param plugin - Plugin instance
+     *
+     * Duplicate names OVERWRITE, with one `warn` naming both versions — the
+     * declared contract in `plugin-registration.ts`, applied identically by
+     * `ObjectKernel.use()` (#9864, maintainer ruling 2026-08-19).
+     *
+     * This method used to `throw` `[Kernel] Plugin '<name>' already
+     * registered` here while `ObjectKernel` overwrote silently, so one input
+     * had two meanings depending on which kernel was running — and the kernel
+     * that runs in production was the silent one. The ruling converged them on
+     * the behaviour that already works (an app config superseding a plugin the
+     * CLI auto-registered, #9863) and made it audible rather than removing it.
      */
     use(plugin: Plugin): this;
     /**
@@ -882,11 +901,67 @@ declare class TestRunner {
 declare class HttpTestAdapter implements TestExecutionAdapter {
     private baseUrl;
     private authToken?;
+    /**
+     * The single discovery probe of a run, memoised as the in-flight promise so
+     * concurrent record actions share one request rather than racing N.
+     *
+     * `os test` builds ONE adapter for the whole run (`packages/cli/src/commands/
+     * test.ts`) and hands it to every suite, so instance scope IS run scope.
+     */
+    private mountPromise?;
     constructor(baseUrl: string, authToken?: string | undefined);
-    /** `{baseUrl}{apiBasePath}{dataPrefix}/{object}` — the collection URL. */
+    /** The resolved data mount; probes at most once per adapter. */
+    private dataMount;
+    /**
+     * Ask the server where it serves the Data Protocol, and fall back to the
+     * convention — loudly — when it cannot say.
+     *
+     * ## [#7983] What the probe recovers, measured rather than assumed
+     *
+     * `@objectstack/client` answers the same question through discovery
+     * (`getRoute`, `packages/client/src/index.ts`), and this follows it: prefer
+     * the server's own `routes.data`, fall back to the convention. Measured on a
+     * booted stack (REST generator + dispatcher bridge, three configs):
+     *
+     *   | deployment                     | `{apiBase}/discovery` | serves        |
+     *   |--------------------------------|-----------------------|---------------|
+     *   | stock                          | 200 `/api/v1/data`    | `/api/v1/data`|
+     *   | `crud.dataPrefix: '/objects'`  | 200 `/api/v1/objects` | `/api/v1/objects` |
+     *   | `api.apiPath: '/api/2026-01'`  | **404**               | `/api/2026-01/data` |
+     *
+     * So the probe closes the `dataPrefix` row exactly: `RestServer`'s discovery
+     * handler substitutes the configured prefix into `routes.data`, and reading
+     * it is strictly better than recomputing it here. The `apiPath` row it cannot
+     * close, and the reason is structural rather than an oversight — `apiPath`
+     * moves the base that discovery itself is mounted under, so the document that
+     * would name the new mount is behind the very prefix we are missing.
+     *
+     * ⛔ And the one discovery document at a FIXED path does not rescue it:
+     * `/.well-known/objectstack` is mounted at the site root by the dispatcher
+     * bridge, but its `routes.data` is the DISPATCHER's own `${prefix}/data` —
+     * measured as `/api/v1/data` under all three configs above, including the two
+     * where the server serves elsewhere. Falling back to it would turn "we could
+     * not resolve the mount" into "discovery told us `/api/v1/data`": the same
+     * 404, now with a false provenance attached. Not probed, deliberately.
+     *
+     * Hence: one probe, then a diagnostic that NAMES the mount, the evidence and
+     * the remedy. `api_call` takes the path it is given and is unaffected either
+     * way — it stays the escape hatch for a host this cannot reach.
+     */
+    private resolveDataMount;
+    /** `{baseUrl}{dataMount}/{object}` — the collection URL. */
     private collectionUrl;
     /** `{collection}/{id}` — the single-record URL. */
     private recordUrl;
+    /**
+     * The provenance clause appended to a failed record action's error.
+     *
+     * The card this closes is about a 404 that reads like the author's own URL
+     * mistake; the mount is the one fact that distinguishes the two, so it rides
+     * on the failure itself rather than only on a warning printed earlier in the
+     * transcript.
+     */
+    private mountNote;
     execute(action: QA.TestAction, _context: Record<string, unknown>): Promise<unknown>;
     private createRecord;
     private updateRecord;
@@ -1712,9 +1787,74 @@ declare function isExpired(value: unknown, nowMs: number): boolean;
 /** The principal resolved from a valid `sys_api_key`. */
 interface ApiKeyPrincipal {
     userId: string;
+    /**
+     * The organization this key authenticates INTO — read from the row's
+     * `active_organization_id` and adopted by `resolveAuthzContext` as the
+     * request's active organization (`ExecutionContext.tenantId`), which is what
+     * lets the ADR-0105 Layer 0 wall match. `undefined` for a key minted before
+     * #8287, or one minted under the `single` posture where there is no
+     * organization to inherit.
+     */
     tenantId?: string;
     scopes: string[];
 }
+/**
+ * [#8287] Why a key was refused. Distinct from "no key present" and from "this
+ * key is unknown/revoked/expired": a refusal means the credential is real and
+ * intact but cannot be admitted under this deployment's tenancy posture.
+ */
+type ApiKeyRefusalReason = 'organization_required' | 'organization_membership_ended';
+/**
+ * The verdict on an inbound API key. Three outcomes, deliberately distinct:
+ *
+ *  - `none` — no key header, or a key that is unknown / revoked / expired /
+ *    owner-less. Indistinguishable by design (never tell a prober which), and
+ *    the caller MAY fall through to the session path exactly as before.
+ *  - `admitted` — a usable principal.
+ *  - `refused` — a real, intact key the posture cannot admit. The caller must
+ *    NOT fall through to the session path: falling through would be more
+ *    permissive than today's behaviour (an API key already outranks a session),
+ *    and the whole point of the refusal is that it is LOUD at call time.
+ */
+type ApiKeyAdmission = {
+    outcome: 'none';
+} | {
+    outcome: 'admitted';
+    principal: ApiKeyPrincipal;
+} | {
+    outcome: 'refused';
+    reason: ApiKeyRefusalReason;
+    message: string;
+};
+/**
+ * The shape of the kernel's `tenancy` service this module reads a posture from.
+ * Structural on purpose: `@objectstack/core` must not depend on the plugin that
+ * provides it, and an embedding without that plugin simply supplies nothing.
+ */
+interface TenancyPostureSource {
+    posture?: string;
+    isolationActive?: boolean;
+}
+/**
+ * [#8287] Resolve the EFFECTIVE tenancy posture from the kernel's `tenancy`
+ * service — the same reconciliation `plugin-security` performs before handing a
+ * posture to `computeTenantLayer0Filter`, so the wall and the API-key admission
+ * can never disagree about which posture is in force.
+ *
+ * ⚠️ Deliberately NOT `resolveTenancyPosture()` from `@objectstack/types`, which
+ * reads `OS_TENANCY_POSTURE` directly. That answers what the operator ASKED
+ * for, not what is ENFORCED: under ADR-0093 D4/D5 a deployment that requests
+ * `isolated` without the enterprise `@objectstack/organizations` runtime
+ * resolves to `single` and runs with NO organization wall. Reading the env
+ * there would refuse org-less API keys on a deployment whose wall is not even
+ * active — breaking working automation to enforce a boundary that does not
+ * exist. The `tenancy` service is the one place that already knows the
+ * difference.
+ *
+ * Returns `undefined` when no service is available, which callers must treat as
+ * "no posture-conditional refusal" — see {@link resolveApiKeyAdmission}.
+ */
+declare function effectiveTenancyPosture(tenancy: TenancyPostureSource | undefined | null): TenancyPosture | undefined;
 /**
  * Verify an inbound API key against `sys_api_key` and resolve its principal.
  * This is the ONE verify path shared by the dispatcher/MCP and REST surfaces.
@@ -1726,7 +1866,21 @@ interface ApiKeyPrincipal {
  * @param headers Request headers (Web `Headers` or a plain object).
  * @param nowMs   Clock for expiry checks (injectable for tests).
  */
-declare function resolveApiKeyPrincipal(ql: any, headers: any, nowMs?: number): Promise<ApiKeyPrincipal | undefined>;
+declare function resolveApiKeyPrincipal(ql: any, headers: any, nowMs?: number, tenancyPosture?: TenancyPosture): Promise<ApiKeyPrincipal | undefined>;
+/**
+ * [#8287] The full verdict behind {@link resolveApiKeyPrincipal} — same lookup,
+ * but it distinguishes a POSTURE REFUSAL from "no principal".
+ *
+ * `resolveApiKeyPrincipal` collapses `refused` into `undefined` so every
+ * existing caller keeps working and keeps failing closed; a caller that can
+ * report WHY (the shared `resolveAuthzContext`) uses this instead.
+ *
+ * The only refusal decided here is the org-less one, because it needs nothing
+ * but the row and the posture. The ex-member refusal needs the caller's
+ * membership set and is decided in `resolveAuthzContext`, where that set is
+ * already resolved.
+ */
+declare function resolveApiKeyAdmission(ql: any, headers: any, nowMs?: number, tenancyPosture?: TenancyPosture): Promise<ApiKeyAdmission>;
 
 /** The transport-agnostic authorization envelope produced from a request. */
 interface ResolvedAuthzContext {
@@ -1758,6 +1912,24 @@ interface ResolvedAuthzContext {
      * anonymous requests carry no rung.
      */
     posture?: AuthzPosture;
+    /**
+     * [#8287] Set when an inbound API key was REFUSED — a real, intact
+     * credential this deployment's tenancy posture cannot admit. The context is
+     * otherwise EMPTY (no `userId`), so every transport already fails it closed
+     * to 401 with no change; this field only lets a transport that wants to say
+     * WHY do so, instead of answering the operator with a bare "unauthenticated"
+     * for a key they can see is neither revoked nor expired.
+     *
+     * ⚠️ `reason` is NOT an `error.code`. The wire vocabulary is closed
+     * (ADR-0112: `StandardErrorCode ∪ ERROR_CODE_LEDGER`, both in `packages/spec`)
+     * and a refused credential's standard member is `UNAUTHENTICATED`. This is a
+     * diagnostic discriminator for the message, deliberately lowercase so it can
+     * never be mistaken for one.
+     */
+    authRefusal?: {
+        reason: ApiKeyRefusalReason;
+        message: string;
+    };
 }
 interface ResolveAuthzInput {
     /** Data engine (ObjectQL) exposing `find(object, { where, limit, context })`. */
@@ -1772,6 +1944,18 @@ interface ResolveAuthzInput {
     getSession?: (headers: any) => Promise<any> | any;
     /** Clock injection for API-key expiry (tests). */
     nowMs?: number;
+    /**
+     * [#8287] The deployment's EFFECTIVE tenancy posture, as resolved from the
+     * kernel's `tenancy` service (`effectiveTenancyPosture`) — never from
+     * `OS_TENANCY_POSTURE`, which reports what was requested rather than what is
+     * enforced (ADR-0093 D4/D5).
+     *
+     * Supplied by the transport because this resolver is deliberately
+     * kernel-agnostic. OMITTING it disables the two posture-conditional API-key
+     * refusals and leaves behaviour exactly as it was — so an unwired caller is
+     * never made WORSE, only less strict.
+     */
+    tenancyPosture?: TenancyPosture;
 }
 /**
  * Resolve the authorization context for an inbound request. Always resolves —
@@ -2230,12 +2414,16 @@ declare const ANONYMOUS_DENY_CODE: "UNAUTHENTICATED";
 /** Human-facing message. */
 declare const ANONYMOUS_DENY_MESSAGE = "Authentication is required to access this endpoint.";
 /**
- * The **REST seam's** 401 body — flat `{ error, message }`. NOT the platform's
- * only one; see the two-envelope table below before you reuse this shape.
+ * The **REST seam's** 401 body — flat `{ error, code, message }`. NOT the
+ * platform's only one; see the two-envelope table below before you reuse this
+ * shape.
  *
- * Exactly one consumer writes it: `@objectstack/rest`'s `enforceAuth`
- * (`rest-server.ts` — `res.status(ANONYMOUS_DENY_STATUS).json(ANONYMOUS_DENY_BODY)`),
- * which owns the `/data/*` and `/meta` surfaces.
+ * Two consumers write it verbatim, both flat-family seams: `@objectstack/rest`'s
+ * `enforceAuth` (`rest-server.ts` —
+ * `res.status(ANONYMOUS_DENY_STATUS).json(ANONYMOUS_DENY_BODY)`), which owns the
+ * `/data/*` and `/meta` surfaces, and `@objectstack/runtime`'s
+ * `mountRouteOnServer` (`dispatcher-plugin.ts` — the endpoint-route 401 arm,
+ * #9823), which answers declared routes mounted on the HTTP server.
  *
  * ## Two live envelopes, one denial (#5632)
  *
@@ -2244,8 +2432,11 @@ declare const ANONYMOUS_DENY_MESSAGE = "Authentication is required to access thi
  * {@link ANONYMOUS_DENY_MESSAGE}). What differs is the **wrapper**:
  *
  *  - **REST seam** — `@objectstack/rest` `enforceAuth`, this constant, verbatim:
- *    `{ error: 'UNAUTHENTICATED', message: '…' }`. The code is the value of the
- *    top-level `error` key; there is no `success` key and no nesting.
+ *    `{ error: 'UNAUTHENTICATED', code: 'UNAUTHENTICATED', message: '…' }`.
+ *    The machine code lives in the top-level `code` key — the same documented
+ *    key every other REST error family answers (#9487, maintainer-ruled
+ *    ADDITIVE: `error` keeps carrying the code value it always has, so no
+ *    existing reader breaks). There is no `success` key and no nesting.
  *  - **Dispatcher seams** — the five runtime domains `domains/ai.ts`,
  *    `domains/meta.ts`, `domains/security.ts`, `domains/actions.ts` and
  *    `domains/automation.ts` do NOT use this constant. Each calls
@@ -2257,7 +2448,10 @@ declare const ANONYMOUS_DENY_MESSAGE = "Authentication is required to access thi
  * (#4007) records the flat and wrapped envelopes as the two live ones, and
  * assigns retiring one of them to the envelope-convergence line (#3843 family).
  * Converging them is a breaking wire change; it is not this module's to make,
- * and this constant must not be read as if it had already happened.
+ * and this constant must not be read as if it had already happened. The #9487
+ * `code` key does NOT settle that question either way (ADR-0112 D5 stays
+ * open): it aligns the flat family to the `{ error, code }` shape the other
+ * flat REST error families already answer, without moving or removing a key.
  *
  * ## Reading this from a consumer (human or AI author)
  *
@@ -2274,6 +2468,7 @@ declare const ANONYMOUS_DENY_MESSAGE = "Authentication is required to access thi
  */
 declare const ANONYMOUS_DENY_BODY: {
     readonly error: "UNAUTHENTICATED";
+    readonly code: "UNAUTHENTICATED";
     readonly message: "Authentication is required to access this endpoint.";
 };
 interface AnonymousDenyInput {
@@ -2316,6 +2511,114 @@ declare function isGrantActive(row: GrantValidityWindow | null | undefined, nowM
  */
 declare function isGrantExpired(row: GrantValidityWindow | null | undefined, nowMs: number): boolean;
 
+/** A catalogue row that may carry the `active` flag (`sys_permission_set`, `sys_position`). */
+interface ActivatableRow {
+    active?: unknown;
+}
+/**
+ * True unless the row carries an `active` column that is explicitly OFF.
+ *
+ * The ONE predicate every reader of `sys_permission_set.active` /
+ * `sys_position.active` uses, so the resolver that enforces the flag and the
+ * break-glass guard that simulates a write to it can never disagree about what
+ * "deactivated" means.
+ */
+declare function isRowActive(row: ActivatableRow | null | undefined): boolean;
+
+/**
+ * ADMIN_STANDING_SURFACE — what `resolveAuthzContext` READS when it decides
+ * who is an administrator, declared beside the resolver that reads it.
+ *
+ * ## Why this file exists (#8734)
+ *
+ * `plugin-auth`'s break-glass guard (`last-admin-guard.ts`, ADR-0024 D5.2)
+ * decides whether a pending write can empty the administrator population by
+ * testing the payload against three standing-key lists — `MEMBER_STANDING_KEYS`,
+ * `GRANT_STANDING_KEYS`, `PERMISSION_SET_STANDING_KEYS`. Those lists are not an
+ * independent design artifact: they are a CACHE of the columns this resolver
+ * consumes. A payload touching none of them is skipped without any reads, so a
+ * column this resolver starts reading and the guard's list omits is a write
+ * class the guard silently stops judging — the one write class that can lock an
+ * installation out of its own administration, with no in-product recovery.
+ *
+ * Nothing bound the two together. The correspondence was carried by a comment,
+ * and it had already gone false once: #6084 wrote, beside the list, that
+ * everything a permission-set write touches other than `name` — naming `active`
+ * explicitly — is invisible to "who is an administrator". That was true when
+ * written. #8613 made `active` a resolution-time predicate (a DEACTIVATED
+ * `admin_full_access` set confers nothing, §6b below), and the sentence became
+ * false. It was caught by one agent reading the comment closely enough to
+ * notice it contradicted the code being written. Nothing mechanical would have
+ * caught it: the guard's own tests stay green, because the guard is simply never
+ * consulted for that write.
+ *
+ * ## What this file is, and what it is NOT
+ *
+ * It is a MEASUREMENT, not a wish. Its column lists are asserted equal to what
+ * the resolver actually reads at runtime, by
+ * `admin-standing-surface.test.ts`, which drives the real
+ * `resolveAuthzContext` over a recording engine and collects every property
+ * access and every `where` key per table. That is deliberate: a hand-written
+ * list of "columns the derivation reads" is the same artifact as the comment
+ * that went stale, one indirection along. Observation is also the only reading
+ * that survives the derivation moving INTO a helper — `active` is read by
+ * `isRowActive(ps)` and the window bounds by `isGrantActive(row, now)`, neither
+ * of which names a column at the resolver's own call site.
+ *
+ * It is NOT a projection the resolver consumes. `ql.find` here returns whole
+ * rows and the reads are ordinary property accesses on untyped rows, so nothing
+ * in this file can FORCE the resolver to read only what it declares. The force
+ * comes from the observation test: add a read, and this declaration is red
+ * until it is updated; update this declaration, and `plugin-auth`'s
+ * correspondence test is red until every new column is either in a standing-key
+ * list or explicitly excluded with a reason.
+ *
+ * ## Reading the entries
+ *
+ * Every table this resolution path reads is listed — including the ones that
+ * CANNOT confer administrator standing, each with the reason it cannot. That is
+ * the table-level half of the same guarantee: a resolver that starts deriving
+ * administrator standing from a new table would otherwise be invisible to a
+ * column-set comparison, because the new table appears in neither side's list.
+ */
+/** How a table this resolver reads relates to "who is an administrator". */
+interface AdminStandingTable {
+    /**
+     * `derives` — a write to this table can change the administrator population,
+     * so `last-admin-guard.ts` must carry a standing-key list for it.
+     * `reads-only` — this resolver reads the table for something else entirely.
+     */
+    readonly role: 'derives' | 'reads-only';
+    /** Why the row above is the right classification. Prose, but pinned to a measured table. */
+    readonly reason: string;
+    /**
+     * Every column this resolver reads on the table — property accesses and
+     * `where` keys alike, in every spelling it actually touches. Declared for
+     * `derives` tables only; asserted equal to the observed set.
+     */
+    readonly columns?: readonly string[];
+}
+/**
+ * The measured read surface of the administrator derivation.
+ *
+ * Scope, stated so the gate cannot be read as claiming more than it measures:
+ * this is the SESSION/user-id resolution path — `resolveAuthzContext` with a
+ * principal, and therefore all of `resolveUserAuthzGrants`. The API-key
+ * ADMISSION path (`resolveApiKeyAdmission`) is outside it on purpose: it
+ * authenticates a principal and seeds `permissions` with the key's scopes, and
+ * confers no administrator standing of its own — `hasPlatformAdminGrant` (§6b)
+ * is set only from a `sys_permission_set` row reached through an UNSCOPED
+ * `sys_user_permission_set` grant, never from a scope string.
+ */
+declare const ADMIN_STANDING_SURFACE: Readonly<Record<string, AdminStandingTable>>;
+/** The tables a write to which can change who is an administrator. */
+declare function adminStandingTables(): string[];
+/**
+ * The columns this resolver reads on `table`, or `undefined` when the table is
+ * not part of the administrator derivation.
+ */
+declare function adminStandingColumns(table: string): readonly string[] | undefined;
+
 /**
  * [#7678] The `?status=` vocabulary of the audience-binding suggestion list
  * (ADR-0090 D5/D9) — ONE owner for a rule that had exactly one implementation
@@ -2512,6 +2815,20 @@ interface CalendarParts {
     month: number;
     day: number;
 }
+/**
+ * A wall clock as a human writes it — calendar day plus an optional
+ * time-of-day, with **no zone attached**. `2026-08-01 06:00:00` is this shape:
+ * it names a reading on a clock, and only a reference timezone turns it into an
+ * instant. Omitted time components default to 0, so {@link CalendarParts} alone
+ * is midnight.
+ */
+interface WallClockParts extends CalendarParts {
+    /** 0-23. */
+    hour?: number;
+    minute?: number;
+    second?: number;
+    millisecond?: number;
+}
 /**
  * The year/month/day an instant falls on in `tz`. Throws if `tz` is not a
  * valid IANA zone (callers treat that as a fall-through to UTC).
@@ -2536,8 +2853,52 @@ declare function calendarPartsInTzOrUtc(d: Date, tz?: string): CalendarParts;
  *
  * Used by date-bucket drill ranges (#1752): a `datetime` field buckets on the
  * reference-tz calendar, so its bucket boundary is that tz's midnight instant.
+ *
+ * Date-only by contract: a `YYYY-MM-DD HH:mm:ss` argument is still `NaN` here.
+ * Callers holding a wall clock with a time-of-day want
+ * {@link zonedWallClockToUtcMs}, which this delegates its zone arithmetic to.
  */
 declare function zonedDateStartToUtcMs(ymd: string, tz?: string): number;
+/**
+ * The UTC instant (epoch ms) at which a **wall clock** reading happens in
+ * reference timezone `tz` — the general inverse of {@link calendarPartsInTz},
+ * of which {@link zonedDateStartToUtcMs} is the midnight special case.
+ *
+ * `2026-08-01 06:00:00` in `Asia/Shanghai` is `2026-07-31T22:00:00Z`: a
+ * different day, month and quarter. That gap is why this direction exists as a
+ * shared primitive at all — bulk import (#8485) reads offset-free spreadsheet
+ * cells, which are wall clocks and nothing more, and `new Date(cell)` resolves
+ * them against the **process** `TZ`, i.e. a host setting rather than the
+ * tenant's configured zone.
+ *
+ * DST-safe: the zone offset is read from the platform tz database via
+ * `Intl.DateTimeFormat` (never hand-computed), and a two-pass resolution settles
+ * the case where the offset differs side-to-side of the target instant. Two
+ * wall clocks are not a bijection with instants, and this function resolves
+ * both degenerate cases to the **earlier candidate instant** — in both, the
+ * final pass reads the offset on the DST side of the transition (measured, not
+ * merely intended — `datetime.test.ts` pins both):
+ *  - a clock reading the zone **skips** (spring forward: `02:30` on a US
+ *    spring-forward day) settles on the *post*-transition offset (EDT, −04),
+ *    which places the instant just **before** the gap: it reads `01:30` EST
+ *    locally, not `03:30` EDT. Note this is the opposite of Temporal's
+ *    `'compatible'` disambiguation, which pushes a gap reading forward;
+ *  - a clock reading that happens **twice** (fall back: `01:30` on a US
+ *    fall-back day) resolves to its first occurrence, the one still on the
+ *    pre-transition DST offset (EDT, −04).
+ *
+ * A spreadsheet cell naming a wall clock that its zone never had is ambiguous
+ * by construction; what matters for an import is that the answer is
+ * deterministic and host-independent, which both branches above are.
+ *
+ * FALLBACK — an unset, `'UTC'`, or invalid `tz` reads the wall clock **as UTC**,
+ * never as the process-local clock. Every caller of this family already degrades
+ * that way ({@link zonedDateStartToUtcMs}, and the export renderer's cell path),
+ * and a host `TZ` fallback would reintroduce exactly the deployment-dependent
+ * instant this primitive exists to remove. A parts object that produces an
+ * invalid date (`NaN` components) returns `NaN`, as `Date.UTC` does.
+ */
+declare function zonedWallClockToUtcMs(parts: WallClockParts, tz?: string): number;
 
 /**
  * Granularity of a canonical date-bucket key. Mirrors `@objectstack/spec`'s
@@ -3006,6 +3367,34 @@ declare function resolveFilterTokens<T>(filter: T, ctx?: FilterTokenResolutionCo
  */
 declare function filterTokenContextFrom(execCtx: ExecutionContextLike | undefined, now?: Date): FilterTokenResolutionContext;
 
+/** Which temporal storage rule a declared field takes. */
+type TemporalComparandKind = 'datetime' | 'date' | 'time';
+/**
+ * The kind a declared field's `type` takes, or `null` for every non-temporal
+ * field.
+ *
+ * The same three-way split `driver-memory`'s `indexTemporalFields` and
+ * `SqlDriver.temporalFieldKind` make, so the door and the drivers cannot
+ * disagree about which fields are temporal at all.
+ */
+declare function temporalComparandKind(fieldType: unknown): TemporalComparandKind | null;
+/**
+ * Is `value` a comparand that a `kind` column's storage rule cannot read?
+ *
+ * `true` ONLY for a non-empty, non-placeholder STRING that the kind's rule
+ * would hand back unchanged. Everything else — a number, a `Date`, `null`, a
+ * `{ $field }` reference, filter structure, the empty string, a `{token}` —
+ * answers `false`, each for a reason recorded in the module note or below.
+ *
+ * A `{placeholder}` is stepped around rather than judged because it is another
+ * layer's vocabulary and that layer already refuses the unknown ones loudly
+ * (`FILTER_TOKEN_UNKNOWN` / 400, with the resolvable tokens listed). Both doors
+ * that call this run BEFORE token resolution, so judging a placeholder here
+ * would refuse `{30_days_ago}` — the platform's own correct spelling, and the
+ * positive control this fix is pinned against.
+ */
+declare function isUninterpretableTemporalComparand(kind: TemporalComparandKind, value: unknown): boolean;
+
 /**
  * [#4435] The 404 a single-record operation answers when the id names no row.
  *
@@ -3630,4 +4019,4 @@ declare class NamespaceResolver {
     private suggestAlternative;
 }
 
-export { ANONYMOUS_DENY_BODY, ANONYMOUS_DENY_CODE, ANONYMOUS_DENY_MESSAGE, ANONYMOUS_DENY_STATUS, API_KEY_PREFIX, AUDIENCE_BINDING_SUGGESTION_STATUSES, AUDIENCE_BINDING_SUGGESTION_STATUS_VALUES, type AnonymousDenyInput, type ApiKeyPrincipal, type AudienceBindingSuggestionStatus, type AuthGate, type BucketGranularity, type BulkWriteOptions, type BulkWriteRowResult, CORE_FALLBACK_FACTORIES, type CalendarParts, DependencyResolver, ENTRY_EXECUTION_CONTEXT_FIELDS, type EngineWithTransaction, type EntryExecutionContextField, type EntryLocalization, type ExecutionContextAssemblyInput, type ExecutionContextEntryFields, type ExecutionContextLike, type FilterTokenResolutionContext, type GeneratedApiKey, type GrantValidityWindow, HotReloadManager, type InterruptedRun, type KernelState, type KeyInput, type LadderPrincipal, type LadderRow, LiteKernel, type MigrationChunk, type MigrationChunkContext, MigrationJournalRefusal, type MigrationPlan, type MigrationPlanProvider, MigrationPlanRegistry, type MigrationPlanStep, type MigrationRunResult, type NamespaceCheckResult, type NamespaceConflict, type NamespaceEntry, NamespaceResolver, type OAuthTokenProvenance, OPERATION_PRIVATE_KEY_PREFIX, ObjectKernel, ObjectKernelBase, type ObjectKernelConfig, ObjectLogger, type OrderablePlugin, POSTURE_INJECTION_RULE, POSTURE_LADDER, POSTURE_RANK, type ParsedSignature, type PermissionCheckResult$1 as PermissionCheckResult, type PermissionGrant, type Plugin, type PluginArtifactVerifyResult, PluginConfigValidator, type PluginContext, PluginHealthMonitor, type PluginHealthStatus, type PluginLoadResult, PluginLoader, type PluginMetadata, type PermissionCheckResult as PluginPermissionCheckResult, PluginPermissionEnforcer, PluginPermissionManager, type PluginPermissions, PluginSandboxRuntime, PluginSecurityScanner, type PluginSignatureConfig, PluginSignatureVerifier, type PluginStartupResult, type PostureEvidence, type PublisherVerifyResult, index as QA, type ResolveAuthzInput, type ResolveLocalizationInput, type ResolveUserAuthzGrantsOptions, type ResolvedAuthzContext, type ResourceUsage, type RetryOptions, type RunMigrationJournalOptions, SIGNATURE_ALG, type SandboxContext, type ScanTarget, SecurePluginContext, type SecurityIssue, SemanticVersionManager, type ServiceFactory, ServiceLifecycle, type ServiceRegistration, type SignatureVerificationResult, UnknownFilterTokenError, UnresolvedFilterTokenError, type UserAuthzGrants, type VersionCompatibility, assembleExecutionContext, assembleExecutionContextOrGuest, assertInitServiceRequirements, assertMetadataRegisterContract, bucketKeyToCalendarRange, buildPermissionsFromGrants, bulkWrite, calendarPartsInTz, calendarPartsInTzOrUtc, canonicalMetadataServiceType, collectInternalWriteResponseFields, counterSignPayload, createMemoryCache, createMemoryI18n, createMemoryJob, createMemoryMetadata, createMemoryQueue, createPluginConfigValidator, createPluginPermissionEnforcer, deepMerge, defaultIsTransientError, derivePosture, describeInitOrderFault, engineCanRollBack, evaluateAuthGate, extractApiKey, filterTokenContextFrom, findInterruptedRuns, generateApiKey, generateEd25519KeyPair, getEnv, getMemoryUsage, hashApiKey, hashMigrationPlan, isAudienceBindingSuggestionStatus, isAuthGateAllowlisted, isExpired, isGrantActive, isGrantExpired, isNode, normalizeAuthGate, omitInternalFieldsFromWriteResponse, parseScopes, parseSignature, planChunks, postureVisibleRows, readAuthoredTranslationLayer, readRunJournal, recordNotFoundError, resolveApiKeyPrincipal, resolveAuthzContext, resolveFilterToken, resolveFilterTokens, resolveLocale, resolveLocalizationContext, resolvePluginOrder, resolveUserAuthzGrants, resumeMigrationJournal, runMigrationJournal, safeExit, shouldDenyAnonymous, signPayload, unknownAudienceBindingSuggestionStatusMessage, validateInitServiceContract, verifyPayload, verifyPlatformSignature, verifyPluginArtifact, verifyPublisherSignature, wireAuthoredTranslationSync, withTransientRetry, withoutOperationPrivateKeys, zonedDateStartToUtcMs };
+export { ADMIN_STANDING_SURFACE, ANONYMOUS_DENY_BODY, ANONYMOUS_DENY_CODE, ANONYMOUS_DENY_MESSAGE, ANONYMOUS_DENY_STATUS, API_KEY_PREFIX, AUDIENCE_BINDING_SUGGESTION_STATUSES, AUDIENCE_BINDING_SUGGESTION_STATUS_VALUES, type ActivatableRow, type AdminStandingTable, type AnonymousDenyInput, type ApiKeyAdmission, type ApiKeyPrincipal, type ApiKeyRefusalReason, type AudienceBindingSuggestionStatus, type AuthGate, type BucketGranularity, type BulkWriteOptions, type BulkWriteRowResult, CORE_FALLBACK_FACTORIES, type CalendarParts, DependencyResolver, ENTRY_EXECUTION_CONTEXT_FIELDS, type EngineWithTransaction, type EntryExecutionContextField, type EntryLocalization, type ExecutionContextAssemblyInput, type ExecutionContextEntryFields, type ExecutionContextLike, type FilterTokenResolutionContext, type GeneratedApiKey, type GrantValidityWindow, HotReloadManager, type InterruptedRun, type KernelState, type KeyInput, type LadderPrincipal, type LadderRow, LiteKernel, type MigrationChunk, type MigrationChunkContext, MigrationJournalRefusal, type MigrationPlan, type MigrationPlanProvider, MigrationPlanRegistry, type MigrationPlanStep, type MigrationRunResult, type NamespaceCheckResult, type NamespaceConflict, type NamespaceEntry, NamespaceResolver, type OAuthTokenProvenance, OPERATION_PRIVATE_KEY_PREFIX, ObjectKernel, ObjectKernelBase, type ObjectKernelConfig, ObjectLogger, type OrderablePlugin, POSTURE_INJECTION_RULE, POSTURE_LADDER, POSTURE_RANK, type ParsedSignature, type PermissionCheckResult$1 as PermissionCheckResult, type PermissionGrant, type Plugin, type PluginArtifactVerifyResult, PluginConfigValidator, type PluginContext, PluginHealthMonitor, type PluginHealthStatus, type PluginLoadResult, PluginLoader, type PluginMetadata, type PermissionCheckResult as PluginPermissionCheckResult, PluginPermissionEnforcer, PluginPermissionManager, type PluginPermissions, PluginSandboxRuntime, PluginSecurityScanner, type PluginSignatureConfig, PluginSignatureVerifier, type PluginStartupResult, type PostureEvidence, type PublisherVerifyResult, index as QA, type ResolveAuthzInput, type ResolveLocalizationInput, type ResolveUserAuthzGrantsOptions, type ResolvedAuthzContext, type ResourceUsage, type RetryOptions, type RunMigrationJournalOptions, SIGNATURE_ALG, type SandboxContext, type ScanTarget, SecurePluginContext, type SecurityIssue, SemanticVersionManager, type ServiceFactory, ServiceLifecycle, type ServiceRegistration, type SignatureVerificationResult, type TemporalComparandKind, type TenancyPostureSource, UnknownFilterTokenError, UnresolvedFilterTokenError, type UserAuthzGrants, type VersionCompatibility, type WallClockParts, adminStandingColumns, adminStandingTables, assembleExecutionContext, assembleExecutionContextOrGuest, assertInitServiceRequirements, assertMetadataRegisterContract, bucketKeyToCalendarRange, buildPermissionsFromGrants, bulkWrite, calendarPartsInTz, calendarPartsInTzOrUtc, canonicalMetadataServiceType, collectInternalWriteResponseFields, counterSignPayload, createMemoryCache, createMemoryI18n, createMemoryJob, createMemoryMetadata, createMemoryQueue, createPluginConfigValidator, createPluginPermissionEnforcer, deepMerge, defaultIsTransientError, derivePosture, describeInitOrderFault, effectiveTenancyPosture, engineCanRollBack, evaluateAuthGate, extractApiKey, filterTokenContextFrom, findInterruptedRuns, generateApiKey, generateEd25519KeyPair, getEnv, getMemoryUsage, hashApiKey, hashMigrationPlan, isAudienceBindingSuggestionStatus, isAuthGateAllowlisted, isExpired, isGrantActive, isGrantExpired, isNode, isRowActive, isUninterpretableTemporalComparand, normalizeAuthGate, omitInternalFieldsFromWriteResponse, parseScopes, parseSignature, planChunks, postureVisibleRows, readAuthoredTranslationLayer, readRunJournal, recordNotFoundError, resolveApiKeyAdmission, resolveApiKeyPrincipal, resolveAuthzContext, resolveFilterToken, resolveFilterTokens, resolveLocale, resolveLocalizationContext, resolvePluginOrder, resolveUserAuthzGrants, resumeMigrationJournal, runMigrationJournal, safeExit, shouldDenyAnonymous, signPayload, temporalComparandKind, unknownAudienceBindingSuggestionStatusMessage, validateInitServiceContract, verifyPayload, verifyPlatformSignature, verifyPluginArtifact, verifyPublisherSignature, wireAuthoredTranslationSync, withTransientRetry, withoutOperationPrivateKeys, zonedDateStartToUtcMs, zonedWallClockToUtcMs };