app-plugin.ts

// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.

import {
    Plugin,
    PluginContext,
    artifactPackageId,
    createPluginPermissionEnforcer,
    resolveArtifactPackageOrder,
    wireAuthoredTranslationSync,
    type PluginPermissionEnforcer,
} from '@objectstack/core';
import { resolveArtifactCollections } from './artifact-collections.js';
import {
    registerArtifactGrantedPermissions,
    type ArtifactGrantBinding,
} from './security/artifact-granted-permissions.js';
import {
    applyArtifactForwardConversions,
    assertProtocolCompat,
    type ArtifactForwardConversionResult,
} from '@objectstack/metadata-core';
import { OBJECTQL_DRIVERS_READY_HOOK } from '@objectstack/objectql';
import { resolveTenancyPosture } from '@objectstack/types';
import { postureEnforcesWall, type TenancyPosture } from '@objectstack/spec/security';
import { SeedLoaderService } from './seed-loader.js';
import { recordSeedOutcome } from './seed-summary.js';
import { contributeCodeDatasourceNames } from './code-datasource-names.js';
import { mergeSeedDatasets, readSeedDatasets, registerSeedReplayerOnce } from './seed-datasets.js';
import { declareSeedSource, recordOrganizationReplay, type SeedLandingReport } from './seed-settlement.js';
import { loadDisabledPackageIds } from './package-state-store.js';
import type { IMetadataService, IObjectQLEngine, II18nService } from '@objectstack/spec/contracts';
import { normalizeFlowFunctionEntry, type NormalizedFlowFunction } from '@objectstack/spec/automation';
import { readServiceSelfInfo } from '@objectstack/spec/api';
import { SEED_WRITE_EXECUTION_CONTEXT } from '@objectstack/spec/kernel';
import { applyProtection } from '@objectstack/spec/shared';
import { QuickJSScriptRunner } from './sandbox/quickjs-runner.js';
import { hookBodyRunnerFactory, actionBodyRunnerFactory } from './sandbox/body-runner.js';
import { bindAppArtifactHandlers, scheduleAppArtifactJobs } from './app-artifact-handlers.js';
import { countServerTiming } from '@objectstack/observability';

/**
 * The write options every seed insert must use — the shared
 * {@link SEED_WRITE_EXECUTION_CONTEXT} posture, wrapped in the options bag
 * `IObjectQLEngine.insert` takes. It no longer MIRRORS
 * `SeedLoaderService.SEED_OPTIONS`; both now read the same export, so the two
 * cannot drift apart (#17178).
 *
 * `skipTriggers` is the load-bearing part: seed rows are pre-existing end-state
 * data, not user events, so firing "on create" automation for them is
 * semantically wrong and was the vector for a self-trigger loop that wedged
 * first boot. `isSystem` alone does NOT suppress dispatch — only `skipTriggers`
 * does — so the two basic-insert fallbacks below used to seed with automation
 * live while the main path had it suppressed (#3760).
 */
const SEED_WRITE_OPTIONS = { context: SEED_WRITE_EXECUTION_CONTEXT } as const;

/**
 * Optional per-project context attached when AppPlugin is instantiated by the
 * project kernel factory. Required for the `app:registered` / `app:unregistered`
 * hooks that drive the org-scoped `sys_app` catalog. Standalone (single-tenant)
 * usages may omit this — no catalog hooks are emitted in that case.
 */

export interface AppPluginProjectContext {
    environmentId: string;
    organizationId: string;
    projectName?: string;
    /** When the app comes from a package installation, the source package id. */
    packageId?: string;
    /** Defaults to 'package' when packageId is set, otherwise 'user'. */
    source?: 'package' | 'user';
}

/**
 * Who registers the stack-declared SECURITY collections (`positions`,
 * `permissions`, `capabilities`, `sharingRules`) into the metadata service on
 * this boot — the ADR-0057 block in `AppPlugin.start()`.
 *
 * - `'app-plugin'` (default): this plugin registers them itself. Every
 *   composition that has no artifact door is this shape — `new AppPlugin(config)`
 *   over a `defineStack()` module (`os serve` / `os migrate` host configs, the
 *   plain stacks in a config's `plugins[]`), `DevPlugin`, `@objectstack/verify`'s
 *   `bootStack`, an embedder.
 * - `'artifact-door'`: the composition ALSO runs `MetadataPlugin` with
 *   `artifactSource` over the same artifact this bundle was read from, so the
 *   artifact door (`packages/metadata/src/plugin.ts`, `ARTIFACT_FIELD_TO_TYPE`)
 *   registers the strict-parsed, forward-converted, ADR-0010-stamped copy of
 *   every item and this plugin leaves those four collections to it (#12892
 *   step 2 — maintainer ruling 2026-08-29: the door owns the route).
 *   `createStandaloneStack` is the composition that says so.
 *
 * ⛔ Declare `'artifact-door'` ONLY beside a `MetadataPlugin({ artifactSource })`
 * reading the same artifact: a declared collection with zero registrars boots
 * green and logs nothing (measured on #12892 step 1), and the default is the
 * registering branch precisely so a composition that never heard of this option
 * cannot lose a registrar.
 */
export type AppPluginSecurityMetadataRegistrar = 'app-plugin' | 'artifact-door';

/**
 * AppPlugin
 *
 * Adapts a generic App Bundle (Manifest + Runtime Code) into a Kernel Plugin.
 * 
 * Responsibilities:
 * 1. Register App Manifest as a service (for ObjectQL discovery)
 * 2. Execute Runtime `onEnable` hook (for code logic) — withheld on a
 *    declaration boot that passes `skipOnEnable`
 * 3. Auto-load i18n translation bundles into the kernel's i18n service
 */
export class AppPlugin implements Plugin {
    name: string;
    type = 'app' as const;
    version?: string;
    /**
     * Ordering — declared, not positional (ADR-0116, the #4131 close of
     * #4085). `init()` synchronously registers the manifest through the
     * `manifest` service and seeds package state / sandbox runners through
     * `objectql` — both registered by ObjectQLPlugin's init. For months that
     * ordering held only because callers happened to `use()` this plugin in
     * the right slot; #4085 is what the wrong slot looks like. Soft (order-
     * if-present) rather than hard because AppPlugin is deliberately
     * composed on engine-less kernels too (metadata-only one-shot commands,
     * mock-engine tests) where it degrades: every `objectql` touch in init
     * is behind a try/catch.
     *
     * `com.objectstack.auth` (ADR-0131 D3): under the `single` posture the
     * auth plugin creates the Default Organization in its `start()`, and that
     * organization must exist before this plugin's `start()` loads the inline
     * seed — every seed row is stamped with it or refused. A kernel without
     * the auth plugin that registers plugin-auth's identity objects
     * (`com.objectstack.auth.identity-objects`, `createIdentityObjectsPlugin()`)
     * registers the organization object too, and that plugin's `start()` keeps
     * the same invariant, so it is ordered ahead for the same reason.
     * Order-if-present: a composition with neither registers no organization
     * object, and its seeds keep today's unstamped branch.
     */
    optionalDependencies = [
        'com.objectstack.engine.objectql',
        'com.objectstack.auth',
        'com.objectstack.auth.identity-objects',
    ];
    /**
     * The one init-time service this plugin CANNOT degrade without: a
     * non-empty bundle is registered via `getService('manifest').register()`
     * with no fallback. Declared so a composition that breaks it fails as a
     * named ordering/composition error before init side effects (#4131).
     * Cleared in the constructor for the empty-env no-op path, which never
     * touches the service.
     */
    requiresServices: string[] = ['manifest'];

    /**
     * Private to the type checker only: three readers outside this class read
     * `bundle` structurally off a plugin entry, with no type to break when it
     * changes. `stackDeclaresOrganizationRecordPage` (`@objectstack/core`,
     * `stack-organization-record-page.ts`) looks for an app's own
     * `sys_organization` record page; `@objectstack/cli`'s `serve.ts` looks for
     * declared translations, and its `graft-runtime-hooks.ts` finds an app's
     * bundle by manifest id to graft hooks onto. Renaming or reshaping this
     * field silently blinds all three; change them together.
     */
    private bundle: any;
    /** Memoized backing store for {@link collections}. */
    private resolvedCollections?: any;
    private projectContext?: AppPluginProjectContext;
    /**
     * The context handed to `init()`, retained so `destroy()` can emit the
     * `app:unregistered` catalog event. [#10772] `Plugin.destroy()` takes NO
     * argument — it is the kernel's only teardown hook — so the context the
     * old `stop(ctx)` alias received has to be captured at init time instead
     * of arriving at teardown time.
     */
    private initCtx?: PluginContext;
    /**
     * The enforcer holding this artifact's install-time GRANTED permission sets
     * (ADR-0025 F4), or `undefined` when the artifact carried no
     * `grantedPermissions` key — which is every artifact built before consent
     * existed and every `defineStack()` config, so this stays `undefined` on
     * every boot shape that ships today.
     *
     * Constructed in `init()` only when there is something to register, so a
     * boot with no consent record allocates nothing and behaves byte-for-byte
     * as it did. Public and readonly-by-accessor so the materialize seam that
     * will QUERY it — and a composition pin — can reach the registry rather
     * than rebuilding it from the artifact a second time.
     */
    private grantEnforcer?: PluginPermissionEnforcer;
    /** What `grantedPermissions` bound to on this artifact — see {@link ArtifactGrantBinding}. */
    private grantBindingResult?: ArtifactGrantBinding;
    /**
     * [#21922] {@link codeDefinedDatasourceOwners}, computed once: the host's
     * code-datasource set reads the names through the contribution `init()`
     * registers, and `start()` registers the same list, so the two can never
     * disagree about which datasources this artifact registers from code — and
     * the residual-owner warning prints once, at whichever read comes first.
     */
    private codeDatasourceOwners?: Array<{ datasource: any; owner: { packageId?: string; packageVersion?: string } }>;
    /**
     * [#23649] Set once {@link installDatasourceMapping} has handed the stack's
     * rules to the engine, so `start()` installs them only on a composition
     * whose engine never announced its pre-sync moment.
     */
    private datasourceMappingInstalled = false;
    /** Memoized backing store for {@link forwardConverted} — the boot's one conversion. */
    private bootConversion?: ArtifactForwardConversionResult<any>;
    /** When true, init/start become no-ops — env has no app payload. */
    private readonly empty: boolean = false;
    /**
     * Suppress the inline boot seed (#3917). One-shot schema commands
     * (`os migrate plan` / `os migrate apply`) boot the full plugin set purely
     * to read metadata, and a boot that writes demo rows into the operator's
     * live database before they have confirmed anything is the same class of
     * bug as boot-time DDL. The `seed-replayer` service is still registered —
     * it only writes when something calls it.
     */
    private readonly skipSeedData: boolean;
    /**
     * Do not execute the bundle's `onEnable` (#21054) — the same one-shot
     * schema commands as {@link skipSeedData}, for the same reason one step
     * further. `os migrate plan` / `apply` compose this app for what it
     * DECLARES; `onEnable` is the app's imperative code, and what it does —
     * register handlers, drivers and lifecycle hooks, read and write data —
     * belongs to a served boot. Measured on `examples/app-crm`: its `onEnable`
     * hooks `kernel:bootstrapped` and reads `sys_position` /
     * `sys_permission_set`, tables the plan's composition never declares, so
     * every plan printed six `DATABASE_ERROR` lines.
     *
     * Read HERE, by the executor, rather than arranged by stripping the member
     * off a copy of the bundle: this method alone resolves which object owns
     * the hook (`bundle.default` before the bundle itself), a stripped copy
     * would re-state that rule at the call site, and the boot would then log
     * "No runtime.onEnable function found" about an app that has one.
     */
    private readonly skipOnEnable: boolean;
    /** Set by `start()` when {@link skipOnEnable} withheld an `onEnable` the bundle carries. */
    private onEnableWithheldFlag = false;
    /**
     * See {@link AppPluginSecurityMetadataRegistrar}. Public and readonly so a
     * composition test can pin which registrar a boot shape declared.
     */
    readonly securityMetadataRegistrar: AppPluginSecurityMetadataRegistrar;

    /**
     * `this.bundle` with every package-owned collection resolved across BOTH
     * artifact shapes — the flattened top level and `packages[]` (ADR-0130 D4 /
     * option B, #15005; the resolution itself is `resolveArtifactCollections`
     * in `./artifact-collections.ts`, package-private because every call site
     * it has today ships in this package).
     *
     * ⛔ Read COLLECTIONS through this, never `this.bundle` — `this.bundle` is
     * what the caller handed us and, on a multi-package option-B artifact, its
     * `objects` / `jobs` / `data` / `translations` / `datasources` /
     * `datasourceMapping` / `permissions` / `positions` are simply ABSENT while
     * `packages[]` carries every one of them. Nothing throws on that path: the
     * subsystem is handed an empty list and the app boots having lost the
     * collection (#15004 measured 24 such subsystems).
     *
     * ENVELOPE keys stay on `this.bundle`, and the two are the same object
     * whenever the bundle carries no `packages[]` — which is every
     * single-package artifact and every `defineStack()` config — so this
     * accessor cannot move the shape that ships today.
     *
     * Lazy so construction stays free of the ADR-0112 refusal a malformed
     * `packages[]` raises: that refusal belongs to the boot, where the
     * `manifest` service already raises it on the same bytes, not to `new
     * AppPlugin(...)`.
     */
    private get collections(): any {
        return (this.resolvedCollections ??= resolveArtifactCollections(this.bundle));
    }

    /**
     * [#22994] The ONE ADR-0087 forward conversion this boot runs over its
     * definition, and the copy every reader in this plugin takes:
     *
     *  - the `manifest` service's decomposition in `init()` (so the ObjectQL
     *    registry, which `GET /meta/<type>` lists and every reader of the
     *    flattened list — the email loader among them — reads as its code
     *    layer);
     *  - the security registrar in `start()`;
     *  - job scheduling (`scheduleAppArtifactJobs`, #23029);
     *  - the datasource readers, through {@link convertedCollection} (#23029):
     *    the code-defined registration and its owners, the reserved-name
     *    check and `connectDeclared`'s input;
     *  - the declared `apis` endpoints ({@link registerDeclaredApiEndpoints});
     *  - the hook binder (`bindAppArtifactHandlers`, #23090);
     *  - `loadTranslations` (#23090): the stack's own list through
     *    {@link convertedCollection}, a lifted `manifest.translations` list
     *    off the copy.
     *
     * The input is `{ ...manifest, ...collections }`, the definition the
     * security block has converted since #12844, and for a bundle carrying no
     * `packages[]` it is byte for byte the payload `init()` has always
     * registered. So every reader above reads one conversion of one input,
     * and none of them converts again. The door's
     * own policy function decides the window, as at the artifact door: the
     * same bytes, the same verdict.
     *
     * Only the converted copy goes forward. Which SOURCE a collection came
     * from (the manifest or the stack, #18034) is still decided on the RAW
     * inputs, at the security block, because the conversion can rewrite a
     * collection KEY (`roles` -> `positions`).
     *
     * Memoized on first read. `init()` reads it only when the bundle carries
     * no `packages[]`: resolving that list belongs to the `manifest` service's
     * `register()` (#15292), and `collections` would resolve it here.
     *
     * `debug`, not `info`: on an artifact boot the door prints its own deduped
     * operator summary for these bytes, and the notice is a fact about the
     * authored floor, not a degradation.
     */
    private forwardConverted(ctx: PluginContext): ArtifactForwardConversionResult<any> {
        if (this.bootConversion === undefined) {
            const collections = this.collections;
            const manifest: any = collections?.manifest;
            const conversion = applyArtifactForwardConversions(manifest ? { ...manifest, ...collections } : collections);
            this.bootConversion = conversion;
            if (conversion.notices.length > 0) {
                ctx.logger.debug('[AppPlugin] applied ADR-0087 forward conversion to the stack definition', {
                    pluginName: this.name,
                    verdict: conversion.verdict,
                    authoredFloor: conversion.authoredFloor,
                    runtimeSpecVersion: conversion.runtimeSpecVersion,
                    notices: conversion.notices.length,
                });
            }
        }
        return this.bootConversion;
    }

