plugin.ts

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

import { readFile } from 'node:fs/promises';
import { createHash } from 'node:crypto';
import { Plugin, PluginContext } from '@objectstack/core';
// ADR-0130 D4/D5 — the ONE reader of a release artifact's `packages[]`.
// It lives in `@objectstack/core` rather than in the load path that first
// needed it because `@objectstack/objectql` depends on THIS package, so the
// artifact door could not import it from there; hosting it in a package both
// readers already depend on adds no edge to the graph. Reused, never
// re-derived: it is the ordering (D5) AND the entry gate, so a second read of
// `packages[]` here would make the two readers disagree about which artifacts
// are loadable at all.
import { resolveArtifactPackageOrder, artifactPackageId } from '@objectstack/core';
import { NodeMetadataManager } from './node-metadata-manager.js';
import { MemoryLoader } from './loaders/memory-loader.js';
import { DEFAULT_METADATA_TYPE_REGISTRY, judgeCollectionItemOwnerStamp, OWNER_STAMP_JUDGED_COLLECTIONS } from '@objectstack/spec/kernel';
import type { MetadataPluginConfig } from '@objectstack/spec/kernel';
import { applyProtection } from '@objectstack/spec/shared';
import {
    SysMetadataObject,
    SysMetadataHistoryObject,
    SysMetadataCommitObject,
    SysMetadataAuditObject,
    applyArtifactForwardConversions,
    detectUnboundFormViewPredicateRoots,
    BOUND_FORM_VIEW_PREDICATE_ROOTS,
    BOUND_FORM_FIELD_PREDICATE_ROOTS,
    type ArtifactForwardConversionResult,
    type ArtifactForwardConversionVerdict,
} from '@objectstack/metadata-core';

/**
 * Which forward-conversion verdicts mean the versioned window OPENED for an
 * artifact — the one reading both artifact-door notices below take, off the
 * pass's own verdict rather than a second comparison of their own.
 *
 * A total table rather than a guard naming only some verdicts: a verdict added
 * to `ArtifactForwardConversionVerdict` is a compile error here until someone
 * decides which side of the window it is on. The guard this replaced named the
 * open verdicts by hand, and when the per-entry half of the window
 * (`'converted-retired-after'`) arrived it silently fell on the closed side, so
 * the #12915 notice depended on the package label again.
 */
const FORWARD_WINDOW_OPENED: Readonly<Record<ArtifactForwardConversionVerdict, boolean>> = {
    'converted-forward': true,
    'converted-undeclared': true,
    'converted-retired-after': true,
    'converted-major-step': true,
    'authored-current': false,
    'runtime-version-unknown': false,
    'not-an-object': false,
};

/**
 * The clause both artifact-door notices open with: why this artifact's window
 * opened. Under the per-entry half the floor is NOT below the runtime's
 * label — `main` enforces retirements its label has not moved past — so
 * "predates this runtime's spec", printed beside a runtime version equal to
 * the floor, would read as a contradiction; that verdict says what actually
 * opened it instead. So does the major-step half, whose floor sits ABOVE a
 * prerelease runtime's label: it names the floor as the first release of its
 * protocol major, which a build from that major's prerelease declares too.
 */
function artifactWindowClause(result: ArtifactForwardConversionResult<unknown>): string {
    const floor = result.authoredFloor ?? '<undeclared>';
    if (result.verdict === 'converted-major-step') {
        const major = floor.split('.')[0];
        return `declares the first release of protocol ${major} (authored engines.protocol floor ${floor}), `
            + `which a build from any ${major}.0.0 prerelease declares too, so it may predate retirements in the `
            + `conversion step into protocol ${major} that this runtime enforces (runtime spec ${result.runtimeSpecVersion})`;
    }
    if (result.verdict === 'converted-retired-after') {
        return `was built on a surface that still accepted shapes this runtime has since retired `
            + `(authored engines.protocol floor ${floor}, at or below the last release that accepted them; `
            + `runtime spec ${result.runtimeSpecVersion}, whose label has not moved past that release)`;
    }
    return `predates this runtime's spec (authored engines.protocol floor ${floor}, runtime spec `
        + `${result.runtimeSpecVersion})`;
}

// `SysMetadataObject` + `SysMetadataHistoryObject` are the customer overlay
// storage substrate (ADR-0005). They must always be auto-provisioned so
// `PUT /api/v1/meta/{view,dashboard}/...` has a place to write. All other
// metadata types (object/view/flow/agent/tool/dashboard/app/...) live as
// JSON inside `sys_metadata` — there are no separate per-type tables. The
// previously shipped `SysObject` / `SysView` / `SysFlow` / `SysAgent` /
// `SysTool` projection objects were removed in 2026-05 (see ADR 0005
// addendum); the projection pipeline was removed at the same time.
//
// `SysMetadataAuditObject` (ADR-0010) is the append-only audit trail for
// metadata write decisions — provisioned alongside the storage tables so
// `_lock` enforcement always has a place to record decisions, even when
// the deployment skipped @objectstack/plugin-audit.
//
// `SysMetadataCommitObject` (ADR-0067) is the package-scoped commit log that
// GROUPS a turn's `sys_metadata_history` events (the unit `revertCommit`
// operates on). It MUST be provisioned alongside its history sibling: every
// publish/apply writes a commit row, so a per-project (cloud) env kernel that
// omitted it hit `no such table: sys_metadata_commit` on the first AI build —
// the write is best-effort so the build still landed, but the error spammed
// logs and the commit timeline silently recorded nothing. Registered here
// (not only in the ObjectQLPlugin `environmentId === undefined` standalone
// path) so env kernels — the only place this table is written — get it.
const queryableMetadataObjects = [
    SysMetadataObject,
    SysMetadataHistoryObject,
    // ADR-0067 commit log — sibling of sys_metadata_history (see note above).
    SysMetadataCommitObject,
    SysMetadataAuditObject,
    // ⛔ No `sys_view_definition`: it retired as inert under ADR-0131 D13 — no
    // framework writer or reader of its rows ever existed, and runtime-authored
    // views are `view` items written through `PUT /api/v1/meta/view/...` into
    // `sys_metadata` like every other overlay.
];

// Subdirectory under `rootDir` reserved for the ADR-0008 repository's
// canonical JSON storage + JSONL change log. Kept separate from user
// source code (which the legacy FilesystemLoader still scans).
const REPO_SUBDIR = '.objectstack/metadata';

// Map from ObjectStackDefinition field name to MetadataType name.
//
// PINNED against the schema: `scripts/check-stack-collection-maps.mjs` reconciles
// this map with `ObjectStackDefinitionSchema` in both directions, and every
// deviation carries a reason there (#6242). It is one of seven hand-maintained
// enumerations of the same set, and the reason this one has a gate is its own
// history — `docs` and `roles → positions` were each fixed here one line at a
// time, after a missing key silently dropped a whole collection.
const ARTIFACT_FIELD_TO_TYPE: Record<string, string> = {
    objects: 'object',
    objectExtensions: 'object_extension',
    apps: 'app',
    views: 'view',
    pages: 'page',
    dashboards: 'dashboard',
    reports: 'report',
    // [ADR-0021, ADR-0130 D4] The analytics datasets a dashboard or report names.
    // Mapped so the residual rule walks them too: without this entry a
    // `packages[]` stack's top-level dataset that no body declared was neither
    // registered nor refused, and the dashboard naming it failed at run time.
    // Not the seed `data:` collection, which stays unmapped (see the end of
    // this map).
    datasets: 'dataset',
    actions: 'action',
    // `themes: 'theme'` removed by commit 35ad101bc (ADR-0049): the carrier key is
    // retired, so a parsed artifact can no longer carry the field — and the
    // ingest half of the dead pipeline (items stored, read by nothing) goes
    // with the authoring half rather than surviving it as drift.
    workflows: 'workflow',
    flows: 'flow',
    // ADR-0090 D3: stacks declare `positions` (stack.zod.ts); the retired
    // `roles: 'role'` mapping matched nothing and silently dropped compiled
    // positions from artifact ingestion.
    positions: 'position',
    permissions: 'permission',
    // [ADR-0066 D1] `capabilities` reaches the door at #12892 step 1, the
    // maintainer's `option 1` ruling ("the door owns the registration
    // route" for the five artifact security collections). Until #12894
    // measured it, `AppPlugin`'s `SECURITY_FIELDS` block
    // (packages/runtime/src/app-plugin.ts) was this collection's SOLE
    // registrar on an artifact boot — the one security collection the door
    // could not reach — so a declared capability was registered from bytes
    // nothing strict-parses, with no schema default and no ADR-0010
    // provenance. Measured on the two-reader harness, the door's copy adds
    // exactly four keys the raw copy lacks: `scope` (the schema default)
    // and `_packageId` / `_packageVersion` / `_provenance`.
    //
    // ⚠️ This entry makes the door a SECOND writer, not yet the only one:
    // `AppPlugin` still registers `capabilities`, and it runs last, so the
    // raw copy still wins a real artifact boot. Step 2 of the ruling (that
    // block stops registering these five on the artifact path, after a
    // census of the non-artifact boot paths) is what makes this the only
    // copy. Until then the divergence is the interim reality the ruling
    // explicitly permits, and #12878's pins are what keep it visible.
    capabilities: 'capability',
    sharingRules: 'sharing_rule',
    // [ADR-0142 D1/D5] Declared ownership queues and assignment rules, beside the
    // sharing rules that can name a queue as their recipient.
    queues: 'queue',
    assignmentRules: 'assignment_rule',
    // `policies: 'policy'` removed at #12894: the stack schema is a
    // `strictObject` that declares no top-level `policies` key, so a
    // definition carrying one is refused by the strict parse a few lines
    // below — the entry could never match, and nothing was ever registered
    // under `policy` from this map. The word is real, but it lives ONE LEVEL
    // DOWN: on a permission set it is an alias for `rowLevelSecurity`
    // (`PERMISSION_SET_KEY_ALIASES`, packages/spec/src/security/permission.zod.ts)
    // — a key on an ITEM, never a collection. Third retirement of this exact
    // shape in this map (`themes` and `roles` above); the reasons are kept
    // in place because the first two are what made this one findable.
    apis: 'api',
    webhooks: 'webhook',
    agents: 'agent',
    tools: 'tool',
    skills: 'skill',
    ragPipelines: 'rag_pipeline',
    hooks: 'hook',
    mappings: 'mapping',
    // Shared option lists. Registered as items here so the artifact boot
    // serves `GET /meta/picklist` like every other kind; what a FIELD is
    // served with is resolved by the ObjectQL registry, which also merges
    // `picklistExtensions` into the list they name — that collection is not a
    // kind of its own and has no entry here (see check:stack-collection-maps).
    picklists: 'picklist',
    analyticsCubes: 'analytics_cube',
    connectors: 'connector',
    emailTemplates: 'email_template',
    docs: 'doc',
    books: 'book',
    // `data:` (the SEED collection) is deliberately absent — #6242 row 4(a).
    // It used to map to `'dataset'`, the ADR-0021 analytics kind: the exact name
    // collision `metadata-plugin.zod.ts` warns about in prose. The entry never
    // registered anything (SeedSchema declares no `name`, and the loop below
    // skips nameless items) — a dead pointer aimed at the wrong kind, which
    // would have begun mis-registering the day either side moved. Removed rather
    // than repointed at `'seed'`: seeds are APPLIED by SeedLoaderService off the
    // bundle, never registered as metadata items, so a `seed` mapping would be
    // new behaviour rather than a corrected name.
};

