@objectstack/metadata 17.0.0-rc.0 → 17.0.0-rc.2

package/dist/index.d.cts

@@ -1,8 +1,8 @@
 import * as System from '@objectstack/spec/system';
 import { MetadataFormat, MetadataLoaderContract, MetadataLoadOptions, MetadataLoadResult, MetadataStats, MetadataSaveOptions, MetadataSaveResult, MetadataWatchEvent, MetadataManagerConfig, PackagePublishResult, MetadataHistoryQueryOptions, MetadataHistoryQueryResult, MetadataDiffResult, MetadataHistoryRecord, MetadataHistoryRetentionPolicy } from '@objectstack/spec/system';
-export { MetadataCollectionInfo, MetadataDiffResult, MetadataExportOptions, MetadataFormat, MetadataHistoryQueryOptions, MetadataHistoryQueryResult, MetadataHistoryRecord, MetadataHistoryRetentionPolicy, MetadataImportOptions, MetadataLoadOptions, MetadataLoadResult, MetadataLoaderContract, MetadataManagerConfig, MetadataSaveOptions, MetadataSaveResult, MetadataStats, MetadataWatchEvent } from '@objectstack/spec/system';
+export { MetadataCollectionInfo, MetadataDiffResult, MetadataFormat, MetadataHistoryQueryOptions, MetadataHistoryQueryResult, MetadataHistoryRecord, MetadataHistoryRetentionPolicy, MetadataLoadOptions, MetadataLoadResult, MetadataLoaderContract, MetadataManagerConfig, MetadataSaveOptions, MetadataSaveResult, MetadataStats, MetadataWatchEvent } from '@objectstack/spec/system';
 import { IMetadataService, IDataDriver, IDataEngine, IRealtimeService, MetadataWriteOptions, MetadataWatchCallback, MetadataWatchHandle, MetadataExportOptions, MetadataImportOptions, MetadataImportResult, MetadataTypeInfo, IPubSub, ISchemaDriver } from '@objectstack/spec/contracts';
-export { IMetadataService, MetadataImportResult, MetadataTypeInfo, MetadataWatchCallback, MetadataWatchHandle } from '@objectstack/spec/contracts';
+export { IMetadataService, MetadataExportOptions, MetadataImportOptions, MetadataImportResult, MetadataTypeInfo, MetadataWatchCallback, MetadataWatchHandle } from '@objectstack/spec/contracts';
 import { MetadataTypeRegistryEntry, MetadataQuery, MetadataQueryResult, MetadataBulkResult, MetadataOverlay, MetadataValidationResult, MetadataDependency, MetadataPluginConfig } from '@objectstack/spec/kernel';
 export { MetadataBulkResult, MetadataDependency, MetadataPluginConfig, MetadataPluginManifest, MetadataQuery, MetadataQueryResult, MetadataType, MetadataTypeRegistryEntry, MetadataValidationResult } from '@objectstack/spec/kernel';
 import { Logger, Plugin, PluginContext } from '@objectstack/core';