    /**
     * [#23029] One COLLECTION of the boot's converted copy
     * ({@link forwardConverted}), for the datasource readers that used to read
     * it off the RAW {@link collections}: the code-defined registration and its
     * owners, the reserved-name check and `connectDeclared`'s input. A turso
     * `config.timeout` or a memory `config.persistence.autoSaveInterval`
     * authored by 17.x tooling is renamed by the conversion; read raw, the
     * driver found no `*Ms` key and fell back to its default with no notice.
     * [#23090] `loadTranslations` reads the stack's own `translations` through
     * it too. (Job scheduling and the hook binder take the whole copy: see
     * `start()`.)
     *
     * WHICH source the collection comes from is still decided on the raw
     * inputs, as the security block decides it (#18034). The converted copy is
     * `{ ...manifest, ...collections }`, so where the stack declares no such
     * collection it would hand over the MANIFEST's key of that name — for
     * `datasources` and `objects` the glob-pattern lists `ManifestSchema`
     * declares, which these readers have never read. Where the stack declares
     * it, the stack wins the spread, so the value is the stack's own, converted.
     */
    private convertedCollection(ctx: PluginContext, key: 'datasources' | 'objects' | 'translations'): any {
        if ((this.collections as Record<string, unknown> | null | undefined)?.[key] === undefined) return undefined;
        return this.forwardConverted(ctx).definition?.[key];
    }

    /**
     * The enforcer this artifact's consent records were registered on, or
     * `undefined` when the artifact declared no `grantedPermissions` key.
     *
     * ⛔ `undefined` here means "no consent record for this environment", NEVER
     * "denied": a caller that reads `undefined` as a deny bricks every boot
     * shape that ships today (clause 1.3). The three states this distinguishes
     * are written out on `registerArtifactGrantedPermissions`.
     */
    get permissionEnforcer(): PluginPermissionEnforcer | undefined {
        return this.grantEnforcer;
    }

    /**
     * What the artifact's `grantedPermissions` map bound to on this boot —
     * `undefined` when the key was absent. Public so a composition pin can read
     * the binding without re-deriving it, and so a caller can tell a declared
     * empty map (`declared: true`, nothing registered) from an absent one.
     */
    get grantBinding(): ArtifactGrantBinding | undefined {
        return this.grantBindingResult;
    }

    /**
     * `true` once `start()` found an `onEnable` on this bundle and did NOT run
     * it, because the composition passed `skipOnEnable` (#21054). `false` on
     * every boot that runs it and on a bundle that carries none — so a caller
     * reporting what its boot withheld names only what was really there.
     */
    get onEnableWithheld(): boolean {
        return this.onEnableWithheldFlag;
    }

    constructor(
        bundle: any,
        projectContext?: AppPluginProjectContext,
        opts: {
            skipSeedData?: boolean;
            skipOnEnable?: boolean;
            securityMetadataRegistrar?: AppPluginSecurityMetadataRegistrar;
        } = {},
    ) {
        this.bundle = bundle;
        this.projectContext = projectContext;
        this.skipSeedData = opts.skipSeedData ?? false;
        this.skipOnEnable = opts.skipOnEnable ?? false;
        // Refused loudly rather than defaulted: a misspelt registrar would
        // otherwise fall through to whichever branch the typo happened to
        // miss, and both branches are silent about what they did not do.
        const registrar = opts.securityMetadataRegistrar ?? 'app-plugin';
        if (registrar !== 'app-plugin' && registrar !== 'artifact-door') {
            throw new Error(
                `[AppPlugin] securityMetadataRegistrar '${String(registrar)}' is not one of `
                + `'app-plugin' | 'artifact-door'`,
            );
        }
        this.securityMetadataRegistrar = registrar;
        // Support both direct manifest (legacy) and Stack Definition (nested manifest)
        const sys = bundle?.manifest || bundle;
        const appId = sys?.id || sys?.name;

        if (!appId) {
            // No app id at all. Two scenarios:
            //   (a) Empty environment — the artifact only ships the bootstrap
            //       envelope ({ manifest: { plugins, drivers, engines }, functions: [] })
            //       with no app categories. We must NOT crash kernel boot
            //       here, otherwise every brand-new env returns 500.
            //   (b) Malformed envelope where an app payload exists but the
            //       caller forgot to pass `manifest`. We throw loudly with
            //       diagnostics so the bug surfaces immediately.
            // App-category keys that indicate "this bundle was supposed to
            // register an app". `manifest`/`functions` are envelope-level
            // wrappers and don't count.
            const APP_CATEGORY_KEYS = [
                'objects', 'views', 'apps', 'pages', 'dashboards', 'reports',
                'flows', 'workflows', 'triggers', 'agents', 'tools', 'skills',
                'actions', 'permissions', 'positions', 'translations',
                'sharingRules', 'ragPipelines', 'data', 'emailTemplates',
                'docs', 'books',
            ];
            const hasAppPayload = APP_CATEGORY_KEYS.some((k) => {
                const v = (bundle && bundle[k]) ?? (sys && sys[k]);
                return Array.isArray(v) && v.length > 0;
            });

            if (!hasAppPayload) {
                // Empty env — degrade to a no-op plugin so kernel boot
                // succeeds. Auth / data routes will still work; there's
                // simply nothing to register. No manifest is registered on
                // this path, so the init-service requirement is dropped —
                // empty envs boot on kernels with no engine at all.
                this.empty = true;
                this.requiresServices = [];
                const envSlug = projectContext?.environmentId
                    ? projectContext.environmentId.slice(0, 8)
                    : 'empty';
                this.name = `plugin.app.empty-${envSlug}`;
                return;
            }

            // Has app payload but no id — genuine malformed envelope.
            const bundleKeys = bundle && typeof bundle === 'object'
                ? Object.keys(bundle).slice(0, 20).join(',')
                : typeof bundle;
            const sysKeys = sys && typeof sys === 'object'
                ? Object.keys(sys).slice(0, 20).join(',')
                : typeof sys;
            const ctxHint = projectContext
                ? ` projectContext=${JSON.stringify({
                    environmentId: projectContext.environmentId,
                    packageId: projectContext.packageId,
                    source: projectContext.source,
                })}`
                : '';
            throw new Error(
                `[AppPlugin] bundle has app payload but no manifest.id / manifest.name — `
                + `cannot register as a plugin. bundleKeys=[${bundleKeys}] `
                + `sysKeys=[${sysKeys}]${ctxHint}`,
            );
        }

        this.name = `plugin.app.${appId}`;
        this.version = sys?.version;
    }

    init = async (ctx: PluginContext) => {
        // [#10772] Retained for `destroy()`, which the kernel calls with no
        // context. Assigned before anything that can throw, and before the
        // empty-env early return, so teardown is armed on every path init
        // takes.
        this.initCtx = ctx;
        // Bind the install-time GRANTED permission set (ADR-0025 F4, #13457)
        // BEFORE anything this plugin registers on the kernel. This is the
        // materialize-time moment the artifact contract names as the consumer
        // of `EnvironmentArtifactSchema.grantedPermissions`, and it runs ahead
        // of the empty-env return on purpose: a consent record that binds to
        // nothing has to be heard on an empty environment too, which is exactly
        // where an artifact carrying grants for packages it does not ship shows
        // up. A no-op — not even an allocation — on every artifact that carries
        // no `grantedPermissions` key.
        this.bindGrantedPermissions(ctx);
        // Install the engine-wide default hook body runner FIRST — even for
        // empty envs (an empty env is exactly where a user will author their
        // first Studio hook). Runs in init (Phase 1) so it is in place before
        // ObjectQLPlugin.start binds metadata-service hooks in Phase 2 (#2588).
        this.installDefaultHookBodyRunner(ctx);
        // Same for the action runner — authored actions register in Phase 2's
        // authored-action re-sync and need the sandbox bridge in place (#2605).
        this.installDefaultActionBodyRunner(ctx);
        // Feed per-hook execution time into the request-scoped perf collector
        // so the `Server-Timing` header can split "hook time" from "DB time".
        // Same boot point as the runners so it is in place before Phase 2 binds
        // metadata-service hooks; a no-op unless perf-tuning is on.
        this.installHookMetricsTiming(ctx);
        // Wire the authored-translation sync (#2591) — also BEFORE the empty-env
        // return: an empty env is exactly where a user authors their first
        // Studio translation. Covers whatever `i18n` service this kernel ends
        // up with (the core in-memory fallback included); idempotent across
        // multiple wirers via the ownership marker in core.
        wireAuthoredTranslationSync(ctx as any);
        // Seed persisted package disable-state — also BEFORE the empty-env
        // return (#5047). An empty env is EXACTLY the hydration-only scenario:
        // the artifact ships no app payload, so every package in that
        // environment arrives later from `sys_packages` (PackageServicePlugin's
        // Phase 2 rehydrate) or from an HTTP install. Seeding after the return
        // meant the registry's initial-disabled set stayed empty on those
        // envs, and a package an operator had disabled came back ENABLED on
        // every restart. The seed must land before ANY registration path runs,
        // which is Phase 1, unconditionally.
        this.seedPersistedDisabledPackages(ctx);
        if (this.empty) {
            ctx.logger.debug('[AppPlugin] empty env — no app payload, skipping init', {
                pluginName: this.name,
            });
            return;
        }
        const sys = this.bundle.manifest || this.bundle;
        const appId = sys.id || sys.name;

        // ADR-0087 D1 — protocol handshake on the code-defined-stack LOAD seam,
        // BEFORE the manifest is decomposed into the registry. A bundle whose
        // declared `engines.protocol` excludes this runtime's major fails boot
        // fast with the structured OS_PROTOCOL_INCOMPATIBLE diagnostic (naming
        // the `migrate meta` command) instead of crashing later in a schema
        // `.parse()` or renderer contract. Absent/unparsable ranges are admitted
        // with a warning (grandfathering; never a false rejection).
        assertProtocolCompat(sys, undefined, (m) => ctx.logger.warn(`[AppPlugin] ${m}`));

        ctx.logger.info('Registering App Service', {
            appId,
            pluginName: this.name,
            version: this.version
        });
        
        // Register the app manifest directly via the manifest service.
        // This immediately decomposes the manifest into SchemaRegistry entries.
        //
        // [#22994] The CONVERTED copy, AFTER the handshake above (ADR-0087 D1
        // before D2), and the same conversion the security block in `start()`
        // registers from — see `forwardConverted`. Registering the raw bundle
        // here is what made `GET /meta/<type>` list an item with its retired
        // key (`_diagnostics.valid: false`) while `GET /meta/<type>/NAME`
        // served the artifact door's converted copy of it, and what handed the
        // email loader a template it refuses to send.
        //
        // A bundle carrying `packages[]` is handed over as it arrived, as before:
        // `forwardConverted` would resolve `packages[]` here, ahead of the
        // `manifest` service (#15292). Its package BODIES are already converted
        // when the bundle came through `loadArtifactBundle`, which runs the
        // ADR-0087 pass once over every body at load (#23027); a bundle handed
        // to this plugin by any other route reaches the `manifest` service as
        // authored.
        const servicePayload = (this.bundle as { packages?: unknown }).packages === undefined
            ? this.forwardConverted(ctx).definition
            : this.bundle.manifest
                ? { ...this.bundle.manifest, ...this.bundle }
                : this.bundle;

        ctx.getService<{ register(m: any): void }>('manifest').register(servicePayload);

        // [#21922] The datasources this artifact registers from code join the
        // host's code-datasource set HERE, in Phase 1, so the datasource-admin
        // plugin's boot restore — a `start()` — never registers a stored row
        // over one of them, whatever order the plugins were composed in. The
        // in-memory registration itself stays in `start()` (see there).
        //
        // Contributed as a FUNCTION the set resolves at its first read, never
        // resolved here: the names come from `collections`, which walks
        // `packages[]`, and the manifest registration above is the one thing
        // in `init()` allowed to touch `packages[]` (#15292's falsifier in
        // `plugin-dev` pins it). `CodeDatasourceNames` says the rest.
        contributeCodeDatasourceNames(ctx, () => this.codeDefinedDatasourceOwners(ctx)
            .map(({ datasource }) => datasource?.name)
            .filter((name): name is string => typeof name === 'string' && name.length > 0));

        // [#23649] The stack's `datasourceMapping` governs the engine from its
        // FIRST schema sync — see `honourDatasourceMappingBeforeSchemaSync`.
        // Subscribed here and resolved there: the rules come from `collections`,
        // which walks `packages[]`, and the registration above is the one thing
        // in `init()` allowed to touch that list. A context with no hook bus (a
        // mock) leaves `start()` to install the rules.
        if (typeof (ctx as { hook?: unknown }).hook === 'function') {
            ctx.hook(OBJECTQL_DRIVERS_READY_HOOK, (engine: unknown) =>
                this.honourDatasourceMappingBeforeSchemaSync(ctx, engine as IObjectQLEngine, appId));
        }
    }

    /**
     * Register the install-time GRANTED permission set this artifact carries,
     * one entry per consent-bearing package, on an enforcer this plugin owns
     * (ADR-0025 F4 / #13457 — the consumer half of
     * `EnvironmentArtifactSchema.grantedPermissions`).
     *
     * The whole method is behind the `=== undefined` gate below, and that gate
     * is the clause-1.3 guarantee in code: an artifact with no consent record
     * takes no branch, allocates no enforcer and registers nothing, so ABSENT
     * can never become "denied". `{}` is not absent and does not take the early
     * return — a declared-but-empty map is a consent record that names no
     * package, which is a different reading and is recorded as one.
     *
     * ⛔ Never `??`/`||` on `grantedPermissions`: both spellings turn a declared
     * `{}` into absence and erase a distinction the producer pins both ways.
     */
    private bindGrantedPermissions(ctx: PluginContext): void {
        if ((this.bundle as { grantedPermissions?: unknown } | null | undefined)?.grantedPermissions === undefined) {
            return;
        }
        const enforcer = createPluginPermissionEnforcer(ctx.logger);
        const binding = registerArtifactGrantedPermissions(this.bundle, enforcer, { logger: ctx.logger });
        this.grantEnforcer = enforcer;
        this.grantBindingResult = binding;
        ctx.logger.info('[AppPlugin] registered install-time granted permissions', {
            pluginName: this.name,
            registered: [...binding.registered],
            unregistered: [...binding.unregistered],
            unbound: [...binding.unbound],
        });
    }

    /**
     * Seed persisted package disable-state into the registry's initial-disabled
     * set, so every later registration path — boot artifact decomposition,
     * marketplace / `sys_packages` rehydrate, local import — installs those
     * packages DISABLED and they stay hidden after a restart.
     *
     * Runs in init (Phase 1) and BEFORE the empty-env return (#5047), for the
     * same reason the runners above do: the seed only works if it is in place
     * before the FIRST `installPackage` call, and on an empty env every
     * package arrives from Phase 2 hydration rather than from this bundle.
     * On a non-empty env it still lands before the manifest is decomposed,
     * because that decomposition happens at the `manifest.register()` call at
     * the end of init.
     *
     * Best-effort — never block boot on this. Degrades silently on kernels
     * with no engine (metadata-only one-shot commands, mock-engine tests).
     */
    private seedPersistedDisabledPackages(ctx: PluginContext): void {
        try {
            const ql = ctx.getService<{ registry?: { setInitialDisabledPackageIds?: (ids: Iterable<string>) => void } }>('objectql');
            const setter = ql?.registry?.setInitialDisabledPackageIds;
            if (typeof setter === 'function') {
                const disabled = loadDisabledPackageIds(this.projectContext?.environmentId);
                if (disabled.size > 0) {
                    setter.call(ql!.registry, disabled);
                    ctx.logger.info('[AppPlugin] seeded persisted disabled packages', {
                        environmentId: this.projectContext?.environmentId,
                        disabled: Array.from(disabled),
                    });
                }
            }
        } catch (err) {
            ctx.logger.warn('[AppPlugin] failed to seed persisted package state', {
                error: (err as Error)?.message ?? String(err),
            });
        }
    }