// ───────────────────────────────────────────────────────────────────────────
// View container expansion — "Object has-many View" (ADR-0017)
// ───────────────────────────────────────────────────────────────────────────
//
// `defineView({ list, form, listViews, formViews })` aggregates every view of
// an object into one document. The loader expands such a container into N
// independent ViewItems (one per named view) registered under
// `<object>.<viewKey>`, so each view is individually addressable and the
// runtime switcher can be rebuilt by querying `object`. The original container
// is ALSO kept under the bare `<object>` key for backward-compatible reads.
//
// The implementation lives in `@objectstack/spec` (`isAggregatedViewContainer`
// / `expandViewContainer`) so this HMR loader and the ObjectQL engine boot loop
// share ONE canonical expansion and can never drift. Re-exported here for the
// callers below and for `view-expand.test.ts`.
export { isAggregatedViewContainer, expandViewContainer } from '@objectstack/spec';
import { isAggregatedViewContainer, expandViewContainer } from '@objectstack/spec';
// [#13912] WHICH object a container binds to is a separate question from HOW it
// expands, and it is the one that had drifted here: this file walked two levels
// (`list.data.object` then `form.data.object`) and never read the container's
// own top-level `object` — the field `ViewSchema.object` documents as the
// authorial signal "read by getViewsByObject() / GET /meta/view?object=". The
// one spelling of that derivation for this package already exists:
// `view-container-expansion.ts`'s `deriveViewContainerObject`, whose header
// declares it to be the single place the drift is repaired rather than a third
// private copy to fall behind. Both sites below call it instead of restating a
// chain of their own; it carries the same order #13407 settled at the runtime
// door (`expandRuntimeViewContainer` in `packages/metadata-protocol`).
import { deriveViewContainerObject } from './view-container-expansion.js';
// [#21412] The divergent container `name` refusal — the one judge the boot
// loop, `os validate` and the runtime save door call too. See the container
// branch of `registerArtifactBodyCollections`.
import { viewContainerNameRefusal } from './view-container-name.js';
import type { IHttpServer } from '@objectstack/spec/contracts';

// ───────────────────────────────────────────────────────────────────────────
// The residual rule — ONE rule, for both boot doors (ADR-0130 D4)
// ───────────────────────────────────────────────────────────────────────────
//
// A stack that carries `packages[]` registers each package BODY under that
// package's id. What its TOP LEVEL carries that no body declares is the
// residual: it is registered under the stack's own `manifest.id`, and the boot
// says so. Two doors reach a stack:
//
//   - the ARTIFACT door — `MetadataPlugin`'s load of a compiled
//     `objectstack.json` (`_parseAndRegisterArtifact` below);
//   - the CONFIG door — `os serve objectstack.config.ts`, whose `AppPlugin`
//     hands the stack to the `manifest` service, which registers the package
//     bodies (`resolveArtifactPackageOrder` answers `packages[]` alone when
//     the key is present) and, of the top level, only the residual's objects
//     (the engine half, below). Before this rule had a
//     second caller, a config boot served such an item through no door and
//     said nothing, while an artifact boot of the same project served it
//     under `manifest.id` and warned.
//
// Both call {@link MetadataPlugin.registerUnclaimedTopLevel}, so which items
// are residual, which id they take, how each is registered and what the boot
// says are decided here and nowhere else. ⛔ Never a second copy at a door.
//
// The ENGINE half reads the same answer. Both doors hand the whole stack to
// the `manifest` service (`@objectstack/objectql`), which registers the bodies
// and then, from {@link unclaimedTopLevel}, the residual's OBJECTS under the
// same id, so the data door serves the objects this rule lists. An object it
// cannot register without refusing the boot (a name another package already
// owns, a field naming a picklist no body declares) stays listed here and
// unserved there, and the engine names it at boot.
//
// The residual's PICKLISTS are the one exception to "registered under the
// stack's id": this rule lists them, and the engine never registers them, so
// a residual picklist is metadata only. When a residual object's field names
// it, that object is listed and not served, as above; when a body's field
// names it, the boot's picklist audit refuses that field (`os validate` /
// `os build` report it as `picklist-reference-unknown`). When no object field
// the engine registers names it, the engine refuses the stack
// before anything of it registers (`INVALID_METADATA`), and `os validate` /
// `os build` refuse the same stack first.

/**
 * Where one door's registrations land. The artifact door writes its in-memory
 * loader and the `MetadataManager`; the config door writes the metadata
 * service's in-memory registry (`AppPlugin`), the route it already uses for
 * the code-owned items it surfaces. ⛔ The sink only STORES: what is
 * registered, under which key and with which owner stamp is
 * {@link registerArtifactBodyCollections}'s decision, made once for both.
 */
export interface ArtifactRegistrationSink {
    /** Store one item under `(type, name)`. It arrives already stamped with its owner. */
    register(type: string, name: string, item: unknown): Promise<void> | void;
    /** Say one line at `warn`. */
    warn(message: string): void;
}

/** Which door a stack arrived through — chooses the words, never the rule. */
export interface UnclaimedTopLevelSource {
    door: 'artifact' | 'config';
    /** The artifact's path or URL; the config's manifest id. */
    label: string;
}

/**
 * The `(type, name)` slot one item occupies in the registry, derived the one
 * way both the registration and the claim walk derive it.
 *
 * A `defineView` container has no own `name`: it is filed under the object it
 * binds to (`deriveViewContainerObject`, #13912) and expands into one view
 * item per named view. Most other items carry a top-level `name`; a view
 * written without one falls back to the same object derivation. An item with
 * no derivable slot is not registered, and so claims nothing.
 */
function artifactItemSlot(
    metaType: string,
    item: unknown,
): { container: true; object: string } | { container: false; name: string } | undefined {
    if (metaType === 'view' && isAggregatedViewContainer(item)) {
        const object = deriveViewContainerObject(item);
        return object ? { container: true, object } : undefined;
    }
    let name = (item as any)?.name;
    if (!name && metaType === 'view') name = deriveViewContainerObject(item);
    return name ? { container: false, name } : undefined;
}

/**
 * Every `(type, name)` slot the package bodies register: a container's own
 * slot and each view it expands into, every named item's slot. Read only to
 * tell "the top level repeats what a package already owns" (the normal case —
 * `composeStacks(…, { manifest: 'preserve' })` is ADDITIVE, so the flattened
 * top level repeats every body) from "the top level carries something no
 * package declares".
 */
function claimedArtifactSlots(bodies: readonly unknown[]): (type: string, name: string) => boolean {
    const owned = new Map<string, Set<string>>();
    const claim = (type: string, name: string): void => {
        let names = owned.get(type);
        if (!names) owned.set(type, names = new Set<string>());
        names.add(name);
    };
    for (const body of bodies) {
        for (const [field, metaType] of Object.entries(ARTIFACT_FIELD_TO_TYPE)) {
            const items = (body as any)?.[field];
            if (!Array.isArray(items)) continue;
            for (const item of items) {
                const slot = artifactItemSlot(metaType, item);
                if (!slot) continue;
                if (!slot.container) {
                    claim(metaType, slot.name);
                    continue;
                }
                claim('view', slot.object);
                for (const vi of expandViewContainer(slot.object, item)) claim('view', vi.name);
            }
        }
    }
    return (type, name) => owned.get(type)?.has(name) === true;
}

/** One top-level item of a multi-package stack that none of its package bodies declares. */
export interface UnclaimedTopLevelItem {
    /** The stack collection the item sits in, e.g. `views`. */
    field: string;
    /** Its position in that collection, e.g. `0` for `views[0]`. */
    index: number;
    /** The metadata type it registers as, e.g. `view`. */
    type: string;
    /** The item itself, as the stack carries it. */
    item: unknown;
}

