@objectstack/core 17.2.0 → 17.3.0

package/dist/index.d.ts

@@ -1,12 +1,11 @@
 import { Logger, LifecycleEventName, IServiceRegistry, AudienceBindingSuggestionFilter, IObjectQLEngine } 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 { CORE_PLUGIN_TYPES, 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 { ObjectLogger } from './logger.js';
 export { createLogger } from './logger.js';
 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 { TenancyPosture, AuthzPosture } from '@objectstack/spec/security';
 export { nextUtcCalendarDay, utcInstantMs } from '@objectstack/spec/data';
 
@@ -42,16 +41,12 @@ interface ServiceRegistration {
 interface PluginMetadata extends Plugin {
     /** Semantic version (e.g., "1.0.0") */
     version: string;
-    /** Configuration schema for validation */
-    configSchema?: z.ZodSchema;
     /** Plugin signature for security verification */
     signature?: string;
     /** Plugin health check function */
     healthCheck?(): Promise<PluginHealthStatus>;
     /** Startup timeout in milliseconds (default: 30000) */
     startupTimeout?: number;
-    /** Whether plugin supports hot reload */
-    hotReloadable?: boolean;
 }
 /**
  * Plugin Health Status
@@ -97,7 +92,6 @@ interface VersionCompatibility {
 declare class PluginLoader {
     private logger;
     private context?;
-    private configValidator;
     private loadedPlugins;
     private serviceFactories;
     private serviceInstances;
@@ -160,7 +154,6 @@ declare class PluginLoader {
     private validatePluginStructure;
     private checkVersionCompatibility;
     private isValidSemanticVersion;
-    private validatePluginConfig;
     private verifyPluginSignature;
     private getSingletonService;
     private createTransientService;
@@ -466,6 +459,17 @@ interface PluginContext {
      */
     getKernel(): ObjectKernel;
 }
+/**
+ * The closed set of plugin types (#13925): `'standard'` plus the seven
+ * `CORE_PLUGIN_TYPES` members, in exactly the shape `PluginSchema.type`
+ * declares in `@objectstack/spec` (`kernel/plugin.zod.ts`:
+ * `z.enum(['standard', ...CORE_PLUGIN_TYPES])`). Derived from the spec's own
+ * constant rather than re-spelled here, so the compiler's accept set and the
+ * Zod gate's cannot drift apart: `plugin-type-closed-set.test.ts` pins the
+ * parity at runtime, and `packages/rest`'s `plugin-type-closed-set.pin.test.ts`
+ * pins the published `.d.ts` at compile time.
+ */
+type PluginType = 'standard' | (typeof CORE_PLUGIN_TYPES)[number];
 /**
  * Plugin Interface
  *
@@ -481,10 +485,13 @@ interface Plugin {
      */
     version?: string;
     /**
-     * Plugin type (standard, ui, driver, server, app, theme, agent)
+     * Plugin type categorisation for runtime behaviour — a {@link PluginType},
+     * the closed set the spec declares. The enumeration lives on that type
+     * (derived from `CORE_PLUGIN_TYPES`), not in this comment: a value outside
+     * it no longer type-checks, and `PluginSchema.type` refuses it at parse.
      * @default 'standard'
      */
-    type?: string;
+    type?: PluginType;
     /**
      * List of other plugin names that this plugin depends on.
      * The kernel ensures these plugins are initialized before this one.
@@ -799,6 +806,41 @@ declare function describeInitOrderFault(currentlyInitializing: string | undefine
  */
 declare function assertInitServiceRequirements(plugin: OrderablePlugin, isServiceRegistered: (name: string) => boolean): void;
 
+/**
+ * Refusals raised by {@link resolveArtifactPackageOrder}, as ADR-0112 envelopes
+ * (`code` + `status`) — the shape this repository's rejection tests assert
+ * against, never a bare throw.
+ */
+type ArtifactPackageError = Error & {
+    code: string;
+    status: number;
+};
+/**
+ * The id one artifact package is keyed by.
+ *
+ * `||`, not `??`, on purpose: `ObjectQL.registerApp` keys the installed package
+ * on `manifest.id || manifest.name`, so an empty-string `id` falls back to
+ * `name` there. Every seam that has to name a package — this module's ordering
+ * map, and the install gate's co-ownership set (ADR-0130 D1) — reads the id
+ * through THIS function, so none of them can order or admit a package under a
+ * key the registry never stores it by.
+ *
+ * @returns The package id, or `undefined` when the manifest carries neither a
+ *   usable `id` nor a usable `name`.
+ */
+declare function artifactPackageId(manifest: unknown): string | undefined;
+/**
+ * Resolve an artifact into the manifests to register, in dependency-topological
+ * order (ADR-0130 D4 + D5).
+ *
+ * @param artifact - A release artifact (`{ packages: [...] }`), or a bare
+ *   manifest / single-`manifest` artifact — both shapes are read.
+ * @returns The manifest bodies to register, in the order to register them.
+ * @throws An ADR-0112 envelope (`code` + `status: 422`) for a malformed entry or
+ *   a duplicate package id, and `resolvePluginOrder`'s own error for a cycle.
+ */
+declare function resolveArtifactPackageOrder(artifact: unknown): unknown[];
+
 /**
  * ObjectKernel - MiniKernel Architecture
  *
@@ -862,6 +904,100 @@ declare class LiteKernel extends ObjectKernelBase {
     isRunning(): boolean;
 }
 
+/**
+ * [#13905] The discriminator that tells **"nothing ever registered this
+ * service"** apart from **"the service IS registered and could not be built"**
+ * on the ASYNCHRONOUS resolution path.
+ *
+ * ## The fault
+ *
+ * `PluginLoader.getService` (reached through `Kernel.getServiceAsync`) answered
+ * both facts with the same bare `Error`. A caller that holds only the rejection
+ * therefore could not tell an UNWIRED embedder from a BROKEN one, and the only
+ * thing separating them was message text.
+ *
+ * That mattered one layer out. `RestServer.computeExecCtx`'s kernel branch
+ * absorbs a failed `getServiceAsync('objectql')` and degrades to "no engine is
+ * wired". It must keep doing so — a kernel with no data plane is a SUPPORTED
+ * configuration (`rest-api-plugin.ts` declares
+ * `optionalDependencies: ['com.objectstack.engine.objectql']`) — but a
+ * multi-tenant host whose engine FAILED TO CONSTRUCT reached that same resolver
+ * as "no engine is wired", degrading silently where it should have refused
+ * loudly. The branch could not be repaired from the outside, because the fact
+ * it needed had been collapsed before it arrived.
+ *
+ * ## Why a brand, and ⛔ not message text
+ *
+ * The SYNCHRONOUS accessor in `kernel.ts` already draws exactly this line, and
+ * the comment there records what happened the last time someone read the fact
+ * off the wrong surface: reading "not found" off the async path "reported every
+ * missing service as `is async - use await` — the wrong fix, pointing at the
+ * wrong layer". A second text classifier on a resolution path is the failure
+ * mode this module removes, ⛔ not a repair of it.
+ *
+ * The sync side decides from the REGISTRY — synchronous and authoritative — and
+ * raises two different messages. The async side now carries that same
+ * distinction as a branded, `code`-bearing rejection: one fact, spelled for a
+ * caller that only ever sees the rejection.
+ *
+ * ## The test is CLOSED, and its default is LOUD
+ *
+ * Exactly one throw in `PluginLoader.getService` means "never registered", and
+ * it is the one branded here. Every other way that method can reject — a
+ * factory that threw, a missing scope id, an unset loader context, a circular
+ * service dependency — is a service that IS registered and could not be
+ * produced, and stays unbranded. So `false` is the safe answer: a consumer that
+ * absorbs only the branded rejection stays loud about everything else,
+ * including rejections added to that method later.
+ *
+ * ## Two deliberate omissions
+ *
+ * - **No `status`.** An ADR-0112 envelope pairs `code` with a `status`, but
+ *   the whole point of this discriminator is that the CONSUMER decides what an
+ *   unwired service means — absorb and degrade (the supported no-data-plane
+ *   kernel) or refuse. Carrying an HTTP status here would presuppose that
+ *   decision at the layer that must not make it.
+ * - **No `name` override.** The rejection stays `name: 'Error'` with a
+ *   byte-identical message, so `String(err)`, logs and existing assertions
+ *   render exactly as before. The only observable change is two added
+ *   own-properties.
+ *
+ * Brand shape follows `AuthzStoreUnavailableError` (2026-08-30): a string-keyed
+ * own property rather than `instanceof`, so the predicate still answers
+ * correctly when two copies of `@objectstack/core` are installed (a duplicated
+ * module makes `instanceof` say "no" to an error it built itself).
+ *
+ * ⚠️ The brand does NOT survive `structuredClone`, and no claim here depends on
+ * it doing so — measured on Node 22: cloning an `Error` keeps `name`, `message`,
+ * `stack` and `cause` and DROPS every other own property, brand and `code`
+ * alike. This discriminator is for an in-process rejection travelling from
+ * `PluginLoader.getService` to a seam that catches it, which is the only path
+ * it is used on.
+ */
+/**
+ * The code carried by the "never registered" rejection.
+ *
+ * ⚠️ Spelled the ADR-0112 way, but deliberately NOT wire vocabulary: this value
+ * is read in-process by the seam that catches the rejection and is never
+ * serialized into an `error.code` envelope. `dispatcher-error-vocabulary.ts`
+ * classifies it `door: 'none'` / `boot-refusal` for exactly that reason — the
+ * same class as the migration-journal runner refusals. If a transport ever
+ * needs to ANSWER with this fact, that is a registration question for #8846's
+ * ledger, ⛔ not something to start doing at a door.
+ */
+declare const SERVICE_NOT_REGISTERED_CODE = "SERVICE_NOT_REGISTERED";
+/**
+ * True when `err` is the rejection meaning **nothing was ever registered under
+ * that service name** — never when a registered service failed to construct.
+ *
+ * The predicate a seam uses to keep absorbing the supported "no data plane"
+ * composition while staying loud about a service that IS wired and broke.
+ */
+declare function isServiceNotRegisteredError(err: unknown): err is Error & {
+    readonly code: typeof SERVICE_NOT_REGISTERED_CODE;
+    readonly serviceName: string;
+};
+
 /**
  * Interface for executing test actions against a target system.
  * The target could be a local Kernel instance or a remote API.
@@ -1193,82 +1329,45 @@ declare function verifyPluginArtifact(input: {
     requirePlatform?: boolean;
 }): Promise<PluginArtifactVerifyResult>;
 
-/**
- * Plugin Configuration Validator
- *
- * Validates plugin configurations against Zod schemas to ensure:
- * 1. Type safety - all config values have correct types
- * 2. Business rules - values meet constraints (min/max, regex, etc.)
- * 3. Required fields - all mandatory configuration is provided
- * 4. Default values - missing optional fields get defaults
- *
- * Architecture:
- * - Uses Zod for runtime validation
- * - Provides detailed error messages with field paths
- * - Supports nested configuration objects
- * - Allows partial validation for incremental updates
- *
- * Usage:
- * ```typescript
- * const validator = new PluginConfigValidator(logger);
- * const validConfig = validator.validatePluginConfig(plugin, userConfig);
- * ```
- */
-declare class PluginConfigValidator {
-    private logger;
-    constructor(logger: Logger);
-    /**
-     * Validate plugin configuration against its Zod schema
-     *
-     * @param plugin - Plugin metadata with configSchema
-     * @param config - User-provided configuration
-     * @returns Validated and typed configuration
-     * @throws Error with detailed validation errors
-     */
-    validatePluginConfig<T = any>(plugin: PluginMetadata, config: any): T;
-    /**
-     * Validate partial configuration (for incremental updates)
-     *
-     * @param plugin - Plugin metadata
-     * @param partialConfig - Partial configuration to validate
-     * @returns Validated partial configuration
-     */
-    validatePartialConfig<T = any>(plugin: PluginMetadata, partialConfig: any): Partial<T>;
-    /**
-     * Get default configuration from schema
-     *
-     * @param plugin - Plugin metadata
-     * @returns Default configuration object
-     */
-    getDefaultConfig<T = any>(plugin: PluginMetadata): T | undefined;
-    /**
-     * Check if configuration is valid without throwing
-     *
-     * @param plugin - Plugin metadata
-     * @param config - Configuration to check
-     * @returns True if valid, false otherwise
-     */
-    isConfigValid(plugin: PluginMetadata, config: any): boolean;
-    /**
-     * Get configuration errors without throwing
-     *
-     * @param plugin - Plugin metadata
-     * @param config - Configuration to check
-     * @returns Array of validation errors, or empty array if valid
-     */
-    getConfigErrors(plugin: PluginMetadata, config: any): Array<{
-        path: string;
-        message: string;
-    }>;
-    private formatZodErrors;
+/** A single unpacked artifact file. `path` is POSIX, archive-relative. */
+interface IntegrityFile {
+    path: string;
+    data: Uint8Array;
+}
+type IntegrityViolationKind = 'digest_mismatch' | 'missing_file' | 'extra_file';
+/** One structured integrity finding (the rejection envelope's unit). */
+interface IntegrityViolation {
+    kind: IntegrityViolationKind;
+    /** Artifact-relative POSIX path the finding is about. */
+    path: string;
+    /** The digest the manifest declares (absent for `extra_file`). */
+    declared?: string;
+    /** The digest computed from the supplied bytes (absent unless comparable). */
+    actual?: string;
+}
+interface VerifyIntegrityResult {
+    /** Overall verdict: every declared digest matched and no file was unaccounted for. */
+    ok: boolean;
+    /** True when no integrity map was supplied, so nothing was checked (still `ok`). */
+    skipped: boolean;
+    /** Number of declared entries whose digests were computed and compared. */
+    checked: number;
+    violations: IntegrityViolation[];
 }
 /**
- * Create a plugin config validator
+ * Verify `files` against the manifest's declared `integrity` map.
  *
- * @param logger - Logger instance
- * @returns Plugin config validator
+ * `options.exempt` names paths outside the map's coverage — the compiled
+ * manifest itself and the signature placeholder, which `computeIntegrity`
+ * excludes at build time (the manifest cannot hash itself, and the
+ * signature signs the manifest) — so their presence is never an
+ * `extra_file` finding.
  */
-declare function createPluginConfigValidator(logger: Logger): PluginConfigValidator;
+declare function verifyIntegrity(files: readonly IntegrityFile[], integrity: Readonly<Record<string, string>> | null | undefined, options?: {
+    exempt?: readonly string[];
+}): VerifyIntegrityResult;
+/** Render one violation as a single human-actionable line. */
+declare function formatIntegrityViolation(v: IntegrityViolation): string;
 
 /**
  * Plugin Permissions
@@ -1884,6 +1983,188 @@ declare function resolveApiKeyPrincipal(ql: any, headers: any, nowMs?: number, t
  */
 declare function resolveApiKeyAdmission(ql: any, headers: any, nowMs?: number, tenancyPosture?: TenancyPosture): Promise<ApiKeyAdmission>;
 
+/**
+ * [#13279] The LOUD failure an unreachable permission store raises.
+ *
+ * ## The defect this exists to end
+ *
+ * `resolveAuthzContext`'s per-read helper `tryFind` used to answer a THROWN
+ * read the same way it answers an EMPTY one: `[]`. So a permission-store
+ * outage resolved as a well-formed context for an AUTHENTICATED principal
+ * holding ZERO capabilities, and the package-management door answered
+ * `403 FORBIDDEN` — "Reading packages requires the `studio.access` or
+ * `setup.access` capability." That answer was measured BYTE-IDENTICAL
+ * (`JSON.stringify` equal, against a positive control that separates two
+ * answers which differ) to the answer a caller who genuinely holds nothing
+ * gets. An administrator was told they lack a capability, during an outage of
+ * the store that holds the capability.
+ *
+ * The resolver was asserting a fact it did not have. "No rows came back"
+ * and "the read failed" are different facts, and only one of them licenses
+ * the sentence "this user holds nothing".
+ *
+ * ## …and "the read failed" turned out to be TWO facts (ruled 2026-08-30, A)
+ *
+ * A read ALSO throws when the table was never PROVISIONED — a real engine,
+ * wired and reachable, whose `sys_*` tables were never created. There "this
+ * user holds nothing" is TRUE, not invented, so failing loud would refuse
+ * service to a correctly-configured deployment. The first implementation of
+ * this card did exactly that and four CI suites measured it.
+ *
+ * So `tryFind` raises this error only for a read failure that is NOT
+ * positively identified as an unprovisioned table, asking the one relocated
+ * `isMissingTableError` predicate (`@objectstack/types`) rather than a second
+ * copy. The boundary, the ruling's verbatim text and the false-positive risk
+ * signed off with it are written beside that call in `resolve-authz-context.ts`;
+ * both directions are pinned in `authz-store-unavailable.test.ts` §4.
+ *
+ * ## Maintainer ruling, 2026-08-30, verbatim 「第一批其余同意」
+ *
+ * > `tryFind` 区分「无行」与「读失败」,读失败 fail-loud —— 权限库不可达时
+ * > 不再解析为「已认证零能力」,而是响亮拒绝(与真实能力拒绝的 403 可区分),
+ * > 让宕机不再伪装成一次逐字节相同的能力否决。
+ *
+ * The ruling fixes the DIRECTION and leaves the spelling to the implementation.
+ *
+ * ## Why a THROW, and not a field on the envelope
+ *
+ * The alternative was a discriminator field on `ResolvedAuthzContext` — the
+ * shape `authRefusal` already has. That was rejected on a MEASUREMENT, not a
+ * preference: `authRefusal` has existed since #8287 and, outside this module
+ * and its own unit test, has **zero** consumers anywhere in the repo. A
+ * diagnostic field on this envelope is demonstrably not read by any door. Every
+ * transport reads `userId` and `systemPermissions`; a new sibling field would
+ * have to be taught to eight separate call sites before it made a single door
+ * louder, and would answer the old quiet 403 at every site that was missed.
+ *
+ * A field is quiet by default and must be deliberately made loud. A throw is
+ * loud by default and must be deliberately silenced. On a security surface
+ * whose whole defect is a silence, the default is the entire decision.
+ *
+ * It is also the idiom this platform already uses for unresolvable authority:
+ * `packages/mcp`'s stdio entry throws and refuses to start rather than run with
+ * an authority it could not resolve.
+ *
+ * ## Why `SERVICE_UNAVAILABLE` / 503, and why that is not a new wire shape
+ *
+ * `SERVICE_UNAVAILABLE` is an EXISTING member of the closed ADR-0112 wire
+ * vocabulary (`StandardErrorCode`, `packages/spec/src/api/errors.zod.ts`), and
+ * `HttpStatusErrorCodeMap` already maps it to 503 — "service exists but is
+ * temporarily down". Nothing is added to the vocabulary and no envelope gains
+ * or loses a key: a door that already renders `{ code, message }` renders this
+ * one the same way. What changes is WHICH declared code an outage selects —
+ * from the caller's `FORBIDDEN` to the operator's `SERVICE_UNAVAILABLE`.
+ *
+ * That is the ruling's own test, stated on the wire: 503 is not 403, so an
+ * outage is no longer answerable as a capability denial.
+ *
+ * ## Recognise by BRAND, never by `instanceof`
+ *
+ * {@link isAuthzStoreUnavailableError} tests a own-property brand rather than
+ * `instanceof`. This error crosses package boundaries (`@objectstack/core` →
+ * rest / runtime / mcp / services / plugins) and a monorepo resolves the same
+ * module through more than one path (`src` under vitest aliases, `dist` under
+ * the published `exports`). Two copies of this class make `instanceof` answer
+ * FALSE for a genuine instance — which, here, silently restores the exact
+ * quiet 403 this module exists to remove. The brand survives duplication.
+ */
+/** HTTP status an unreachable authorization store answers with. */
+declare const AUTHZ_STORE_UNAVAILABLE_STATUS: 503;
+/**
+ * Machine code — an EXISTING `StandardErrorCode` member (ADR-0112: SCREAMING).
+ * Deliberately NOT a new code: the wire vocabulary is closed.
+ */
+declare const AUTHZ_STORE_UNAVAILABLE_CODE: "SERVICE_UNAVAILABLE";
+/**
+ * Human-facing message. States the OUTAGE, and says explicitly that no
+ * capability judgement was reached — so neither the caller nor the operator
+ * reads it as a permission verdict.
+ */
+declare const AUTHZ_STORE_UNAVAILABLE_MESSAGE: string;
+/**
+ * The own-property brand {@link isAuthzStoreUnavailableError} tests for.
+ * A string-keyed own property (not a `Symbol.for` registry key), so a
+ * duplicated copy of this module still brands identically — which is exactly
+ * what `instanceof` cannot do (module doc above).
+ *
+ * ⚠️ The brand does NOT survive `structuredClone`, and no claim here depends
+ * on it doing so — the same measured behaviour `service-not-registered.ts`
+ * records for its own brand. Reproduce on Node 22.22.2:
+ *
+ * ```js
+ * const e = new Error('x'); e.__brand = true; e.code = 'C';
+ * const c = structuredClone(e);
+ * // c.__brand === undefined   c.code === undefined   c.message === 'x'
+ * // control: structuredClone({ __brand: true, code: 'C' }) keeps BOTH keys
+ * ```
+ *
+ * `Error` has a dedicated serialization carrying `message`, `stack` and
+ * `cause` only, so it DROPS every other own property — this brand, the
+ * ADR-0112 `code`, `status` and `object` alike (and a subclass's own `name`
+ * returns as `'Error'`). The plain-object control is the half that proves the
+ * loss is specific to `Error`, not general to `structuredClone`.
+ *
+ * ⛔ So never branch on this brand across a worker or `postMessage` boundary:
+ * it would answer `false` and fail OPEN. Every call site today is in-process —
+ * `rethrowAuthzStoreUnavailable` on the rest rethrow paths and
+ * `isAuthzStoreUnavailableError` inside service `catch` blocks.
+ */
+declare const AUTHZ_STORE_UNAVAILABLE_BRAND: "__objectstackAuthzStoreUnavailable";
+/**
+ * Raised when a permission-store read FAILED — never when it legitimately
+ * returned no rows.
+ *
+ * Carries the `object` whose read failed so an operator sees WHICH table was
+ * unreachable, and the originating error as `cause` so the driver's own
+ * diagnostic is not lost behind this one.
+ */
+declare class AuthzStoreUnavailableError extends Error {
+    /** Brand — see the module doc on why this is not `instanceof`. */
+    readonly [AUTHZ_STORE_UNAVAILABLE_BRAND]: true;
+    /** ADR-0112 wire code. */
+    readonly code: "SERVICE_UNAVAILABLE";
+    /** HTTP status a transport should answer. */
+    readonly status: 503;
+    /** The object/table whose read failed (e.g. `sys_user_permission_set`). */
+    readonly object: string;
+    /** The driver's originating failure, kept so its diagnostic is not lost. */
+    readonly cause?: unknown;
+    constructor(object: string, cause?: unknown);
+}
+/**
+ * True when `err` is the loud authorization-store failure above.
+ *
+ * The predicate every transport uses to tell "the store was unreachable" apart
+ * from every other throw, so a fail-closed `catch` can re-raise THIS one
+ * without loosening its handling of anything else.
+ */
+declare function isAuthzStoreUnavailableError(err: unknown): err is AuthzStoreUnavailableError;
+/**
+ * The `.catch` argument every fail-closed seam between `resolveAuthzContext`
+ * and a door should use in place of `() => undefined`.
+ *
+ * Re-raises {@link AuthzStoreUnavailableError} and swallows everything else to
+ * `undefined`, so a seam keeps its existing fail-closed behaviour for every
+ * fault EXCEPT the one the 2026-08-30 ruling requires to stay loud.
+ *
+ * ## Why the seams need this at all
+ *
+ * Making `tryFind` throw is necessary but NOT sufficient, and that was
+ * MEASURED rather than assumed. Between the resolver and the package door sit
+ * three independent nets — `computeExecCtx`'s `try { … } catch { return
+ * undefined; }`, `resolvePackageRouteExecutionContext`'s `.catch(() =>
+ * undefined)`, and `refusePackageRequest`'s own — and with the throw in place
+ * but the nets untouched, the door answered **401**: the outage had simply
+ * changed disguises, from "you hold no capability" (403) into "you are not
+ * authenticated" (401), which is byte-identical to a genuine anonymous caller.
+ * Distinguishable from a capability denial, yes — but still not LOUD, and now
+ * wearing the costume of a different card's defect.
+ *
+ * A blanket `catch` cannot tell a fault from a refusal, so each net has to be
+ * told once, in one shape. This is that shape.
+ */
+declare function rethrowAuthzStoreUnavailable(err: unknown): undefined;
+
 /** The transport-agnostic authorization envelope produced from a request. */
 interface ResolvedAuthzContext {
     userId?: string;
@@ -1907,7 +2188,9 @@ interface ResolvedAuthzContext {
     /**
      * [ADR-0095 D2/D3] The monotonic posture rung this principal resolves to,
      * DERIVED once here from held capability grants (never a better-auth role):
-     * `PLATFORM_ADMIN` (unscoped `admin_full_access`) > `TENANT_ADMIN`
+     * `PLATFORM_ADMIN` (an unscoped `admin_full_access` grant, or — since #11663
+     * L2 — a VERIFIED `sys_user.email` on the deployment's declared
+     * administrator list) > `TENANT_ADMIN`
      * (`organization_admin`) > `MEMBER` (the authenticated floor). `EXTERNAL` is
      * defined/test-locked but never resolved yet (no external principal type —
      * see `posture-ladder.ts`). Present only for an authenticated principal;
@@ -1960,8 +2243,19 @@ interface ResolveAuthzInput {
     tenancyPosture?: TenancyPosture;
 }
 /**
- * Resolve the authorization context for an inbound request. Always resolves —
- * never throws. Anonymous requests yield `{ positions: [], permissions: [], ... }`.
+ * Resolve the authorization context for an inbound request. Anonymous requests
+ * yield `{ positions: [], permissions: [], ... }`.
+ *
+ * ⚠️ [#13279] This function used to document itself as "Always resolves — never
+ * throws", and that total guarantee WAS the defect: the only way to always
+ * resolve across a permission-store outage is to report a capability set the
+ * resolver never actually read. It now throws exactly one error —
+ * {@link AuthzStoreUnavailableError}, when a permission-store read was issued
+ * and failed FOR A REASON THAT IS NOT AN UNPROVISIONED TABLE. Every other path
+ * still resolves, including every MISSING-service path and every
+ * never-provisioned one. A transport that fails closed on unexpected throws should re-raise this
+ * one ({@link isAuthzStoreUnavailableError}) rather than degrade it to a
+ * refusal — degrading it restores the disguise the ruling removed.
  */
 declare function resolveAuthzContext(input: ResolveAuthzInput): Promise<ResolvedAuthzContext>;
 /** The authorization grants a KNOWN user holds — a subset of {@link ResolvedAuthzContext}. */
@@ -1992,6 +2286,25 @@ interface ResolveUserAuthzGrantsOptions {
     seedPermissions?: string[];
     /** A caller-supplied email (e.g. from the session) that wins over the `sys_user` read. */
     seedEmail?: string;
+    /**
+     * ⭐ Force a FRESH resolution even when the #11971 grants cache is enabled
+     * — the ruled bypass list of #11633 (leg B, maintainer acceptance
+     * 2026-08-25). Two call sites carry it, for two ruled reasons:
+     *
+     *  - `plugin-security/src/explain-engine.ts` (`buildContextForUser`): the
+     *    permission explainer is the tool an administrator uses to VERIFY that
+     *    a revocation took effect. An explainer answering from cache would
+     *    explain a state that no longer exists, and would do it at exactly the
+     *    moment someone is checking.
+     *  - `service-automation/src/plugin.ts` (`runAs:'user'` runs): automation
+     *    runs are not request-shaped and can be long-lived; they must not pin
+     *    an envelope.
+     *
+     * Bypassing reads NOTHING from the cache and writes NOTHING into it — a
+     * bypassed resolution must not repopulate an entry the next cached caller
+     * would then trust.
+     */
+    bypassGrantsCache?: boolean;
 }
 /**
  * resolveUserAuthzGrants — the userId-driven core of {@link resolveAuthzContext}.
@@ -2012,13 +2325,84 @@ interface ResolveUserAuthzGrantsOptions {
  * automation engine calls this to run the flow's data ops exactly as that user
  * — not the bare member/everyone fallback the missing grants used to leave it.
  *
- * Fail-closed like its parent: every read is defensive, a missing engine/table
- * yields an empty-but-valid envelope, and it never throws.
+ * Fail-closed like its parent: a missing engine yields an empty-but-valid
+ * envelope.
+ *
+ * ⚠️ [#13279] "and it never throws" was removed from this sentence deliberately.
+ * A permission-store read that is issued and FAILS now raises
+ * {@link AuthzStoreUnavailableError} rather than contributing an empty grant
+ * set, so a `runAs:'user'` automation cannot silently run with the authority of
+ * a user whose grants were never read.
  */
 declare function resolveUserAuthzGrants(ql: any, userId: string, opts?: ResolveUserAuthzGrantsOptions): Promise<UserAuthzGrants>;
+/**
+ * hasPlatformAdminStanding — the ID-SHAPED platform-admin question, asked in
+ * exactly one place.
+ *
+ * ADR-0068 D2 defined PLATFORM standing as one thing: an UNSCOPED
+ * (`organization_id = null`) `sys_user_permission_set` grant on the
+ * `admin_full_access` set, held **now**. Since #11663 L2 there is a SECOND
+ * anchor beside it — a `sys_user` row whose VERIFIED email is on the
+ * deployment's declared administrator list (`OS_PLATFORM_OWNER_EMAIL`) — and
+ * this predicate answers for both, for free, because it is a projection rather
+ * than a copy (see below). A surface that only knows a user id —
+ * a session-payload derivation, a platform-operator route gate, an
+ * impersonation oracle — asks here, so it never has to re-read the grant tables
+ * itself, which is the prohibition this module's header states.
+ *
+ * It is a PROJECTION of {@link resolveUserAuthzGrants}, never a second
+ * derivation: the answer is the `PLATFORM_ADMIN` rung of the posture ladder,
+ * and that rung is derived from the unscoped-grant evidence and nothing else.
+ * Everything that governs those grants therefore applies here by construction
+ * and cannot drift from it — the ADR-0091 validity window (§6), the ADR-0049
+ * `active` flag on the catalogue row (§6b), the system-identity read, and the
+ * resolution of `admin_full_access` BY ID rather than by scanning a page of the
+ * catalogue. Each of those was missing from a hand-written copy of this
+ * predicate; none of them can be missing from a projection.
+ *
+ * ⛔ Read the RUNG — never `positions.includes(BUILTIN_IDENTITY_PLATFORM_ADMIN)`.
+ * The positions list is wider on purpose: an ADR-0057 D4 `sys_user_position`
+ * row may spell that very name, and a platform-RBAC assignment is not the D2
+ * capability grant. The two readings genuinely differ, so the narrow one is the
+ * one that gets a name here.
+ *
+ * ⛔ The options are deliberately NOT {@link ResolveUserAuthzGrantsOptions}.
+ * That type carries caller-supplied seeds (`seedEmail`, `seedPermissions`) for
+ * transports that already resolved part of a principal; an authorization
+ * predicate that accepted them would let a caller supply part of its own
+ * verdict. Clock injection is the only thing a caller may pass, so this
+ * function's answer is a function of `(ql, userId)` and the stored rows alone.
+ *
+ * ⚠️ This is the PER-USER predicate. The POPULATION question ("which user is
+ * the platform admin?" — `ensure-default-organization.ts`) is a different kind
+ * and is deliberately not expressible through it; do not widen this to serve
+ * it.
+ *
+ * Fail-CLOSED: an empty id, a missing engine, or any unreadable lookup answers
+ * `false`. This backs security gates, and an unverifiable actor never passes.
+ */
+declare function hasPlatformAdminStanding(ql: any, userId: string, opts?: {
+    nowMs?: number;
+}): Promise<boolean>;
 interface ResolveLocalizationInput {
     ql: any;
-    /** Settings service exposing `get(namespace, key, { tenantId, userId })`. */
+    /**
+     * Settings service occupant. Two methods are consumed, in this order:
+     *
+     *  - `getMany(namespace, keys, { tenantId, userId })` — PREFERRED since
+     *    #10826, and what this resolver calls for all three localization keys in
+     *    ONE grouped read.
+     *  - `get(namespace, key, { tenantId, userId })` — the per-key fallback,
+     *    taken only when the occupant does not expose `getMany` (three parallel
+     *    reads; see the feature-detect below).
+     *
+     * `getMany` is OPTIONAL for an occupant: the branch is feature-detected, so
+     * a service that predates it still resolves — at three reads instead of one.
+     * Typed `any` deliberately (the occupant's shape varies by host); the
+     * declaration above is the contract this resolver actually relies on, and it
+     * is prose precisely because nothing type-checks it — `getService` is a cast
+     * and `rest-server.ts` widens the provider's return to a bare promise.
+     */
     settings?: any;
     tenantId?: string;
     userId?: string;
@@ -2034,14 +2418,22 @@ type LocalizationResult = {
  * platform default → global → tenant); falls back to direct tenant-scoped
  * `sys_setting` rows, then the built-ins `UTC` / `en-US`. Never throws.
  *
- * A read that fails outright (backend fault — table missing, connection
- * refused, etc.) is memoized for {@link LOCALIZATION_FAILURE_CACHE_TTL_MS}
- * per `(ql, tenantId, userId)` so the failing query — and the driver's log
- * line for it — does not repeat every request (#10221). A successful read,
- * including a legitimate "no settings configured yet" empty result, is NEVER
- * cached: the next call always re-reads, so a settings write takes effect
- * immediately (see the cache doc above for why — the dogfood analytics
- * bucketing test pins this).
+ * The DIRECT `sys_setting` read failing outright (backend fault — table
+ * missing, connection refused, etc.) is memoized for
+ * {@link LOCALIZATION_FAILURE_CACHE_TTL_MS} per `(ql, tenantId, userId)` so
+ * the failing query — and the driver's log line for it — does not repeat
+ * every request (#10221). A settings-service refusal is not a backend fault
+ * and never populates that memo (#11877).
+ *
+ * A SUCCESSFUL read is cached too, since #11966 (leg C of #11633) — but only
+ * when the engine carries the write-epoch seam, and only until the first of:
+ * a `localization` settings change, an engine write, or
+ * `OS_LOCALIZATION_CACHE_TTL_MS`. Both invalidations are synchronous and
+ * in-process, which is what lets the success cache exist at all: the
+ * dogfood analytics-bucketing test writes a new org timezone and reads it back
+ * on the very next request, and it is kept unweakened as this leg's acceptance
+ * criterion. See the leg-C docblock above for the full contract, including why
+ * a `ql` with no seam declines to cache rather than falling back to the TTL.
  */
 declare function resolveLocalizationContext(input: ResolveLocalizationInput): Promise<LocalizationResult>;
 
@@ -2592,6 +2984,20 @@ declare function isRowActive(row: ActivatableRow | null | undefined): boolean;
  * 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.
+ *
+ * ## ⚠️ Tables are no longer the whole surface (#11663 L2)
+ *
+ * Since the platform-admin re-anchor's core leg, one input to the administrator
+ * derivation is NOT a table at all: the deployment's declared administrator
+ * list, read from the environment on every resolution
+ * (`security/platform-admin.ts`). A file that listed only tables would go on
+ * being perfectly accurate about the tables while silently claiming the
+ * derivation reads nothing else — the same shape as the stale comment this file
+ * replaced, one level up. {@link ADMIN_STANDING_NON_TABLE_INPUTS} is the place
+ * that says so, and it is deliberately a SEPARATE export rather than a
+ * pseudo-row in the table map: the map is compared for equality against
+ * observed table reads, and a pseudo-row would have to be excluded from that
+ * comparison by name, which is exactly the kind of special case that rots.
  */
 /** How a table this resolver reads relates to "who is an administrator". */
 interface AdminStandingTable {
@@ -2618,11 +3024,37 @@ interface AdminStandingTable {
  * 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.
+ * confers no administrator standing of its own — `hasPlatformAdminGrant` is set
+ * from a `sys_permission_set` row reached through an UNSCOPED
+ * `sys_user_permission_set` grant (§6b) or from the deployment config matched
+ * against the caller's own STORED `sys_user` row (§6b-config), never from a
+ * scope string and never from the caller-seedable `grants.email`.
  */
 declare const ADMIN_STANDING_SURFACE: Readonly<Record<string, AdminStandingTable>>;
+/** A derivation input that is not a table — see {@link ADMIN_STANDING_NON_TABLE_INPUTS}. */
+interface AdminStandingNonTableInput {
+    /** How the value reaches the resolver, e.g. `env` for a process environment variable. */
+    readonly kind: 'env';
+    /** The exact spelling an operator sets — quotable verbatim in a refusal message. */
+    readonly name: string;
+    /** What it decides, and what a break-glass guard can and cannot do about it. */
+    readonly reason: string;
+}
+/**
+ * [#11663 L2] Inputs to the administrator derivation that no table write can
+ * reach — declared here so this file's silence about them cannot be read as
+ * "the derivation reads only tables".
+ *
+ * The practical consequence is the one worth writing down: a break-glass guard
+ * simulates a pending WRITE, and there is no write to simulate for any of
+ * these. Standing that rests on one of them is taken away by changing the
+ * deployment's configuration and rolling the process, which is deliberately
+ * outside every in-product path — including every path an agent could be talked
+ * into calling. That is the whole point of the config anchor, and it is also
+ * the reason a guard cannot promise to prevent this class of lockout: it can
+ * only refuse the writes it can see.
+ */
+declare const ADMIN_STANDING_NON_TABLE_INPUTS: readonly AdminStandingNonTableInput[];
 /** The tables a write to which can change who is an administrator. */
 declare function adminStandingTables(): string[];
 /**
@@ -2631,6 +3063,147 @@ declare function adminStandingTables(): string[];
  */
 declare function adminStandingColumns(table: string): readonly string[] | undefined;
 
+/**
+ * The one separator {@link parsePlatformAdminEmails} splits on (Choice 2B).
+ * Same shape as `OS_CORS_ORIGIN`, the existing comma-separated precedent.
+ */
+declare const PLATFORM_ADMIN_EMAIL_SEPARATOR = ",";
+/**
+ * The ONE normalization, applied to both sides of every comparison: trim, then
+ * lowercase. Email domains are case-insensitive and every mailbox this platform
+ * issues is too, so an operator who types `Ada@Example.com` and a row storing
+ * `ada@example.com` must be one administrator, not two half-matches.
+ */
+declare function normalizePlatformAdminEmail(value: unknown): string;
+/** The parsed state of `OS_PLATFORM_OWNER_EMAIL` for one raw value. */
+interface PlatformAdminEmailConfig {
+    /**
+     * Normalized, de-duplicated administrator addresses in the order the operator
+     * declared them. EMPTY when the variable is unset, blank, or refused — those
+     * three are one outcome by design (zero config-derived administrators), and
+     * they are told apart by {@link refusal} rather than by a second empty value.
+     */
+    readonly emails: readonly string[];
+    /**
+     * The SAME administrators as {@link emails} and index-aligned with it, each
+     * spelled as the operator typed it — trimmed only, never lowercased (exactly
+     * what `resolvePlatformOwnerEmail()` used to hand a single-value reader).
+     *
+     * It exists so that no consumer ever has a reason to split {@link raw} a
+     * second time. Two readers need the as-typed form and neither may re-parse
+     * to get it: the platform-admin STANDING surface's by-email `sys_user`
+     * lookup queries the verbatim spelling alongside the normalized one (an
+     * imported/legacy row may not be stored lowercased, and a driver `where` is
+     * an exact match) — that lookup is `resolvePlatformAdminStanding` in
+     * plugin-security's `platform-admin-service.ts`, which inherited the
+     * two-spelling discipline from the elevation gate the #11663 re-anchor
+     * (leg L4) retired — and the walled boot diagnostic quotes the addresses
+     * back to the operator, who should see what they wrote.
+     */
+    readonly declaredSpellings: readonly string[];
+    /** What the operator actually typed, when the variable was set to anything. */
+    readonly raw?: string;
+    /**
+     * Set when the variable was DECLARED but refused, naming the offending entry.
+     * `emails` is empty in that case: the whole variable fails closed, never the
+     * one entry (Choice 2B).
+     */
+    readonly refusal?: string;
+}
+/**
+ * Parse one raw `OS_PLATFORM_OWNER_EMAIL` value into the administrator list.
+ *
+ * Pure — no env read, no logging — so the whole parse is testable as a
+ * function of its input. {@link resolvePlatformAdminEmails} is the env-reading,
+ * memoizing, once-per-value-loud wrapper around it.
+ */
+declare function parsePlatformAdminEmails(raw: string | undefined): PlatformAdminEmailConfig;
+/**
+ * Sink for the refusal notice. `console` by default so the loudness does not
+ * depend on any host wiring it up — a deployment that declared administrators
+ * and got none must never find that out silently. Swappable for tests.
+ */
+interface PlatformAdminConfigSink {
+    error(message: string): void;
+    warn(message: string): void;
+}
+/** Redirect this module's notices (tests). Returns the previous sink. */
+declare function setPlatformAdminConfigSink(next: PlatformAdminConfigSink | undefined): PlatformAdminConfigSink;
+/**
+ * Resolve the deployment's declared platform administrators — live from the
+ * environment, memoized on the raw string, and LOUD exactly once per distinct
+ * refused value.
+ *
+ * Silence for an UNSET variable is deliberate and is not the same decision:
+ * every `single`-posture deployment runs that way by design (Choice 4A leaves
+ * first-user promotion in place there), and warning on the shipped default is
+ * how a log people read becomes a log people skim. A walled posture with the
+ * variable unset already REFUSES BOOT one layer up, in plugin-auth.
+ */
+declare function resolvePlatformAdminEmails(): PlatformAdminEmailConfig;
+/** Drop the memo — for tests that drive several values through one process. */
+declare function resetPlatformAdminEmailMemo(): void;
+/**
+ * Does this stored `sys_user` row belong to a declared platform administrator?
+ *
+ * Fail-closed on every axis: an empty/refused config answers `false` without
+ * looking at the row at all, an address that is not on the list answers
+ * `false`, and an address that IS on the list but whose `email_verified`
+ * column does not read verified answers `false` too. The last one is the point
+ * of the whole leg — an unverified account holding a configured address confers
+ * nothing, so an attacker who registers the operator's address before the
+ * operator does gains no standing by it.
+ *
+ * ⚠️ `row` MUST be the caller's own stored `sys_user` row. See this module's
+ * header: `grants.email` is caller-seedable and reading it here would be an
+ * escalation channel.
+ */
+declare function matchesConfiguredPlatformAdmin(row: unknown, config: PlatformAdminEmailConfig): boolean;
+/**
+ * [#13147] Is this bare ADDRESS one of the declared administrators?
+ *
+ * The membership half of {@link matchesConfiguredPlatformAdmin}, spelled once
+ * and exported, because the row-and-verified predicate above is not the shape
+ * every reader of `OS_PLATFORM_OWNER_EMAIL` needs:
+ *
+ *  - the walled platform-admin STANDING surface must keep the two halves
+ *    SEPARATE — `resolvePlatformAdminStanding`
+ *    (`plugin-security/platform-admin-service.ts`, reported at boot by
+ *    `bootstrap-platform-admin.ts`) answers `registered` and `verified` as two
+ *    independent per-entry fields, so the operator's log can tell "not
+ *    registered yet" apart from "registered, NOT verified". ⚠️ That reason
+ *    predates the #11663 re-anchor and survives it: the pair used to be the
+ *    retired elevation gate's `walled_owner_not_registered` /
+ *    `walled_owner_not_verified` reasons — the mechanism moved, the need to
+ *    keep the halves apart did not;
+ *  - the creation-time operator stamp (`plugin-auth`) is handed an email
+ *    STRING by better-auth, before any row exists to read;
+ *  - the Layer 0 wall bypass takes a fast negative on the session's
+ *    server-resolved email before it spends a `sys_user` read.
+ *
+ * ⛔ Those readers must NOT hand-roll `config.emails.includes(x.toLowerCase())`
+ * instead. That expression is where a seventh dialect gets born: it silently
+ * drops the trim, and a stray space in one list entry then makes an
+ * administrator vanish with nothing to notice. One membership expression, one
+ * normalization ({@link normalizePlatformAdminEmail}), one place to fix.
+ *
+ * Fail-closed like everything else here: an empty or refused config answers
+ * `false` without looking at the candidate, and a blank/non-string candidate
+ * answers `false` against any config.
+ *
+ * ⚠️ This is a match against CONFIGURATION only — it says nothing about whether
+ * the address is verified, or whether the caller actually holds it. Standing
+ * still requires {@link matchesConfiguredPlatformAdmin} over the caller's own
+ * stored row; see this module's header for why `grants.email` is never it.
+ */
+declare function isConfiguredPlatformAdminEmail(email: unknown, config: PlatformAdminEmailConfig): boolean;
+declare function reportLegacyPlatformAdminGrant(input: {
+    userId: string;
+    email?: unknown;
+}): void;
+/** Drop the once-per-process latch — for tests. */
+declare function resetLegacyPlatformAdminGrantReport(): void;
+
 /**
  * [#7678] The `?status=` vocabulary of the audience-binding suggestion list
  * (ADR-0090 D5/D9) — ONE owner for a rule that had exactly one implementation
@@ -2697,7 +3270,12 @@ declare const unknownAudienceBindingSuggestionStatusMessage: (value: string) =>
  *    `__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.
+ *    authorizes the referential-clear write. [#13644] The latter also has a
+ *    DECLARED, read-only projection — `HookContext.referentialFieldClear`
+ *    (`@objectstack/spec/data`), populated by objectql's `update()` assembly
+ *    and carried across the sandbox boundary by contract — which is what an
+ *    APP reads; the `__` key here remains the engine/middleware authorization
+ *    channel, and this file's stripping rule is unchanged by the projection.
  *
  * 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
@@ -2786,6 +3364,244 @@ declare const OPERATION_PRIVATE_KEY_PREFIX = "__";
  */
 declare function withoutOperationPrivateKeys(exec: Record<string, unknown>): ExecutionContext;
 
+/**
+ * ── The `authz.invalidated` cluster channel (#11968, #11633 §3) ─────────────
+ *
+ * The cross-node half of the authorization invalidation substrate: one channel
+ * name, one payload shape, and the contract statement that governs how both may
+ * be read. It carries no cache and no consumer — leg B (#11967) is the first.
+ *
+ * ## ⭐ THE TTL IS THE CORRECTNESS CONTRACT. THIS CHANNEL IS NOT.
+ *
+ * A message on this channel is a **hint**, and **a missed message is EXPECTED**.
+ * That is not a caveat about an unreliable network; it is the shipped
+ * guarantee, measured rather than assumed:
+ *
+ *   - `content/docs/kernel/cluster.mdx` §4.2, on `at-least-once`:
+ *     *"**No shipped driver provides this yet.** The `redis` driver publishes
+ *     over plain Redis pub/sub, which is *at-most-once* — fire-and-forget, no
+ *     persistence, no replay for a node that was down at publish time."*
+ *   - `@objectstack/service-cluster-redis`'s own `publish` docblock:
+ *     *"there is no delivery guarantee to subscribers and no replay for a node
+ *     that was down or slow at publish time. This is acceptable **only** for
+ *     events that are pure cache-invalidation hints, never the source of
+ *     truth."*
+ *   - The `memory` driver does not cross a process boundary at all
+ *     (`service-cluster/src/memory/pubsub.ts`, and the split-brain guard's
+ *     `IN_PROCESS_DRIVERS`).
+ *
+ * So a dropped message on an at-most-once transport is a staleness window with
+ * **no upper bound**, and no amount of care at the publish site changes that.
+ * What bounds it is the **TTL** every cached authorization answer must carry:
+ * a peer that never hears the message still converges when its entry expires.
+ *
+ * ⇒ **A consumer that would be incorrect if a message were lost is misusing
+ * this channel.** The channel exists for one thing: moving the *typical*
+ * convergence from "one TTL" down to "one network hop". It never moves the
+ * worst case, and it is never the mechanism that makes a cached authorization
+ * answer safe.
+ *
+ * ⚠️ For the same reason this channel is **best-effort at the publish site
+ * too**: a publish failure is logged and swallowed, never propagated into the
+ * write that triggered it. A grant revocation must not fail because a cache
+ * hint could not be delivered — the TTL already covers exactly that case.
+ *
+ * `IPubSub`'s own interface docblock (`@objectstack/spec/contracts`) states the
+ * same thing from the contract side — delivery is whatever the configured
+ * driver declares, no shipped driver exceeds at-most-once, and handlers must be
+ * idempotent **and** tolerate loss. That docblock, `cluster.mdx` §4.2 and the
+ * redis driver agree; there is no disagreement here for a later reader to go
+ * looking for.
+ *
+ * ## Why a new channel on the existing bus, and not a new transport
+ *
+ * `MetadataClusterBridgePlugin` already shows the whole shape — a channel on
+ * `IPubSub`, bridged by a plugin that late-binds at `kernel:ready` and does
+ * nothing when the services it needs are absent. Reusing it adds no dependency
+ * and no new failure mode. The one thing metadata's channel does NOT have to
+ * carry is what makes this one different: a missed `metadata.changed` costs a
+ * stale schema until reload and loses no data, while a missed
+ * `authz.invalidated` would cost a permission honoured past its revocation —
+ * which is why the bound lives in the TTL and why the absence of this bridge is
+ * stated out loud at boot ({@link ../security/authz-cache-posture.js}).
+ */
+/**
+ * The cluster channel authorization-cache invalidation hints travel on.
+ *
+ * Named as a fact about authorization, not about any one cache, because a
+ * second consumer must reuse this channel rather than mint a parallel one —
+ * two channels would be two chances to miss a bridge.
+ */
+declare const AUTHZ_INVALIDATED_CHANNEL = "authz.invalidated";
+/**
+ * Why an authorization epoch advanced. Coarse on purpose (#11633 §2.2, Fork 1 →
+ * A): the engine seam sees `update`/`delete` expressed as a `where`, from which
+ * the affected user or organization is frequently **not derivable without
+ * reading the row back**. So the substrate carries "something authorization-
+ * relevant changed", never "whose entry to drop", and a consumer retires its
+ * whole bucket. Keyed invalidation is gated behind a measurement of a
+ * write-heavy tenant and is explicitly not the starting point.
+ */
+type AuthzInvalidationReason = 
+/** A write (`insert` / `update` / `delete`) passed the engine middleware seam. */
+'write'
+/** A metadata change — a permission set can be DECLARED, so no row is written. */
+ | 'metadata'
+/** A hint received from a peer node on this channel. */
+ | 'remote'
+/** An explicit bump by a host that knows something the seam cannot see. */
+ | 'manual';
+/**
+ * The payload on {@link AUTHZ_INVALIDATED_CHANNEL}.
+ *
+ * Deliberately tiny and deliberately NOT a description of what to invalidate:
+ * see {@link AuthzInvalidationReason} for why the seam cannot supply that. A
+ * receiver's only correct response is to retire its authorization cache
+ * wholesale — and to remain correct if this message never arrives.
+ *
+ * ⛔ Not a `packages/spec` contract type. #11633 §5 reserves a declared shape
+ * for the invalidation event to the spec seat and does not pre-commit it; this
+ * is the runtime shape the substrate publishes today.
+ */
+interface AuthzInvalidatedPayload {
+    /**
+     * Publishing node, for loopback suppression — a node must not act on its own
+     * hint. Mirrors `ClusterMetadataChangedPayload.originNode`.
+     */
+    originNode?: string;
+    /** The publisher's local epoch after the bump. Diagnostic only. */
+    epoch: number;
+    /** What advanced the epoch. Diagnostic only — see the type's doc. */
+    reason: AuthzInvalidationReason;
+    /** Wall-clock publish time, ms since epoch. Best-effort. */
+    at: number;
+}
+
+/**
+ * ── The boot-time authorization-cache posture statement (#11968, #11633 §3) ──
+ *
+ * ⭐ **Non-optional**, by the 2026-08-25 ruling on #11633 (Fork 2 → B): whenever
+ * a grants cache is enabled and there is **no** cross-node invalidation bus, the
+ * deployment is told so, **out loud**, at boot.
+ *
+ * ## Why a statement and not a refusal
+ *
+ * A per-process cache bounded only by its TTL is a legitimate configuration —
+ * #11633 §3 rules the TTL, not the bus, as the correctness contract, so a
+ * single-node deployment (or one that simply accepts the window) is correct
+ * with no bus at all. What is NOT acceptable is arriving there **without
+ * noticing**: that is the shape of #4785, where a control was silently disabled
+ * by configuration and nothing said so. The metadata bridge logs its own
+ * absence at `debug` and that is right for metadata — a missed
+ * `metadata.changed` costs a stale schema until reload and loses no data. Here
+ * the same silence would cost a permission honoured past its revocation.
+ *
+ * ⇒ Enabled cache + no bus is a `warn`, every boot, naming the window it just
+ * accepted. Not a refusal — a statement.
+ *
+ * ## The three postures, and the reason `disabled` is silent
+ *
+ *   - `disabled`      — no cache is enabled. **Silent.** There is no window to
+ *                       state, and a line every boot on the shipped default
+ *                       (TTL `0`, Fork 4) would train operators to ignore it —
+ *                       which is how the loud line stops being loud.
+ *   - `ttl-only`      — cache enabled, no cross-node bus. **LOUD (`warn`).**
+ *   - `bus-narrowed`  — cache enabled, bus bridged. `info`, so the bridge's
+ *                       presence is on the record next to its absence.
+ *
+ * Both arms are pinned in `authz-cache-posture.test.ts`: a statement that
+ * appears always is no more useful than one that never appears.
+ */
+/** Deployment variable that turns the grants cache on. `0` (default) = off. */
+declare const AUTHZ_GRANTS_CACHE_TTL_ENV = "OS_AUTHZ_GRANTS_CACHE_TTL_MS";
+/**
+ * What the local node has, in cross-node terms, for delivering
+ * `authz.invalidated`.
+ *
+ * ⚠️ `in-process` is a distinct state on purpose, and it is the one that would
+ * otherwise go unnoticed: `Runtime` auto-registers a **memory** cluster service
+ * by default, so "is a `cluster` service registered?" answers *yes* on the
+ * shipped default while the bus fans out to exactly nobody
+ * (`service-cluster/src/memory/pubsub.ts`: *"No cross-process delivery"*; the
+ * split-brain guard calls the same set `IN_PROCESS_DRIVERS`). A posture check
+ * that asked only whether a service exists would therefore stay silent in
+ * precisely the multi-replica deployment it exists to warn.
+ */
+type AuthzInvalidationBusState = 
+/** A cross-node transport is attached and carrying the channel. */
+'bridged'
+/** A cluster service exists, but its driver does not cross a process boundary. */
+ | 'in-process'
+/** No cluster service, or no engine seam to attach one to. */
+ | 'absent';
+/** The posture a boot resolves to. */
+type AuthzCachePosture = 'disabled' | 'ttl-only' | 'bus-narrowed';
+interface AuthzCachePostureInput {
+    /** Configured grants-cache TTL in ms. `<= 0` means the cache is off. */
+    ttlMs: number;
+    /** What the node has for cross-node invalidation. */
+    bus: AuthzInvalidationBusState;
+    /** Cluster driver name, when one is registered. Surfaced in the message. */
+    driver?: string;
+}
+interface AuthzCachePostureStatement {
+    posture: AuthzCachePosture;
+    /** True when this must be said at `warn`. See the module doc. */
+    loud: boolean;
+    /** The statement itself. Empty only for the silent `disabled` posture. */
+    message: string;
+}
+/**
+ * Resolve the posture. Pure — it reads its inputs and nothing else, so both
+ * arms of the acceptance criterion ("appears exactly when a cache flag is on
+ * without a bus, and not otherwise") are testable without a boot.
+ */
+declare function resolveAuthzCachePosture(input: AuthzCachePostureInput): AuthzCachePostureStatement;
+/** The reading of {@link AUTHZ_GRANTS_CACHE_TTL_ENV}, malformed input included. */
+interface AuthzGrantsCacheTtlReading {
+    /** The effective TTL. `0` whenever the cache is off — including malformed. */
+    ttlMs: number;
+    /** The raw value read, when one was set. */
+    raw?: string;
+    /** True when a value was set but could not be read as a non-negative number. */
+    malformed: boolean;
+}
+/**
+ * Read the grants-cache TTL from deployment config.
+ *
+ * Deployment config, never a settings row (#11633 §5): the knob that bounds a
+ * cache must not itself be served through a cached path, and operator-level
+ * configuration comes from the environment.
+ *
+ * Default `0` — the grants cache is **off** unless a deployment turns it on and
+ * accepts the staleness window explicitly (#11633 Fork 4, ruled 2026-08-25).
+ *
+ * ⚠️ A malformed value resolves to `0` but is reported as malformed rather than
+ * folded into "off": `OS_AUTHZ_GRANTS_CACHE_TTL_MS=5OOO` (letter O) silently
+ * meaning "disabled" is the same silent-disable class the posture statement
+ * exists to prevent.
+ */
+declare function readAuthzGrantsCacheTtlMs(env?: Record<string, string | undefined>): AuthzGrantsCacheTtlReading;
+/** Minimal sink shape — `warn` is the member every logger in this repo has. */
+interface AuthzPostureSink {
+    warn(message: string, meta?: Record<string, unknown>): void;
+    info?(message: string, meta?: Record<string, unknown>): void;
+    debug?(message: string, meta?: Record<string, unknown>): void;
+}
+/**
+ * State the posture at boot. `warn` for the loud arm, `info` for the bridged
+ * one, and nothing at all when no cache is enabled (see the module doc for why
+ * silence is the right default rather than a courtesy line).
+ *
+ * A malformed TTL value is warned about on its own, because "we read your
+ * setting as off" is exactly what a deployment must not have to infer.
+ */
+declare function reportAuthzCachePosture(input: AuthzCachePostureInput & {
+    malformedTtl?: {
+        raw?: string;
+    };
+}, sink: AuthzPostureSink): AuthzCachePostureStatement;
+
 /**
  * Environment utilities for universal (Node/Browser) compatibility.
  */
@@ -3407,6 +4223,204 @@ declare function temporalComparandKind(fieldType: unknown): TemporalComparandKin
  */
 declare function isUninterpretableTemporalComparand(kind: TemporalComparandKind, value: unknown): boolean;
 
+/**
+ * [ADR-0126 §4] THE activation-ledger row contract — one implementation,
+ * parameterized by `metadata_type`.
+ *
+ * ## Why this file exists (#12350)
+ *
+ * ADR-0126 §4 declares ONE activation ledger for the whole disable+clone
+ * family. It briefly had two implementations of that one row contract:
+ *
+ * | Implementation                    | Package                            | Landed |
+ * | :-------------------------------- | :--------------------------------- | :----- |
+ * | `ObjectStoreFlowActivationStore`  | `@objectstack/service-automation`  | #12296 |
+ * | `ObjectStoreActionActivationStore`| `@objectstack/objectql`            | #12348 |
+ *
+ * They agreed on every load-bearing detail because the second was written from
+ * the first — and nothing structurally held them together. ADR-0126 §8
+ * pre-charts `tool`, `skill` and `position` as later consumers, and a third
+ * and fourth copy is where the row semantics start drifting: the org-row skip
+ * and the `0`-is-false read are exactly the kind of detail a copy loses
+ * quietly, in a direction (an artifact silently re-arming) nothing else
+ * measures.
+ *
+ * ## Why the code lives HERE and the object does not
+ *
+ * Neither consumer could import the other: `@objectstack/service-automation`
+ * does not depend on `@objectstack/objectql` (devDependency only), and the
+ * engine must not depend on a service — the dependency arrow points the other
+ * way. `@objectstack/core` is the package BOTH already depend on, so this is
+ * the one home that needs no new edge. ⛔ NOT `@objectstack/platform-objects`,
+ * which declares the OBJECT: `objectql` does not depend on it and adding that
+ * edge would invert the tiering, since platform-objects is a catalog the
+ * engine serves. That is a MODULE-IMPORT question, and it is independent of
+ * where the object's REGISTRATION lives (a composition question, ruled
+ * separately on #12359 — `PlatformObjectsPlugin`).
+ *
+ * The table is reached by NAME, never by importing the declaration, exactly as
+ * the engine already reaches `sys_metadata` / `sys_secret`.
+ *
+ * ## The row shape — ⛔ this module writes COLUMNS, never schema
+ *
+ * `metadata_type` · `name` · `package_id` · `active`, exactly the four
+ * ADR-0126 §4 declares. Three properties are load-bearing and each is pinned on
+ * both consumers' sides (`flow-activation-ledger.test.ts`,
+ * `action-activation.test.ts` — unchanged by the consolidation, which is what
+ * makes them the proof it lost nothing):
+ *
+ *   - **The ledger is DEPLOYMENT-level, and carries no tenant column at all.**
+ *     A row says "this environment switched this managed item off" — a fact no
+ *     organization owns. The table briefly declared a nullable tenant column
+ *     marked RESERVED and never written, and this module correspondingly
+ *     filtered reads to the NULL ones and skipped any row carrying an
+ *     organization. Both are gone: a reserved nullable tenant
+ *     column is the shape the total-organization-ownership record proposed in
+ *     PR #14976 rules out, so the column was dropped before it ever shipped
+ *     (17.2.0 predates the table). There is no filter here any more because
+ *     there is no column to filter on — `list()` is simply every activation
+ *     row of this type. Should a per-organization dimension ever be wanted, it
+ *     returns as a separate org-owned object, never as a column here.
+ *   - **Absence of a row means ACTIVE.** Nothing here ever writes a row to say
+ *     "active by default", and `list()` returning nothing is the normal
+ *     stock-boot state, not an error. Re-enabling UPDATES the row to
+ *     `active: true` rather than deleting it, so the ledger records the
+ *     administrator's CHOICE instead of erasing it (§6 wall 3) — which is why
+ *     {@link MetadataActivationStoreEngine} deliberately has no `delete`.
+ *   - **A driver `0` reads as false.** SQLite/libsql round-trip booleans as
+ *     0/1; a `!== false` test alone would read a disabled artifact as armed.
+ *
+ * ## The discriminator is never optional
+ *
+ * The ledger is generic and shared — flow rows and action rows live in the
+ * same table today, and §8 charts more. Every read and write below is scoped
+ * by `metadata_type`, so no consumer can touch a neighbour's state through a
+ * table all of them are told to treat as generic. It is a constructor
+ * argument, not a per-call one, so a caller cannot forget it at a single site.
+ */
+/**
+ * The ledger table. A NAME, not an import: the object is declared in
+ * `@objectstack/platform-objects` and this package must not depend on it.
+ */
+declare const METADATA_ACTIVATION_TABLE = "sys_metadata_activation";
+/**
+ * [ADR-0126 §4] One packaged artifact's install-level activation row.
+ *
+ * The ledger's own columns are `metadata_type` / `name` / `package_id` /
+ * `active`; `metadata_type` is fixed by the store, so it never reaches a
+ * consumer's projection.
+ */
+interface MetadataActivationRow {
+    /** The packaged artifact's declarative machine name (ADR-0126 §4). */
+    name: string;
+    /** The package that ships the base artifact. */
+    packageId: string;
+    /** Is the packaged artifact armed for this installation. */
+    active: boolean;
+}
+/**
+ * [ADR-0126 §4] The durable off-switch for one class of packaged artifact.
+ *
+ * Absence of a row means the packaged default — ACTIVE — so a runtime with no
+ * store attached, or a store with no rows, behaves exactly as a stock boot
+ * always has.
+ */
+interface MetadataActivationStore {
+    /** Every activation row for this type — the ledger is deployment-wide. */
+    list(): Promise<MetadataActivationRow[]>;
+    /** Insert or update the row for one packaged artifact. */
+    setActive(row: MetadataActivationRow): Promise<void>;
+}
+/**
+ * The exact engine slice this store needs: a keyed read, an insert and an
+ * update. Deliberately WITHOUT `delete` — re-enabling updates the `active`
+ * bit, it never removes the row (see the module header), and demanding only
+ * what is used keeps every test double honest about that.
+ */
+interface MetadataActivationStoreEngine {
+    find(object: string, options?: any): Promise<any[]>;
+    insert(object: string, data: any, options?: any): Promise<any>;
+    update(object: string, data: any, options?: any): Promise<any>;
+}
+/**
+ * In-memory {@link MetadataActivationStore} — process-lifetime only, for tests
+ * and for hosts with no durable plane. What it lacks versus the ObjectStore
+ * implementation is DURABILITY, which is exactly the property ADR-0126 §6
+ * wall 3 asks for; it is not a sanctioned production off-switch.
+ *
+ * No discriminator: an in-memory map is per-instance, so there is no shared
+ * table for a neighbouring type's rows to be in.
+ */
+declare class InMemoryMetadataActivationStore implements MetadataActivationStore {
+    private readonly rows;
+    list(): Promise<MetadataActivationRow[]>;
+    setActive(row: MetadataActivationRow): Promise<void>;
+}
+/**
+ * Durable {@link MetadataActivationStore} backed by the
+ * `sys_metadata_activation` object (ADR-0126 §4), scoped to one
+ * `metadata_type`.
+ *
+ * All access uses a system context: the object is `managedBy: 'engine-owned'`
+ * and declares `apiMethods: ['get', 'list']`, i.e. the generic data API cannot
+ * write it at all — these rows are written by the ADR-0126 enable/disable
+ * doors and by nothing else.
+ */
+declare class ObjectStoreMetadataActivationStore implements MetadataActivationStore {
+    private readonly engine;
+    /**
+     * The ledger's `metadata_type` discriminator for this consumer —
+     * `'flow'`, `'action'`, … Required, and fixed for the store's
+     * lifetime: see the module header on why it is never a per-call
+     * argument.
+     */
+    private readonly metadataType;
+    constructor(engine: MetadataActivationStoreEngine, 
+    /**
+     * The ledger's `metadata_type` discriminator for this consumer —
+     * `'flow'`, `'action'`, … Required, and fixed for the store's
+     * lifetime: see the module header on why it is never a per-call
+     * argument.
+     */
+    metadataType: string);
+    /**
+     * Every row of this type. Read once at boot to hydrate the consumer's
+     * projection.
+     *
+     * The only scoping is the `metadata_type` discriminator: the ledger is
+     * deployment-wide and has no tenant column, so there is no second axis to
+     * filter on (see the module header).
+     */
+    list(): Promise<MetadataActivationRow[]>;
+    /**
+     * Insert or update the row for one packaged artifact.
+     *
+     * Read-then-write rather than a blind upsert because the object's
+     * uniqueness is a DECLARED index (`unique: 'global'` over
+     * `(metadata_type, name)`), not a primary key this store controls: there is
+     * no id to collide on, so an insert-and-catch could not tell "already
+     * there" from a real store failure.
+     *
+     * That index is also why taking the FIRST match is taking the only one: the
+     * read below is keyed on exactly the index's two columns, so it can match
+     * at most one row. It used to pick the first row with a NULL organization
+     * out of the result, back when the table carried a reserved tenant column;
+     * with no such column the set it was choosing from can no longer hold more
+     * than one member.
+     */
+    setActive(row: MetadataActivationRow): Promise<void>;
+    /**
+     * Read the backing table once so a misconfiguration surfaces at BOOT
+     * rather than as a failed toggle later. Throws the driver error verbatim —
+     * `no such table: sys_metadata_activation` means the object was never
+     * registered (or its schema never synced) in this composition.
+     *
+     * ⚠️ Unscoped by design: the question is "does the TABLE read at all",
+     * which is a property of the composition, not of one `metadata_type`.
+     */
+    probe(): Promise<void>;
+}
+
 /**
  * [#4435] The 404 a single-record operation answers when the id names no row.
  *
@@ -3710,7 +4724,7 @@ declare const CORE_FALLBACK_FACTORIES: Record<string, () => Record<string, any>>
  * (#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
+ * `@objectstack/spec/meta-spelling`); a name with no plural mapping — which includes
  * every canonical singular type — passes through unchanged.
  */
 declare function canonicalMetadataServiceType(type: string): string;
@@ -3739,8 +4753,37 @@ declare function assertMetadataRegisterContract(type: string, name: string, data
 /**
  * Plugin Health Monitor
  *
- * Monitors plugin health status and performs automatic recovery actions.
- * Implements the advanced lifecycle health monitoring protocol.
+ * Monitors plugin health status. It REPORTS; it does not act on what it finds.
+ *
+ * ## The monitor no longer "restarts" anything (#12032)
+ *
+ * It used to claim it did. `attemptRestart` called `plugin.destroy()` and
+ * stopped there — the comment above the call read "Call destroy and init to
+ * restart", and `init` appeared in this file ONLY inside that comment. What a
+ * plugin got was: destroy, a log line reading 'Plugin restarted', status
+ * `recovering`, and periodic checks continuing against the destroyed instance.
+ * The default check when no `checkMethod` resolves is
+ * `{ name: 'plugin-loaded', status: 'passed' }`, which a destroyed plugin
+ * passes indefinitely, so the TERMINAL report on a destroyed, never
+ * re-initialised plugin was `healthy` — and #11955 made that MORE convincing
+ * rather than less, because reaching `healthy` now costs `successThreshold`
+ * consecutive passing rounds.
+ *
+ * The restart could not be repaired in place. `Plugin.init(ctx)` needs a
+ * `PluginContext`, and the only two `plugin.init(...)` call sites in the tree
+ * are the kernel's own boot loops, over the full plugin list, with a context
+ * that is `private` on `ObjectKernel` and `protected` on `KernelBase`. No host
+ * can obtain one, so there was nothing for a re-init hook to call. ADR-0049
+ * enforce-or-remove, with no roadmap to point EXPERIMENTAL at, therefore
+ * removed the declaration: `autoRestart`, `maxRestartAttempts` and
+ * `restartBackoff` are tombstoned in `@objectstack/spec` 18, and this class
+ * refuses a config that still carries one instead of accepting it and doing
+ * something else.
+ *
+ * What a failing plugin gets now is the truth: `degraded`, `unhealthy` or
+ * `failed`, and no destroy. Acting on that is the HOST's job — this is a
+ * host-driven library (#11825 route 2), and the host is the only party that
+ * owns the plugin's lifetime.
  */
 declare class PluginHealthMonitor {
     private logger;
@@ -3750,7 +4793,6 @@ declare class PluginHealthMonitor {
     private checkIntervals;
     private failureCounters;
     private successCounters;
-    private restartAttempts;
     constructor(logger: ObjectLogger);
     /**
      * Register a plugin for health monitoring
@@ -3769,13 +4811,28 @@ declare class PluginHealthMonitor {
      */
     private performHealthCheck;
     /**
-     * Attempt to restart a plugin
-     */
-    private attemptRestart;
-    /**
-     * Calculate backoff delay for restarts
+     * Handle one failed round — the single path BOTH failure routes take.
+     *
+     * `performHealthCheck` can fail two disjoint ways: the check *returns* a
+     * failure (`false` or `{ status: 'unhealthy' }`), or it *throws* — which by
+     * `raceCheckTimeout` includes every `timeout` overrun, the severest case of
+     * the two. The routes used to be handled in separate blocks, and only the
+     * returned one cleared `successCounters`, so the counters a declared
+     * `failureThreshold` / `successThreshold` are counted with depended on which
+     * way the round happened to fail (#11852).
+     *
+     * What stays route-specific is the *status label*, deliberately. A throw is
+     * the separate `failed` status applied immediately with no threshold — that
+     * is the documented contract (`content/docs/protocol/kernel/lifecycle.mdx`,
+     * "Custom Health Checks") and is pinned by the timeout test. Only the
+     * counters are shared, because that is what `failureThreshold` declares, and
+     * it does not name a route.
+     *
+     * This round ENDS here. Nothing is done TO the plugin — see the #12032 note
+     * on the class: a monitor that cannot re-initialise a plugin has no business
+     * destroying one.
      */
-    private calculateBackoff;
+    private recordFailedRound;
     /**
      * Get current health status of a plugin
      */
@@ -3857,7 +4914,6 @@ declare class HotReloadManager {
     private logger;
     private stateManager;
     private reloadConfigs;
-    private watchHandles;
     private reloadTimers;
     constructor(logger: ObjectLogger);
     /**
@@ -3865,11 +4921,35 @@ declare class HotReloadManager {
      */
     registerPlugin(pluginName: string, config: HotReloadConfigParsed): void;
     /**
-     * Start watching for changes (requires file system integration)
+     * Refuse the file-watching call this class never implemented (#12428).
+     *
+     * The body used to be a guard plus `logger.info('File watching started')`
+     * over an in-source note saying real watching "would require chokidar or
+     * similar". Nothing was ever watched, so an operator who set
+     * `enabled: true` and read that line at INFO had been told the opposite of
+     * the truth — positive confirmation of a capability that did not exist.
+     * ADR-0049 leaves three states and this surface qualified for none of the
+     * other two: no runtime composes this class, so ENFORCE would build for a
+     * caller that does not exist, and no roadmap entry anywhere claims the
+     * feature, so EXPERIMENTAL would be a promise nobody made.
+     *
+     * Kept as a throwing door rather than deleted: removing the method leaves a
+     * JavaScript host a bare `TypeError: not a function` with no prescription,
+     * and this is the one place a caller of the old placeholder is guaranteed
+     * to arrive. The refusal carries an ADR-0112 envelope so it can be asserted
+     * rather than merely caught.
      */
-    startWatching(pluginName: string): void;
+    startWatching(pluginName: string): never;
     /**
-     * Stop watching for changes
+     * Cancel a pending debounced reload for a plugin.
+     *
+     * The name is historical (#12428). This never stopped a watcher, because
+     * nothing in this class ever started one: its `watchHandles` cleanup branch
+     * read a Map that had no writer anywhere in the tree, so the branch was
+     * structurally unreachable rather than merely untaken, and it left with
+     * `startWatching`'s placeholder. What survives is the half that always did
+     * something — the debounce timer armed by `scheduleReload` is cleared, so a
+     * reload that was scheduled but has not fired yet is cancelled.
      */
     stopWatching(pluginName: string): void;
     /**
@@ -4053,4 +5133,4 @@ declare class NamespaceResolver {
     private suggestAlternative;
 }
 
-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 };
+export { ADMIN_STANDING_NON_TABLE_INPUTS, 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, AUTHZ_GRANTS_CACHE_TTL_ENV, AUTHZ_INVALIDATED_CHANNEL, AUTHZ_STORE_UNAVAILABLE_CODE, AUTHZ_STORE_UNAVAILABLE_MESSAGE, AUTHZ_STORE_UNAVAILABLE_STATUS, type ActivatableRow, type AdminStandingNonTableInput, type AdminStandingTable, type AnonymousDenyInput, type ApiKeyAdmission, type ApiKeyPrincipal, type ApiKeyRefusalReason, type ArtifactPackageError, type AudienceBindingSuggestionStatus, type AuthGate, type AuthzCachePosture, type AuthzCachePostureInput, type AuthzCachePostureStatement, type AuthzGrantsCacheTtlReading, type AuthzInvalidatedPayload, type AuthzInvalidationBusState, type AuthzInvalidationReason, type AuthzPostureSink, AuthzStoreUnavailableError, 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, InMemoryMetadataActivationStore, type IntegrityFile, type IntegrityViolation, type IntegrityViolationKind, type InterruptedRun, type KernelState, type KeyInput, type LadderPrincipal, type LadderRow, LiteKernel, METADATA_ACTIVATION_TABLE, type MetadataActivationRow, type MetadataActivationStore, type MetadataActivationStoreEngine, 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, ObjectStoreMetadataActivationStore, type OrderablePlugin, PLATFORM_ADMIN_EMAIL_SEPARATOR, POSTURE_INJECTION_RULE, POSTURE_LADDER, POSTURE_RANK, type ParsedSignature, type PermissionCheckResult$1 as PermissionCheckResult, type PermissionGrant, type PlatformAdminConfigSink, type PlatformAdminEmailConfig, type Plugin, type PluginArtifactVerifyResult, 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 PluginType, type PostureEvidence, type PublisherVerifyResult, index as QA, type ResolveAuthzInput, type ResolveLocalizationInput, type ResolveUserAuthzGrantsOptions, type ResolvedAuthzContext, type ResourceUsage, type RetryOptions, type RunMigrationJournalOptions, SERVICE_NOT_REGISTERED_CODE, 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 VerifyIntegrityResult, type VersionCompatibility, type WallClockParts, adminStandingColumns, adminStandingTables, artifactPackageId, assembleExecutionContext, assembleExecutionContextOrGuest, assertInitServiceRequirements, assertMetadataRegisterContract, bucketKeyToCalendarRange, buildPermissionsFromGrants, bulkWrite, calendarPartsInTz, calendarPartsInTzOrUtc, canonicalMetadataServiceType, collectInternalWriteResponseFields, counterSignPayload, createMemoryCache, createMemoryI18n, createMemoryJob, createMemoryMetadata, createMemoryQueue, createPluginPermissionEnforcer, deepMerge, defaultIsTransientError, derivePosture, describeInitOrderFault, effectiveTenancyPosture, engineCanRollBack, evaluateAuthGate, extractApiKey, filterTokenContextFrom, findInterruptedRuns, formatIntegrityViolation, generateApiKey, generateEd25519KeyPair, getEnv, getMemoryUsage, hasPlatformAdminStanding, hashApiKey, hashMigrationPlan, isAudienceBindingSuggestionStatus, isAuthGateAllowlisted, isAuthzStoreUnavailableError, isConfiguredPlatformAdminEmail, isExpired, isGrantActive, isGrantExpired, isNode, isRowActive, isServiceNotRegisteredError, isUninterpretableTemporalComparand, matchesConfiguredPlatformAdmin, normalizeAuthGate, normalizePlatformAdminEmail, omitInternalFieldsFromWriteResponse, parsePlatformAdminEmails, parseScopes, parseSignature, planChunks, postureVisibleRows, readAuthoredTranslationLayer, readAuthzGrantsCacheTtlMs, readRunJournal, recordNotFoundError, reportAuthzCachePosture, reportLegacyPlatformAdminGrant, resetLegacyPlatformAdminGrantReport, resetPlatformAdminEmailMemo, resolveApiKeyAdmission, resolveApiKeyPrincipal, resolveArtifactPackageOrder, resolveAuthzCachePosture, resolveAuthzContext, resolveFilterToken, resolveFilterTokens, resolveLocale, resolveLocalizationContext, resolvePlatformAdminEmails, resolvePluginOrder, resolveUserAuthzGrants, resumeMigrationJournal, rethrowAuthzStoreUnavailable, runMigrationJournal, safeExit, setPlatformAdminConfigSink, shouldDenyAnonymous, signPayload, temporalComparandKind, unknownAudienceBindingSuggestionStatusMessage, validateInitServiceContract, verifyIntegrity, verifyPayload, verifyPlatformSignature, verifyPluginArtifact, verifyPublisherSignature, wireAuthoredTranslationSync, withTransientRetry, withoutOperationPrivateKeys, zonedDateStartToUtcMs, zonedWallClockToUtcMs };