    /**
     * Install the engine's DEFAULT hook body runner (`engine.setDefaultBodyRunner`).
     *
     * Hooks authored at runtime (Studio → `protocol.saveMetaItem` → publish)
     * bind through paths that pass no explicit `bodyRunner` — notably
     * ObjectQLPlugin's metadata-service bind — so without this default their
     * L1/L2 `body` is silently dropped by `bindHooksToEngine` and the hook
     * never runs (#2588). The runtime owns the sandbox bridge (objectql stays
     * sandbox-free), so this is the boot point that wires it: same
     * QuickJS-sandboxed, capability-gated runner the `defineStack({ hooks })`
     * bind already uses.
     *
     * `OS_DISABLE_AUTHORED_HOOKS=1` opts out for deployments that want
     * runtime-authored (DB-stored, non-code-reviewed) hook bodies to stay
     * inert; code-shipped hooks are unaffected (AppPlugin passes its own
     * runner explicitly).
     *
     * Idempotent: the first AppPlugin to run installs it; the runner is
     * bundle-agnostic (it only closes over the engine + logger).
     */
    private installDefaultHookBodyRunner(ctx: PluginContext): void {
        if (process.env.OS_DISABLE_AUTHORED_HOOKS === '1') {
            ctx.logger.info('[AppPlugin] OS_DISABLE_AUTHORED_HOOKS=1 — runtime-authored hook bodies will not execute');
            return;
        }
        let ql: IObjectQLEngine | undefined;
        try {
            ql = ctx.getService<IObjectQLEngine>('objectql');
        } catch {
            return; // no engine on this kernel — nothing to wire
        }
        if (!ql || typeof ql.setDefaultBodyRunner !== 'function') return;
        // [#4251] The setter is first-wins — the engine keeps the first runner
        // when several AppPlugins share one kernel; this caller no longer
        // probes the engine's private `_defaultBodyRunner` field to find out.
        const installed = ql.setDefaultBodyRunner(hookBodyRunnerFactory(new QuickJSScriptRunner(), {
            ql,
            logger: ctx.logger,
            appId: 'runtime-authored',
        }));
        if (installed !== false) {
            ctx.logger.info('[AppPlugin] Installed default hook body runner (runtime-authored hooks can execute)');
        }
    }

    /**
     * Install the engine's DEFAULT action body runner (`engine.setDefaultActionRunner`).
     *
     * The exact action-path parallel of {@link installDefaultHookBodyRunner}
     * (#2605 item 1): actions authored at runtime (Studio → `action` metadata →
     * publish) are registered by ObjectQLPlugin's authored-action re-sync,
     * which lives in `objectql` and therefore has no sandbox of its own. This
     * boot point hands it the same QuickJS-sandboxed runner that
     * `defineStack({ actions })` bundles already execute through, so an
     * authored `body` becomes a real `executeAction` handler instead of a
     * silent "Action not found".
     *
     * `OS_DISABLE_AUTHORED_ACTIONS=1` opts out for deployments that want
     * runtime-authored (DB-stored, non-code-reviewed) action bodies to stay
     * inert; code-shipped actions are unaffected (AppPlugin registers those
     * itself with its own runner).
     */
    private installDefaultActionBodyRunner(ctx: PluginContext): void {
        if (process.env.OS_DISABLE_AUTHORED_ACTIONS === '1') {
            ctx.logger.info('[AppPlugin] OS_DISABLE_AUTHORED_ACTIONS=1 — runtime-authored action bodies will not execute');
            return;
        }
        let ql: IObjectQLEngine | undefined;
        try {
            ql = ctx.getService<IObjectQLEngine>('objectql');
        } catch {
            return; // no engine on this kernel — nothing to wire
        }
        if (!ql || typeof ql.setDefaultActionRunner !== 'function') return;
        // [#4251] First-wins setter — same as the hook body runner above.
        const installed = ql.setDefaultActionRunner(actionBodyRunnerFactory(new QuickJSScriptRunner(), {
            ql,
            logger: ctx.logger,
            appId: 'runtime-authored',
        }));
        if (installed !== false) {
            ctx.logger.info('[AppPlugin] Installed default action body runner (runtime-authored actions can execute)');
        }
    }

    /**
     * Install an engine-wide {@link HookMetricsRecorder} that folds every
     * hook's execution time into the request-scoped `Server-Timing` collector
     * (the `hooks;dur=…;desc="N hooks"` span). This is the framework's ONLY
     * caller of `setHookMetricsRecorder`, so it owns the engine's recorder;
     * objectql stays observability-free (the lean `core` tier, ADR-0076) — the
     * timing lives here in the runtime, which already depends on it.
     *
     * `countServerTiming` is a no-op unless a request opened a perf collector
     * (perf-tuning mode), so this costs nothing when the feature is off. It
     * composes with any recorder a host wired earlier (chains to it), and is
     * idempotent across the multiple AppPlugins a multi-app env installs.
     */
    private installHookMetricsTiming(ctx: PluginContext): void {
        let ql: IObjectQLEngine | undefined;
        try {
            ql = ctx.getService<IObjectQLEngine>('objectql');
        } catch {
            return; // no engine on this kernel — nothing to wire
        }
        if (!ql || typeof ql.setHookMetricsRecorder !== 'function') return;
        const existing = typeof ql.getHookMetricsRecorder === 'function'
            ? ql.getHookMetricsRecorder()
            : undefined;
        if (existing?.__perfTimingFeed) return; // already installed by a sibling AppPlugin
        ql.setHookMetricsRecorder({
            __perfTimingFeed: true,
            recordExecution(label: any, outcome: any, durationMs: number) {
                try { existing?.recordExecution?.(label, outcome, durationMs); } catch { /* keep timing isolated */ }
                countServerTiming('hooks', durationMs, 'hooks');
            },
            recordSkip(label: any, reason: any) {
                try { existing?.recordSkip?.(label, reason); } catch { /* noop */ }
            },
            recordRetry(label: any, attempt: number) {
                try { existing?.recordRetry?.(label, attempt); } catch { /* noop */ }
            },
        });
        ctx.logger.debug('[AppPlugin] Installed hook-metrics Server-Timing feed');
    }

    /**
     * Hand the stack's `datasourceMapping` rules to the engine — the one
     * install site, called at most once per boot. Answers whether there were
     * rules to install.
     */
    private installDatasourceMapping(ctx: PluginContext, ql: IObjectQLEngine, appId: string): boolean {
        this.datasourceMappingInstalled = true;
        const datasourceMapping = this.collections.datasourceMapping;
        if (!Array.isArray(datasourceMapping)) return false;
        ctx.logger.info('Configuring datasource mapping rules', {
            appId,
            ruleCount: datasourceMapping.length,
        });
        ql.setDatasourceMapping(datasourceMapping);
        return datasourceMapping.length > 0;
    }

    /**
     * [#23649] Make the stack's `datasourceMapping` govern the engine from its
     * FIRST schema sync. Runs inside `ObjectQLPlugin.start()`, on
     * `OBJECTQL_DRIVERS_READY_HOOK`: the boot's drivers are adopted and
     * connected, and nothing has been synced, hydrated, read or written yet.
     *
     * Two steps, in this order:
     *
     *  1. install the rules ({@link installDatasourceMapping});
     *  2. connect every declared datasource they route an ALREADY-REGISTERED
     *     object to — platform objects included — through the same
     *     `connectDeclared` `start()` calls (ADR-0062 D2 (d): "a datasource a
     *     mapping rule routes at least one registered object to is
     *     auto-connected at boot", fail-fast on a `declared-auto` failure). The
     *     connect also syncs those objects' schemas onto the datasource, and the
     *     engine plugin's own sync that follows finds them there.
     *
     * Before this, the rules were installed in `start()`, after the engine
     * plugin's schema sync and after the auth plugin's Default Organization
     * had both used the default store, and step 2 counted this app's own
     * objects only. A `{ default: true, datasource: 'primary' }` rule then
     * re-routed every platform object to a `primary` whose schema never
     * synced: the server reported ready while the URL store held the platform
     * tables and the Default Organization, and `primary` answered "no such
     * table". A rule routing platform objects to a datasource nothing else
     * addressed (`objectPattern: 'sys_*'`) left it never connected at all.
     *
     * Which objects a rule matches is the ENGINE's answer
     * ({@link resolveMappedObjects}), over the same registry the sync reads.
     * Objects registered after this moment are routed by the installed rules
     * as they arrive; `start()` connects for them as it always has. A
     * datasource no rule routes a registered object to is left to `start()`,
     * which connects it by its other D2 reasons at the moment it always did.
     *
     * Connecting HERE, after the engine adopted its `driver.*` services, keeps
     * the default driver what it was: the engine makes its first registered
     * driver the default, so a mapped datasource connected earlier (in
     * `init()`) would take that slot from a stack plugin's driver.
     */
    private async honourDatasourceMappingBeforeSchemaSync(
        ctx: PluginContext,
        ql: IObjectQLEngine,
        appId: string,
    ): Promise<void> {
        if (this.datasourceMappingInstalled) return;
        if (!this.installDatasourceMapping(ctx, ql, appId)) return;

        const dsDefs = this.convertedCollection(ctx, 'datasources');
        const dsList: any[] = Array.isArray(dsDefs)
            ? dsDefs
            : dsDefs && typeof dsDefs === 'object'
                ? Object.entries(dsDefs).map(([name, def]) => ({ name, ...(def as any) }))
                : [];
        if (dsList.length === 0) return;

        // Absent on a runtime without the datasource-admin plugin: declared
        // datasources stay metadata-only there, and `start()` says so.
        let connection:
            | {
                  connectDeclared?: (input: {
                      datasources: any[];
                      objects?: Array<{ name?: string; datasource?: string }>;
                      mappedObjects?: Record<string, string[]>;
                  }) => Promise<Array<{ name: string; status: string }>>;
              }
            | undefined;
        try {
            connection = ctx.getService('datasource-connection');
        } catch {
            connection = undefined;
        }
        if (typeof connection?.connectDeclared !== 'function') return;

        const registered = ql.registry.getAllObjects() as Array<{ name?: string; datasource?: string }>;
        const mappedObjects = this.resolveMappedObjects(ql, registered);
        const routedTo = dsList.filter(
            (ds) => typeof ds?.name === 'string' && (mappedObjects[ds.name]?.length ?? 0) > 0,
        );
        if (routedTo.length === 0) return;

        const declaredObjects = this.convertedCollection(ctx, 'objects');
        try {
            const results = await connection.connectDeclared({
                datasources: routedTo,
                objects: Array.isArray(declaredObjects) ? declaredObjects : [],
                mappedObjects,
            });
            const connected = results.filter((r) => r.status === 'connected');
            if (connected.length > 0) {
                ctx.logger.info('Auto-connected declared datasources', {
                    appId,
                    connected: connected.map((r) => r.name),
                    before: 'schema sync',
                });
            }
        } catch (err) {
            // Same verdict and the same line as `start()`'s connect: a
            // datasource a mapping routes objects to has no fallback store.
            ctx.logger.error(
                `[AppPlugin] declared-datasource auto-connect failed for app '${appId}': ${(err as Error)?.message ?? String(err)}`,
            );
            throw err;
        }
    }

    /**
     * Datasource name → the objects a `datasourceMapping` rule routes to it
     * (#4462), asked of the ENGINE rather than re-derived here.
     *
     * The gate this feeds (`isDatasourceAddressed` (d)) and the routing that
     * makes it correct (`ObjectQLEngine.getDriver` step 2) must agree exactly
     * about which rules match which objects. A second matcher living in this
     * plugin — or in the connection service — would drift by one clause and
     * produce either a datasource connected that routing never uses, or one
     * routed to and never connected, which is the defect itself.
     *
     * Objects with an EXPLICIT `object.datasource` binding are excluded: that
     * binding outranks mapping in `getDriver`, so counting them here would let
     * a mapping rule they never obey force a fail-fast on their behalf.
     * `default` is excluded for the same reason `getDriver` lets it through —
     * the host's default driver is registered under its natural name and needs
     * no per-app connect.
     */
    private resolveMappedObjects(
        ql: IObjectQLEngine,
        objects: Array<{ name?: string; datasource?: string }>,
    ): Record<string, string[]> {
        const resolve = (ql as unknown as {
            resolveMappedDatasource?: (objectName: string) => string | null;
        }).resolveMappedDatasource;
        if (typeof resolve !== 'function') return {};
        const out: Record<string, string[]> = {};
        for (const obj of objects) {
            const name = obj?.name;
            if (typeof name !== 'string' || !name) continue;
            if (obj.datasource && obj.datasource !== 'default') continue;
            let mapped: string | null = null;
            try {
                mapped = resolve.call(ql, name);
            } catch {
                continue; // a resolver that throws must not brick boot
            }
            if (!mapped || mapped === 'default') continue;
            (out[mapped] ??= []).push(name);
        }
        return out;
    }

    /**
     * Every code-defined datasource this artifact declares, each paired with
     * the coordinates of the package that declares it — what `start()` hands
     * `applyProtection` when it registers the datasource.
     *
     * [#21889] The federation service reads those coordinates back: its
     * `getNamespace` (`@objectstack/service-datasource`) takes the datasource's
     * `_packageId` to the engine registry's package record, whose
     * `manifest.namespace` is the ADR-0028 prefix an object imported over the
     * datasource must carry. Registered without coordinates, a code-defined
     * datasource resolved no namespace: the import accepted an unprefixed
     * name and the draft emitted one.
     *
     * The owner is read the way the metadata plugin's artifact door reads it
     * (ADR-0130 D4, `packages/metadata/src/plugin.ts`), and for its reasons:
     *
     *  - `packages` ABSENT: the artifact is its one package's body, so every
     *    datasource takes the manifest's id, the key `registerApp` installs the
     *    package under. The list is the stack's `datasources` (D7), read off
     *    the boot's converted copy ({@link convertedCollection}, #23029).
     *  - `packages` PRESENT: each body's datasources take THAT body's id
     *    (`artifactPackageId`, the one spelling `registerApp` keys on), in the
     *    order `resolveArtifactPackageOrder` gives, over the converted copy's
     *    bodies (#23029: the conversion replays every body). ⛔ Never the artifact's
     *    top-level manifest id on every entry: on a composed artifact that id
     *    is one member's, and stamping it everywhere hands one package another
     *    package's datasources (#14599). ⛔ Never a name-to-package index over
     *    the flattened list either: that is a second resolution path for
     *    ownership, and a dangling one fails silently.
     *  - A datasource no body declares (an artifact composed from a stack that
     *    already carried `packages` and one that did not) falls back to the
     *    artifact's own manifest id, as the door's residual sweep does, and is
     *    logged, because the artifact's two halves disagree.
     */
    private codeDefinedDatasourceOwners(ctx: PluginContext): Array<{
        datasource: any;
        owner: { packageId?: string; packageVersion?: string };
    }> {
        this.codeDatasourceOwners ??= this.resolveCodeDefinedDatasourceOwners(ctx);
        return this.codeDatasourceOwners;
    }

    /** The resolution {@link codeDefinedDatasourceOwners} memoizes. */
    private resolveCodeDefinedDatasourceOwners(ctx: PluginContext): Array<{
        datasource: any;
        owner: { packageId?: string; packageVersion?: string };
    }> {
        const listOf = (dsDefs: unknown): any[] =>
            Array.isArray(dsDefs)
                ? dsDefs
                : dsDefs && typeof dsDefs === 'object'
                    ? Object.entries(dsDefs).map(([name, def]) => ({ name, ...(def as any) }))
                    : [];
        const coordsOf = (body: any) => ({
            packageId: artifactPackageId(body),
            packageVersion: typeof body?.version === 'string' ? body.version : undefined,
        });
        const own = coordsOf(this.bundle.manifest || this.bundle);
        const declared = listOf(this.convertedCollection(ctx, 'datasources'));

        if ((this.bundle as { packages?: unknown }).packages === undefined) {
            return declared.map((datasource) => ({ datasource, owner: own }));
        }

        const owned: Array<{ datasource: any; owner: { packageId?: string; packageVersion?: string } }> = [];
        const claimed = new Set<unknown>();
        for (const body of resolveArtifactPackageOrder(this.forwardConverted(ctx).definition)) {
            const owner = coordsOf(body);
            for (const datasource of listOf((body as { datasources?: unknown } | null)?.datasources)) {
                claimed.add(datasource?.name);
                owned.push({ datasource, owner });
            }
        }
        const residual = declared.filter((datasource) => !claimed.has(datasource?.name));
        if (residual.length > 0) {
            ctx.logger.warn(
                `[AppPlugin] artifact '${own.packageId ?? '<none>'}' carries ${residual.length} top-level `
                + 'datasource(s) that none of its package bodies declare: '
                + `${residual.map((d) => `'${String(d?.name)}'`).join(', ')}. They were registered under `
                + "the artifact's own manifest id because no package in the artifact claims them, so the "
                + 'ADR-0028 namespace an import over them must carry is that package\'s. Rebuild the '
                + 'artifact with one `composeStacks` run so every datasource sits in the body that owns it.',
            );
            owned.push(...residual.map((datasource) => ({ datasource, owner: own })));
        }
        return owned;
    }