/** A multi-package stack's residual, and the identity it is registered under. */
export interface UnclaimedTopLevel {
    /** The stack's own manifest id — the owner of every unclaimed item. */
    ownerId: string | undefined;
    /** The stack's own manifest version, stamped beside that id. */
    ownerVersion: string | undefined;
    /** How many package bodies the stack carries. */
    bodyCount: number;
    /** The unclaimed items, in the order a door registers them. */
    items: UnclaimedTopLevelItem[];
}

/**
 * WHICH top-level items of a stack that carries `packages[]` no package body
 * declares, and under which id they are registered — the decision half of the
 * residual rule, with nothing registered and nothing thrown.
 *
 * {@link MetadataPlugin.registerUnclaimedTopLevel} registers exactly these, in
 * this order, through either boot door, and the engine's `manifest` service
 * registers the objects among them under the same id. `os validate` / `os build`
 * (`@objectstack/cli`'s view-container walk) read the same answer to judge what
 * that registration will judge, so an author-time door and a boot door cannot
 * disagree about which items are residual. ⛔ Never re-derived by a caller.
 *
 * An item is unclaimed when it occupies a registry slot (`artifactItemSlot`)
 * that no package body occupies (`claimedArtifactSlots`): a container is
 * compared on its own slot, every other item on its name. An item with no
 * derivable slot is registered by no door, so it is not listed.
 *
 * @returns `undefined` for a stack without `packages[]`: its top level IS its
 *   one package's body, so it has no residual.
 */
export function unclaimedTopLevel(stack: unknown): UnclaimedTopLevel | undefined {
    if (!Array.isArray((stack as any)?.packages)) return undefined;
    const bodies = resolveArtifactPackageOrder(stack);
    const claimed = claimedArtifactSlots(bodies);
    const items: UnclaimedTopLevelItem[] = [];
    for (const [field, metaType] of Object.entries(ARTIFACT_FIELD_TO_TYPE)) {
        const collection = (stack as any)[field];
        if (!Array.isArray(collection)) continue;
        collection.forEach((item: unknown, index: number) => {
            const slot = artifactItemSlot(metaType, item);
            if (!slot) return;
            if (claimed(metaType, slot.container ? slot.object : slot.name)) return;
            items.push({ field, index, type: metaType, item });
        });
    }
    return {
        ownerId: (stack as any)?.manifest?.id ?? (stack as any)?.id ?? undefined,
        ownerVersion: (stack as any)?.manifest?.version ?? (stack as any)?.version ?? undefined,
        bodyCount: bodies.length,
        items,
    };
}

/**
 * Register ONE body's collections through `sink`.
 *
 * A "body" is the whole artifact (the single-package branch, where the
 * artifact and its one package are the same object), one entry of
 * `packages[]` (ADR-0130 D4) — an assembled `{ ...manifest, ...collections }`
 * payload carrying the same collection keys the top level does — or a
 * multi-package stack's residual ({@link unclaimedTopLevel}). The loop is
 * identical for all three: there is one ingestion of a collection, not one per
 * shape or per door.
 *
 * @param provenance - The `(packageId, packageVersion)` every item found in
 *   this body is stamped with (ADR-0010 §3.7, via `applyProtection`). It is
 *   the body's OWN identity, never the enclosing artifact's, which is what
 *   makes a multi-package artifact's items agree with the registry and with
 *   `GET /api/v1/packages` about who owns them.
 * @param sourceLabel - The words naming the source in a divergent container
 *   `name` refusal: `artifact` for a compiled artifact; `manifest` for a
 *   config's residual, the word the config boot's own registrar uses for the
 *   same stack. Two items of one name inside one body still register as they
 *   always have (last wins): suppressing that would be a behaviour change on
 *   the single-package branch D7 pins.
 * @returns How many items this body registered.
 */
/**
 * [#28697] The owner-stamp refusal at this door: an item of a judged
 * collection ({@link OWNER_STAMP_JUDGED_COLLECTIONS}) whose body already wears
 * a `_packageId` other than the body's own package, judged by the one judge
 * (`judgeCollectionItemOwnerStamp`, `@objectstack/spec/kernel`) in the
 * registration door's words and envelope (`VALIDATION_ERROR` / 400, `issues[]`
 * at `_packageId`, the envelope the engine's body seam throws).
 *
 * Why here: `applyProtection` below stamps an unset key only, so a body's own
 * stamp used to be what this door stored, and the engine's boot sync
 * (`ObjectQLPlugin.loadMetadataFromService`) files every `app` / `view` /
 * `flow` / `hook` it reads back under that stamp. A stack the schema parsed
 * was judged at the build door first; a body no parse judged (a config boot's
 * residual from a `strict: false` stack) was not, so this door judges every
 * body it registers. The collections are the build door's, so neither door
 * refuses what the other accepts.
 */
function artifactItemOwnerStampRefusal(
    field: string,
    metaType: string,
    name: string,
    item: unknown,
    packageId: string | undefined,
): (Error & { code: 'VALIDATION_ERROR'; status: 400; httpStatus: 400; issues: Array<{ path: string; message: string; code: string }> }) | undefined {
    if (!(OWNER_STAMP_JUDGED_COLLECTIONS as readonly string[]).includes(field)) return undefined;
    const refusal = judgeCollectionItemOwnerStamp(item, metaType, name, packageId, 'register');
    if (!refusal) return undefined;
    const err = new Error(refusal.message) as Error & {
        code: 'VALIDATION_ERROR'; status: 400; httpStatus: 400; issues: Array<{ path: string; message: string; code: string }>;
    };
    err.code = 'VALIDATION_ERROR';
    err.status = 400;
    err.httpStatus = 400;
    err.issues = [{ path: '_packageId', message: refusal.issueMessage, code: 'custom' }];
    return err;
}

async function registerArtifactBodyCollections(
    sink: ArtifactRegistrationSink,
    body: Record<string, unknown>,
    provenance: { packageId?: string; packageVersion?: string },
    sourceLabel: string,
): Promise<number> {
    const { packageId, packageVersion } = provenance;
    let totalRegistered = 0;
    for (const [field, metaType] of Object.entries(ARTIFACT_FIELD_TO_TYPE)) {
        const items = (body as any)[field];
        if (!Array.isArray(items) || items.length === 0) continue;
        for (const item of items) {
            const slot = artifactItemSlot(metaType, item);
            if (!slot) continue;
            // Expand aggregated view containers into independent ViewItems
            // ("Object has-many View"), while still registering the
            // container under the bare <object> key for backward-compatible
            // reads. Already-independent ViewItems carry a top-level `name`
            // and take the normal path below.
            if (slot.container) {
                // [#13912] `object` FIRST — a package-shipped
                // `defineView({ object: 'crm_lead', list: { columns } })`
                // sets the binding there and nowhere else, and the old
                // two-deep chain skipped that container entirely, so it never
                // reached the registry at all and `getViewsByObject()` had
                // nothing to expand.
                const viewObject = slot.object;
                // [#21412] A container whose own `name` disagrees with the
                // key derived above is refused through the one judge every
                // door that files a container calls, in its words — and
                // BEFORE the sink stores anything, so a refusal files nothing.
                // `manager.register` would refuse the same document too
                // (#7378 row 1, `assertMetadataRegisterContract`), but in the
                // generic register contract's words and only after the loader
                // write; row 1 is unchanged for every type.
                const nameRefusal = viewContainerNameRefusal(item, sourceLabel, packageId);
                if (nameRefusal) throw nameRefusal;
                const ownerStamp = artifactItemOwnerStampRefusal(field, metaType, viewObject, item, packageId);
                if (ownerStamp) throw ownerStamp;
                applyProtection(item as any, {
                    packageId: packageId,
                    packageVersion: packageVersion,
                });
                await sink.register('view', viewObject, item);
                totalRegistered++;
                for (const vi of expandViewContainer(viewObject, item)) {
                    for (const w of vi._diagnostics?.warnings ?? []) {
                        sink.warn(`[MetadataPlugin] View expansion warning for '${vi.name}': ${w.message}`);
                    }
                    applyProtection(vi as any, {
                        packageId: packageId,
                        packageVersion: packageVersion,
                    });
                    await sink.register('view', vi.name, vi);
                    totalRegistered++;
                }
                continue;
            }
            // Most metadata items carry a top-level `name`. The `View`
            // container (UI namespace) is an exception: it has no own
            // `name` — its identity is the target object, declared in the
            // container's own top-level `object` field and, for containers
            // written before that field was read here, under
            // `list.data.object` (or `form.data.object`). Mirror the
            // resolution used by `ObjectQL.SchemaRegistry` so that
            // artifact-loaded views land in `MetadataManager` under the
            // SAME key reads expect (`metadataService.get('view', <object>)`).
            // Without this, HMR pushes views into the registry only via
            // AppPlugin's `manifest.register`, which targets the
            // boot-only SchemaRegistry cache and is never refreshed on
            // file edits — leaving MetadataService empty for view/* and
            // forcing all reads to return the stale boot copy.
            //
            // [#13912] `deriveViewContainerObject` is that resolution, in
            // the package's one spelling (`artifactItemSlot` reads it). Its
            // last fallback — the row's own `name` — cannot fire on that
            // branch (it is reached only when `item.name` is falsy), so what
            // it adds there is exactly the leading `object` term this path
            // was missing.
            const name = slot.name;
            const ownerStamp = artifactItemOwnerStampRefusal(field, metaType, name, item, packageId);
            if (ownerStamp) throw ownerStamp;
            // ADR-0010 §3.7 — translate the author-facing
            // `protection` block into the private `_lock` envelope
            // and stamp package provenance in one call. Strips the
            // public block so it never lands in sys_metadata.
            applyProtection(item as any, {
                packageId: packageId,
                packageVersion: packageVersion,
            });
            await sink.register(metaType, name, item);
            totalRegistered++;
        }
    }
    return totalRegistered;
}