@@ -199,6 +199,28 @@ declare class MetadataManager implements IMetadataService {
      * @param service - An IRealtimeService instance for event publishing
      */
     setRealtimeService(service: IRealtimeService): void;
+    /**
+     * Publish a realtime {@link RealtimeMetadataEvent} for a metadata write
+     * (#4602 — contract-first).
+     *
+     * What reaches a `subscribeMetadata` callback must BE the spec's
+     * `MetadataEvent` (`@objectstack/spec/api`): `id` (uuid) at the top level,
+     * flattened `metadataType`/`name`/`definition`, `userId` when the write
+     * carried an actor. The transport keeps its `RealtimeEventPayload`
+     * envelope — `payload` carries the complete `MetadataEvent`, and the client
+     * SDK unwraps + validates it at the boundary.
+     *
+     * Two loud-by-design gates:
+     *  - `MetadataEventType` is a CLOSED enum. A metadata type outside it has
+     *    no declared realtime event contract, so we skip publishing (debug log)
+     *    instead of emitting an event every compliant consumer must reject.
+     *    Declared = enforced; widening coverage means widening the spec enum,
+     *    not producing off-contract events.
+     *  - The event body is `MetadataEventSchema.parse`d before publish, so a
+     *    malformed producer fails here (warn log, event not published) rather
+     *    than delivering a lie downstream.
+     */
+    private publishRealtimeMetadataEvent;
     /**
      * Register a new metadata loader (data source)
      */
@@ -444,8 +466,32 @@ declare class MetadataManager implements IMetadataService {
     /**
      * Load a single metadata item from loaders.
      * Iterates through registered loaders until found.
+     *
+     * Returns `null` both when no loader HAS the item and when every loader
+     * FAILED — see {@link loadDiagnosed} when the caller must tell those apart.
      */
     load<T = any>(type: string, name: string, options?: MetadataLoadOptions): Promise<T | null>;
+    /**
+     * `load`, plus whether the answer can be trusted as complete.
+     *
+     * [ADR-0110 D3] A miss and an outage are different facts with opposite
+     * security meanings, and plain `load` cannot express the difference: a
+     * loader that throws is warn-logged and skipped, so a database the metadata
+     * plane cannot reach returns the same `null` as a name that was never
+     * declared. Callers that gate on a declaration MUST NOT read that `null` as
+     * "the author declared no gate" — an availability failure would silently
+     * widen access (the REST `/actions` route's fail-open branch, #3935).
+     *
+     * `degraded` is true when at least one loader threw AND no loader answered
+     * with the item. The posture is deliberately conservative: with a loader
+     * down we cannot prove the item is absent, so we decline to claim it is.
+     * A clean miss (every loader answered, none had it) is NOT degraded.
+     */
+    loadDiagnosed<T = any>(type: string, name: string, options?: MetadataLoadOptions): Promise<{
+        data: T | null;
+        degraded: boolean;
+        errors: string[];
+    }>;
     /**
      * Load multiple metadata items from loaders.
      * Aggregates results from all loaders.
@@ -568,23 +614,38 @@ interface MetadataPluginOptions {
     config?: Partial<MetadataPluginConfig>;
     /** Organization ID for metadata-scoped consumers; MetadataPlugin itself does not persist runtime metadata. */
     organizationId?: string;
-    /** Project ID used by local artifact envelopes and metadata-scoped consumers. */
+    /**
+     * 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 an artifact instead of scanning
-     * the filesystem. Only `local-file` is implemented now; `artifact-api` is
-     * reserved for M3/M4.
+     * 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;
-    } | {
-        mode: 'artifact-api';
-        url: string;
-        token?: string;
-        commitId?: string;
-        fetchTimeoutMs?: number;
     };
     /**
      * Register the `sys_metadata` + `sys_metadata_history` storage objects
@@ -615,6 +676,20 @@ declare class MetadataPlugin implements Plugin {
     name: string;
     type: string;
     version: string;
+    /**
+     * Services init() UNCONDITIONALLY registers (ADR-0116, #4131) — lets the
+     * kernel name this plugin when a consumer requires `metadata` before it
+     * initializes.
+     */
+    providesServices: string[];
+    /**
+     * 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: string[];
     private manager;
     private options;
     private repository?;
@@ -663,11 +738,19 @@ declare class MetadataPlugin implements Plugin {
      * logged but never blocks the reload.
      */
     private _reloadAndAnnounce;
-    private _loadFromLocalFile;
     /**
-     * P2: Load metadata from the cloud artifact API endpoint.
+     * @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 _loadFromArtifactApi;
+    private _loadFromLocalFile;
     private _loadFromFileSystem;
 }
 
@@ -844,6 +927,19 @@ declare class DatabaseLoader implements MetadataLoader {
     private trackHistory;
     private schemaReady;
     private historySchemaReady;
+    /**
+     * Whether the loud "DDL failed" report has already been printed for the
+     * metadata table / history table respectively. AGENTS.md → "Degradation log
+     * levels": say it **once**, at the first degradation, not once per retry.
+     */
+    private schemaFailureReported;
+    private historySchemaFailureReported;
+    /**
+     * Same once-only discipline for the #4825 seam: the history table is readable
+     * or it is not, and repeating the report per skipped write turns a real
+     * degradation into noise people learn to skim.
+     */
+    private historySeqFailureReported;
     /** (type, name) → metadata payload — primes `load()` */
     private readonly loadCache?;
     /** type → array of payloads — primes `loadMany()` */
@@ -881,6 +977,24 @@ declare class DatabaseLoader implements MetadataLoader {
      * Reads `MAX(event_seq) + 1` for the configured `organization_id`.
      * Legacy path — not transactional, so concurrent writes can collide.
      * The canonical (transactional) producer is `SysMetadataRepository`.
+     *
+     * #4825 (same shape as #4728, rule from #4632) — discriminate by error TYPE.
+     * This used to `catch { return 1 }`, with a comment that named BOTH reasons a
+     * read can fail and then answered both the same way. Exactly one of them is
+     * benign: the history table has not been provisioned, so there is no row to
+     * be inconsistent with and 1 genuinely IS the next number. Every other reason
+     * — connection drop, timeout, insufficient privileges — means the rows are
+     * still there and simply were not seen, and answering 1 against a table with
+     * N rows **collides with existing rows**: the insert succeeds, the log stays
+     * empty, and `event_seq` (the ordering key that history listing and rollback
+     * targeting both stand on) is silently wrong from then on. Note this is the
+     * costlier half of the #4728 family — not bytes that never landed, but bytes
+     * that landed *wrong*, which no retry and no restart repairs.
+     *
+     * @throws The underlying driver error, unchanged, for every non-benign read
+     *         failure. Deliberate: a sequence number this method cannot derive
+     *         from data it actually read is not a number it may invent. The
+     *         caller ({@link createHistoryRecord}) owns the consequence.
      */
     private nextEventSeq;
     /**
@@ -915,8 +1029,23 @@ declare class DatabaseLoader implements MetadataLoader {
      */
     private createHistoryRecord;
     /**
-     * Convert a database row to a metadata payload.
-     * Parses the JSON `metadata` column back into an object.
+     * Once-per-process dedupe for stored-row conversion notices — `load` /
+     * `loadMany` are hot read paths (cached, but re-hit on every TTL expiry),
+     * so a legacy row must warn once, not once per cache miss.
+     */
+    private storedConversionWarned;
+    /**
+     * Convert a LIVE database row to a metadata payload.
+     *
+     * Parses the JSON `metadata` column back into an object, then replays the
+     * full ADR-0087 conversion chain over it (#3903): rows written under a past
+     * protocol are served canonical, exactly like the metadata-protocol's
+     * `sys_metadata` seams. History rows do NOT pass through here — history
+     * readers parse inline and stay verbatim, as a record of what was written.
+     *
+     * `flow` is skipped for the same reason the protocol skips it: flow-node
+     * conversions need the automation engine's live executor registry for their
+     * open-namespace conflict guard; flows canonicalize at `registerFlow`.
      */
     private rowToData;
     /**

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import * as System from '@objectstack/spec/system';
 import { MetadataFormat, MetadataLoaderContract, MetadataLoadOptions, MetadataLoadResult, MetadataStats, MetadataSaveOptions, MetadataSaveResult, MetadataWatchEvent, MetadataManagerConfig, PackagePublishResult, MetadataHistoryQueryOptions, MetadataHistoryQueryResult, MetadataDiffResult, MetadataHistoryRecord, MetadataHistoryRetentionPolicy } from '@objectstack/spec/system';
-export { MetadataCollectionInfo, MetadataDiffResult, MetadataExportOptions, MetadataFormat, MetadataHistoryQueryOptions, MetadataHistoryQueryResult, MetadataHistoryRecord, MetadataHistoryRetentionPolicy, MetadataImportOptions, MetadataLoadOptions, MetadataLoadResult, MetadataLoaderContract, MetadataManagerConfig, MetadataSaveOptions, MetadataSaveResult, MetadataStats, MetadataWatchEvent } from '@objectstack/spec/system';
+export { MetadataCollectionInfo, MetadataDiffResult, MetadataFormat, MetadataHistoryQueryOptions, MetadataHistoryQueryResult, MetadataHistoryRecord, MetadataHistoryRetentionPolicy, MetadataLoadOptions, MetadataLoadResult, MetadataLoaderContract, MetadataManagerConfig, MetadataSaveOptions, MetadataSaveResult, MetadataStats, MetadataWatchEvent } from '@objectstack/spec/system';
 import { IMetadataService, IDataDriver, IDataEngine, IRealtimeService, MetadataWriteOptions, MetadataWatchCallback, MetadataWatchHandle, MetadataExportOptions, MetadataImportOptions, MetadataImportResult, MetadataTypeInfo, IPubSub, ISchemaDriver } from '@objectstack/spec/contracts';
-export { IMetadataService, MetadataImportResult, MetadataTypeInfo, MetadataWatchCallback, MetadataWatchHandle } from '@objectstack/spec/contracts';
+export { IMetadataService, MetadataExportOptions, MetadataImportOptions, MetadataImportResult, MetadataTypeInfo, MetadataWatchCallback, MetadataWatchHandle } from '@objectstack/spec/contracts';
 import { MetadataTypeRegistryEntry, MetadataQuery, MetadataQueryResult, MetadataBulkResult, MetadataOverlay, MetadataValidationResult, MetadataDependency, MetadataPluginConfig } from '@objectstack/spec/kernel';
 export { MetadataBulkResult, MetadataDependency, MetadataPluginConfig, MetadataPluginManifest, MetadataQuery, MetadataQueryResult, MetadataType, MetadataTypeRegistryEntry, MetadataValidationResult } from '@objectstack/spec/kernel';
 import { Logger, Plugin, PluginContext } from '@objectstack/core';
@@ -199,6 +199,28 @@ declare class MetadataManager implements IMetadataService {
      * @param service - An IRealtimeService instance for event publishing
      */
     setRealtimeService(service: IRealtimeService): void;
+    /**
+     * Publish a realtime {@link RealtimeMetadataEvent} for a metadata write
+     * (#4602 — contract-first).
+     *
+     * What reaches a `subscribeMetadata` callback must BE the spec's
+     * `MetadataEvent` (`@objectstack/spec/api`): `id` (uuid) at the top level,
+     * flattened `metadataType`/`name`/`definition`, `userId` when the write
+     * carried an actor. The transport keeps its `RealtimeEventPayload`
+     * envelope — `payload` carries the complete `MetadataEvent`, and the client
+     * SDK unwraps + validates it at the boundary.
+     *
+     * Two loud-by-design gates:
+     *  - `MetadataEventType` is a CLOSED enum. A metadata type outside it has
+     *    no declared realtime event contract, so we skip publishing (debug log)
+     *    instead of emitting an event every compliant consumer must reject.
+     *    Declared = enforced; widening coverage means widening the spec enum,
+     *    not producing off-contract events.
+     *  - The event body is `MetadataEventSchema.parse`d before publish, so a
+     *    malformed producer fails here (warn log, event not published) rather
+     *    than delivering a lie downstream.
+     */
+    private publishRealtimeMetadataEvent;
     /**
      * Register a new metadata loader (data source)
      */
@@ -444,8 +466,32 @@ declare class MetadataManager implements IMetadataService {
     /**
      * Load a single metadata item from loaders.
      * Iterates through registered loaders until found.
+     *
+     * Returns `null` both when no loader HAS the item and when every loader
+     * FAILED — see {@link loadDiagnosed} when the caller must tell those apart.
      */
     load<T = any>(type: string, name: string, options?: MetadataLoadOptions): Promise<T | null>;
+    /**
+     * `load`, plus whether the answer can be trusted as complete.
+     *
+     * [ADR-0110 D3] A miss and an outage are different facts with opposite
+     * security meanings, and plain `load` cannot express the difference: a
+     * loader that throws is warn-logged and skipped, so a database the metadata
+     * plane cannot reach returns the same `null` as a name that was never
+     * declared. Callers that gate on a declaration MUST NOT read that `null` as
+     * "the author declared no gate" — an availability failure would silently
+     * widen access (the REST `/actions` route's fail-open branch, #3935).
+     *
+     * `degraded` is true when at least one loader threw AND no loader answered
+     * with the item. The posture is deliberately conservative: with a loader
+     * down we cannot prove the item is absent, so we decline to claim it is.
+     * A clean miss (every loader answered, none had it) is NOT degraded.
+     */
+    loadDiagnosed<T = any>(type: string, name: string, options?: MetadataLoadOptions): Promise<{
+        data: T | null;
+        degraded: boolean;
+        errors: string[];
+    }>;
     /**
      * Load multiple metadata items from loaders.
      * Aggregates results from all loaders.
@@ -568,23 +614,38 @@ interface MetadataPluginOptions {
     config?: Partial<MetadataPluginConfig>;
     /** Organization ID for metadata-scoped consumers; MetadataPlugin itself does not persist runtime metadata. */
     organizationId?: string;
-    /** Project ID used by local artifact envelopes and metadata-scoped consumers. */
+    /**
+     * 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 an artifact instead of scanning
-     * the filesystem. Only `local-file` is implemented now; `artifact-api` is
-     * reserved for M3/M4.
+     * 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;
-    } | {
-        mode: 'artifact-api';
-        url: string;
-        token?: string;
-        commitId?: string;
-        fetchTimeoutMs?: number;
     };
     /**
      * Register the `sys_metadata` + `sys_metadata_history` storage objects
@@ -615,6 +676,20 @@ declare class MetadataPlugin implements Plugin {
     name: string;
     type: string;
     version: string;
+    /**
+     * Services init() UNCONDITIONALLY registers (ADR-0116, #4131) — lets the
+     * kernel name this plugin when a consumer requires `metadata` before it
+     * initializes.
+     */
+    providesServices: string[];
+    /**
+     * 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: string[];
     private manager;
     private options;
     private repository?;
@@ -663,11 +738,19 @@ declare class MetadataPlugin implements Plugin {
      * logged but never blocks the reload.
      */
     private _reloadAndAnnounce;
-    private _loadFromLocalFile;
     /**
-     * P2: Load metadata from the cloud artifact API endpoint.
+     * @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 _loadFromArtifactApi;
+    private _loadFromLocalFile;
     private _loadFromFileSystem;
 }
 
@@ -844,6 +927,19 @@ declare class DatabaseLoader implements MetadataLoader {
     private trackHistory;
     private schemaReady;
     private historySchemaReady;
+    /**
+     * Whether the loud "DDL failed" report has already been printed for the
+     * metadata table / history table respectively. AGENTS.md → "Degradation log
+     * levels": say it **once**, at the first degradation, not once per retry.
+     */
+    private schemaFailureReported;
+    private historySchemaFailureReported;
+    /**
+     * Same once-only discipline for the #4825 seam: the history table is readable
+     * or it is not, and repeating the report per skipped write turns a real
+     * degradation into noise people learn to skim.
+     */
+    private historySeqFailureReported;
     /** (type, name) → metadata payload — primes `load()` */
     private readonly loadCache?;
     /** type → array of payloads — primes `loadMany()` */
@@ -881,6 +977,24 @@ declare class DatabaseLoader implements MetadataLoader {
      * Reads `MAX(event_seq) + 1` for the configured `organization_id`.
      * Legacy path — not transactional, so concurrent writes can collide.
      * The canonical (transactional) producer is `SysMetadataRepository`.
+     *
+     * #4825 (same shape as #4728, rule from #4632) — discriminate by error TYPE.
+     * This used to `catch { return 1 }`, with a comment that named BOTH reasons a
+     * read can fail and then answered both the same way. Exactly one of them is
+     * benign: the history table has not been provisioned, so there is no row to
+     * be inconsistent with and 1 genuinely IS the next number. Every other reason
+     * — connection drop, timeout, insufficient privileges — means the rows are
+     * still there and simply were not seen, and answering 1 against a table with
+     * N rows **collides with existing rows**: the insert succeeds, the log stays
+     * empty, and `event_seq` (the ordering key that history listing and rollback
+     * targeting both stand on) is silently wrong from then on. Note this is the
+     * costlier half of the #4728 family — not bytes that never landed, but bytes
+     * that landed *wrong*, which no retry and no restart repairs.
+     *
+     * @throws The underlying driver error, unchanged, for every non-benign read
+     *         failure. Deliberate: a sequence number this method cannot derive
+     *         from data it actually read is not a number it may invent. The
+     *         caller ({@link createHistoryRecord}) owns the consequence.
      */
     private nextEventSeq;
     /**
@@ -915,8 +1029,23 @@ declare class DatabaseLoader implements MetadataLoader {
      */
     private createHistoryRecord;
     /**
-     * Convert a database row to a metadata payload.
-     * Parses the JSON `metadata` column back into an object.
+     * Once-per-process dedupe for stored-row conversion notices — `load` /
+     * `loadMany` are hot read paths (cached, but re-hit on every TTL expiry),
+     * so a legacy row must warn once, not once per cache miss.
+     */
+    private storedConversionWarned;
+    /**
+     * Convert a LIVE database row to a metadata payload.
+     *
+     * Parses the JSON `metadata` column back into an object, then replays the
+     * full ADR-0087 conversion chain over it (#3903): rows written under a past
+     * protocol are served canonical, exactly like the metadata-protocol's
+     * `sys_metadata` seams. History rows do NOT pass through here — history
+     * readers parse inline and stay verbatim, as a record of what was written.
+     *
+     * `flow` is skipped for the same reason the protocol skips it: flow-node
+     * conversions need the automation engine's live executor registry for their
+     * open-namespace conflict guard; flows canonicalize at `registerFlow`.
      */
     private rowToData;
     /**