    /**
     * The config door's half of the residual rule (ADR-0130 D4): what this
     * bundle's TOP LEVEL carries that none of its `packages[]` bodies declares
     * is registered under the stack's own `manifest.id`, with the boot's
     * warning — exactly as the artifact door does it for a compiled artifact.
     *
     * The `manifest` service this plugin hands the bundle to in `init()`
     * registers the package bodies and never the top level of a stack that
     * carries `packages[]` (`resolveArtifactPackageOrder` answers the bodies
     * alone). So on a config boot (`os serve objectstack.config.ts`, with or
     * without `--dev`) such an item was served by no door and the boot said
     * nothing, while `os build` of the same project booted as an artifact
     * served it under `manifest.id` and warned.
     *
     * ⛔ The rule is not written here. Which items are residual, the key and
     * owner each is registered under, and the line the boot prints are all
     * `MetadataPlugin.registerUnclaimedTopLevel`'s, the one copy the artifact
     * door calls too. This method only says WHERE this door stores: the
     * metadata service's in-memory registry, the route this plugin already
     * uses for the code-owned items it surfaces (never persisted to a
     * writable loader, so a config edit is never shadowed by a stored row).
     *
     * One registrar per boot, declared by the composition: on a boot whose
     * composition runs the artifact door over the same stack
     * (`securityMetadataRegistrar: 'artifact-door'`), the door registers the
     * residual and this does nothing. A composition with no metadata service
     * that can register in memory has no registry to serve the residual from;
     * it is skipped with a `debug` line, as the security block below is.
     *
     * A refusal the rule raises (a residual view container whose own `name`
     * disagrees with its key) is NOT caught: the artifact boot of the same
     * stack refuses it too, and the config boot answers the same. `os validate`
     * reports it before either boot, from the same residual answer
     * (`unclaimedTopLevel`).
     */
    private async registerUnclaimedTopLevel(ctx: PluginContext, appId: string): Promise<void> {
        if (this.securityMetadataRegistrar === 'artifact-door') return;
        let metadata: { registerInMemory?: (type: string, name: string, item: unknown) => void } | undefined;
        try {
            metadata = ctx.getService('metadata');
        } catch {
            // Not registered on this kernel — handled below.
        }
        const registerInMemory = metadata?.registerInMemory;
        if (typeof registerInMemory !== 'function') {
            ctx.logger.debug('[AppPlugin] no in-memory metadata registry — the top-level residual of a multi-package stack is not registered', { appId });
            return;
        }
        const { MetadataPlugin } = await import('@objectstack/metadata');
        await MetadataPlugin.registerUnclaimedTopLevel(
            {
                register: (type, name, item) => registerInMemory.call(metadata, type, name, item),
                warn: (message) => ctx.logger.warn(message),
            },
            this.bundle,
            { door: 'config', label: String(appId) },
        );
    }

    /**
     * [#22989] The config door's registrar of the stack's declared `apis`
     * endpoints: each item goes into the metadata service's in-memory registry
     * by the route and the ADR-0010 stamp the code-defined datasources take in
     * `start()` (`registerInMemory` + `applyProtection`). So the endpoint
     * matcher's one index (`MetadataManager.listForIndex('api')`) holds them on
     * this door as it holds them on the artifact door, whose
     * `ARTIFACT_FIELD_TO_TYPE` maps `apis` to `api`. Before this a config boot
     * registered them into the ObjectQL registry alone (`manifest.register` in
     * `init()`), which the matcher never reads, so every declared path answered
     * the transport's `404 ENDPOINT_NOT_FOUND` while the artifact boot of the
     * same stack matched it.
     *
     * The items are the boot's ONE forward-converted copy
     * ({@link forwardConverted}), the copy `init()` handed the `manifest`
     * service: ⛔ never the raw bundle, ⛔ never a second conversion. Each is
     * copied before it is stamped, because `applyProtection` writes in place and
     * the converted definition shares its items with the ObjectQL registry (and,
     * when nothing converts, with the caller's config module).
     *
     * The owner is the stack's own manifest (`artifactPackageId`, the key
     * `registerApp` installs the package under, and its `version`): the pair
     * the artifact door stamps on the single-package branch (ADR-0130 D7).
     *
     * A bundle carrying `packages[]` is left alone. Its top-level residual,
     * `api` items included, is registered by {@link registerUnclaimedTopLevel};
     * a package BODY's item would need the body walk, which reads bodies no
     * conversion reaches rather than this boot's converted copy.
     *
     * One registrar per boot, declared by the composition, with the guard
     * {@link registerUnclaimedTopLevel} uses: under
     * `securityMetadataRegistrar: 'artifact-door'` the door registers every
     * `api` item (strict-parsed and stamped) and this does nothing, so an
     * artifact boot registers each item exactly once.
     *
     * ⛔ This gives no composition an endpoint matcher. Only a metadata service
     * that carries `matchEndpoint` serves the items, which in-tree is
     * `@objectstack/metadata`'s manager. Where the `metadata` slot holds the
     * kernel's in-memory fallback instead, the items are listed and none is
     * served — so that composition is told, once per boot of this app, at
     * `warn`, with the count and the remedy (maintainer ruling on #22989,
     * option B; AGENTS.md "Absence must be loud"). ⛔ No second matcher: the
     * remedy is the composition's, never a fallback match here. Read in
     * `start()`, after every `init()` has registered its services and the
     * kernel has injected its fallbacks, so the slot's occupant is final.
     */
    private registerDeclaredApiEndpoints(ctx: PluginContext, appId: string): void {
        if (this.securityMetadataRegistrar === 'artifact-door') return;
        if ((this.bundle as { packages?: unknown }).packages !== undefined) return;
        const apis: unknown = this.forwardConverted(ctx).definition?.apis;
        if (!Array.isArray(apis) || apis.length === 0) return;
        let metadata: {
            registerInMemory?: (type: string, name: string, item: unknown) => void;
            matchEndpoint?: unknown;
        } | undefined;
        try {
            metadata = ctx.getService('metadata');
        } catch {
            // Not registered on this kernel — handled below.
        }
        if (typeof metadata?.matchEndpoint !== 'function') {
            ctx.logger.warn(
                `[AppPlugin] app '${appId}' declares ${apis.length} api endpoint(s), but this boot's 'metadata' `
                + 'service has no endpoint matcher (matchEndpoint), so every declared path answers '
                + '404 ENDPOINT_NOT_FOUND. Compose @objectstack/metadata\'s MetadataPlugin on this kernel '
                + 'to serve them.',
                { appId, count: apis.length },
            );
        }
        if (typeof metadata?.registerInMemory !== 'function') {
            ctx.logger.debug('[AppPlugin] no in-memory metadata registry — the stack-declared api endpoints are not registered', { appId });
            return;
        }
        const sys = this.bundle.manifest || this.bundle;
        const owner = {
            packageId: artifactPackageId(sys),
            packageVersion: typeof sys?.version === 'string' ? sys.version : undefined,
        };
        let count = 0;
        for (const api of apis as Array<Record<string, unknown> | null | undefined>) {
            const name = api?.name;
            if (typeof name !== 'string' || name.length === 0) continue;
            metadata.registerInMemory('api', name, applyProtection({ ...api }, owner));
            count += 1;
        }
        if (count > 0) {
            ctx.logger.info('Registered stack-declared api endpoints in metadata registry', { appId, count });
        }
    }