/**
 * The one line a boot prints when it registered a residual — the same
 * sentence through either door, with the door's own noun and remedy: an
 * artifact is rebuilt, a config is re-declared. The `top-level metadata
 * item(s)` sentence is what operators grep for, and the artifact door's text
 * is unchanged byte for byte.
 */
function unclaimedTopLevelWarning(
    source: UnclaimedTopLevelSource,
    residual: number,
    bodyCount: number,
    manifestPackageId: string | undefined,
): string {
    const owner = manifestPackageId ?? '<none>';
    if (source.door === 'artifact') {
        return `[MetadataPlugin] artifact '${source.label}' carries ${residual} top-level metadata item(s) that `
            + `none of its ${bodyCount} package bodies declare. They were registered under the `
            + `artifact's own manifest id ('${owner}') because no package in the `
            + 'artifact claims them, so every door will report that id as their owner. Rebuild the '
            + 'artifact so each collection it ships is carried by the package that owns it.';
    }
    return `[AppPlugin] config stack '${source.label}' carries ${residual} top-level metadata item(s) that `
        + `none of its ${bodyCount} package bodies declare. They were registered under the `
        + `stack's own manifest id ('${owner}') because no package in the stack claims them, `
        + 'so every door will report that id as their owner. Declare each one inside the '
        + '`packages[]` entry of the package that owns it; a flat `src/docs/` page moves under '
        + '`src/<package>/docs/`, where `<package>` is the package id or its last dot-separated segment.';
}


export interface MetadataPluginOptions {
    rootDir?: string;
    /**
     * When `true`, NodeMetadataManager scans `rootDir` for source-file metadata
     * (yaml/json/ts/js loaders) AND attaches a chokidar watcher to react to
     * filesystem changes. In **artifact-mode** (this is the normal path when
     * a `defineStack()` config is compiled into `dist/objectstack.json`) this
     * filesystem scan is redundant and expensive — leave `watch: false`.
     *
     * The artifact-file HMR watcher is controlled separately by
     * {@link artifactWatch} so that the cheap, single-file polling watcher
     * can be enabled in dev without paying the cost of scanning the entire
     * project root.
     *
     * Default: `false` (post PR-10e — was previously `true`).
     */
    watch?: boolean;
    /**
     * When `true` AND `artifactSource.mode === 'local-file'`, attach a
     * polling chokidar watcher to the artifact file so the server reloads
     * metadata when the CLI recompiles `dist/objectstack.json` in dev mode.
     * Independent of {@link watch} (which controls the source-file scanner).
     *
     * Default: `true` when `artifactSource` is set, otherwise `false`.
     */
    artifactWatch?: boolean;
    config?: Partial<MetadataPluginConfig>;
    /** Organization ID for metadata-scoped consumers; MetadataPlugin itself does not persist runtime metadata. */
    organizationId?: string;
    /**
     * Environment ID used by local artifact envelopes and metadata-scoped
     * consumers. (The v5.0 rename retired the "project ID" wording this
     * comment used to carry; see ADR-0006.)
     */
    environmentId?: string;
    /**
     * When set, MetadataPlugin loads metadata from a compiled artifact instead
     * of scanning the filesystem, honored by all three bootstrap modes
     * (`eager` / `lazy` / `artifact-only`) — see `start()`.
     *
     * `path` is a filesystem path, or an `http(s)://` URL fetched verbatim —
     * the control plane's public artifact route
     * (`/pub/v1/environments/:id/artifact[?commit=…]`) serves exactly such
     * URLs, so a sealed runtime can boot straight off a published revision.
     * Remote reads honor `fetchTimeoutMs` / `OS_ARTIFACT_FETCH_TIMEOUT_MS`;
     * the artifact-file HMR watcher ({@link artifactWatch}) applies to
     * non-URL paths only.
     *
     * `local-file` is the only mode. A second `artifact-api` mode (a
     * Bearer-authenticated control-plane pull) existed here through v17 with
     * zero consumers in any repo — the cloud runtime uses its own
     * `ArtifactApiClient`, and package distribution into a running OSS
     * instance goes through `@objectstack/cloud-connection` — and was removed
     * when #4246 forced the declared-vs-enforced question. `start()` rejects
     * an unknown mode loudly rather than silently scanning the filesystem
     * instead.
     */
    artifactSource?: { mode: 'local-file'; path: string; fetchTimeoutMs?: number };
    /**
     * Register the `sys_metadata` + `sys_metadata_history` storage objects
     * on this kernel. Default `true` for backward compatibility.
     *
     * Set to `false` for **per-project** kernels: in cloud / project mode the
     * control plane is the sole owner of metadata storage tables — exposing
     * them inside each project kernel would leak control-plane schema into
     * business-data namespaces.
     */
    registerSystemObjects?: boolean;
    /**
     * Owning package id for source-file metadata loaded by the filesystem
     * scanner (`watch`/eager mode) — the project's `defineStack({ manifest:
     * { id } })` id. When set, scanned items are stamped with
     * `_packageId`/`_provenance: 'package'` via `applyProtection`, exactly
     * like the artifact path, so GET /meta consumers can tell code-defined
     * metadata from user-authored rows.
     *
     * Leave unset when the host has no package identity — items then stay
     * unstamped (runtime-authored semantics). Do NOT pass a guessed value:
     * `_packageId` feeds `isArtifactBacked()` write authorization, so a
     * wrong id silently changes who may edit these items.
     */
    packageId?: string;
}

export class MetadataPlugin implements Plugin {
    name = 'com.objectstack.metadata';
    type = 'standard' as const;
    version = '1.0.0';
    /**
     * Services init() UNCONDITIONALLY registers (ADR-0116, #4131) — lets the
     * kernel name this plugin when a consumer requires `metadata` before it
     * initializes.
     */
    providesServices = ['metadata'];
    /**
     * init() registers the metadata system objects through the `manifest`
     * service ObjectQLPlugin provides — order-if-present so that
     * registration is deterministic instead of "whichever init ran first"
     * (ADR-0116, #4471). Soft, not hard: without an engine the plugin
     * degrades on purpose (objects are discovered via the legacy fallback).
     */
    optionalDependencies = ['com.objectstack.engine.objectql'];

    private manager: NodeMetadataManager;
    private options: MetadataPluginOptions;
    private repository?: import('@objectstack/metadata-core').MetadataRepository;
    /** Chokidar watcher on the artifact file (local-file mode) — ADR-0008 PR-8. */
    private artifactWatcher?: { close: () => Promise<void> };
    /**
     * The context handed to `init()`, retained so `destroy()` can log.
     * [#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 most recently parsed artifact metadata (the plural-field record:
     * `objects`, `views`, `data`, …). Carried on the `metadata:reloaded`
     * payload so runtime consumers can react to collections that never enter
     * the MetadataManager — notably seeds (`data`), whose items have no
     * `name` and are skipped by `_parseAndRegisterArtifact`'s register loop.
     */
    private lastParsedMetadata?: Record<string, unknown[]>;

    /**
     * Once-per-process dedupe for the summaries the versioned artifact window
     * emits. The artifact watcher replays `_parseAndRegisterArtifact` on every
     * file change, so without this a dev loop over a legacy artifact would
     * re-announce the same finding on every reload — the same shape
     * `Protocol.storedConversionWarned` guards on the stored-row pass, which
     * this surfacing is modeled on.
     *
     * Two key families share the set, because they share the replay:
     * `<conversionId>|<label>` for a forward-conversion summary (#12772), and
     * `unbound-form-predicate-root|<label>` for the unbound-root notice
     * (#12915) — one line per artifact there, not one per conversion, since
     * the notice already aggregates every finding it made.
     */
    private artifactConversionWarned = new Set<string>();

    constructor(options: MetadataPluginOptions = {}) {
        // Documented default: `watch: false` (see {@link MetadataPluginOptions.watch}).
        // Normalized here rather than spelled `{ watch: false, ...options }` because a
        // spread preserves an explicitly-passed `watch: undefined` verbatim, and not
        // every read of this flag routes through the nullish fallback below — the
        // `start()`-time FileSystemRepository `disableWatch` keys on `=== false`. Coercing
        // once here makes the omitted key and an explicit `undefined` resolve identically
        // at EVERY downstream read.
        this.options = {
            ...options,
            watch: options.watch ?? false
        };

        const rootDir = this.options.rootDir || process.cwd();

        // Sealed-runtime carve-out: `bootstrap: 'artifact-only'` MUST NOT touch
        // the filesystem at all — that includes chokidar subscriptions. Force
        // watch off in that mode regardless of `options.watch`. The other two
        // modes ('eager', 'lazy') honor the user's flag; `lazy` + watch is a
        // valid combination because chokidar attaches to `rootDir` directly,
        // not as a side effect of any priming pass.
        const bootstrapMode = this.options.config?.bootstrap ?? 'eager';
        const effectiveWatch =
            bootstrapMode === 'artifact-only' ? false : (this.options.watch ?? false);

        this.manager = new NodeMetadataManager({
            rootDir,
            watch: effectiveWatch,
            formats: ['yaml', 'json', 'typescript', 'javascript']
        });

        // Initialize with default type registry
        this.manager.setTypeRegistry(DEFAULT_METADATA_TYPE_REGISTRY);
    }

