@objectstack/core 17.0.0-rc.5 → 17.0.0-rc.6

package/dist/index.d.cts

@@ -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
      */
@@ -1831,6 +1845,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 +2219,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 +2312,117 @@ declare function isGrantActive(row: GrantValidityWindow | null | undefined, nowM
  */
 declare function isGrantExpired(row: GrantValidityWindow | null | undefined, nowMs: number): boolean;
 
+/**
+ * [#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` waives the object-level CRUD check for a lookup expansion,
+ *    `__referentialFieldClear` 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.
  */
@@ -2564,8 +2928,9 @@ 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;
 
@@ -2787,7 +3152,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 +3227,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 +3260,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 +3450,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, type AnonymousDenyInput, type ApiKeyPrincipal, 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, 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, normalizeAuthGate, 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, withoutOperationPrivateKeys, zonedDateStartToUtcMs };