    start = async (ctx: PluginContext) => {
        if (this.empty) {
            ctx.logger.debug('[AppPlugin] empty env — no app payload, skipping start', {
                pluginName: this.name,
            });
            return;
        }
        const sys = this.bundle.manifest || this.bundle;
        const appId = sys.id || sys.name;
        
        // Execute Runtime Step
        // Retrieve ObjectQL engine from services
        // ctx.getService throws when a service is not registered, so we
        // must use try/catch instead of a null-check.
        let ql: IObjectQLEngine | undefined;
        try {
            ql = ctx.getService<IObjectQLEngine>('objectql');
        } catch {
            // Service not registered — handled below
        }

        if (!ql) {
            ctx.logger.warn('ObjectQL engine service not found', { 
                appName: this.name,
                appId 
            });
            return;
        }

        ctx.logger.debug('Retrieved ObjectQL engine service', { appId });

        // [#23649] The stack's `datasourceMapping` is normally already installed:
        // `honourDatasourceMappingBeforeSchemaSync` ran inside
        // `ObjectQLPlugin.start()`, before its schema sync. Installed HERE only on
        // a composition that never announced that moment (no `ObjectQLPlugin`
        // start on this kernel, e.g. a declaration-only boot that suppresses
        // it, or a mock context with no hook bus), where nothing synced or
        // wrote through that engine before this line.
        if (!this.datasourceMappingInstalled) {
            this.installDatasourceMapping(ctx, ql, appId);
        }

        // Surface code-defined datasources (ADR-0015 Addendum) in the metadata
        // registry so the datasource-admin list returns them alongside any
        // UI-created (`origin:'runtime'`) ones. These are GitOps-managed
        // (declared in `*.datasource.ts`), so they are registered IN MEMORY
        // ONLY — never persisted to the runtime DB store — and stamped
        // `origin:'code'` so the admin service enforces them as read-only.
        // The engine already indexed them for the write gate via registerApp().
        //
        // `default` is a HOST-owned reserved name (#3826): the runtime declares
        // and connects it (DefaultDatasourcePlugin). An app declaring it would
        // shadow the host's metadata row and — if it passed the D2 gate —
        // divert every unbound object to a fresh connection. Contract-first:
        // reject at load, loudly (outside the lenient catch below), instead of
        // letting the collision produce undefined routing.
        //
        // [#23029] This check, the registration and `connectDeclared` below
        // all read the boot's converted copy (`convertedCollection`).
        {
            const dsDefs = this.convertedCollection(ctx, 'datasources');
            const declared = Array.isArray(dsDefs)
                ? dsDefs
                : dsDefs && typeof dsDefs === 'object'
                    ? Object.values(dsDefs as Record<string, unknown>)
                    : [];
            const names = Array.isArray(dsDefs)
                ? declared.map((d: any) => d?.name)
                : Object.keys((dsDefs as Record<string, unknown>) ?? {});
            if (declared.some((d: any) => d?.name === 'default') || names.includes('default')) {
                throw new Error(
                    `[AppPlugin] app '${appId}' declares a datasource named 'default' — that name is ` +
                    `reserved for the host's primary datasource. Rename it (e.g. '${appId.split('.').pop()}_primary') ` +
                    `and route objects to it explicitly, or omit it to use the host default.`,
                );
            }
        }
        try {
            const dsDefs = this.convertedCollection(ctx, 'datasources');
            const dsList = Array.isArray(dsDefs)
                ? dsDefs
                : dsDefs && typeof dsDefs === 'object'
                    ? Object.entries(dsDefs).map(([name, def]) => ({ name, ...(def as any) }))
                    : [];
            if (dsList.length > 0) {
                const metadata = ctx.getService('metadata') as
                    | { registerInMemory?: (t: string, n: string, d: unknown) => void }
                    | undefined;
                if (typeof metadata?.registerInMemory === 'function') {
                    // [#21889] Each one stamped with the package that declares
                    // it (ADR-0010 `_packageId` / `_packageVersion`), through the
                    // one stamping helper both other load paths use. See
                    // `codeDefinedDatasourceOwners` for who that package is.
                    for (const { datasource: ds, owner } of this.codeDefinedDatasourceOwners(ctx)) {
                        if (!ds?.name) continue;
                        metadata.registerInMemory(
                            'datasource',
                            ds.name,
                            applyProtection({ ...ds, origin: 'code' }, owner),
                        );
                    }
                    ctx.logger.info('Registered code-defined datasources in metadata registry', {
                        appId,
                        count: dsList.length,
                    });
                }
            }
        } catch (err) {
            ctx.logger.warn('[AppPlugin] failed to register code-defined datasources', {
                error: (err as Error)?.message ?? String(err),
            });
        }

        // [#22989] The stack's declared `apis`, by the same route — see
        // `registerDeclaredApiEndpoints`.
        this.registerDeclaredApiEndpoints(ctx, appId);

        // Auto-connect declared datasources (ADR-0062 D1/D2/D5). The metadata
        // registration above only makes a datasource *visible*; to make its
        // federated objects *queryable* with zero app boilerplate, build + open
        // + register a live driver via the shared `'datasource-connection'`
        // service (when present — wired by the datasource-admin plugin). The
        // service applies the D2 gate (connect only when `external`, an object
        // explicitly binds via `object.datasource`, a `datasourceMapping` rule
        // routes objects to it, or `autoConnect:true`) and the host connect
        // policy, so a managed datasource nothing routes to stays metadata-only.
        // Idempotent vs. a legacy `onEnable` driver registration.
        //
        // Runs in `start()` (before the `kernel:ready` external-validation gate)
        // so the kernel's init-all-then-start-all ordering guarantees the
        // connection service was already registered during init.
        try {
            const dsDefs = this.convertedCollection(ctx, 'datasources');
            const dsList: any[] = Array.isArray(dsDefs)
                ? dsDefs
                : dsDefs && typeof dsDefs === 'object'
                    ? Object.entries(dsDefs).map(([name, def]) => ({ name, ...(def as any) }))
                    : [];
            if (dsList.length > 0) {
                // `ctx.getService` throws when a service is absent, so resolve
                // defensively — a runtime without the datasource-admin plugin
                // simply has no connection service, and declared datasources
                // stay metadata-only (the legacy `onEnable` escape hatch still
                // works). This must NOT fall into the fail-fast catch below.
                let connection:
                    | {
                          connectDeclared?: (input: {
                              datasources: any[];
                              objects?: Array<{ name?: string; datasource?: string }>;
                              mappedObjects?: Record<string, string[]>;
                          }) => Promise<Array<{ name: string; status: string }>>;
                      }
                    | undefined;
                try {
                    connection = ctx.getService('datasource-connection');
                } catch {
                    connection = undefined;
                }
                if (typeof connection?.connectDeclared === 'function') {
                    const declaredObjects = this.convertedCollection(ctx, 'objects');
                    const objects = Array.isArray(declaredObjects) ? declaredObjects : [];
                    const results = await connection.connectDeclared({
                        datasources: dsList,
                        objects,
                        mappedObjects: this.resolveMappedObjects(ql, objects),
                    });
                    const connected = results.filter((r) => r.status === 'connected');
                    if (connected.length > 0) {
                        ctx.logger.info('Auto-connected declared datasources', {
                            appId,
                            connected: connected.map((r) => r.name),
                        });
                    }
                } else {
                    ctx.logger.debug('No datasource-connection service — declared datasources stay metadata-only', { appId });
                }
            }
        } catch (err) {
            // A fail-fast connect error propagates to brick boot as intended
            // (ADR-0062 D5): the datasource has no fallback path — `external` +
            // onMismatch:'fail', or objects that bind to it explicitly and would
            // otherwise fail every query with "Datasource 'x' is not registered"
            // (#3758). Other errors are already degraded inside the connection
            // service. Re-throw so the kernel surfaces the real cause.
            // (Single-string message: the context logger types
            // `error(message, error?)`, not a meta object.)
            ctx.logger.error(
                `[AppPlugin] declared-datasource auto-connect failed for app '${appId}': ${(err as Error)?.message ?? String(err)}`,
            );
            throw err;
        }

        // [ADR-0130 D4] The residual of a multi-package stack — top-level
        // items no package body declares — through the metadata door's one
        // rule. BEFORE the security block below on purpose: that block is the
        // registrar of every stack-declared security item, so on a slot both
        // write, its copy (forward-converted from the same, now-stamped item)
        // is the one that stays.
        await this.registerUnclaimedTopLevel(ctx, appId);

        // [ADR-0057 / #2077] Surface stack-declared SECURITY metadata
        // (positions, permission sets, capabilities, sharing rules) in the
        // metadata registry so the boot seeders (plugin-security /
        // plugin-sharing) and runtime resolvers can read them via
        // `list('position'|'permission'|'capability'|'sharing_rule')`.
        // Without this, a code-defined stack's metadata service holds only
        // objects, leaving the declarations decorative.
        //
        // [#12892 step 2] ONE registrar per boot path. On an ARTIFACT boot
        // (`createStandaloneStack`, which composes `MetadataPlugin` with
        // `artifactSource` over the very artifact this bundle was read from)
        // the artifact door — `MetadataPlugin._parseAndRegisterArtifact`,
        // `ARTIFACT_FIELD_TO_TYPE` in packages/metadata/src/plugin.ts — reads
        // the same bytes, replays the versioned ADR-0087 forward conversion,
        // STRICT-PARSES the definition (schema defaults, ADR-0122 input
        // transforms) and stamps the ADR-0010 provenance envelope, and since
        // #12892 step 1 it reaches all four of these collections. This block
        // used to register a second, unparsed copy of every item on that same
        // boot, and because it ran LAST its copy won: a sharing rule's
        // `condition` was a STRING here and `{ dialect, source }` on the
        // door's copy, a capability carried no `scope` default and no
        // `_packageVersion`, and which shape a consumer read depended on
        // registration order (pinned in
        // app-plugin-artifact-forward-conversion.test.ts). Maintainer ruling
        // (2026-08-29, #12892): the door owns the route; two permanent writers
        // with matched shapes was refused as an end state. So the composition
        // that runs the door declares it — `securityMetadataRegistrar:
        // 'artifact-door'` — and this block leaves the four collections to it.
        // Every composition without a door (`new AppPlugin(config)` over a
        // `defineStack()` module in `os serve` / `os migrate`, `DevPlugin`,
        // `@objectstack/verify`'s `bootStack`, an embedder) keeps registering
        // exactly as before under the default `'app-plugin'`.
        //
        // The discriminator is DECLARED at the composition site rather than
        // inferred here — from a marker on the bundle, or from whether the
        // metadata service already holds the door's items — on purpose: a
        // parsed bundle carries no provenance, and a registry read during
        // `start()` would turn on start ORDER, the very dependence this
        // removes. The default is the registering branch, so a composition
        // that never heard of the option cannot lose a registrar.
        try {
            const metadata = ctx.getService('metadata') as
                | { registerInMemory?: (t: string, n: string, d: unknown) => void }
                | undefined;
            if (typeof metadata?.registerInMemory === 'function') {
                const SECURITY_FIELDS: Array<[string, string]> = [
                    ['positions', 'position'],
                    ['permissions', 'permission'],
                    // [ADR-0066 D1] Package-declared authorization capabilities —
                    // read back by the security catalog read and the anchor
                    // predicates' declared-capability context (ADR-0131 D3).
                    ['capabilities', 'capability'],
                    ['sharingRules', 'sharing_rule'],
                    // `['policies', 'policy']` removed at #12894, together with
                    // its twin in the artifact door's `ARTIFACT_FIELD_TO_TYPE`
                    // (`packages/metadata/src/plugin.ts`). It could never match:
                    // `ObjectStackDefinitionSchema` is a `strictObject` declaring
                    // no top-level `policies` key, so the door refuses such a
                    // definition outright and this loop reads `undefined`. The
                    // word belongs one level down — on a permission set it is an
                    // alias for `rowLevelSecurity` (`PERMISSION_SET_KEY_ALIASES`,
                    // packages/spec/src/security/permission.zod.ts) — so a
                    // top-level collection of that name never existed to register.
                    // `check:stack-collection-maps` now pins this list, so a
                    // fourth attempt at a key the schema does not declare fails
                    // in CI instead of sitting here inert.
                ];
                if (this.securityMetadataRegistrar === 'artifact-door') {
                    // Not surfaced operator-visibly: the door prints its own
                    // `Artifact metadata loaded` summary for these very bytes,
                    // and a second line per boot would add no fact. `debug`
                    // keeps "who registered this collection?" answerable from
                    // the boot log.
                    ctx.logger.debug(
                        '[AppPlugin] artifact boot — stack-declared security metadata is registered by the artifact door (MetadataPlugin), not here',
                        {
                            appId,
                            registrar: this.securityMetadataRegistrar,
                            collections: SECURITY_FIELDS.map(([field]) => field),
                        },
                    );
                } else {
                    const manifestSource: any = this.collections.manifest;
                    // [#12844] Same bytes, same conversion policy — one funnel.
                    //
                    // A `defineStack()` module can declare an `engines.protocol`
                    // floor below the installed spec exactly as a compiled
                    // artifact can, so this reader consumes the door's OWN
                    // policy function rather than a second opinion about it —
                    // the whole definition, exactly as the door converts it, so
                    // no conversion-specific knowledge leaks in here (the
                    // `roles` -> `positions` entry rewrites a COLLECTION KEY,
                    // not an item, and a projection would silently miss it).
                    // Reading the bytes raw here is what made "metadata is
                    // converted at ingestion" only half true: a retired key
                    // whose value a consumer reads would diverge silently at
                    // registration and explode at whatever seam re-validates
                    // (a Studio re-save through `saveMetaItem`, which rejects
                    // with the current schema).
                    //
                    // [#22994] Not converted HERE any more: this is the boot's
                    // one conversion (`forwardConverted`), the copy `init()`
                    // already handed the `manifest` service, so the registry and
                    // this registrar cannot read two conversions of one bundle.
                    const securityBundle: any = this.forwardConverted(ctx).definition;
                    let count = 0;
                    for (const [field, type] of SECURITY_FIELDS) {
                        const arr = securityBundle?.[field];
                        // [#18034] Which SOURCE the value above came from, decided
                        // on the RAW inputs rather than on the flattened copy: the
                        // manifest contributed this key only when the stack's own
                        // collections do not declare it, because `{ ...manifest,
                        // ...collections }` lets the stack win. Computed here and
                        // not from `securityBundle` because the ADR-0087 pass can
                        // rewrite a COLLECTION KEY (`roles` -> `positions`), and a
                        // key the conversion produced came from the stack.
                        const fromManifest = manifestSource !== undefined
                            && manifestSource !== null
                            && manifestSource[field] !== undefined
                            && (this.collections as any)[field] === undefined;
                        let dropped = 0;
                        let members = 0;
                        if (Array.isArray(arr)) {
                            members = arr.length;
                            for (const item of arr) {
                                if (!item?.name) { dropped += 1; continue; }
                                metadata.registerInMemory(type, item.name, item);
                                count += 1;
                            }
                        }
                        // The registrar wants ADR-0090 `PermissionSet[]`; the key
                        // it just read off the MANIFEST means something else, and
                        // skipping it is the right outcome. Saying nothing is not
                        // (AGENTS.md, Route & surface ownership §3 — absence must
                        // be loud). ⛔ The loop is NOT made tolerant of the other
                        // reading: widening the key was rejected by name (#14242
                        // road C, maintainer 2026-09-02).
                        //
                        // Measured against `ManifestSchema`, `permissions` is the
                        // one `SECURITY_FIELDS` key that can arrive this way at
                        // all: `capabilities` is a `retiredKey()` tombstone that
                        // refuses any value at parse, and `positions` /
                        // `sharingRules` are undeclared on a `strictObject`. The
                        // report is written per field anyway, because a bundle
                        // that never reached that parse can still carry them and
                        // this block is the last reader before the value is gone.
                        //
                        // `warn`, not `error`: nothing here claimed to persist
                        // anything — a permission set is simply not registered and
                        // the next person to look for it finds out. Once per boot,
                        // because `start()` runs once per app per kernel.
                        if (fromManifest && (dropped > 0 || !Array.isArray(arr))) {
                            ctx.logger.warn(
                                `[AppPlugin] \`manifest.${field}\` reached the stack-declared \`${type}\` `
                                + `registrar, which cannot read it: ${Array.isArray(arr)
                                    ? `it dropped ${dropped} of ${members} entr${members === 1 ? 'y' : 'ies'}, `
                                      + `because a \`${type}\` is identified by its \`name\` and `
                                      + `${dropped === 1 ? 'that entry carries' : 'those entries carry'} none`
                                    : `the value is ${arr === null ? '`null`' : `${/^[aeiou]/i.test(typeof arr) ? 'an' : 'a'} ${typeof arr}`}, `
                                      + 'not a list, so the whole of it was skipped'}`
                                + `. ${field === 'permissions'
                                    ? 'Nothing is lost if an ADR-0025 §3.2 capability GRANT was meant — '
                                      + '`manifest.permissions` is the manifest-stage grant a package requests '
                                      + '(`{ services, hooks, network, fs }`; a flat list of permission strings is '
                                      + 'its retired legacy form, refused at parse and never read at load), and '
                                      + 'this registrar only reads ADR-0090 permission sets. But if permission '
                                      + 'sets were meant, none is registered, no audience-binding suggestion is '
                                      + 'offered, and the boot goes on looking healthy'
                                    : `\`${field}\` is not a key \`ManifestSchema\` declares, so this value reached `
                                      + 'the runtime without passing an authoring parse'}`
                                + `. Declare the collection at the stack's own top level — `
                                + `\`defineStack({ ${field}: [ … ] })\` — not on the manifest.`,
                                { appId, field, type, dropped, members, registrar: this.securityMetadataRegistrar },
                            );
                        }
                    }
                    if (count > 0) {
                        ctx.logger.info('Registered stack-declared security metadata', { appId, count });
                    }
                }
            }
        } catch (err) {
            ctx.logger.warn('[AppPlugin] failed to register security metadata', {
                error: (err as Error)?.message ?? String(err),
            });
        }

        // Resolve the runtime hook owner. Modules that declare both a
        // `default` (defineStack(...)) export and a named `onEnable` export
        // hide the named export from `bundle.default`, so we fall back to the
        // top-level bundle when the default doesn't carry the hook.
        const stackBundle = this.bundle.default || this.bundle;
        const runtime: any = (stackBundle && typeof stackBundle.onEnable === 'function')
            ? stackBundle
            : this.bundle;

        if (runtime && typeof runtime.onEnable === 'function' && this.skipOnEnable) {
             // [#21054] A declaration boot: the hook exists and is withheld,
             // and the boot says so rather than reading as an app without one.
             this.onEnableWithheldFlag = true;
             ctx.logger.info(
                 'runtime.onEnable NOT executed — this boot composes the app for its declarations only (skipOnEnable)',
                 { appName: this.name, appId },
             );
        } else if (runtime && typeof runtime.onEnable === 'function') {
             ctx.logger.info('Executing runtime.onEnable', {
                 appName: this.name,
                 appId 
             });
             
             // Construct the Host Context (mirroring old ObjectQL.use logic)
             const hostContext = {
                ...ctx,
                ql,
                logger: ctx.logger,
                drivers: {
                    register: (driver: any) => {
                        ctx.logger.debug('Registering driver via app runtime', { 
                            driverName: driver.name,
                            appId 
                        });
                        ql.registerDriver(driver);
                    }
                },
             };
             
             await runtime.onEnable(hostContext);
             ctx.logger.debug('Runtime.onEnable completed', { appId });
        } else {
             ctx.logger.debug('No runtime.onEnable function found', { appId });
        }

        // ── Auto-bind declarative Hook + Action handlers ────────────────
        // Hooks declared via `defineStack({ hooks })` (inline function handlers,
        // string-named `bundle.functions`, or a sandboxed `body`) and actions
        // carrying an extracted `body` are wired into the ObjectQL engine here,
        // with no boilerplate from user code, so `POST /api/v1/actions/<obj>/<name>`,
        // MCP `run_action` and the record pipeline run them.
        //
        // [#21321] Through `bindAppArtifactHandlers` — the ONE binder, which the
        // install-local plugin also calls for an installed package on install
        // and on rehydrate. This block used to BE that loop, which made
        // `AppPlugin.start` the only path that ever bound an artifact's
        // handlers. See `./app-artifact-handlers.ts` for the contract.
        //
        // Runs AFTER `runtime.onEnable` so user code may still imperatively
        // register additional hooks/functions/actions for advanced cases — both
        // coexist on the engine (the binder only replaces what it owns,
        // `app:<appId>`).
        //
        // [#23090] Handed the boot's converted copy (`forwardConverted`), not
        // the raw bundle, so a hook authored with the retired `timeout` binds
        // with its `timeoutMs`. Read raw, the engine's hook wrapper found no
        // `timeoutMs` and the hook ran with no time limit and no notice.
        //
        // The binder's collectors read the copy's top level AND its nested
        // `manifest` (the `manifest.hooks` / `.functions` / `.actions` /
        // `.objects` legs below). The copy is `{ ...manifest, ...collections }`:
        // where the stack declares no such list, the spread lifted the
        // manifest's list to the top level, converted, while the nested
        // `manifest` still carries the raw original, so a renamed hook would
        // bind twice, once bounded and once not. For each list the spread
        // lifted (decided on the RAW collections, as #18034 decides the
        // source), the nested `manifest` the binder reads points at the copy's
        // converted list, which the collectors' reference de-duplication reads
        // once. Where the stack declares its own list, the stack wins the
        // spread and the copy holds no converted manifest list, so that one is
        // read raw, as before: there is no second pass.
        const handlerSource: any = this.forwardConverted(ctx).definition;
        let handlerDefinition: any = handlerSource;
        const nestedManifest: any = handlerSource?.manifest;
        if (nestedManifest !== null && typeof nestedManifest === 'object') {
            for (const key of ['hooks', 'functions', 'actions', 'objects'] as const) {
                if (nestedManifest[key] === undefined || nestedManifest[key] === handlerSource[key]) continue;
                if (Object.prototype.hasOwnProperty.call(this.collections, key)) continue;
                if (handlerDefinition === handlerSource) {
                    handlerDefinition = { ...handlerSource, manifest: { ...nestedManifest } };
                }
                handlerDefinition.manifest[key] = handlerSource[key];
            }
        }
        bindAppArtifactHandlers(ql, handlerDefinition, { appId, logger: ctx.logger, source: 'AppPlugin' });

        // [ADR-0110 D5] The action-governance inventory used to hang off a
        // `kernel:ready` hook HERE. Moved to ObjectQLPlugin: AppPlugin is
        // registered conditionally (serve.ts skips it when the host wraps
        // itself; the `os dev` fast path loads apps without it), so on the
        // platform's own dev loop the inventory never ran — and the engine
        // plugin owns the very registry being audited, is unconditionally
        // present, and re-runs the audit on `metadata:reloaded`.

        // ── Auto-register declarative Background Jobs ────────────────────
        // Jobs declared via `defineStack({ jobs })` are scheduled against the
        // running `IJobService` on `kernel:ready` (so the service plugin and
        // ObjectQL engine have had a chance to register).
        //
        // [#21489] Through `scheduleAppArtifactJobs` — the binder's job half,
        // which the install-local plugin also calls for an installed package on
        // install and on rehydrate. This block used to BE that loop, resolving
        // `fnMap[job.handler]` only: a job's sandboxed `body` was skipped at
        // warn, and ignored when a `handler` stood beside it. The binder runs
        // the body, and the body wins. See `./app-artifact-handlers.ts`.
        //
        // [#23029] Handed the boot's converted copy (`forwardConverted`), the
        // definition the `manifest` service registered, so a job authored with
        // the retired `timeout` is scheduled with its `timeoutMs`. Read raw, the
        // scheduler found no `timeoutMs` and the job ran under the adapter's
        // default with no notice. `collectBundleJobs`' rule is unmoved on that
        // copy: the stack's `jobs` win the spread, and the legacy
        // `manifest.jobs` is read only when the stack declares none. A `handler`
        // job's `ctx.bundle` is that copy too.
        try {
            const jobsDefinition = this.forwardConverted(ctx).definition;
            if (collectBundleJobs(jobsDefinition).length > 0) {
                ctx.hook('kernel:ready', async () => {
                    await scheduleAppArtifactJobs(ctx, jobsDefinition, { appId, ql, source: 'AppPlugin' });
                });
            }
        } catch (err: any) {
            ctx.logger.error('[AppPlugin] Failed to schedule background-job registration', err as Error, { appId });
        }