    init = async (ctx: PluginContext) => {
        // [#10772] Retained for `destroy()`, which the kernel calls with no
        // context. Assigned before anything that can throw.
        this.initCtx = ctx;
        ctx.logger.info('Initializing Metadata Manager', {
            root: this.options.rootDir || process.cwd(),
            watch: this.options.watch,
            artifactSource: this.options.artifactSource?.mode,
        });

        // Register Metadata Manager as the primary metadata service provider.
        ctx.registerService('metadata', this.manager);

        // Register metadata system objects via the manifest service (if available).
        // MetadataPlugin may init before ObjectQLPlugin, so wrap in try/catch.
        // Skipped when `registerSystemObjects: false` (per-project kernels in
        // cloud / project mode — sys_* live exclusively in the control plane).
        const registerSysObjects = this.options.registerSystemObjects !== false;
        if (registerSysObjects) {
            try {
                const manifestService = ctx.getService<{ register(m: any): void }>('manifest');

                // Register the queryable metadata-layer platform objects.
                manifestService.register({
                    id: 'com.objectstack.metadata-objects',
                    name: 'Metadata Platform Objects',
                    version: '1.0.0',
                    type: 'plugin',
                    scope: 'system',
                    defaultDatasource: 'cloud',
                    objects: queryableMetadataObjects,
                });

                ctx.logger.info('Registered system metadata objects', {
                    queryable: queryableMetadataObjects.map((object) => object.name),
                });
            } catch {
                // ObjectQL not loaded yet — objects will be discovered via legacy fallback
            }
        }

        ctx.logger.info('MetadataPlugin providing metadata service (primary mode)', {
            mode: this.options.artifactSource?.mode ?? 'file-system',
            features: ['watch', 'multi-format', 'query', 'type-registry']
        });
    }

    start = async (ctx: PluginContext) => {
        const src = this.options.artifactSource;
        const mode = this.options.config?.bootstrap ?? 'eager';

        ctx.logger.info('[MetadataPlugin] Bootstrapping metadata', {
            bootstrap: mode,
            artifactSource: src?.mode ?? 'none',
        });

        // Reject a non-`local-file` source before choosing any load path. The
        // union is single-member so TypeScript callers can't get here, but JS
        // callers and config plumbed through `any` can — and the fall-through
        // below would otherwise treat "unsupported source" as "no source"
        // (eager would silently scan the filesystem instead of loading the
        // artifact the caller named). The removed `artifact-api` mode gets a
        // pointed migration message (#4246).
        if (src && (src as { mode: string }).mode !== 'local-file') {
            const bad = (src as { mode: string }).mode;
            throw new Error(
                `[MetadataPlugin] artifactSource.mode '${bad}' is not supported`
                + (bad === 'artifact-api'
                    ? " — the 'artifact-api' source was removed. Load the same artifact with"
                      + " { mode: 'local-file', path: '<http(s) URL>' } (e.g. the control plane's"
                      + " /pub/v1/environments/:id/artifact route), or install packages into a running"
                      + ' runtime via @objectstack/cloud-connection.'
                    : ". The only artifact source is { mode: 'local-file', path }."),
            );
        }

        if (mode === 'artifact-only') {
            // Sealed-runtime mode: ONLY load from a pre-compiled artifact. Never
            // touch the filesystem. Required for Edge / serverless / read-only
            // production deployments where the running process must not depend
            // on local source files.
            if (src) {
                await this._loadFromLocalFile(ctx, src.path, src.fetchTimeoutMs);
            } else {
                throw new Error('[MetadataPlugin] bootstrap=artifact-only requires options.artifactSource to be set');
            }
        } else if (mode === 'lazy') {
            // On-demand mode: skip the eager filesystem priming pass entirely.
            // Reads go through MetadataManager.load*/list* which are backed by
            // the DatabaseLoader read-through cache and any registered loaders.
            // An artifact source, if present, is still honored so projects can
            // pin a known set of metadata at boot without paying the FS scan.
            if (src) {
                await this._loadFromLocalFile(ctx, src.path, src.fetchTimeoutMs, { optional: true });
            } else {
                ctx.logger.info('[MetadataPlugin] lazy bootstrap — skipping filesystem priming; metadata loads on demand');
            }
        } else {
            // 'eager' (default): preserve historical behavior.
            if (src) {
                await this._loadFromLocalFile(ctx, src.path, src.fetchTimeoutMs, { optional: true });
            } else {
                await this._loadFromFileSystem(ctx);
            }
        }

        // ── ADR-0008 PR-6: attach FileSystemRepository as a supplementary
        //    event source so PR-7 (ObjectQL SchemaRegistry), PR-9 (Studio
        //    SSE hook) and future cloud consumers can subscribe to the
        //    same canonical event stream. No write mirroring yet.
        const bootstrapMode = this.options.config?.bootstrap ?? 'eager';
        if (bootstrapMode !== 'artifact-only') {
            try {
                const path = await import('node:path');
                const { FileSystemRepository } = await import('@objectstack/metadata-fs');
                const rootDir = this.options.rootDir || process.cwd();
                const repoRoot = path.join(rootDir, REPO_SUBDIR);
                // [#23086] The actor rule, stated rather than inherited: no
                // `fsActor`. An edit seen on disk, or a file no recorded write
                // produced, has no acting user here, so it records `null`
                // (`PutOptions.actor`, #4556), and `source: 'fs'` names the
                // origin. ⛔ Never pass a label as `fsActor`. Pinned in
                // `plugin-fs-repository-actor.test.ts`.
                const repo = new FileSystemRepository({
                    root: repoRoot,
                    org: this.options.organizationId ?? 'system',
                    disableWatch: this.options.watch === false,
                });
                await repo.start();
                this.repository = repo;
                this.manager.setRepository(repo);
                ctx.logger.info('[MetadataPlugin] FileSystemRepository attached', {
                    repoRoot,
                    watch: this.options.watch !== false,
                });
            } catch (e: any) {
                ctx.logger.warn('[MetadataPlugin] Failed to attach FileSystemRepository', {
                    error: e?.message,
                });
            }
        }

        // Bridge realtime service from kernel service registry to MetadataManager.
        try {
            const realtimeService = ctx.getService('realtime');
            if (realtimeService && typeof realtimeService === 'object' && 'publish' in realtimeService) {
                ctx.logger.info('[MetadataPlugin] Bridging realtime service to MetadataManager for event publishing');
                this.manager.setRealtimeService(realtimeService as any);
            }
        } catch (e: any) {
            ctx.logger.debug('[MetadataPlugin] No realtime service found — metadata events will not be published', {
                error: e.message,
            });
        }

        // Register the HMR SSE endpoint when an HTTP server is available
        // that exposes a raw Hono app. The endpoint is registered regardless
        // of the `watch` option:
        //  - In `watch: true` mode the FS watcher feeds events into the hub.
        //  - In `watch: false` mode (e.g. artifact-mode `os dev`), an
        //    external watch-recompile pipeline POSTs to the same endpoint
        //    after rebuilding the artifact, and we reload it here before
        //    broadcasting.
        // [commit f4e7ae5c7] PRODUCTION BOOTS DO NOT GET THIS DOOR, and that is now
        // enforced rather than predicted. This comment used to read
        // "production deployments simply won't have a CLI POSTing to this
        // endpoint and won't surface the route to clients" — a claim about who
        // is on the network, which is exactly the shape #9391 closed for
        // `datasource-admin`. It was also false in the half that mattered: the
        // official image runs `os start` under `NODE_ENV=production`
        // (`docker/Dockerfile`), that boot reaches `createStandaloneStack`,
        // and the stack composes this plugin UNCONDITIONALLY
        // (`packages/runtime/src/standalone-stack.ts` gates only `artifactWatch`
        // on NODE_ENV) onto a kernel that registers `HonoServerPlugin` whenever
        // it serves. Both routes were therefore mounted, unauthenticated, on a
        // production-shaped boot. The gate lives in the registrar — see
        // `isDevMetadataEndpointEnabled` in `routes/hmr-routes.ts` — so the
        // decision cannot be bypassed by a second caller; here we only handle
        // its answer.
        try {
            // [#4251] Both names are the SAME instance; `http.server` is the
            // canonical one (the only name every provider registers), read
            // first. Per-name try — `getService` THROWS for an empty slot, so
            // a single try around `canonical ?? alias` never reaches the
            // alias: exactly the shape this read had before (alias-first),
            // whose fallback therefore never once fired. `getRawApp?()` is on
            // the contract now — the deliberate framework-handle escape,
            // declared once there instead of per consumer. The alias fallback
            // dies with the alias registrations.
            const readServer = (name: string): IHttpServer | undefined => {
                try { return ctx.getService<IHttpServer>(name); } catch { return undefined; }
            };
            const httpServer = readServer('http.server') ?? readServer('http-server');
            if (httpServer && typeof httpServer.getRawApp === 'function') {
                const { registerMetadataHmrRoutes } = await import('./routes/hmr-routes.js');
                // `null` when the environment gate refused: nothing was
                // mounted, so there is no hub, no POST handler to wire, and
                // nothing to broadcast to.
                const hub = registerMetadataHmrRoutes(httpServer.getRawApp(), this.manager);
                // Wire POST → re-load the artifact from disk (when in
                // local-file artifact mode) so subsequent reads see fresh
                // metadata. The broadcast happens after the handler returns.
                hub?.setOnPostReload(async (body: { reason?: string; changed?: string[] } = {}) => {
                    const src = this.options.artifactSource;
                    if (src?.mode === 'local-file') {
                        try {
                            await this._reloadAndAnnounce(ctx, src, body?.changed ?? [src.path]);
                            ctx.logger.info('[MetadataPlugin] artifact reloaded via HMR POST', {
                                path: src.path,
                                reason: body?.reason,
                            });
                        } catch (e: any) {
                            ctx.logger.warn('[MetadataPlugin] artifact reload failed', { error: e?.message });
                            throw e;
                        }
                    }
                });

                // ── ADR-0008 PR-8 / PR-10e: server-side artifact-file watcher ──
                //
                // When running in local-file artifact mode (e.g. `os dev`
                // serving from `dist/objectstack.json`), watch the
                // artifact path directly so the server reloads on
                // recompile WITHOUT requiring the CLI to ping the HMR
                // POST endpoint. The POST route stays available for
                // external trigger sources (cloud webhook, git hook,
                // ad-hoc curl) but is no longer the only signal.
                //
                // Gated on `artifactWatch` (NOT `watch` — the latter
                // controls the source-file scanner which is redundant in
                // artifact mode). Default: on when artifactSource is
                // present, off otherwise.
                const src = this.options.artifactSource;
                const wantArtifactWatch = this.options.artifactWatch
                    ?? (src?.mode === 'local-file');
                if (src?.mode === 'local-file' && wantArtifactWatch && !/^https?:\/\//i.test(src.path)) {
                    try {
                        const { watch: chokidarWatch } = await import('chokidar');
                        const w = chokidarWatch(src.path, {
                            ignoreInitial: true,
                            awaitWriteFinish: { stabilityThreshold: 50, pollInterval: 20 },
                            persistent: true,
                            // Use polling to avoid `fs.watch` exhausting the
                            // process file-descriptor limit on macOS (chokidar
                            // recursively wires watches on the parent
                            // directory tree which can trip EMFILE on busy
                            // dev hosts). 500ms polling is fast enough for
                            // HMR (a recompile takes ~400ms anyway).
                            usePolling: true,
                            interval: 500,
                            binaryInterval: 1000,
                        });
                        let pending = false;
                        const reload = async () => {
                            if (pending) return;
                            pending = true;
                            try {
                                await this._reloadAndAnnounce(ctx, src, [src.path]);
                                // Optional for the same reason the wiring
                                // above is: with the door closed there are no
                                // SSE clients to tell. The RELOAD still
                                // happened — `_reloadAndAnnounce` above is
                                // unconditional, so the server-side artifact
                                // watcher keeps working exactly as before on
                                // every boot shape that had it.
                                hub?.broadcastReload('artifact-file-changed', [src.path]);
                                ctx.logger.info('[MetadataPlugin] artifact auto-reloaded (file watcher)', {
                                    path: src.path,
                                });
                            } catch (e: any) {
                                ctx.logger.warn('[MetadataPlugin] artifact auto-reload failed', { error: e?.message });
                            } finally {
                                pending = false;
                            }
                        };
                        w.on('change', () => { void reload(); });
                        w.on('add', () => { void reload(); });
                        this.artifactWatcher = { close: () => w.close() };
                        console.log('[MetadataPlugin] artifact file watcher attached', src.path);
                    } catch (e: any) {
                        ctx.logger.warn('[MetadataPlugin] artifact watcher failed to start', { error: e?.message });
                    }
                }
                if (hub) {
                    console.log('[MetadataPlugin] HMR endpoint registered at /api/v1/dev/metadata-events');
                } else {
                    // Printed on every non-development boot, deliberately: a
                    // closed door that says nothing is indistinguishable from a
                    // door that was never asked about, and this line is what an
                    // operator greps when the Studio preview stops
                    // auto-reloading.
                    console.log(
                        '[MetadataPlugin] dev metadata-HMR endpoints NOT mounted — they require '
                        + `NODE_ENV=development (this process: ${process.env.NODE_ENV ? `NODE_ENV=${process.env.NODE_ENV}` : 'NODE_ENV unset, treated as production'})`,
                    );
                }
            } else {
                console.log('[MetadataPlugin] HTTP server with getRawApp() not available — skipping HMR endpoint');
            }
        } catch (e: any) {
            console.warn('[MetadataPlugin] Failed to register HMR endpoint', e?.message);
        }
    }

