@objectstack/core 17.0.0-rc.5 → 17.0.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { Logger, LifecycleEventName, IServiceRegistry, IObjectQLEngine } from '@objectstack/spec/contracts';
+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';
 import { z } from 'zod';
 import { LoggerConfig, MigrationOnCrashPolicy, MigrationJournalEvent } from '@objectstack/spec/system';
@@ -6,7 +6,7 @@ import { ObjectLogger } from './logger.cjs';
 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, PluginHealthCheck, PluginHealthStatus as PluginHealthStatus$1, PluginHealthReport, HotReloadConfig, VersionConstraint, DependencyConflict, SemanticVersion, CompatibilityLevel } from '@objectstack/spec/kernel';
+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';
 export { nextUtcCalendarDay, utcInstantMs } from '@objectstack/spec/data';
 
@@ -353,13 +353,18 @@ declare class ObjectKernel {
      * one bad handler must not amplify into leaked resources and unflushed
      * writes. Same reasoning, same wording, same `Hook handler failed:
      * kernel:shutdown` log line as `LiteKernel`'s dispatch site, which reaches
-     * the shared isolating dispatcher `ObjectKernelBase.triggerHook` (#5257).
+     * the isolating dispatcher through `ObjectKernelBase.triggerHook` (#5257).
      *
-     * `ObjectKernel` cannot call that dispatcher: it does not extend
+     * Until #5282 "same wording" was literally that — the loop was typed out a
+     * second time here, because `ObjectKernel` does not extend
      * `ObjectKernelBase` (only `LiteKernel` does) and owns its own `hooks` map,
-     * so the semantics are mirrored here rather than shared. One hook name
-     * meaning two opposite things across the two kernels is exactly the bug
-     * #5170/#5257 closed, so the pin for this one lives on both sides too.
+     * so the base's `protected triggerHook` is out of reach. The loop now lives
+     * in {@link dispatchHookIsolating}, which BOTH sides call: the storage is
+     * still two maps (deliberately — unifying it was out of #5282's scope), but
+     * "isolating" is one implementation, so it can no longer drift on one
+     * kernel while the other keeps the old shape. That drift is exactly the bug
+     * #5170 / #5257 / #5274 each closed one hook at a time, and the paired-pin
+     * gate (`scripts/check-kernel-hook-pairs.mjs`) covers the residue.
      */
     private triggerShutdownHookIsolating;
     private performShutdown;
@@ -622,6 +627,11 @@ declare abstract class ObjectKernelBase {
      * (`kernel:ready`, `kernel:bootstrapped`, `kernel:listening`) use
      * {@link triggerHookOrThrow} (#5170, #5257).
      *
+     * The loop itself lives in {@link dispatchHookIsolating} — one
+     * implementation shared with `ObjectKernel`'s own `kernel:shutdown`
+     * dispatch, which cannot inherit this method (`ObjectKernel` does not
+     * extend this class) and used to hand-mirror it (#5282).
+     *
      * @param name - Hook name
      * @param args - Arguments to pass to handlers
      */
@@ -661,6 +671,10 @@ declare abstract class ObjectKernelBase {
      * default — and it is the reason this dispatcher is chosen per hook rather
      * than swapped in wholesale.
      *
+     * The loop itself lives in {@link dispatchHookPropagating} — the same
+     * function `PluginContext.trigger` runs on both kernels, so "propagating"
+     * means one thing repo-wide (#5282).
+     *
      * @param name - Hook name
      * @param args - Arguments to pass to handlers
      */
@@ -869,6 +883,10 @@ declare class HttpTestAdapter implements TestExecutionAdapter {
     private baseUrl;
     private authToken?;
     constructor(baseUrl: string, authToken?: string | undefined);
+    /** `{baseUrl}{apiBasePath}{dataPrefix}/{object}` — the collection URL. */
+    private collectionUrl;
+    /** `{collection}/{id}` — the single-record URL. */
+    private recordUrl;
     execute(action: QA.TestAction, _context: Record<string, unknown>): Promise<unknown>;
     private createRecord;
     private updateRecord;
@@ -1831,6 +1849,275 @@ declare function resolveLocalizationContext(input: ResolveLocalizationInput): Pr
     currency?: string;
 }>;
 
+/**
+ * ADR-0069 — authentication-policy session gate.
+ *
+ * Some auth policies (password expiry, enforced MFA) must block an
+ * authenticated user from PROTECTED RESOURCES until they remediate, while
+ * still letting them reach the auth endpoints (change-password, two-factor
+ * enrollment, sign-out) and a few UI-bootstrap reads.
+ *
+ * The posture is computed ONCE, in the auth `customSession` enrichment, and
+ * attached to the session user as `user.authGate = { code, message }`. The
+ * transport seams (REST middleware, dispatcher) then call
+ * {@link evaluateAuthGate} to decide whether THIS request is blocked. Keeping
+ * the allow-list + decision in one pure function means the seams can never
+ * drift on what is blocked.
+ */
+
+/**
+ * The gate posture, DERIVED from its declaration on `ExecutionContextSchema`
+ * (`packages/spec/src/kernel/execution-context.zod.ts`) rather than restated
+ * here (#7280).
+ *
+ * It was a hand-written interface while the envelope field was undeclared, so
+ * the two could have drifted with nothing to catch it — the exact class of
+ * defect the closed entry field set (#6216) exists to make unrepresentable.
+ * One declaration, one type.
+ */
+type AuthGate = NonNullable<ExecutionContext['authGate']>;
+/**
+ * Normalize the `authGate` a better-auth session user carries into the shape
+ * `ExecutionContextSchema` declares — or `null` when there is no gate.
+ *
+ * The session user crosses an external boundary as `any`, so this is where the
+ * declared contract is actually met: a gate naming no string `code` is not a
+ * gate, and a missing/blank `message` is filled with the default rather than
+ * riding onto the envelope (and into a `403` body) as `undefined`. Both
+ * consumers normalize HERE, at the one producer, instead of tolerating a loose
+ * shape downstream: {@link evaluateAuthGate} for the seams that decide per
+ * path, and REST's `computeExecCtx` for the seam that lifts the posture onto
+ * the execution context.
+ */
+declare function normalizeAuthGate(sessionUser: any): AuthGate | null;
+/** True when `path` is exempt from the auth gate (auth + remediation + health). */
+declare function isAuthGateAllowlisted(rawPath: string | undefined | null): boolean;
+/**
+ * Returns the active gate when `sessionUser` carries an `authGate` AND `path`
+ * is not allow-listed; otherwise null. Anonymous users (no `authGate`) and
+ * allow-listed paths always pass.
+ */
+declare function evaluateAuthGate(sessionUser: any, path: string): AuthGate | null;
+
+/**
+ * assembleExecutionContext — the SINGLE assembly of an inbound request's
+ * {@link ExecutionContext}, shared by every transport entry point.
+ *
+ * `resolveAuthzContext` (next door) already made AUTHORIZATION resolution
+ * single-sourced. The step AFTER it — turning the resolved
+ * {@link ResolvedAuthzContext} into the `ExecutionContext` envelope that
+ * reaches enforcement — stayed hand-written per transport, and that duplication
+ * produced a measured defect family:
+ *
+ *  - **#6071 — field drift.** The REST copy never set `principalKind`, so every
+ *    enforcement judgment reading it (explain's guest⇒EXTERNAL floor, the
+ *    security plugin's agent baseline, the perf-disclosure gate) was silently
+ *    never-true on that face.
+ *  - **#6206 / #6551 — dropped fields.** The share-link copies omitted
+ *    `accessible_org_ids`, and the `group` posture's Layer 0 wall reads it
+ *    directly: real 403s for callers who should have been let through. Both
+ *    surfaces were since converted to pass the WHOLE envelope through.
+ *
+ * Both defects are the same shape: a field exists on `ExecutionContext`, one
+ * copy carries it, another silently does not. This module makes that shape
+ * unrepresentable by CLOSING the field set with a type
+ * ({@link ExecutionContextEntryFields}) — every field a transport entry point
+ * decides must be decided HERE, explicitly, and a new `ExecutionContext` field
+ * fails to compile until it is either assembled or listed as
+ * non-entry-resolved.
+ *
+ * ## Two named entries — the anonymous face is genuinely divergent (#6216)
+ *
+ * The maintainer ruling of 2026-08-08 on #6216 (Option A) settled the one
+ * question that blocked convergence: what an anonymous request yields.
+ *
+ *  - {@link assembleExecutionContext} — the DEFAULT, fail-closed entry. No
+ *    resolved principal → `undefined`, and the surface answers 401. This is the
+ *    REST face's contract, unchanged.
+ *  - {@link assembleExecutionContextOrGuest} — the EXPLICIT guest entry. No
+ *    resolved principal → a first-class guest envelope
+ *    (`principalKind: 'guest'`, `positions: ['guest']`), which the runtime /
+ *    MCP dispatcher has always produced and whose consumers are live
+ *    (`plugin-security/explain-engine.ts`: guest ⇒ `EXTERNAL` posture). A
+ *    surface adopts this entry ONLY when its product semantics serve anonymous
+ *    principals.
+ *
+ * Neither surface's runtime behaviour changes. What changes is that the
+ * divergence is now NAMED API rather than drift — and the same is true of the
+ * per-face values below (`accessToken`, `oauth`, `localization`): they are
+ * REQUIRED inputs, so a face cannot silently omit one, and what a face chooses
+ * to withhold it withholds on the record.
+ *
+ * Options B (guest everywhere — turns REST's anonymous 401s into authz-shaped
+ * denials and makes anonymous-serving the DEFAULT posture of a new surface) and
+ * C (no-ctx everywhere — deletes the guest principal, the `guest` position and
+ * explain's `EXTERNAL` floor) were both considered and rejected: each breaks a
+ * live consumer side.
+ */
+
+/**
+ * `ExecutionContext` fields a transport ENTRY POINT does not resolve — they are
+ * per-operation flags, engine internals, or attribution supplied further down
+ * the stack. Listing one here is a deliberate, reviewable statement that no
+ * request-identity resolution produces it; everything NOT listed is part of the
+ * closed entry set below and must be assembled.
+ *
+ * - `actor` / `attributedUserId` — audit attribution, set by the host or the
+ *   hook layer (ADR-0014 D2, #4586), never by identity resolution.
+ * - `rlsMembership` — engine-side RLS scoping cache.
+ * - `transaction` / `traceId` — per-operation handles.
+ * - `flowRunId`, `skipTriggers`, `skipAutomations`, `seedReplay`,
+ *   `skipStateMachine`, `preserveAudit` — per-write behaviour flags,
+ *   server-constructed at the call site.
+ */
+type NonEntryExecutionContextField = 'actor' | 'attributedUserId' | 'rlsMembership' | 'transaction' | 'traceId' | 'flowRunId' | 'skipTriggers' | 'skipAutomations' | 'seedReplay' | 'skipStateMachine' | 'preserveAudit';
+/**
+ * The CLOSED field set every transport entry point must decide. Derived from
+ * `ExecutionContext` itself, so adding a field to `ExecutionContextSchema`
+ * widens this union automatically — and the assembly below stops compiling
+ * until the new field is either assembled or declared non-entry-resolved.
+ */
+type EntryExecutionContextField = Exclude<keyof ExecutionContext, NonEntryExecutionContextField>;
+/**
+ * One value per closed field. Every key is REQUIRED (`-?`) while the VALUE may
+ * be `undefined` — the decision may not be omitted, only made explicitly. This
+ * is the type that makes the #6071 drift class unrepresentable.
+ */
+type ExecutionContextEntryFields = {
+    [K in EntryExecutionContextField]-?: ExecutionContext[K];
+};
+/**
+ * Emission order of the assembled envelope, and a second, independent
+ * exhaustiveness bite: `satisfies` rejects a stale name, and
+ * `_ENTRY_FIELDS_EXHAUSTIVE` below rejects a missing one.
+ */
+declare const ENTRY_EXECUTION_CONTEXT_FIELDS: readonly ["positions", "permissions", "systemPermissions", "isSystem", "principalKind", "onBehalfOf", "audience", "userId", "tenantId", "email", "accessToken", "tabPermissions", "posture", "authGate", "org_user_ids", "accessible_org_ids", "oauthScopes", "timezone", "locale", "currency"];
+/**
+ * OAuth 2.1 access-token provenance. Reaches the assembler from the `/mcp`
+ * dispatch door ALONE (`acceptOAuthAccessToken`) — OAuth bearers carry coarse
+ * tool-family scopes enforced at MCP tool dispatch, so honouring them on
+ * another surface would bypass that scope model entirely.
+ */
+interface OAuthTokenProvenance {
+    /** The human `sub` the token was issued for. */
+    userId: string;
+    /** Granted scopes, surfaced on the envelope so MCP can narrow tool families. */
+    scopes: string[];
+    /**
+     * The authorized client (`azp`). Present ⇒ this is an AI AGENT acting on
+     * behalf of the human `userId`; absent ⇒ the token names no client and the
+     * principal stays human (the scopes are still surfaced).
+     */
+    clientId?: string;
+    /**
+     * The agent's OWN permission CEILING, derived from {@link scopes} by the door
+     * that speaks the OAuth scope vocabulary
+     * (`scopesToAgentPermissionSets`, `@objectstack/spec/ai`).
+     *
+     * Interpreted THERE and not here on purpose: the scope vocabulary is
+     * MCP-domain knowledge and `@objectstack/core` is the microkernel — it should
+     * not acquire a dependency on the AI subdomain (concretely, every package
+     * whose test config aliases `@objectstack/core` to its source would then have
+     * to resolve `@objectstack/spec/ai` too, down to `driver-memory`). What the
+     * ceiling REPLACES on the envelope is decided below, once, for every face —
+     * and that is the part that drifted.
+     */
+    scopePermissions: string[];
+    /**
+     * Whether the token carries the user's consent to let this agent invoke
+     * actions on their behalf — the `actions:execute` scope
+     * (`MCP_OAUTH_SCOPE_ACTIONS`), evaluated at the same door for the same
+     * reason.
+     */
+    delegatesActions: boolean;
+}
+/** Reference localization for an authenticated principal (@see resolveLocalizationContext). */
+interface EntryLocalization {
+    timezone?: string;
+    locale?: string;
+    currency?: string;
+}
+/**
+ * Everything the shared assembly needs. Every key is REQUIRED so a face cannot
+ * silently omit one — a face that has no value for an input passes `undefined`
+ * on the record, which is what turns the remaining divergences into named API.
+ */
+interface ExecutionContextAssemblyInput {
+    /** The shared authorization envelope (@see resolveAuthzContext). */
+    authz: ResolvedAuthzContext;
+    /**
+     * OAuth access-token provenance, or `undefined` on a face that does not
+     * accept one. Only the `/mcp` dispatch door passes a value; REST passes
+     * `undefined` — which is why `principalKind: 'agent'`, `onBehalfOf` and
+     * `oauthScopes` are not representable there.
+     */
+    oauth: OAuthTokenProvenance | undefined;
+    /**
+     * Resolved reference localization, or `undefined` when the face resolved
+     * none (anonymous requests have no scope to resolve against).
+     */
+    localization: EntryLocalization | undefined;
+    /**
+     * The request's OWN locale preference (`Accept-Language`, `?locale`, …),
+     * which wins over the workspace default; `undefined` when the caller
+     * expresses none. Each face extracts it its own way — the PRECEDENCE lives
+     * here so the two cannot disagree about it (#3957).
+     */
+    requestLocale: string | undefined;
+    /**
+     * The session bearer to carry on the envelope, surfaced to hooks as
+     * `session.accessToken` (`objectql/engine.ts` `buildSession`,
+     * `spec/data/hook.zod.ts`).
+     *
+     * A NAMED per-face divergence, preserved deliberately (#6216): the runtime /
+     * MCP dispatcher passes `authz.accessToken`; the REST face has never carried
+     * it and passes `undefined`, because widening a published hook surface to
+     * expose the session token on a second transport is a product decision, not a
+     * refactor. Being a required input, the choice is on the record at each face
+     * instead of being an omission nobody can see.
+     */
+    accessToken: string | undefined;
+    /**
+     * [ADR-0069] The AUTHENTICATION-policy gate posture resolved for this
+     * request's session (expired password / enforced MFA), or `undefined` when
+     * the face resolves none — normalize a session user through
+     * `normalizeAuthGate` rather than copying its `authGate` verbatim.
+     *
+     * A NAMED per-face divergence, on the same footing as {@link accessToken}
+     * (#7280):
+     *
+     *  - the **REST** face lifts it onto the envelope, because that is where its
+     *    consumer reads it (`RestServer.enforceAuth` → `403 { code, message }`);
+     *  - the **runtime / MCP dispatcher** passes `undefined`, because it enforces
+     *    the same ADR-0069 gate at its OWN seam (`HttpDispatcher.enforceAuthGate`
+     *    re-reads the session and calls `evaluateAuthGate` there) and never reads
+     *    `context.authGate` — carrying it would be a second, unread copy.
+     *
+     * Until #7280 declared it, this posture reached the envelope through an
+     * `as any` spread AFTER assembly, which put it outside this closed set
+     * entirely — the blind spot the set exists to remove.
+     */
+    authGate: AuthGate | undefined;
+}
+/**
+ * The DEFAULT, fail-closed entry (#6216 Option A). An unauthenticated request
+ * yields NO context — the surface answers 401. Every surface uses this one
+ * unless serving anonymous principals is part of its product semantics.
+ */
+declare function assembleExecutionContext(input: ExecutionContextAssemblyInput): ExecutionContext | undefined;
+/**
+ * The EXPLICIT guest entry (#6216 Option A). An unauthenticated request becomes
+ * a first-class guest principal — `principalKind: 'guest'`, `positions:
+ * ['guest']` — which enforcement consumers read today
+ * (`plugin-security/explain-engine.ts`: guest ⇒ `EXTERNAL` posture).
+ *
+ * Adopt this ONLY on a surface that genuinely serves anonymous principals: the
+ * built-in `guest` position is the declared vocabulary for "what anonymous may
+ * do", and handing a guest envelope to a surface that previously answered 401
+ * converts an authentication failure into an authorization evaluation.
+ */
+declare function assembleExecutionContextOrGuest(input: ExecutionContextAssemblyInput): ExecutionContext;
+
 /**
  * ── The monotonic posture ladder (ADR-0095 D2/D3) ───────────────────────────
  *
@@ -1936,36 +2223,6 @@ interface LadderPrincipal {
  */
 declare function postureVisibleRows(posture: AuthzPosture, rows: readonly LadderRow[], principal: LadderPrincipal): LadderRow[];
 
-/**
- * ADR-0069 — authentication-policy session gate.
- *
- * Some auth policies (password expiry, enforced MFA) must block an
- * authenticated user from PROTECTED RESOURCES until they remediate, while
- * still letting them reach the auth endpoints (change-password, two-factor
- * enrollment, sign-out) and a few UI-bootstrap reads.
- *
- * The posture is computed ONCE, in the auth `customSession` enrichment, and
- * attached to the session user as `user.authGate = { code, message }`. The
- * transport seams (REST middleware, dispatcher) then call
- * {@link evaluateAuthGate} to decide whether THIS request is blocked. Keeping
- * the allow-list + decision in one pure function means the seams can never
- * drift on what is blocked.
- */
-interface AuthGate {
-    /** Stable machine code, e.g. `PASSWORD_EXPIRED` / `MFA_REQUIRED`. */
-    code: string;
-    /** Human-facing message. */
-    message: string;
-}
-/** True when `path` is exempt from the auth gate (auth + remediation + health). */
-declare function isAuthGateAllowlisted(rawPath: string | undefined | null): boolean;
-/**
- * Returns the active gate when `sessionUser` carries an `authGate` AND `path`
- * is not allow-listed; otherwise null. Anonymous users (no `authGate`) and
- * allow-listed paths always pass.
- */
-declare function evaluateAuthGate(sessionUser: any, path: string): AuthGate | null;
-
 /** HTTP status every seam returns for an anonymous-denied request. */
 declare const ANONYMOUS_DENY_STATUS: 401;
 /** Stable machine code (mirrors the REST `enforceAuth` seam). ADR-0112: SCREAMING, a `StandardErrorCode` member. */
@@ -2059,6 +2316,161 @@ declare function isGrantActive(row: GrantValidityWindow | null | undefined, nowM
  */
 declare function isGrantExpired(row: GrantValidityWindow | null | undefined, nowMs: number): boolean;
 
+/**
+ * [#7678] The `?status=` vocabulary of the audience-binding suggestion list
+ * (ADR-0090 D5/D9) — ONE owner for a rule that had exactly one implementation
+ * and two seams needing it.
+ *
+ * The predicate was written for the runtime dispatcher's `/security` domain and
+ * lived there, private. The **live** REST route
+ * (`rest-server.ts` → `registerSecurityEndpoints`) is a second seam onto the
+ * same service call and never had it, so `?status=garbage` reached the service,
+ * matched no row, and answered **200 with an empty list** — which reads as
+ * "there are no suggestions", a plausible and actionable-looking answer, rather
+ * than "your filter was not a status". That silent arm is the defect; the two
+ * seams disagreeing about one contract is the cause.
+ *
+ * So this module is the convergence, not a copy: `domains/security.ts` and
+ * `rest-server.ts` both import from here, and the vocabulary — including the
+ * refusal wording — exists once.
+ *
+ * The record is keyed BY the contract type on purpose (carried over from the
+ * original): adding a status to `AudienceBindingSuggestionFilter` leaves a key
+ * missing here and renaming one leaves a key excess, and either way this fails
+ * to compile. A plain `['pending', …]` array would silently drift.
+ */
+
+/** The `status` arm of {@link AudienceBindingSuggestionFilter}, named. */
+type AudienceBindingSuggestionStatus = NonNullable<AudienceBindingSuggestionFilter['status']>;
+/** The accepted `?status=` values, keyed by the contract type (see module note). */
+declare const AUDIENCE_BINDING_SUGGESTION_STATUSES: Record<AudienceBindingSuggestionStatus, true>;
+/**
+ * The same vocabulary as a list — for refusal messages, and for tests that must
+ * enumerate every valid value FROM the type rather than hand-picking one.
+ */
+declare const AUDIENCE_BINDING_SUGGESTION_STATUS_VALUES: readonly AudienceBindingSuggestionStatus[];
+/**
+ * Is `value` one of the three statuses the contract declares? Case-sensitive on
+ * purpose — the contract's values are lowercase, so `PENDING` is not a status
+ * and gets the same refusal as `garbage`.
+ */
+declare const isAudienceBindingSuggestionStatus: (value: string) => value is AudienceBindingSuggestionStatus;
+/** The refusal wording, shared so both seams answer an unknown status identically. */
+declare const unknownAudienceBindingSuggestionStatusMessage: (value: string) => string;
+
+/**
+ * [#7284] The `__` operation-private-key convention — one owner, on the
+ * CONSUMER side.
+ *
+ * `assemble-execution-context.ts` next door is the single place an
+ * `ExecutionContext` is BUILT at a transport entry point (#6216). This file is
+ * its counterpart at the other end: the single place one is stripped back down
+ * before being forwarded to a question it was not resolved for.
+ *
+ * ## What a `__` key is
+ *
+ * plugin-security's middleware STAMPS keys onto the operation context, resolved
+ * for the object of the operation IN FLIGHT. They are middleware-private
+ * vocabulary, not fields of `ExecutionContext`, and every one of them is read as
+ * a WIDENING input by whoever consumes it:
+ *
+ *  - the ADR-0057 D1 access DEPTH the sharing owner-match expands to —
+ *    `__readScope` / `__writeScope`, plus the ADR-0090 D10 delegator halves
+ *    `__delegatorReadScope` / `__delegatorWriteScope`, stamped in place by
+ *    `security-plugin.ts` (`sc.__readScope = …`);
+ *  - the engine's internal privilege markers on the same channel —
+ *    `__expandRead` marks a read as a lookup EXPANSION sub-read (it no longer
+ *    relaxes any gate — #7626 removed that waiver — but it still travels with
+ *    one operation and must not be inherited by another), `__referentialFieldClear`
+ *    authorizes the referential-clear write.
+ *
+ * plugin-security is the PRODUCER of that vocabulary and would be the most
+ * honest owner of the rule for consuming it, but none of the three consumers
+ * depends on it and a string-prefix filter does not justify three new dependency
+ * edges onto a plugin (the trade the filing card priced, #7284). `@objectstack/
+ * spec` is fenced off by Prime Directive #2. `@objectstack/core` is the only
+ * candidate every consumer already depends on, so the rule lives here and the
+ * producer stays free of reverse edges.
+ *
+ * ## Why a consumer must drop them
+ *
+ * A caller's envelope carries a depth resolved for the object the middleware
+ * last saw. A consumer that forwards that envelope to ask about a DIFFERENT
+ * object applies one object's widening to another object's question — the exact
+ * stale-scope leak `resolveWriteScopeForSharing` was extracted to prevent ("a
+ * stale value can never leak in through a spread", `security-plugin.ts`).
+ *
+ * The leak is not hypothetical and does not require the consumer to be careless:
+ * plugin-security only OVERWRITES `__readScope` when it actually resolves
+ * permission sets for the new object (`if (permissionSets.length > 0)`), so a
+ * stale depth SURVIVES into a question it was never resolved for whenever that
+ * branch does not fire. A REST request that touched another object before
+ * reaching, say, `/reports/:id/run` hands over an envelope the middleware has
+ * already written into.
+ *
+ * Dropping is safe in the one direction that matters: the middleware re-stamps
+ * the depth for THIS object when it resolves any set, so the only thing dropping
+ * can do is leave the sharing owner-match at its narrowest (`own`) — the safe
+ * direction.
+ *
+ * ## Why by PREFIX and never by a name list
+ *
+ * The `__` convention is what marks a key as belonging to the operation in
+ * flight. A hand-maintained list of the six names above would go stale the day
+ * the middleware stamps a seventh, and it would go stale SILENTLY — a forwarded
+ * key nobody remembered to add reads exactly like a key that was meant to be
+ * forwarded. The prefix is the contract; the names are its current membership.
+ *
+ * ⛔ The corollary, for whoever changes the middleware: a key that is
+ * operation-private MUST carry the `__` prefix. Stamping one without it makes it
+ * invisible to every consumer at once, and there is no compiler error.
+ *
+ * ## Known consumers
+ *
+ * `plugin-audit` (`comment-access-hooks.ts`, #7141), `service-storage`
+ * (`attachment-access-hooks.ts`, #7145) and `plugin-reports`
+ * (`report-service.ts`, #7204) — each forwarding a caller envelope to a gate or
+ * a read that asks about a parent/target object rather than about the object the
+ * middleware resolved for. Each of the three grew its own byte-equivalent copy
+ * of this file by hand before #7284 gave the rule a home; `operation-private-
+ * keys.pin.test.ts` is what now catches a fourth.
+ */
+
+/**
+ * The prefix marking a key as private to the operation plugin-security has in
+ * flight. See this module's header for why the convention is a prefix and not a
+ * list of names.
+ */
+declare const OPERATION_PRIVATE_KEY_PREFIX = "__";
+/**
+ * The caller's execution envelope, minus the operation-private keys.
+ *
+ * A FRESH object every time, and that is load-bearing in BOTH directions:
+ *
+ *  - outbound — a callee that stamps its own `__writeScope` onto what it
+ *    receives (which is exactly what plugin-security does before it calls the
+ *    sharing service) can never write back into the operation context the caller
+ *    was handed;
+ *  - inbound — the engine's middleware stamps a depth for the object it is about
+ *    to read onto whatever it is handed, so forwarding a caller's envelope BY
+ *    REFERENCE would write that depth back into the request context the route
+ *    goes on using.
+ *
+ * ⛔ Never `return exec;` on the "nothing to strip" path. The copy is the point,
+ * not an optimisation to skip when the envelope happens to be clean — the two
+ * hazards above are about the callee's future writes, not about the current
+ * contents.
+ *
+ * Note what this deliberately does NOT do: it strips, it never SYNTHESISES a
+ * depth for the new object. Absent depth leaves the sharing owner-match at its
+ * narrowest (`own`), which is the safe direction and byte-for-byte what the
+ * five-field projections these call sites replaced produced.
+ *
+ * @param exec the caller's envelope, as a bare record
+ * @returns a new envelope carrying only the non-operation-private keys
+ */
+declare function withoutOperationPrivateKeys(exec: Record<string, unknown>): ExecutionContext;
+
 /**
  * Environment utilities for universal (Node/Browser) compatibility.
  */
@@ -2277,6 +2689,30 @@ declare function withTransientRetry<T>(fn: (attempt: number) => Promise<T>, opts
  */
 declare function bulkWrite<TRow, TRecord = any>(rows: TRow[], opts: BulkWriteOptions<TRow, TRecord>): Promise<BulkWriteRowResult<TRecord>[]>;
 
+/**
+ * Collect the names of fields declared `internal: true` on `schema`.
+ *
+ * Same verdicts as objectql's `collectInternalReadFields` (see the module
+ * header for why it is restated rather than imported): strict `=== true`,
+ * empty result for a missing/field-less schema.
+ */
+declare function collectInternalWriteResponseFields(schema: unknown): string[];
+/**
+ * Drop every `internal: true` field from a write response's record(s), in
+ * place. THE single helper every external write mouth goes through — see the
+ * module header; the three tripwires enforce the "every".
+ *
+ * @param schema  The registered object schema (`engine.registry.getObject(...)`
+ *                / the protocol's own registry view / `metadataService
+ *                .getObject(...)`). An unknown object (no schema) strips
+ *                nothing — the write itself would have been refused upstream
+ *                by the object-existence gate.
+ * @param records A single record, an array of records, or anything a write
+ *                mouth hands back where a record could sit (`null`, a count, a
+ *                boolean): non-objects are skipped, arrays are walked.
+ */
+declare function omitInternalFieldsFromWriteResponse(schema: unknown, records: unknown): void;
+
 /**
  * Can this runtime actually roll back? — the ADR-0119 D4 gate, shared.
  *
@@ -2564,11 +3000,65 @@ declare function resolveFilterTokens<T>(filter: T, ctx?: FilterTokenResolutionCo
  * `current_user.organization_id`).
  *
  * Typed structurally, not as `ExecutionContext`, so both the parsed context
- * (defaults applied) and the pre-parse `ExecutionContextInput` a caller holds
- * mid-pipeline satisfy it. The three fields read here are optional in both.
+ * (`ExecutionContextParsed`, defaults applied) and the pre-parse
+ * `ExecutionContext` a caller holds mid-pipeline satisfy it. The three fields
+ * read here are optional in both.
  */
 declare function filterTokenContextFrom(execCtx: ExecutionContextLike | undefined, now?: Date): FilterTokenResolutionContext;
 
+/**
+ * [#4435] The 404 a single-record operation answers when the id names no row.
+ *
+ * Extracted so the READ and the two WRITE paths cannot disagree about it. They
+ * did: `getData` answered `404 RECORD_NOT_FOUND` while `updateData` returned
+ * `200 { record: null }` and `deleteData` returned `200 { success: true }` for
+ * any string in the path — so a typo'd id, an already-deleted row and a real
+ * deletion were indistinguishable, and a client PATCHing a concurrently deleted
+ * record was told its write had landed.
+ *
+ * That is the same silent-no-op shape the v17 train removed everywhere else
+ * this window (#4240/#4303/#4315 refuse missing fields, #4169 refuses unknown
+ * params, #4190 stopped dropping filters) — a write that touched zero rows
+ * reporting 200 is that shape one level up, on the verb where it costs the
+ * most.
+ *
+ * [#5138] EXPORTED, for the same "cannot disagree about it" reason one layer
+ * out. `@objectstack/runtime`'s `callData` is protocol-first with an ObjectQL
+ * FALLBACK, and the fallback had reinvented this fact three incompatible ways
+ * (`get` → `null`, `update` → a bare `Error` with no status ⇒ 500, `delete` →
+ * no check at all ⇒ `200 { deleted: true }` for a row that never existed). It
+ * now calls THIS function, so the two paths behind one `callData` answer a
+ * missing id identically — which is the only reason a caller may stop caring
+ * which of them served it. Re-spelling the envelope there would have been a
+ * second not-found envelope; `RECORD_NOT_FOUND` (#5088) is the one this repo
+ * has.
+ *
+ * ── [#7867] Why it lives in `@objectstack/core` and not where it was written ──
+ *
+ * Because the THIRD path that needed it could not reach the second one. An
+ * action body's `ctx.api.object(name).update({ id, … })` traverses neither
+ * `protocol.updateData` nor `callData`: it reaches `ObjectQL.update()`'s by-id
+ * branch directly, which had no existence gate at all, so a ghost id was a
+ * silent no-op that then died on whatever the pipeline complained about first
+ * (a `HookConditionError` 400 on a hooked object, a required-field
+ * `VALIDATION_FAILED` 400 on an unhooked one — the 400 class varied with the
+ * object's declarations; the missing 404 was the constant).
+ *
+ * The gate for that path belongs in the engine, and `packages/objectql` cannot
+ * import `@objectstack/metadata-protocol` where this function was written:
+ * ADR-0076 D2's boundary ratchet (`core-boundary.ratchet.test.ts`) forbids the
+ * whole `@objectstack/objectql/core` closure — `engine.ts` included — from
+ * pulling that package in. So the choice was a FOURTH spelling of the envelope
+ * or one home both layers already depend on. #5138's own sentence rules the
+ * first out, so this is the second: the factory moved down to the lowest
+ * package the three producers share, and `@objectstack/metadata-protocol`
+ * re-exports it unchanged for every existing importer.
+ *
+ * This is the same move `engineCanRollBack` made for the same reason — a fact
+ * two layers must agree on lives in the layer beneath both, not in a copy each.
+ */
+declare function recordNotFoundError(object: string, id: string | number): Error;
+
 /**
  * In-memory Map-backed cache fallback.
  *
@@ -2704,7 +3194,24 @@ declare function createMemoryI18n(): {
      * not a merge — so deleted items/keys stop resolving on the next sync.
      */
     replaceAuthoredTranslations(byLocale: Record<string, Record<string, unknown>>): void;
+    /**
+     * Report the locales this stack offers.
+     *
+     * [#7679] When the app declared `i18n.supportedLocales`, that declaration
+     * IS the answer — in declared order, and including a declared locale no
+     * bundle was ever loaded for (declared-but-unserved). Reporting the
+     * declaration rather than an intersection is what gives a client the
+     * signal that the locale it is being offered has nothing behind it yet;
+     * quietly dropping it would leave the gap invisible on both sides. It is
+     * also the only answer that does not depend on how much had loaded by the
+     * time this was called.
+     *
+     * With nothing declared, the loaded set — the behaviour every app that
+     * never opted in already has.
+     */
     getLocales(): string[];
+    /** @see II18nService.setSupportedLocales — [#7679] */
+    setSupportedLocales(locales: readonly string[] | undefined): void;
     getDefaultLocale(): string;
     setDefaultLocale(locale: string): void;
 };
@@ -2715,6 +3222,13 @@ declare function createMemoryI18n(): {
  * Implements the IMetadataService contract with a simple Map-of-Maps store.
  * Used by ObjectKernel as an automatic fallback when no real metadata plugin
  * (e.g. MetadataPlugin with file-system persistence) is registered.
+ *
+ * [#7378] Carries the ruled register/read argument contract
+ * (`../metadata-service-contract.ts` — the ruling is quoted there):
+ * `register` refuses a `data.name` that disagrees with the `name` argument and
+ * refuses a non-document `data` (rows 1/3), and every type store is keyed on
+ * the CANONICAL type (row 2), so `register('objects', n, d)` and
+ * `get('object', n)` address one store rather than two.
  */
 declare function createMemoryMetadata(): {
     __serviceInfo: {
@@ -2768,6 +3282,37 @@ declare function wireAuthoredTranslationSync(ctx: MinimalCtx): void;
  */
 declare const CORE_FALLBACK_FACTORIES: Record<string, () => Record<string, any>>;
 
+/**
+ * The canonical spelling an `IMetadataService` type store is keyed on
+ * (#7378 row 2). Folds a plural manifest spelling to the singular metadata
+ * type name (`'objects'` → `'object'`, `'views'` → `'view'`, …) through the
+ * platform's one plural↔singular map (`PLURAL_TO_SINGULAR`,
+ * `@objectstack/spec/shared`); a name with no plural mapping — which includes
+ * every canonical singular type — passes through unchanged.
+ */
+declare function canonicalMetadataServiceType(type: string): string;
+/**
+ * Enforce rows 1 and 3 of the #7378 ruling on a
+ * `register(type, name, data)` payload — call it before the first store write,
+ * so a refusal writes nothing anywhere.
+ *
+ * Refuses, with a locating `VALIDATION_ERROR` (status 400):
+ *
+ *  - **a non-document `data`** (row 3): anything that is not a plain object —
+ *    primitives, `null`, arrays. The contract declares `data: unknown`, so
+ *    this is a runtime refusal, not a type error;
+ *  - **a `data.name` that disagrees with the `name` argument** (row 1), in
+ *    either direction. A document with NO `name` of its own is fine — the
+ *    argument is the key, and there is no disagreement to refuse.
+ *
+ * Deliberately NOT called by `registerInMemory`: that optional member is a
+ * boot-time seeding primitive outside the ruled surface (the ruling names
+ * `register`), and its callers hand it artefacts whose shape source control
+ * owns. It shares the row-2 canonical fold — a store key is a store fact, not
+ * a per-member choice — just not the refusals.
+ */
+declare function assertMetadataRegisterContract(type: string, name: string, data: unknown): asserts data is Record<string, unknown>;
+
 /**
  * Plugin Health Monitor
  *
@@ -2787,7 +3332,7 @@ declare class PluginHealthMonitor {
     /**
      * Register a plugin for health monitoring
      */
-    registerPlugin(pluginName: string, config: PluginHealthCheck): void;
+    registerPlugin(pluginName: string, config: PluginHealthCheckParsed): void;
     /**
      * Start monitoring a plugin
      */
@@ -2862,7 +3407,7 @@ declare class PluginStateManager {
     /**
      * Save plugin state before reload
      */
-    saveState(pluginId: string, version: string, state: Record<string, any>, config: HotReloadConfig): Promise<string>;
+    saveState(pluginId: string, version: string, state: Record<string, any>, config: HotReloadConfigParsed): Promise<string>;
     /**
      * Restore plugin state after reload
      */
@@ -2895,7 +3440,7 @@ declare class HotReloadManager {
     /**
      * Register a plugin for hot reload
      */
-    registerPlugin(pluginName: string, config: HotReloadConfig): void;
+    registerPlugin(pluginName: string, config: HotReloadConfigParsed): void;
     /**
      * Start watching for changes (requires file system integration)
      */
@@ -3085,4 +3630,4 @@ declare class NamespaceResolver {
     private suggestAlternative;
 }
 
-export { ANONYMOUS_DENY_BODY, ANONYMOUS_DENY_CODE, ANONYMOUS_DENY_MESSAGE, ANONYMOUS_DENY_STATUS, API_KEY_PREFIX, type AnonymousDenyInput, type ApiKeyPrincipal, type AuthGate, type BucketGranularity, type BulkWriteOptions, type BulkWriteRowResult, CORE_FALLBACK_FACTORIES, type CalendarParts, DependencyResolver, type EngineWithTransaction, 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, 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, assertInitServiceRequirements, bucketKeyToCalendarRange, buildPermissionsFromGrants, bulkWrite, calendarPartsInTz, calendarPartsInTzOrUtc, counterSignPayload, createMemoryCache, createMemoryI18n, createMemoryJob, createMemoryMetadata, createMemoryQueue, createPluginConfigValidator, createPluginPermissionEnforcer, deepMerge, defaultIsTransientError, derivePosture, describeInitOrderFault, engineCanRollBack, evaluateAuthGate, extractApiKey, filterTokenContextFrom, findInterruptedRuns, generateApiKey, generateEd25519KeyPair, getEnv, getMemoryUsage, hashApiKey, hashMigrationPlan, isAuthGateAllowlisted, isExpired, isGrantActive, isGrantExpired, isNode, parseScopes, parseSignature, planChunks, postureVisibleRows, readAuthoredTranslationLayer, readRunJournal, resolveApiKeyPrincipal, resolveAuthzContext, resolveFilterToken, resolveFilterTokens, resolveLocale, resolveLocalizationContext, resolvePluginOrder, resolveUserAuthzGrants, resumeMigrationJournal, runMigrationJournal, safeExit, shouldDenyAnonymous, signPayload, validateInitServiceContract, verifyPayload, verifyPlatformSignature, verifyPluginArtifact, verifyPublisherSignature, wireAuthoredTranslationSync, withTransientRetry, zonedDateStartToUtcMs };
+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 };