        // ── Org-Scoped App Catalog Sync ──────────────────────────────────
        // Emit `app:registered` so AppCatalogService (running on the
        // control-plane kernel) can mirror this app into `sys_app`. Skipped
        // for standalone (single-tenant) usages where no project context is
        // attached.
        this.emitCatalogEvent(ctx, 'app:registered', sys);

        // ── i18n Translation Loading ─────────────────────────────────────
        // Auto-load translation bundles from the app config into the
        // kernel's i18n service, so discovery and handlers stay consistent.
        await this.loadTranslations(ctx, appId);

        // Data Seeding
        // Collect seed data from multiple locations (top-level `data` preferred, `manifest.data` for backward compat)
        const seedDatasets: any[] = [];
        
        // 1. Top-level `data` field (new standard location on ObjectStackDefinition)
        if (Array.isArray(this.collections.data)) {
            seedDatasets.push(...this.collections.data);
        }
        
        // 2. Legacy: `manifest.data` (backward compatibility)
        //
        // [#15262] The reference guard is what makes the two-location read
        // safe, and it is the same guard the sibling `translations` collector
        // in `loadTranslations()` has always carried. On a FLAT bundle —
        // manifest fields written directly on the bundle, no `manifest:` key,
        // a shape `AppPlugin` supports by design (see the constructor's
        // `bundle?.manifest || bundle`) — this base resolves to the bundle
        // itself, so without the check step 2 re-reads the very array step 1
        // just contributed and every dataset lands twice. `mergeSeedDatasets`
        // is a plain `push` with no de-duplication, so both copies reach the
        // shared registry, the inline loader and every later per-org replay:
        // for a `mode: 'insert'` dataset that is the row applied twice per
        // boot, not merely doubled work.
        const manifest = this.bundle.manifest || this.bundle;
        if (manifest && Array.isArray(manifest.data) && manifest.data !== this.collections.data) {
            seedDatasets.push(...manifest.data);
        }

        // Object names in seed data are used as-is — no FQN expansion.
        // Under the current naming convention, the object's short name IS
        // the canonical name and the physical table name.

        if (seedDatasets.length > 0) {
             ctx.logger.info(`[AppPlugin] Found ${seedDatasets.length} seed datasets for ${appId}`);

             // Pass seed datasets through unchanged — object names are canonical
             const normalizedDatasets = seedDatasets
                 .filter((d: any) => d.object && Array.isArray(d.records))
                 .map((d: any) => ({
                     ...d,
                     object: d.object,
                 }));

             // No seed identity is provisioned. The platform never mints a
             // placeholder `usr_system`: seeds leave `owner_id` unset (or use
             // `cel`os.user.id``, which the loader resolves to NULL since the
             // owning admin does not exist yet), and the first-admin handoff
             // (`claimSeedOwnership`) re-owns those NULL rows to the promoted
             // admin. `os.org` is still derived from `organizationId` inside the
             // loader, independent of this.
             const seedIdentity = undefined;

             // Stash datasets on a kernel service so SecurityPlugin's
             // sys_organization insert hook can replay them per-tenant
             // (Salesforce-sandbox style: every new org gets its own
             // private copy of the artifact's demo data).
             //
             // We also register a `seed-replayer` callable so the
             // SecurityPlugin doesn't need to import @objectstack/runtime
             // (would create a circular workspace dep). The replayer
             // captures the SeedLoaderService closure and exposes a
             // narrow `(orgId) => Promise<summary>` surface.
             try {
                 // #3453: append this app's datasets onto the SHARED `seed-datasets`
                 // array (register-once-then-mutate). Reading through the context's
                 // own resolver — NOT the non-existent `(ctx as any).kernel`, which was
                 // always undefined — means a SECOND config app (or a marketplace
                 // install) extends the list instead of clobbering it or tripping the
                 // duplicate-register throw. The per-org replayer below re-reads this
                 // live list on every call, so a new org replays the full union.
                 const sharedDatasets = mergeSeedDatasets(ctx, normalizedDatasets);

                 const loggerRef = ctx.logger;
                 // [#16595] Same capture posture as `loggerRef`: the replayer
                 // outlives `start()` and is invoked by SecurityPlugin's
                 // sys_organization hook, so the locale is resolved once, here,
                 // from the boot bundle rather than re-read per replay.
                 const seedLocale = this.resolveSeedLocale();
                 const replayer = async (organizationId: string) => {
                     if (!organizationId) return { inserted: 0, updated: 0, skipped: 0, errors: [] as any[] };
                     const md = ctx.getService('metadata') as IMetadataService | undefined;
                     if (!md) {
                         loggerRef.warn('[seed-replayer] metadata service unavailable');
                         return { inserted: 0, updated: 0, skipped: 0, errors: [] as any[] };
                     }
                     // Read the LIVE shared list on every replay — NOT the
                     // `sharedDatasets` snapshot captured when this closure was built.
                     // An org created after a later app/marketplace install must still
                     // replay their seeds (the #3453 fix). Fall back to the snapshot
                     // only if the service somehow vanished.
                     const datasetsNow = readSeedDatasets(ctx) ?? sharedDatasets;
                     if (!Array.isArray(datasetsNow) || datasetsNow.length === 0) {
                         return { inserted: 0, updated: 0, skipped: 0, errors: [] as any[] };
                     }
                     const seedLoader = new SeedLoaderService(ql, md, loggerRef);
                     const { SeedLoaderRequestSchema } = await import('@objectstack/spec/data');
                     const request = SeedLoaderRequestSchema.parse({
                         seeds: datasetsNow,
                         config: {
                             defaultMode: 'upsert',
                             multiPass: true,
                             organizationId,
                             // `os.org` is derived from organizationId inside
                             // the loader. `seedIdentity` (os.user) is undefined
                             // unless a seed embeds `cel`os.user.id`` — see the
                             // lazy guard where it is resolved.
                             identity: seedIdentity,
                             // [#16595] `Seed.locale`'s producer. Spread rather
                             // than written as `locale: seedLocale` so an app
                             // with no `i18n.defaultLocale` sends NO key at all
                             // — `undefined` and absent parse the same here, but
                             // absence is what the loader's unresolved-scope
                             // warning is keyed on.
                             ...(seedLocale ? { locale: seedLocale } : {}),
                         },
                     });
                     const result = await seedLoader.load(request);
                     // [#23354] The rows this replay landed on, for the
                     // organization's owner-bind claim (`seededRecordIds` with
                     // this organization): it hands over these rows and no
                     // other unowned row of the organization (ADR-0138 D1).
                     recordOrganizationReplay(ctx, organizationId, result.results);
                     return {
                         inserted: result.summary.totalInserted,
                         updated: result.summary.totalUpdated,
                         // `skipped` lets a cloud host distinguish an all-skip
                         // replay (data already present) from the zero-summary
                         // early-returns above (which never ran the loader), so
                         // it can stamp its seed-once record on progress rather
                         // than re-replaying every cold boot (cloud#853).
                         skipped: result.summary.totalSkipped,
                         errors: result.errors,
                     };
                 };
                 // Register the replayer once; a later config app reuses the first
                 // one, which reads the now-extended shared list on every call — so
                 // there is no duplicate-register throw and no lost datasets (#3453).
                 const replayerRegistered = registerSeedReplayerOnce(ctx, replayer);
                 ctx.logger.info(
                     replayerRegistered
                         ? `[Seeder] Registered ${normalizedDatasets.length} datasets + replayer (total seeds: ${sharedDatasets.length})`
                         : `[Seeder] Appended ${normalizedDatasets.length} datasets to shared registry; reused existing replayer (total seeds: ${sharedDatasets.length})`,
                 );
             } catch (e: any) {
                 ctx.logger.warn('[Seeder] Failed to register seed-datasets/seed-replayer service', { error: e?.message });
             }

             // #4795 — declare this source BEFORE choosing what to do with it.
             // Consumers that must not act until the boot's own rows have
             // landed (the ADR-0104 fresh-datastore attestation) read the
             // tally at `kernel:ready`; counting the source only on the
             // branch that seeds would leave exactly the gap they are asking
             // about. Every branch below closes the handle — settle when the
             // write is done, suppress when this boot will not write at all.
             const seedSource = declareSeedSource(ctx);

             // Decide whether to also run the seed inline at AppPlugin
             // start. In multi-tenant mode, the per-org replay (driven
             // by OrgScopingPlugin's sys_organization middleware) is the
             // source of truth — running it here too would create NULL-
             // org rows that pollute reads and need a separate claim
             // step. So we skip it. Single-tenant deployments keep the
             // legacy behaviour: seed immediately at boot so there's
             // always demo data without needing an org insert.
             const multiTenant = this.organizationWallActive(ctx);
             if (this.skipSeedData) {
                 // #3917: this boot exists to READ metadata (os migrate
                 // plan/apply). It must not write to the target database.
                 // The source stays pending for the life of the boot, which
                 // is what keeps ADR-0104 from self-certifying over rows this
                 // boot deliberately never wrote (#4795).
                 seedSource.suppress('skip-seed-data');
                 ctx.logger.info('[Seeder] skipSeedData — inline seed suppressed; no rows written by this boot');
             } else if (multiTenant) {
                 // Same posture, different cause: the rows these datasets
                 // describe are written per org on `sys_organization` insert,
                 // so at boot they do not exist yet and nothing observed now
                 // can prove a claim about them (#4795).
                 seedSource.suppress('multi-tenant-replay');
                 ctx.logger.info('[Seeder] multi-tenant mode — skipping inline seed; per-org replay will run on sys_organization insert');
             } else {
             // Inline seed budget: large bundles (e.g. CRM Starter's 10
             // datasets) can easily exceed the kernel's plugin-start
             // timeout. We MUST NOT let seed work tear the kernel down —
             // a 500 on /auth and /data is far worse than a delayed seed.
             // Race the actual seed work against a soft budget; if we run
             // out of time, log loudly and let the kernel proceed.
             const seedBudgetMs = Number(process.env.OS_INLINE_SEED_BUDGET_MS ?? 8000);
             const seedPromise = (async () => {
              try {
                  const metadata = ctx.getService('metadata') as IMetadataService | undefined;
                  if (metadata) {
                      const seedLoader = new SeedLoaderService(ql, metadata, ctx.logger);
                      const { SeedLoaderRequestSchema } = await import('@objectstack/spec/data');
                      // [#16595] `Seed.locale`'s producer on the DEFAULT boot
                      // path — see {@link resolveSeedLocale}.
                      const seedLocale = this.resolveSeedLocale();
                      const request = SeedLoaderRequestSchema.parse({
                          seeds: normalizedDatasets,
                          config: {
                              defaultMode: 'upsert',
                              multiPass: true,
                              identity: seedIdentity,
                              ...(seedLocale ? { locale: seedLocale } : {}),
                          },
                      });
                      const result = await seedLoader.load(request);
                      // [#23354] Publish the rows this seed landed on BEFORE the
                      // source settles, so the seed-ownership claim that runs on
                      // `app:seeded` reads them: it hands over these rows and no
                      // other unowned row (ADR-0138 D1). A replay on a later
                      // boot reports the rows an earlier boot wrote, too.
                      seedSource.publishLanded(result.results);
                      const { totalInserted, totalUpdated, totalSkipped, totalErrored } = result.summary;
                      // "Wrote the row, lost the link" (#3932): a reference field
                      // dropped from a row that WAS written moves none of the row
                      // counters, so it needs carrying separately or the banner
                      // reads clean over a severed association.
                      const totalRefsDropped = result.summary.totalReferencesDropped ?? 0;
                      // #3415/#3430: stash a per-source outcome on the kernel so
                      // the CLI boot banner can print a Seeds line. The logs below
                      // are `info`, which sits under the default `warn` level, so
                      // they never reach `os dev` output — without this a fixture
                      // can lose most of its rows with no signal at all. (The
                      // serve boot-quiet window used to swallow them on top of
                      // that, at every level; framework#4012 fixed that half, but
                      // the level gate below is what still hides these.) One
                      // labelled entry per config app.
                      recordSeedOutcome(ctx, {
                          source: String(appId),
                          inserted: totalInserted,
                          updated: totalUpdated,
                          skipped: totalSkipped,
                          rejected: totalErrored,
                          droppedRefs: totalRefsDropped,
                      });
                      if (result.success) {
                          ctx.logger.info('[Seeder] Seed loading complete', {
                              inserted: totalInserted,
                              updated: totalUpdated,
                              skipped: totalSkipped,
                              errored: totalErrored,
                          });
                      } else {
                          // LOUD FAILURE: dropped records were previously
                          // invisible (the summary only logged errors.length and
                          // omitted totalErrored). Report the count AND each
                          // actionable reason so broken seeds can't pass silently.
                          // Dropped reference FIELDS are named separately — the
                          // old line said "0 dropped record(s)" over a load that
                          // had severed associations, which is true and useless.
                          const lostLinks = totalRefsDropped > 0
                              ? `, ${totalRefsDropped} dropped reference field(s) on written rows,`
                              : '';
                          ctx.logger.warn(
                              `[Seeder] Seed loading completed with ${totalErrored} dropped record(s)${lostLinks} and ${result.errors.length} error(s) for ${appId}`,
                              {
                                  inserted: totalInserted,
                                  updated: totalUpdated,
                                  skipped: totalSkipped,
                                  errored: totalErrored,
                                  referencesDropped: totalRefsDropped,
                              },
                          );
                          for (const e of result.errors.slice(0, 20)) {
                              ctx.logger.warn(`[Seeder]   ✗ ${e.message}`);
                          }
                          if (result.errors.length > 20) {
                              ctx.logger.warn(`[Seeder]   …and ${result.errors.length - 20} more error(s)`);
                          }
                      }
                  } else {
                      // Fallback: basic insert when metadata service is not available
                      ctx.logger.debug('[Seeder] No metadata service; using basic insert fallback');
                      const landed: SeedLandingReport[number][] = [];
                      for (const dataset of normalizedDatasets) {
                          ctx.logger.info(`[Seeder] Seeding ${dataset.records.length} records for ${dataset.object}`);
                          const landedIds: string[] = [];
                          for (const record of dataset.records) {
                              try {
                                  const row: any = await ql.insert(dataset.object, record, SEED_WRITE_OPTIONS as any);
                                  if (row?.id != null) landedIds.push(String(row.id));
                              } catch (err: any) {
                                  ctx.logger.warn(`[Seeder] Failed to insert ${dataset.object} record:`, { error: err.message });
                              }
                          }
                          landed.push({ object: dataset.object, landedIds });
                      }
                      // [#23354] Still this source's rows: published like the loader's.
                      seedSource.publishLanded(landed);
                      ctx.logger.info('[Seeder] Data seeding complete.');
                  }
              } catch (err: any) {
                  // If SeedLoaderService fails (e.g., metadata not available), fall back to basic insert
                  ctx.logger.warn('[Seeder] SeedLoaderService failed, falling back to basic insert', { error: err.message });
                  const landed: SeedLandingReport[number][] = [];
                  for (const dataset of normalizedDatasets) {
                      const landedIds: string[] = [];
                      for (const record of dataset.records) {
                          try {
                              const row: any = await ql.insert(dataset.object, record, SEED_WRITE_OPTIONS as any);
                              if (row?.id != null) landedIds.push(String(row.id));
                          } catch (insertErr: any) {
                              ctx.logger.warn(`[Seeder] Failed to insert ${dataset.object} record:`, { error: insertErr.message });
                          }
                      }
                      landed.push({ object: dataset.object, landedIds });
                  }
                  // [#23354] Still this source's rows: published like the loader's.
                  seedSource.publishLanded(landed);
                  ctx.logger.info('[Seeder] Data seeding complete (fallback).');
              }
             })();
             let timer: ReturnType<typeof setTimeout> | undefined;
             const budget = new Promise<'budget'>((resolve) => {
                 timer = setTimeout(() => resolve('budget'), seedBudgetMs);
             });
             // Signal seed settle so reconcilers that read seeded rows can
             // re-run past this point. plugin-auth's ADR-0093 D6 membership
             // backfill runs once on `kernel:ready`, but seeded users are raw
             // `engine.insert` into `sys_user` (bypassing better-auth's
             // `user.create.after` reconciler). If this seed overruns the
             // budget below and finishes in the background — AFTER
             // `kernel:ready` — those users would stay member-less until the
             // next restart. Emitting on settle lets the backfill re-run (#2996).
             const emitSeedSettled = (overBudget: boolean) => {
                 // #4795 — settle FIRST, and before the `trigger` guard below.
                 // Two orderings depend on it: a consumer running inside the
                 // `app:seeded` hook must see this source already settled (it
                 // asks "has everything landed?" and would otherwise defer
                 // forever on the very signal telling it to act), and a kernel
                 // context with no `trigger()` must not strand the tally at
                 // pending — the seed still finished, there is simply nobody
                 // to tell.
                 seedSource.settle();
                 const trigger = (ctx as any).trigger;
                 if (typeof trigger !== 'function') return;
                 try {
                     const p = trigger.call(ctx, 'app:seeded', { appId, overBudget });
                     if (p && typeof p.catch === 'function') {
                         p.catch((err: any) => ctx.logger.debug('[Seeder] app:seeded trigger failed', { appId, error: err?.message ?? String(err) }));
                     }
                 } catch (err: any) {
                     ctx.logger.debug('[Seeder] app:seeded trigger failed', { appId, error: err?.message ?? String(err) });
                 }
             };
             const winner = await Promise.race([seedPromise.then(() => 'done' as const), budget]);
             if (timer) clearTimeout(timer);
             if (winner === 'budget') {
                 ctx.logger.warn(
                     `[Seeder] Inline seed exceeded ${seedBudgetMs}ms budget for ${appId}; continuing in background to avoid blocking kernel start.`,
                 );
                 // Don't leave the promise unobserved; emit the settle signal
                 // once the background seed finishes (fires past kernel:ready).
                 seedPromise
                     .catch((err: any) => {
                         ctx.logger.warn('[Seeder] Background seed failed after budget', { appId, error: err?.message ?? String(err) });
                     })
                     .then(() => emitSeedSettled(true));
             } else {
                 emitSeedSettled(false);
             }
             }
        }