    /**
     * 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 the artifact watcher, the manager and the
     * repository were all still held after `await kernel.shutdown()` had
     * RESOLVED. The `start`/`stop` pair read symmetric to a reviewer because
     * `start()` really is on the interface; only one half was ever called.
     *
     * Idempotent: every handle is cleared as it is released, so a second
     * teardown is a no-op rather than a second close.
     */
    destroy = async (): Promise<void> => {
        if (this.artifactWatcher) {
            try { await this.artifactWatcher.close(); } catch { /* noop */ }
            this.artifactWatcher = undefined;
        }
        try {
            await this.manager.dispose();
        } catch (e: any) {
            this.initCtx?.logger?.warn?.('[MetadataPlugin] manager.dispose() failed', { error: e?.message });
        }
        const repo = this.repository as any;
        if (repo && typeof repo.close === 'function') {
            try { await repo.close(); } catch { /* noop */ }
        }
        this.repository = undefined;
    }

    /**
     * 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 logs through the context
     * captured in `init()`.
     */
    stop = async (_ctx?: PluginContext): Promise<void> => {
        await this.destroy();
    }

    /**
     * Fetch JSON content from a URL with configurable timeout.
     */
    private async _fetchJson(url: string, fetchTimeoutMs?: number): Promise<unknown> {
        const envTimeout = Number(process.env.OS_ARTIFACT_FETCH_TIMEOUT_MS);
        const timeoutMs = fetchTimeoutMs
            ?? (Number.isFinite(envTimeout) && envTimeout > 0 ? envTimeout : undefined)
            ?? 60_000;
        const controller = new AbortController();
        const timer = timeoutMs > 0 ? setTimeout(() => controller.abort(), timeoutMs) : undefined;
        try {
            const headers: Record<string, string> = { Accept: 'application/json, */*;q=0.5' };
            const res = await fetch(url, { redirect: 'follow', signal: controller.signal, headers });
            if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText}`);
            const content = await res.text();
            return JSON.parse(content);
        } catch (e: any) {
            if (e?.name === 'AbortError') {
                throw new Error(
                    `fetch timed out after ${timeoutMs}ms — set artifactSource.fetchTimeoutMs or OS_ARTIFACT_FETCH_TIMEOUT_MS to extend it (0 disables)`,
                );
            }
            throw e;
        } finally {
            if (timer) clearTimeout(timer);
        }
    }

    /**
     * Versioned ADR-0087 forward conversion at the artifact-ingestion door
     * (#12772) — runs BEFORE the strict schema parse below, because the parse
     * is the refusal point.
     *
     * A compiled artifact is data at rest with a version stamp: built by
     * released tooling, then unchanged while the platform moves on. When a
     * spec release retires an authorable key inside a protocol line (spec
     * 17.1 → 17.2 retired the `allowRestore`/`allowPurge` permission bits),
     * every already-built artifact carrying the key becomes unbootable at the
     * tombstone — with no operator remedy, since `os migrate meta` targets
     * sources, not built artifacts. The stored-row read path already replays
     * the conversion chain for exactly this reason
     * (`applyConversionsToStoredItem`, ADR-0087 addendum); this is the same
     * policy at the artifact door, **keyed off the artifact's own declared
     * `engines.protocol` floor**: an artifact authored below the running spec
     * version converts forward; one whose floor is not below the runtime's label
     * but is at or below a retired entry's `retiredAfter` gets exactly those
     * retirements replayed (`converted-retired-after` — `main` between two
     * releases); an artifact authored at the current (or a newer) surface
     * converts nothing and answers to the strict parse, tombstones included.
     * The version key is what keeps this a conversion
     * rather than an amnesty — the retired keys return with the M2 lifecycle
     * batch (#1883), and artifacts authored against that surface must never
     * have them stripped by history.
     *
     * Notices surface the way the stored-row pass's do — operator-visible and
     * deduped — as one summary line per conversion per artifact rather than
     * one per rewritten path (a real 17.1 artifact carried 150 strips of the
     * same two keys; 150 identical warn lines would bury the boot log).
     */
    private _convertArtifactForward(ctx: PluginContext, definition: unknown, label: string): unknown {
        const result = applyArtifactForwardConversions(definition);
        // Runs on every artifact, conversions or not: an artifact can be inside
        // the versioned window and carry NO convertible key while still
        // carrying the fault-open predicates below.
        this._warnUnboundFormPredicateRoots(ctx, result, label);
        if (result.notices.length === 0) return result.definition;

        const byConversion = new Map<string, { count: number; firstPath: string; message: string }>();
        for (const n of result.notices) {
            const existing = byConversion.get(n.conversionId);
            if (existing) existing.count += 1;
            else byConversion.set(n.conversionId, { count: 1, firstPath: n.path, message: n.message });
        }
        // Under the per-entry half of the window, each replayed entry is named
        // as what it is — a retirement this runtime enforces past the
        // artifact's floor — with the release it retired after.
        const retiredAfter = new Map(result.replayedRetirements.map((r) => [r.conversionId, r.retiredAfter]));
        for (const [conversionId, agg] of byConversion) {
            const key = `${conversionId}|${label}`;
            if (this.artifactConversionWarned.has(key)) continue;
            this.artifactConversionWarned.add(key);
            const pastFloor = retiredAfter.get(conversionId);
            ctx.logger.warn(
                pastFloor !== undefined
                    ? `[MetadataPlugin] artifact '${label}' ${artifactWindowClause(result)} — ADR-0087 `
                        + `conversion '${conversionId}' is a retirement this runtime enforces past the `
                        + `artifact's floor (the shape was last accepted by @objectstack/spec ${pastFloor}): `
                        + `converted ${agg.count} site(s) forward (first at ${agg.firstPath}). ${agg.message} `
                        + `The artifact file itself is unchanged, so it converts again on every boot until `
                        + `it is rebuilt ('os build') with tooling from a release that ships this retirement.`
                    : `[MetadataPlugin] artifact '${label}' ${artifactWindowClause(result)} — converted `
                        + `${agg.count} site(s) forward via ADR-0087 conversion '${conversionId}' `
                        + `(first at ${agg.firstPath}). ${agg.message} `
                        + `The artifact file itself is unchanged — rebuild it with current tooling `
                        + `('os build') to persist the canonical shape.`,
            );
        }
        return result.definition;
    }

    /**
     * Operator-facing boot notice for form-view predicates that fault OPEN on
     * this runtime (#12915 scope C — maintainer ruling 2026-08-28, 「同意C」).
     *
     * A form-view predicate binds `record` / `previous` / `parent` (runtime
     * record forms) or `data` (metadata-editing forms) — and a FIELD-level one
     * also binds `current_user` and its ADR-0068 aliases (objectui#6010),
     * which a SECTION-level one does not. The contract states beside that
     * vocabulary that a bare identifier is UNBOUND and the predicate faults,
     * and `visibleWhen`'s fault fallback is `true`. On a real
     * 17.1-built artifact that combination dead-ends record creation in the
     * console: the conditionally hidden field renders, and its unconditional
     * `required: true` — authored to be gated by the visibility that no longer
     * applies — blocks every submit, while the same payload POSTs 201 through
     * REST. Nothing refused, nothing logged, and only the operator can fix it
     * (by rebuilding the artifact), so this is the channel the ruling picked:
     * service startup, server-side, never a console surface — the person at
     * the form cannot act on "your artifact is stale".
     *
     * **Detection only.** No refusal, no rewrite, no behaviour change: the
     * predicate keeps faulting open exactly as before. Rewriting a bare root to
     * `record.` is the ADR-0087 conversion (#12915 scope A), deferred by the
     * same ruling with an explicit start line.
     *
     * **Same versioned window as the conversion replay above** — and read off
     * that pass's own verdict rather than recomputed, so the two can never
     * disagree about which artifacts are "old": {@link FORWARD_WINDOW_OPENED}
     * is the one reading, total over the verdicts, so the per-entry half of the
     * window (`converted-retired-after` — an artifact built by the last release
     * on a runtime enforcing retirements its label has not moved past) is "old"
     * here exactly as it is for the replay, whatever the label says. An artifact
     * declaring the current (or a newer) floor answers to the strict parse and
     * gets nothing from here even when it does carry bare roots; that boundary
     * is what keeps a notice about legacy artifacts out of contract territory.
     * An undeclared range is treated as old data at rest, matching the
     * grandfathering posture the window already takes (`converted-undeclared`).
     */
    private _warnUnboundFormPredicateRoots(
        ctx: PluginContext,
        result: ArtifactForwardConversionResult<unknown>,
        label: string,
    ): void {
        if (!FORWARD_WINDOW_OPENED[result.verdict]) return;

        const findings = detectUnboundFormViewPredicateRoots(result.definition);
        if (findings.length === 0) return;

        const key = `unbound-form-predicate-root|${label}`;
        if (this.artifactConversionWarned.has(key)) return;
        this.artifactConversionWarned.add(key);

        // ONE line per artifact, not one per predicate — a real legacy artifact
        // carries the pattern across many fields of the same form, and the
        // conversion summary beside this one exists because 150 identical warn
        // lines buried a boot log.
        const views = [...new Set(findings.map((f) => f.view))];
        const roots = [...new Set(findings.map((f) => f.root))];
        const quote = (list: readonly string[]) => list.map((v) => `'${v}'`).join(', ');

        // Print only the rule(s) the findings actually implicate, so an
        // operator is never shown a rule their artifact has no instance of.
        // ⚠️ The two lists are the SAME list today: a field bound the
        // `current_user` family at objectui#6010 and a section did at
        // objectui#6110 + objectui#6111, so the per-surface split is currently empty
        // (`@objectstack/metadata-core`, `BOUND_FORM_VIEW_PREDICATE_ROOTS`,
        // carries the mechanism and the two times this claim went stale). The
        // arms stay per surface because the QUESTION is per surface — two
        // different renderers bind the family, and either can move without the
        // other.
        const surfaces = new Set(findings.map((f) => f.surface));
        const vocabulary = [
            surfaces.has('field')
                ? `on a form FIELD: ${quote(BOUND_FORM_FIELD_PREDICATE_ROOTS)}`
                : null,
            surfaces.has('section')
                ? `on a form SECTION: ${quote(BOUND_FORM_VIEW_PREDICATE_ROOTS)}`
                : null,
        ].filter(Boolean).join('; ');

        ctx.logger.warn(
            `[MetadataPlugin] artifact '${label}' ${artifactWindowClause(result)} `
            + `and carries ${findings.length} form-view predicate(s) whose `
            + `root identifier is NOT bound where it evaluates — ${quote(roots)} `
            + `(bound roots ${vocabulary}) — across `
            + `${views.length} view(s): ${views.join(', ')} (first at ${findings[0]!.path}). `
            + `Each one faults at evaluation and visibility fails OPEN, so a field the predicate was `
            + `authored to HIDE renders anyway — and an unconditional 'required: true' on such a field `
            + `dead-ends record creation in the console while the REST door still accepts it. `
            + `Nothing was rewritten and no behaviour changed here; rebuild the artifact with current `
            + `tooling ('os build') so its predicates carry a bound root ('record.<field>').`,
        );
    }

    /**
     * Parse raw artifact JSON (envelope or bare definition) and register all
     * metadata items into the MetadataManager.
     *
     * Registers with `{ notify: false }` — one announcement per artifact, not
     * one per item. Both callers cover the whole set already: the boot load
     * runs before consumers have cached anything, and the reload path
     * (`_reloadAndAnnounce`) fires `metadata:reloaded` carrying the parsed
     * artifact once the ingest is complete. Announcing here too would emit N
     * duplicate events per reload, each racing the batch that is still
     * landing.
     */
    private async _parseAndRegisterArtifact(ctx: PluginContext, raw: unknown, label: string): Promise<number> {
        const { EnvironmentArtifactSchema } = await import('@objectstack/spec/system');
        const { ObjectStackDefinitionSchema } = await import('@objectstack/spec');

        let metadata: Record<string, unknown[]>;

        const obj = raw as any;
        if (obj?.schemaVersion && obj?.commitId && obj?.metadata !== undefined) {
            const artifact = EnvironmentArtifactSchema.parse({
                ...obj,
                metadata: this._convertArtifactForward(ctx, obj.metadata, label),
            });
            metadata = artifact.metadata as Record<string, unknown[]>;
        } else if (obj?.success && obj?.data?.metadata) {
            // Unwrap cloud API envelope: { success: true, data: { metadata: {...} } }
            const artifact = EnvironmentArtifactSchema.parse({
                ...obj.data,
                metadata: this._convertArtifactForward(ctx, obj.data.metadata, label),
            });
            metadata = artifact.metadata as Record<string, unknown[]>;
        } else {
            const def = ObjectStackDefinitionSchema.parse(this._convertArtifactForward(ctx, obj, label));
            const canonical = JSON.stringify(def, Object.keys(def).sort());
            const checksum = createHash('sha256').update(canonical).digest('hex');
            const environmentId = this.options.environmentId ?? 'env_local';
            EnvironmentArtifactSchema.parse({
                schemaVersion: '0.1',
                environmentId,
                commitId: 'local-dev',
                checksum,
                metadata: def,
            });
            metadata = def as Record<string, unknown[]>;
        }

        this.lastParsedMetadata = metadata;

        const memLoader = new MemoryLoader();
        const manifestPackageId =
            (metadata as any)?.manifest?.id ?? (metadata as any)?.id ?? undefined;
        const manifestVersion =
            (metadata as any)?.manifest?.version ?? (metadata as any)?.version ?? undefined;

        // ── ADR-0130 D4, at the metadata door: read BOTH shapes, and attribute
        //    every item to the body it was FOUND in ───────────────────────────
        //
        // `packages` ABSENT → the artifact itself IS the one package's body and
        // `manifest.id` is its owner (D7). That is the branch every artifact
        // built to date takes and it must not move: the loop below runs exactly
        // once, over `metadata`, stamped with the two ids computed above.
        //
        // `packages` PRESENT → the artifact carries N assembled package bodies,
        // each `{ ...manifest, ...collections }` (`AssembledPackageBodySchema`),
        // whose collections are declared by the same shape the top level parses
        // against. Measured, not assumed: every live `ARTIFACT_FIELD_TO_TYPE`
        // key is a member of that schema, so iterating bodies loses no
        // collection. Registering from the BODY is what gives each item the id
        // of the package that owns it. Before this, the flattened top level was
        // the only thing read here and every item took the ARTIFACT's
        // `manifest.id` — which for a composed artifact is one arbitrary
        // member's id (`selectManifest`'s `'last'` pick). So a two-package
        // artifact registered the module's object under the app's id, the
        // registry owned the same object under the module's, and the platform
        // held two answers to "who owns this": the layers door said one, the
        // item door and `GET /api/v1/packages` said the other, and the list
        // door — keyed `${packageId}${name}` — served the object TWICE (#14599).
        //
        // ⛔ The owner is read off the body the item was found in — never
        // reverse-derived by matching a top-level item's name against a
        // name-to-package index. Such an index is a SECOND resolution path for
        // metadata identity, which is the road #14512's triage rejected by name
        // (its option C) precisely because a dangling one fails silently.
        //
        // Ordering AND the entry gate both come from `resolveArtifactPackageOrder`
        // (`@objectstack/core`) — the same call `ObjectQLPlugin` makes on the
        // same artifact, reused rather than re-derived (D5). Two readers of one
        // `packages[]` that sorted or validated differently would disagree about
        // which artifacts load at all, not merely about the order. It returns
        // `[artifact]` for the absent branch, which is what lets both branches
        // share the one loop.
        const carriesPackages = Array.isArray((metadata as any)?.packages);
        const bodies = resolveArtifactPackageOrder(metadata) as Record<string, unknown>[];

        // What the door stores into: the in-memory loader first, then the
        // manager, for every item either pass below registers.
        const sink: ArtifactRegistrationSink = {
            register: async (type, name, item) => {
                await memLoader.save(type, name, item);
                await this.manager.register(type, name, item, { notify: false });
            },
            warn: (message) => ctx.logger.warn(message),
        };

        let totalRegistered = 0;
        for (const body of bodies) {
            totalRegistered += await registerArtifactBodyCollections(
                sink,
                body,
                carriesPackages
                    // `registerApp` keys an installed package on `id || name`
                    // and `artifactPackageId` is that ONE spelling, imported
                    // from the module that also ordered these bodies. Reading
                    // the id any other way here is how a door and
                    // `GET /api/v1/packages` come to name different owners.
                    ? {
                        packageId: artifactPackageId(body),
                        packageVersion: (body as any)?.version ?? undefined,
                    }
                    // Unchanged single-package branch — the same two values
                    // this method has always stamped (D7).
                    : { packageId: manifestPackageId, packageVersion: manifestVersion },
                'artifact',
            );
        }

        // The residual, through the one rule both boot doors call (see
        // `registerUnclaimedTopLevel`). It registers nothing for a normally
        // composed artifact, and nothing at all without `packages[]`.
        totalRegistered += await MetadataPlugin.registerUnclaimedTopLevel(
            sink,
            metadata,
            { door: 'artifact', label },
        );

        this.manager.registerLoader(memLoader);
        ctx.logger.info('[MetadataPlugin] Artifact metadata loaded', { source: label, totalRegistered });
        return totalRegistered;
    }


    /**
     * The residual rule (ADR-0130 D4), the ONE copy both boot doors call: what
     * a multi-package stack's top level carries that none of its package
     * bodies declares is registered under the stack's own `manifest.id`, and
     * the boot warns once, with the count.
     *
     * Called by this plugin's artifact door on a compiled `objectstack.json`,
     * and by `AppPlugin` (`@objectstack/runtime`) on a config boot, whose
     * `manifest` service registers the package bodies and, of the top level of
     * a stack that carries `packages[]`, only the residual's objects (from
     * {@link unclaimedTopLevel}, this rule's own answer). The two doors differ only in where
     * their `sink` stores and in the words of the line; the decision — which
     * items, keyed how, owned by whom — is this method's.
     *
     * Why the residual is registered rather than dropped: `packages` is a
     * `concat` key, so a stack composed from one input that already carried
     * `packages` and one that did not has top-level collections no package
     * body repeats. Dropping those takes metadata off every door in silence.
     * Such an item falls back to the stack's own identity because nothing
     * better exists, and it is logged, because it means the stack's two halves
     * disagree. A normally composed stack registers nothing here:
     * `composeStacks(…, { manifest: 'preserve' })` is ADDITIVE, so every
     * top-level item is a copy a body already owns.
     *
     * WHICH items are residual, and the id they take, is
     * {@link unclaimedTopLevel}'s answer, the pure half `os validate` reads
     * too: the bodies' slots are read by the same derivation the registration
     * uses (`artifactItemSlot`), so "claimed" means exactly "a body registers
     * this key" on either door. Bodies and their order come from
     * `resolveArtifactPackageOrder` (`@objectstack/core`), the one reader of
     * `packages[]` — never re-derived here.
     *
     * A residual view container whose own `name` disagrees with its object is
     * refused, as a body's is: the artifact door names its source `artifact`,
     * the config door `manifest`, the word the config boot's own registrar and
     * `os validate` already use for the same stack.
     *
     * @returns How many items the residual registered — `0` for a stack
     *   without `packages[]`, which has no residual: its top level IS its one
     *   package's body.
     */
    static async registerUnclaimedTopLevel(
        sink: ArtifactRegistrationSink,
        stack: unknown,
        source: UnclaimedTopLevelSource,
    ): Promise<number> {
        const unclaimed = unclaimedTopLevel(stack);
        if (!unclaimed) return 0;
        // The unclaimed items, regrouped per collection in the order the
        // stack carries them; the registration walks the collections in its
        // own order, so it meets them exactly as a walk of the whole top level
        // that skipped every claimed slot would.
        const body: Record<string, unknown[]> = {};
        for (const { field, item } of unclaimed.items) (body[field] ??= []).push(item);
        const residual = await registerArtifactBodyCollections(
            sink,
            body,
            { packageId: unclaimed.ownerId, packageVersion: unclaimed.ownerVersion },
            source.door === 'artifact' ? 'artifact' : 'manifest',
        );
        if (residual > 0) {
            sink.warn(unclaimedTopLevelWarning(source, residual, unclaimed.bodyCount, unclaimed.ownerId));
        }
        return residual;
    }

    /**
     * Reload the artifact from disk into the MetadataManager, then announce a
     * generic `metadata:reloaded` hook. Used by BOTH reload paths (the HMR POST
     * handler and the server-side artifact-file watcher) — but NOT the initial
     * boot load, which other plugins already consume directly.
     *
     * Runtime consumers that cached boot-time metadata re-sync on this signal.
     * The automation engine subscribes to re-bind flow triggers it pulled ONCE
     * at boot — notably scheduled jobs: without this, an edited
     * schedule-triggered flow keeps firing its pre-edit definition (old runAs /
     * schedule / logic) until a full process restart. A subscriber failure is
     * logged but never blocks the reload.
     */
    private async _reloadAndAnnounce(
        ctx: PluginContext,
        src: { path: string; fetchTimeoutMs?: number },
        changed: string[],
    ): Promise<void> {
        // Optional for the same reason boot is: an artifact deleted or moved
        // aside mid-run (a `dist/` clean between recompiles) must not take the
        // running server down — the watcher reloads it when it comes back.
        await this._loadFromLocalFile(ctx, src.path, src.fetchTimeoutMs, { optional: true });
        try {
            // `metadata` carries the freshly parsed artifact collections so
            // subscribers can consume the ones that never reach the
            // MetadataManager (seeds under `data` have no `name`). AppPlugin
            // uses it to load seeds for objects that appear mid-run.
            await ctx.trigger('metadata:reloaded', { changed, metadata: this.lastParsedMetadata });
        } catch (e: any) {
            ctx.logger.warn('[MetadataPlugin] metadata:reloaded subscriber failed', { error: e?.message });
        }
    }

    /**
     * @param opts.optional When true, a LOCAL artifact file that does not exist
     *   is "nothing compiled yet" rather than a fault: log and return, leaving
     *   the manager empty and the artifact watcher armed so the first
     *   `os compile` hydrates the running server (#4085). Callers pass it for
     *   the `eager` / `lazy` bootstrap modes — the development-platform paths,
     *   where an app is optional. `artifact-only` (sealed runtime) does NOT:
     *   there the artifact IS the deployment, so its absence must fail loudly
     *   instead of silently serving an empty runtime. Only ENOENT is tolerated;
     *   a present-but-unreadable artifact (malformed JSON, bad permissions) and
     *   every remote-URL failure stay fatal.
     */
    private async _loadFromLocalFile(
        ctx: PluginContext,
        filePath: string,
        fetchTimeoutMs?: number,
        opts: { optional?: boolean } = {},
    ): Promise<void> {
        const isUrl = /^https?:\/\//i.test(filePath);
        ctx.logger.info(
            `[MetadataPlugin] Loading metadata from ${isUrl ? 'remote URL' : 'local artifact file'}`,
            { path: filePath },
        );

        let raw: unknown;
        try {
            if (isUrl) {
                raw = await this._fetchJson(filePath, fetchTimeoutMs);
            } else {
                const content = await readFile(filePath, 'utf8');
                raw = JSON.parse(content);
            }
        } catch (e: any) {
            if (opts.optional && !isUrl && e?.code === 'ENOENT') {
                ctx.logger.info(
                    '[MetadataPlugin] no compiled artifact yet — starting with no artifact metadata',
                    { path: filePath },
                );
                return;
            }
            throw new Error(`[MetadataPlugin] Cannot read artifact ${isUrl ? 'URL' : 'file'} at "${filePath}": ${e.message}`);
        }

        await this._parseAndRegisterArtifact(ctx, raw, filePath);
    }

    private async _loadFromFileSystem(ctx: PluginContext): Promise<void> {
        ctx.logger.info('Loading metadata from file system...');

        const sortedTypes = [...DEFAULT_METADATA_TYPE_REGISTRY]
            .sort((a, b) => a.loadOrder - b.loadOrder);

        let totalLoaded = 0;
        for (const entry of sortedTypes) {
            try {
                const items = await this.manager.loadMany(entry.type, {
                    recursive: true,
                    patterns: entry.filePatterns,
                });

                if (items.length > 0) {
                    for (const item of items) {
                        const meta = item as any;
                        if (meta?.name) {
                            // Stamp package provenance when the host declared
                            // its package id (see MetadataPluginOptions.packageId)
                            // — same applyProtection call the artifact path
                            // uses, so both load paths produce identical
                            // _packageId/_provenance state. No-op when the
                            // option is unset or the item is already stamped.
                            applyProtection(meta, {
                                packageId: this.options.packageId,
                            });
                            // Silent: boot-time priming, before any consumer
                            // has cached a definition to go stale. Post-boot
                            // edits to these files reach watchers through the
                            // FileSystemRepository attached by onEnable.
                            await this.manager.register(entry.type, meta.name, item, { notify: false });
                        }
                    }
                    ctx.logger.info(`Loaded ${items.length} ${entry.type} from file system`);
                    totalLoaded += items.length;
                }
            } catch (e: any) {
                ctx.logger.debug(`No ${entry.type} metadata found`, { error: e.message });
            }
        }

        ctx.logger.info('Metadata loading complete', {
            totalItems: totalLoaded,
            registeredTypes: sortedTypes.length,
        });
    }
}