        this.registerHotReloadSeeder(ctx, ql);
        this.registerSeedTenancyHandoff(ctx, ql);
    }

    /**
     * [#8686] Adopt untenanted seed rows into the install's organization the
     * moment that organization first exists.
     *
     * ## Why this cannot be done at seed time, and why boot is too late
     *
     * The seed loader already stamps `organization_id` on business seeds — but
     * only when it can resolve an organization to stamp WITH
     * (`resolveSoleOrganizationId`). On a first boot there is none: seeds land
     * during `start()`, and the admin (and their organization) are created later,
     * by a sign-up POST against the running server. So the loader correctly
     * declines, the rows land `organization_id = NULL`, and the SQL driver files
     * their numbers under the `__global__` counter.
     *
     * Then the first API create arrives carrying a real organization, draws from a
     * DIFFERENT counter that is correctly empty, and mints `CASE-00001` — a value
     * the seed already used. The partitioned unique index
     * (`COALESCE(organization_id, '__global__'), <field>`) cannot see the
     * collision because the two rows sit in different partitions. Measured on
     * 17.0.0 GA: four duplicate identifiers, four 201s, no warning.
     *
     * `metadata-protocol`'s `kernel:ready` migration repairs an install that is
     * ALREADY in that state, which covers every existing deployment. It cannot
     * cover a fresh one: at `kernel:ready` the organization still does not exist,
     * so the earliest that migration can act is the NEXT restart — by which time
     * the duplicates of this session have already been minted and, per the ruling,
     * are not the platform's to renumber.
     *
     * Hence this seam. `sys_organization` gaining its first row is exactly the
     * event that makes the answer derivable, and it is the ownership handoff's
     * twin: `claimSeedOwnership` already re-owns seeded rows to the first admin at
     * the analogous moment, and `claim-seed-ownership.ts` names the missing
     * tenancy half in its own header ("the ownership twin of org-scoping's
     * `claimOrphanOrgRows`, which back-fills `organization_id`") — that back-fill
     * ships in the organizations runtime, which a single-tenant install
     * does not have. This is the always-present half of the same handoff.
     *
     * Cheap by construction: the backfill's first act is one indexed probe of
     * `_objectstack_sequences`, and on any install with no untenanted counter it
     * returns `no-split` having written nothing and logged nothing.
     */
    private registerSeedTenancyHandoff(ctx: PluginContext, ql: any): void {
        if (!ql || typeof ql.registerMiddleware !== 'function') return;
        ql.registerMiddleware(async (opCtx: any, next: () => Promise<void>) => {
            await next();
            const isOrgCreate =
                opCtx?.object === 'sys_organization' &&
                (opCtx?.operation === 'create' || opCtx?.operation === 'insert');
            if (!isOrgCreate) return;
            try {
                const { backfillSeedTenancy, resolveSeedTenancySeam } = await import(
                    '@objectstack/metadata-protocol'
                );
                await backfillSeedTenancy(resolveSeedTenancySeam(ql), ctx.logger);
            } catch (e: any) {
                // Best-effort, exactly like the ownership handoff beside it: an
                // organization was just created and that must stand whatever
                // happens here. `warn` and not `error` — nothing was lost, and the
                // `kernel:ready` migration retries the same repair on next boot.
                ctx.logger.warn(
                    '[AppPlugin] seed tenancy handoff failed: the seed rows were not stamped with the new '
                    + 'organization, so seed and API writes stay on separate autonumber counters until the '
                    + 'next boot\'s migration repairs it',
                    {
                    error: e?.message ?? String(e),
                });
            }
        });
    }

    /**
     * [ADR-0093 D4/D5, ADR-0105 D1 / #5262] Is an organization wall actually IN
     * FORCE for this boot? The judge for both seeder decisions below.
     *
     * ⛔ Never `resolveMultiOrgEnabled()`. ADR-0105 D1 demoted that boolean to a
     * back-compat INPUT of `resolveTenancyPosture()`, so it reads `false` on a
     * deployment configured the documented way (`OS_TENANCY_POSTURE=isolated|group`,
     * legacy boolean unset). Both seeder sites then took the single-tenant branch
     * on a fully walled deployment and inline-seeded exactly the NULL-organization
     * rows their own comments exist to avoid — rows that sit behind the wall
     * unreadable and need a separate claim step. Third recurrence of the shape
     * (cloud#1020, #5233).
     *
     * EFFECTIVE, not requested — and this site is the reason the distinction is
     * worth the extra hop. What these decisions actually turn on is "will the
     * per-org replay run instead of me?", and that replay is the enterprise
     * `@objectstack/organizations` middleware on `sys_organization` insert. On a
     * DEGRADED boot (a wall requested, the enterprise runtime absent, operator
     * opted in via `OS_ALLOW_DEGRADED_TENANCY`) that middleware does not exist,
     * so keying on the REQUEST would skip the inline seed in favour of a replay
     * that can never happen — a stack with no seed data at all. The `tenancy`
     * service reports the posture in force (`single` + `degraded` there), which
     * makes the seeded rows land inline, exactly as they should on a deployment
     * with no wall to isolate them behind.
     *
     * AppPlugin starts in kernel Phase 2 and plugin-auth registers `tenancy` in
     * Phase 1, so the service is present on any real boot; the fallback covers
     * lean embeddings that mount AppPlugin without plugin-auth, where the
     * requested posture is the best fact available. Read live per call — never
     * cached — so nothing freezes a verdict a later boot phase can still change.
     */
    private organizationWallActive(ctx: PluginContext): boolean {
        try {
            const tenancy = ctx.getService?.('tenancy') as
                | { posture?: TenancyPosture }
                | undefined;
            if (tenancy?.posture) return postureEnforcesWall(tenancy.posture);
        } catch {
            /* service registry has no `tenancy` — fall through */
        }
        return postureEnforcesWall(resolveTenancyPosture());
    }

    /**
     * The producer half of `Seed.locale` (#16595) — the BCP-47 tag every seed
     * load started by this plugin filters on, read off the app's declared
     * `i18n.defaultLocale`.
     *
     * Same source, same spelling and the same envelope-vs-collection posture as
     * {@link loadTranslations}' `setDefaultLocale` call: `i18n` is an ENVELOPE
     * key, so it is read off `this.bundle` (with the legacy nested-manifest
     * fallback) and NOT through `this.collections`.
     *
     * ⛔ Resolved HERE rather than inside `SeedLoaderService.load()`, which is
     * where the sibling `env` axis resolves ITSELF (`resolveEnvConfig`, off
     * `NODE_ENV`). That asymmetry is forced, not a style choice: `env` has an
     * ambient, process-wide source the loader can read on its own, and a locale
     * has none — the only thing that knows which locale this stack runs in is
     * the app config the loader is never handed. So this axis needs a real
     * producer at the call sites, which is what #16595 is.
     *
     * Returns `undefined` — never a `'en'` default — when the app declares no
     * locale. Absence is the loader's UNRESTRICTED spelling ("seed every
     * dataset"), i.e. today's behaviour; defaulting to `'en'` would silently
     * DROP a `locale: ['zh-CN']` dataset on every stack that never declared an
     * `i18n` block, turning a wiring change into a data change.
     * `SeedLoaderService#warnOnUnresolvedLocaleScope` is what keeps that
     * absence loud rather than silent.
     */
    private resolveSeedLocale(): string | undefined {
        const i18nConfig = this.bundle?.i18n || (this.bundle?.manifest || this.bundle)?.i18n;
        const declared = i18nConfig?.defaultLocale;
        return typeof declared === 'string' && declared.length > 0 ? declared : undefined;
    }

    /**
     * 15.1 third-party eval — dev hot-reload of a NEW object registered its
     * metadata (and, via ObjectQL's `metadata:reloaded` hook, created its
     * table) but its seeds never ran: the seed pipeline in `start()` only
     * reads the boot-time bundle, so `os dev` users had to restart the
     * server to get seed rows. Subscribe to `metadata:reloaded` (fired by
     * MetadataPlugin for both the artifact-file watcher and the HMR POST
     * endpoint; its payload carries the freshly parsed artifact, because
     * seeds have no `name` and never enter the MetadataManager) and load the
     * seeds of objects that did not exist before the reload.
     *
     * Scoped STRICTLY to first-seen objects: an already-loaded (and possibly
     * user-edited) dataset is never re-upserted mid-run — edits to existing
     * seeds still apply on restart, as before. Dev-only (production publish
     * flows own their seeding), single-tenant only (multi-tenant replays
     * per-org on sys_organization insert). Runs AFTER ObjectQL's reload
     * schema sync because kernel hooks fire in registration order and
     * ObjectQLPlugin starts first.
     */
    private registerHotReloadSeeder(ctx: PluginContext, ql: any): void {
        const hook = (ctx as any).hook;
        if (typeof hook !== 'function') return;
        if (process.env.NODE_ENV !== 'development') return;
        // Same judge as the inline seed above, for the same reason — see
        // `organizationWallActive`. Keying this on the demoted boolean installed
        // the hot-reload seeder on posture-only walled dev stacks, where every
        // row it wrote for a newly-registered object landed with a NULL
        // organization (#5262).
        if (this.organizationWallActive(ctx)) return;

        const knownObjects = new Set<string>(
            (Array.isArray(this.collections.objects) ? this.collections.objects : [])
                .map((o: any) => o?.name)
                .filter((n: any): n is string => typeof n === 'string'),
        );

        hook.call(ctx, 'metadata:reloaded', async (payload: any) => {
            try {
                const meta = payload?.metadata;
                const objectsNow: any[] = Array.isArray(meta?.objects) ? meta.objects : [];
                const fresh = objectsNow
                    .map((o: any) => o?.name)
                    .filter((n: any): n is string => typeof n === 'string' && !knownObjects.has(n));
                for (const n of fresh) knownObjects.add(n);
                if (fresh.length === 0) return;

                const seeds = (Array.isArray(meta?.data) ? meta.data : []).filter(
                    (d: any) => d?.object && fresh.includes(d.object) && Array.isArray(d.records),
                );
                if (seeds.length === 0) return;

                const metadata = ctx.getService('metadata') as IMetadataService | undefined;
                if (!metadata) {
                    ctx.logger.warn('[Seeder] hot-reload seed skipped — metadata service unavailable');
                    return;
                }
                const seedLoader = new SeedLoaderService(ql, metadata, ctx.logger);
                const { SeedLoaderRequestSchema } = await import('@objectstack/spec/data');
                // [#16595] `Seed.locale`'s producer on the dev hot-reload
                // path. Resolved from the BOOT bundle, not from `payload`: a
                // reload re-parses the artifact's metadata collections, and
                // `i18n` is an envelope key that does not travel in it.
                const seedLocale = this.resolveSeedLocale();
                const request = SeedLoaderRequestSchema.parse({
                    seeds,
                    config: {
                        defaultMode: 'upsert',
                        multiPass: true,
                        ...(seedLocale ? { locale: seedLocale } : {}),
                    },
                });
                const result = await seedLoader.load(request);
                const { totalInserted, totalUpdated, totalErrored } = result.summary;
                ctx.logger.info(
                    `[Seeder] Hot-reload seeded new object(s) ${fresh.join(', ')}: ` +
                        `${totalInserted} inserted, ${totalUpdated} updated` +
                        (totalErrored ? `, ${totalErrored} errored` : ''),
                );
                for (const e of (result.errors ?? []).slice(0, 10)) {
                    ctx.logger.warn(`[Seeder]   ✗ ${e.message}`);
                }
            } catch (err: any) {
                ctx.logger.warn('[Seeder] hot-reload seed failed', { error: err?.message ?? String(err) });
            }
        });
    }

    /**
     * Teardown — the kernel's ONLY teardown hook.
     *
     * [#10772] This body used to be spelled `stop(ctx)`. `Plugin`
     * (`@objectstack/core`'s `types.ts`) declares `init()`, `start?(ctx)` and
     * `destroy?()` and no `stop()`, and `ObjectKernel.performShutdown()` /
     * `LiteKernel.destroy()` walk the plugins in reverse calling
     * `plugin.destroy()` — so `app:unregistered` was never emitted on a real
     * shutdown and the control plane's `sys_app` row outlived the kernel that
     * registered it. The `start`/`stop` pair read symmetric to a reviewer
     * because `start()` really is on the interface; only one half was called.
     *
     * No-ops without a project context or a captured context, exactly as the
     * alias did.
     */
    destroy = async (): Promise<void> => {
        const ctx = this.initCtx;
        if (!ctx) return;
        const sys = this.bundle.manifest || this.bundle;
        this.emitCatalogEvent(ctx, 'app:unregistered', sys);
    }

    /**
     * Retained alias for {@link destroy}. Kept because it is public API of an
     * exported class: an embedder may have learned to call it directly
     * precisely BECAUSE the kernel never did, and deleting it would break them.
     * Still an arrow property, so a detached `const { stop } = plugin` call
     * keeps working too. The parameter is now optional and ignored —
     * `destroy()` takes no context, so teardown uses the context captured in
     * `init()`.
     */
    stop = async (_ctx?: PluginContext): Promise<void> => {
        await this.destroy();
    }

    /**
     * Emit a kernel hook so the control-plane `AppCatalogService` can
     * upsert / delete the corresponding `sys_app` row. Silently no-ops
     * when no project context is attached (standalone single-tenant mode)
     * or when the kernel has no `trigger` API available.
     */
    private emitCatalogEvent(ctx: PluginContext, event: 'app:registered' | 'app:unregistered', sys: any): void {
        if (!this.projectContext) return;

        const trigger = (ctx as any).trigger;
        if (typeof trigger !== 'function') {
            ctx.logger.debug('[AppPlugin] kernel has no trigger() — skipping catalog hook', { event });
            return;
        }

        const appName = sys.name || sys.id;
        if (!appName) return;

        const payload = {
            environmentId: this.projectContext.environmentId,
            organizationId: this.projectContext.organizationId,
            projectName: this.projectContext.projectName,
            app: {
                name: appName,
                label: sys.label,
                icon: sys.icon,
                branding: sys.branding,
                isDefault: sys.isDefault ?? sys.is_default,
                active: sys.active !== false,
            },
            source: this.projectContext.source ?? (this.projectContext.packageId ? 'package' : 'user'),
            packageId: this.projectContext.packageId,
        };

        try {
            trigger.call(ctx, event, payload);
        } catch (err: any) {
            ctx.logger.warn('[AppPlugin] catalog hook trigger failed', { event, error: err?.message });
        }
    }

    /**
     * Auto-load i18n translation bundles from the app config into the
     * kernel's i18n service. Handles both `translations` (array of
     * TranslationBundle) and `i18n` config (default locale, etc.).
     *
     * Gracefully skips when the i18n service is not registered —
     * this keeps AppPlugin resilient across server/dev/mock environments.
     */
    private async loadTranslations(ctx: PluginContext, appId: string): Promise<void> {
        // ctx.getService throws when a service is not registered, so we
        // must use try/catch to gracefully skip when no i18n plugin is loaded.
        let i18nService: II18nService | undefined;
        try {
            i18nService = ctx.getService('i18n') as II18nService;
        } catch {
            // Service not registered — handled below
        }

        // Collect translation bundles early to determine if we have data.
        //
        // [#23090] Read off the boot's converted copy (`forwardConverted`), so
        // the retired translation keys (a per-app `settings` group, a page
        // component's `submitLabel`, a dashboard widget's `subCaption`) are not
        // served. Read raw, the i18n service served all three, and the
        // `settings` group still filled the gaps in the platform's own copy.
        // WHICH lists are merged is still decided on the RAW inputs, as before:
        //   - the stack's own list, its value taken from the copy
        //     (`convertedCollection`);
        //   - a different `manifest.translations` list. Where the stack
        //     declares no `translations`, the copy's `{ ...manifest,
        //     ...collections }` spread lifted this very list to the top level,
        //     converted, and that is what is read. Where the stack declares its
        //     own, the stack wins the spread and the copy holds no converted
        //     manifest list, so it is read raw, as before: no second pass.
        const bundles: Array<Record<string, unknown>> = [];
        const stackTranslations = this.convertedCollection(ctx, 'translations');
        if (Array.isArray(stackTranslations)) {
            bundles.push(...stackTranslations);
        }
        const manifest = this.bundle.manifest || this.bundle;
        if (manifest && Array.isArray(manifest.translations) && manifest.translations !== this.collections.translations) {
            const lifted = !Object.prototype.hasOwnProperty.call(this.collections, 'translations');
            bundles.push(...(lifted ? this.forwardConverted(ctx).definition.translations : manifest.translations));
        }

        if (!i18nService) {
            if (bundles.length > 0) {
                // Auto-register the in-memory i18n fallback so the bundles
                // we already loaded server-side become discoverable through
                // `getService('i18n')` (used by the REST API to localize
                // view / action / object metadata). Without this step,
                // bundles authored in `defineStack({ translations })` were
                // silently dropped on standalone/dev stacks that didn't
                // explicitly install I18nServicePlugin.
                try {
                    const mod = await import('@objectstack/core');
                    const createMemoryI18n = (mod as any).createMemoryI18n;
                    if (typeof createMemoryI18n === 'function') {
                        const fallback = createMemoryI18n();
                        (ctx as any).registerService('i18n', fallback);
                        i18nService = fallback;
                        ctx.logger.info(
                            `[i18n] Auto-registered in-memory i18n fallback for "${appId}" (${bundles.length} bundle(s) detected). ` +
                            'Install I18nServicePlugin from @objectstack/service-i18n for file-based / production use.'
                        );
                    }
                } catch (err: any) {
                    ctx.logger.warn(
                        `[i18n] App "${appId}" has ${bundles.length} translation bundle(s) but auto-fallback failed: ${err?.message ?? err}.`
                    );
                    return;
                }
                if (!i18nService) {
                    ctx.logger.warn(
                        `[i18n] App "${appId}" has ${bundles.length} translation bundle(s) but no i18n service is registered.`
                    );
                    return;
                }
            } else {
                ctx.logger.debug('[i18n] No i18n service registered; skipping translation loading', { appId });
                return;
            }
        }

        // Apply i18n config (default locale, etc.)
        const i18nConfig = this.bundle.i18n || (this.bundle.manifest || this.bundle)?.i18n;
        if (i18nConfig?.defaultLocale && typeof i18nService.setDefaultLocale === 'function') {
            i18nService.setDefaultLocale(i18nConfig.defaultLocale);
            ctx.logger.debug('[i18n] Set default locale', { appId, locale: i18nConfig.defaultLocale });
        }

        // [#15694] Thread the declared `i18n.fallbackLocale` the same way, for
        // the same reason: it is authorable on the stack artifact and this is
        // the only layer that can see it. A provider CONSTRUCTED with it —
        // `FileI18nAdapter`, which both boot paths build with
        // `fallbackLocale || defaultLocale || 'en'` — has no `setFallbackLocale`
        // (it does have the other two) and is skipped by the probe, keeping the
        // value it was built with. The
        // kernel's in-memory fallback (auto-registered above when no i18n
        // plugin is installed) is constructed with nothing, so without this
        // line the declaration was INERT there: a stack declaring
        // `defaultLocale: 'zh-CN'` with `fallbackLocale: 'en'` answered a
        // missing `zh-CN` key from `en` under `I18nServicePlugin` and from
        // `zh-CN` — i.e. not at all — under the fallback.
        //
        // Same optional-capability probe as `setDefaultLocale` above, and
        // guarded on "declared something" for the same reason: several
        // AppPlugins can share one kernel, and an app that declares no `i18n`
        // block must not clear a fallback another app declared.
        if (i18nConfig?.fallbackLocale && typeof i18nService.setFallbackLocale === 'function') {
            i18nService.setFallbackLocale(i18nConfig.fallbackLocale);
            ctx.logger.debug('[i18n] Set fallback locale', { appId, locale: i18nConfig.fallbackLocale });
        }

        // [#7679] Narrow what `getLocales()` REPORTS to the locales the app
        // declared. This is the only layer that can: `getLocales()` sees the
        // loaded set, and what is loaded is not the app's decision — every
        // platform plugin (platform-objects, service-settings, service-storage,
        // service-messaging, service-realtime, plugin-security, plugin-sharing,
        // plugin-webhooks) pushes its own `en/zh-CN/ja-JP/es-ES` bundle at
        // `kernel:ready`. A showcase declaring `['en','zh-CN']` therefore
        // advertised four locales on `GET /i18n/locales`, two of which
        // translate `sys_*` metadata and nothing the app owns.
        //
        // Threaded exactly like `defaultLocale` immediately above, and applied
        // through the same optional-capability probe: `setSupportedLocales` is
        // optional on `II18nService`, so a provider that has not implemented it
        // keeps today's behaviour rather than breaking.
        //
        // Only the REPORTED set narrows. The bundles stay loaded and stay
        // servable — an unreported locale still returns its `sys_*`
        // translations if asked for by code. Unloading them is a bigger change
        // than this fix and buys nothing.
        //
        // A locale declared with no bundle behind it is still reported
        // (declared-but-unserved) rather than intersected away — see
        // `normalizeSupportedLocales` / `II18nService.setSupportedLocales` for
        // why, and note that an intersection computed HERE would in any case be
        // wrong: the platform bundles have not arrived yet at this point in the
        // lifecycle.
        // Guarded on "declared something" rather than called unconditionally,
        // for the same reason `setDefaultLocale` above is: several AppPlugins
        // can share one kernel (the config apps are AppPlugins too), and an app
        // that declares no `i18n` block must not clear the narrowing another
        // app declared. Absent stays absent — that is the no-narrowing default,
        // not something anyone has to write.
        const declaredLocales = i18nConfig?.supportedLocales;
        if (
            Array.isArray(declaredLocales) && declaredLocales.length > 0
            && typeof i18nService.setSupportedLocales === 'function'
        ) {
            i18nService.setSupportedLocales(declaredLocales);
            ctx.logger.debug('[i18n] Narrowed reported locales to the app\'s declared set', {
                appId, supportedLocales: declaredLocales,
            });
        }

        if (bundles.length === 0) {
            return;
        }

        let loadedLocales = 0;
        for (const bundle of bundles) {
            // Each bundle is a TranslationBundle: Record<locale, TranslationData>
            for (const [locale, data] of Object.entries(bundle)) {
                if (data && typeof data === 'object') {
                    try {
                        i18nService.loadTranslations(locale, data as Record<string, unknown>);
                        loadedLocales++;
                    } catch (err: any) {
                        ctx.logger.warn('[i18n] Failed to load translations', { appId, locale, error: err.message });
                    }
                }
            }
        }

        // Emit diagnostic when the active i18n service is a fallback/stub.
        // [#4058] Reads the standard D12 self-description instead of duck-typing
        // the two ad-hoc markers this branch knew about (`_fallback` / `_dev`).
        // `_fallback` was recognized by nothing else — which is exactly how the
        // kernel fallbacks carrying it ended up reported as fully `available`.
        // Both ad-hoc markers are gone now (#4082 moved their producers onto
        // the descriptor; #4319 retired the last `_dev` reader), so this is the
        // only spelling left to read.
        if (readServiceSelfInfo(i18nService)) {
            ctx.logger.info(
                `[i18n] Loaded ${loadedLocales} locale(s) into in-memory i18n fallback for "${appId}". ` +
                'For production, consider registering I18nServicePlugin from @objectstack/service-i18n.'
            );
        } else {
            ctx.logger.info('[i18n] Loaded translation bundles', { appId, bundles: bundles.length, locales: loadedLocales });
        }
    }
}

// ─── Bundle hook & function collectors ──────────────────────────────
// Hooks declared in `defineStack({ hooks })` end up at `bundle.hooks`;
// some legacy bundles still nest them under `manifest.hooks`. We dedupe
// (by reference) so the same array isn't bound twice when both shapes
// happen to point at the same list.
//
// [ADR-0130 D4 / option B, #15005] Each collector below reads its collection
// through `resolveArtifactCollections` FIRST, so a multi-package artifact that
// carries the collection under `packages[]` instead of flattened at the top
// level is read rather than silently seen as empty. The resolution is shared
// (`./artifact-collections.ts`) rather than open-coded per collector: three
// walks of one `packages[]` that ordered or de-duplicated differently would
// disagree about what the artifact CONTAINS. On any bundle without `packages[]` it
// returns the argument itself, so these three functions are unchanged for every
// single-package artifact and every `defineStack()` config.

/**
 * Collect declarative `Hook` definitions from a bundle — top-level,
 * `manifest.hooks`, and (ADR-0130 D4) every package body's `hooks`.
 */
export function collectBundleHooks(bundle: any): any[] {
    const out: any[] = [];
    const seen = new Set<any>();
    const push = (arr: any) => {
        if (!Array.isArray(arr)) return;
        for (const h of arr) {
            if (h && !seen.has(h)) {
                seen.add(h);
                out.push(h);
            }
        }
    };
    const stack = resolveArtifactCollections(bundle) as any;
    push(stack?.hooks);
    push(stack?.manifest?.hooks);
    return out;
}

/**
 * Collect declarative `Job` definitions from a bundle (#21489) — the resolved
 * top-level `jobs` (ADR-0130 D4: every package body's too), else the legacy
 * `manifest.jobs`. One list or the other, never a merge: the read `AppPlugin`
 * always made, moved here so the binder's job half and the install-local job
 * gate read the jobs the boot reads.
 */
export function collectBundleJobs(bundle: any): any[] {
    const stack = resolveArtifactCollections(bundle) as any;
    if (Array.isArray(stack?.jobs)) return stack.jobs;
    const manifest = bundle?.manifest;
    return Array.isArray(manifest?.jobs) ? manifest.jobs : [];
}

/**
 * Collect declarative actions from the bundle. Walks both root-level
 * `actions[]` and per-object `objects[*].actions[]`, attaching the parent
 * object name where applicable so `engine.registerAction(object, name, ...)`
 * sees the correct routing key.
 *
 * Each returned record is a shallow copy with `object` set when the action
 * originated under an object (and not already present on the action itself).
 *
 * Deliberately type-BLIND, and it must stay that way: this collects every
 * declared action, most of which (`url`, `modal`, `flow`, `api`, `form`)
 * legitimately have no body and bind nothing. The `type: 'script'` gate that
 * decides whether a `body` becomes an executable handler lives at the single
 * bind point — `actionBodyRunnerFactory` (#4352) — because the other binder
 * (`engine.setDefaultActionRunner`, for Studio-authored actions) never walks
 * this collector at all. Re-filtering here would duplicate half the rule and
 * leave the other binder ungated.
 */
export function collectBundleActions(
    bundle: any,
): Array<{ name: string; object?: string; body?: unknown; type?: string; [k: string]: unknown }> {
    const out: any[] = [];
    const seen = new Set<any>();
    const push = (arr: any, parentObject?: string) => {
        if (!Array.isArray(arr)) return;
        for (const a of arr) {
            if (!a || typeof a !== 'object' || typeof a.name !== 'string') continue;
            if (seen.has(a)) continue;
            seen.add(a);
            const inferredObject =
                typeof a.object === 'string' ? a.object
                : typeof a.objectName === 'string' ? a.objectName
                : parentObject;
            out.push(inferredObject ? { ...a, object: inferredObject } : { ...a });
        }
    };
    // Both walks read the RESOLVED stack: an option-B artifact loses the
    // object-embedded actions with the top-level `objects` array that carried
    // them, which is the widening #14512 comment 5523603341 measured (4 -> 0,
    // every declarative action 404-ing at dispatch).
    const stack = resolveArtifactCollections(bundle) as any;
    push(stack?.actions);
    push(stack?.manifest?.actions);
    if (Array.isArray(stack?.objects)) {
        for (const o of stack.objects) push(o?.actions, o?.name);
    }
    if (Array.isArray(stack?.manifest?.objects)) {
        for (const o of stack.manifest.objects) push(o?.actions, o?.name);
    }
    return out;
}

/**
 * Collect a name → {@link NormalizedFlowFunction} map from `bundle.functions`,
 * keeping each entry's DECLARATION (its data `effect`, #4396) attached to the
 * handler. Accepted shapes:
 *
 *   - `{ functions: { foo: fn, bar: fn } }`                        ← preferred map form
 *   - `{ functions: { foo: { handler: fn, effect: 'writes' } } }`  ← declared map entry
 *   - `{ functions: [{ name: 'foo', handler: fn, effect: … }] }`   ← array of records
 *
 * The declaration matters at exactly one consumer — a `script` node reporting
 * what its run did to the data — but it has to survive the collection step to
 * get there, and dropping it here is how the shape would silently become
 * unsupported.
 */
export function collectBundleFunctionEntries(bundle: any): Record<string, NormalizedFlowFunction> {
    const out: Record<string, NormalizedFlowFunction> = {};
    const merge = (src: any) => {
        if (!src) return;
        if (Array.isArray(src)) {
            for (const item of src) {
                if (!item || typeof item.name !== 'string') continue;
                const fn = normalizeFlowFunctionEntry(item);
                if (fn) out[item.name] = fn;
            }
        } else if (typeof src === 'object') {
            for (const [name, entry] of Object.entries(src)) {
                const fn = normalizeFlowFunctionEntry(entry);
                if (fn) out[name] = fn;
            }
        }
    };
    const stack = resolveArtifactCollections(bundle) as any;
    merge(stack?.functions);
    merge(stack?.manifest?.functions);
    return out;
}

/**
 * Collect a name → handler map from `bundle.functions` — {@link
 * collectBundleFunctionEntries} with the declarations dropped, for the callers
 * that only need something callable (string-named hook handlers via
 * `Hook.handler: 'foo'`, job handlers).
 */
export function collectBundleFunctions(bundle: any): Record<string, (ctx: any) => any> {
    const out: Record<string, (ctx: any) => any> = {};
    for (const [name, fn] of Object.entries(collectBundleFunctionEntries(bundle))) {
        out[name] = fn.handler as (ctx: any) => any;
    }
    return out;
}