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

package/dist/index.js

@@ -169,6 +169,10 @@ var init_hmr_routes = __esm({
 
 // src/metadata-manager.ts
 import { getMetadataTypeActions } from "@objectstack/spec/kernel";
+import {
+  MetadataEventType,
+  MetadataEventSchema
+} from "@objectstack/spec/api";
 import { createLogger } from "@objectstack/core";
 
 // src/serializers/json-serializer.ts
@@ -340,6 +344,8 @@ export default metadata;
 
 // src/loaders/database-loader.ts
 import { SysMetadataObject, SysMetadataHistoryObject } from "@objectstack/metadata-core";
+import { applyConversionsToStoredItem } from "@objectstack/spec";
+import { PLURAL_TO_SINGULAR } from "@objectstack/spec/shared";
 
 // src/utils/metadata-history-utils.ts
 async function calculateChecksum(metadata) {
@@ -505,6 +511,70 @@ var LRUCache = class {
   }
 };
 
+// src/utils/schema-sync-errors.ts
+var ALREADY_EXISTS = {
+  codes: /* @__PURE__ */ new Set([
+    // PostgreSQL SQLSTATE (class 42 — syntax error or access rule violation)
+    "42P07",
+    // duplicate_table
+    "42701",
+    // duplicate_column
+    "42710",
+    // duplicate_object — index / constraint already exists
+    // MySQL / MariaDB (mysql2 puts the symbolic name on `code`)
+    "ER_TABLE_EXISTS_ERROR",
+    // 1050
+    "ER_DUP_FIELDNAME",
+    // 1060
+    "ER_DUP_KEYNAME"
+    // 1061
+  ]),
+  errnos: /* @__PURE__ */ new Set([1050, 1060, 1061]),
+  /**
+   * Message fallback for drivers that carry no machine-readable code —
+   * notably SQLite, whose `code` is the undifferentiated `SQLITE_ERROR` for
+   * every DDL failure, so the message is the only signal available:
+   *   - `table sys_metadata already exists`
+   *   - `duplicate column name: environment_id`
+   *   - `index idx_x already exists`
+   * Postgres phrases its own as `relation "x" already exists` /
+   * `column "x" of relation "y" already exists`, which matches the same test.
+   */
+  message: /already exists|duplicate column name|duplicate key name/i
+};
+var MISSING_TABLE = {
+  codes: /* @__PURE__ */ new Set([
+    "42P01",
+    // PostgreSQL undefined_table
+    "ER_NO_SUCH_TABLE"
+    // MySQL / MariaDB 1146
+  ]),
+  errnos: /* @__PURE__ */ new Set([1146]),
+  /**
+   *   - SQLite / libsql: `no such table: sys_metadata_history`
+   *   - PostgreSQL:      `relation "sys_metadata_history" does not exist`
+   *   - MySQL/MariaDB:   `Table 'app.sys_metadata_history' doesn't exist`
+   */
+  message: /no such table|relation ["'`][^"'`]+["'`] does not exist|table ["'`][^"'`]+["'`] doesn'?t exist|unknown table/i
+};
+var MAX_CAUSE_DEPTH = 4;
+function matchesDriverError(error, signature, depth) {
+  if (error === null || error === void 0 || depth > MAX_CAUSE_DEPTH) return false;
+  if (typeof error === "string") return signature.message.test(error);
+  if (typeof error !== "object") return false;
+  const err = error;
+  if (typeof err.code === "string" && signature.codes.has(err.code)) return true;
+  if (typeof err.errno === "number" && signature.errnos.has(err.errno)) return true;
+  if (typeof err.message === "string" && signature.message.test(err.message)) return true;
+  return matchesDriverError(err.cause, signature, depth + 1);
+}
+function isSchemaAlreadyExistsError(error, depth = 0) {
+  return matchesDriverError(error, ALREADY_EXISTS, depth);
+}
+function isMissingTableError(error, depth = 0) {
+  return matchesDriverError(error, MISSING_TABLE, depth);
+}
+
 // src/migrations/add-sys-metadata-overlay-index.ts
 var INDEX_NAME = "idx_sys_metadata_overlay_active";
 var TABLE = "sys_metadata";
@@ -615,6 +685,25 @@ var DatabaseLoader = class {
     };
     this.schemaReady = false;
     this.historySchemaReady = false;
+    /**
+     * 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.
+     */
+    this.schemaFailureReported = false;
+    this.historySchemaFailureReported = false;
+    /**
+     * 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.
+     */
+    this.historySeqFailureReported = false;
+    /**
+     * 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.
+     */
+    this.storedConversionWarned = /* @__PURE__ */ new Set();
     if (!options.driver && !options.engine) {
       throw new Error("DatabaseLoader requires either a driver or engine");
     }
@@ -718,6 +807,24 @@ var DatabaseLoader = class {
    * 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.
    */
   async nextEventSeq() {
     const where = this.organizationId ? { organization_id: this.organizationId } : {};
@@ -729,8 +836,9 @@ var DatabaseLoader = class {
         if (v > max) max = v;
       }
       return max + 1;
-    } catch {
-      return 1;
+    } catch (error) {
+      if (isMissingTableError(error)) return 1;
+      throw error;
     }
   }
   /**
@@ -767,17 +875,32 @@ var DatabaseLoader = class {
         ...SysMetadataObject,
         name: this.tableName
       });
-      this.schemaReady = true;
-      try {
-        await migrateProjectIdToEnvironmentId(this.driver);
-      } catch {
-      }
-      try {
-        await addSysMetadataOverlayIndex(this.driver);
-      } catch {
+    } catch (error) {
+      if (!isSchemaAlreadyExistsError(error)) {
+        if (!this.schemaFailureReported) {
+          this.schemaFailureReported = true;
+          console.error(
+            `[Metadata] DDL for the metadata table \`${this.tableName}\` FAILED \u2014 its table/columns were NOT created or altered. Every metadata write from here on (Studio saves, app installs, org overlays) targets storage that may not exist: writes will error out, or silently drop columns on a lenient driver, while the server keeps reporting healthy. This is NOT the benign "already exists" case \u2014 check the datasource/driver error below (insufficient privileges, datasource not connected, incompatible column type), fix it and restart. Schema sync is retried on the next metadata operation, so a transient cause recovers on its own.`,
+            error
+          );
+        }
+        return;
       }
+    }
+    if (this.schemaFailureReported) {
+      this.schemaFailureReported = false;
+      console.info(
+        `[Metadata] DDL for the metadata table \`${this.tableName}\` succeeded on retry \u2014 metadata writes are durable again.`
+      );
+    }
+    this.schemaReady = true;
+    try {
+      await migrateProjectIdToEnvironmentId(this.driver);
+    } catch {
+    }
+    try {
+      await addSysMetadataOverlayIndex(this.driver);
     } catch {
-      this.schemaReady = true;
     }
   }
   /**
@@ -795,9 +918,25 @@ var DatabaseLoader = class {
         ...SysMetadataHistoryObject,
         name: this.historyTableName
       });
+      if (this.historySchemaFailureReported) {
+        this.historySchemaFailureReported = false;
+        console.info(
+          `[Metadata] DDL for the metadata history table \`${this.historyTableName}\` succeeded on retry \u2014 change history is being recorded again.`
+        );
+      }
       this.historySchemaReady = true;
     } catch (error) {
-      console.error("Failed to ensure history schema, will retry on next operation:", error);
+      if (isSchemaAlreadyExistsError(error)) {
+        this.historySchemaReady = true;
+        return;
+      }
+      if (!this.historySchemaFailureReported) {
+        this.historySchemaFailureReported = true;
+        console.error(
+          `[Metadata] DDL for the metadata history table \`${this.historyTableName}\` FAILED \u2014 its table/columns were NOT created. Metadata change history (versions, diffs, rollback) will NOT be persisted while every metadata write keeps succeeding, so the audit trail silently ends here. Fix the datasource/driver error below and restart; the sync is retried on the next metadata operation.`,
+          error
+        );
+      }
     }
   }
   /**
@@ -838,7 +977,25 @@ var DatabaseLoader = class {
     }
     const historyId = generateId();
     const metadataJson = JSON.stringify(metadata);
-    const eventSeq = await this.nextEventSeq();
+    let eventSeq;
+    try {
+      eventSeq = await this.nextEventSeq();
+    } catch (error) {
+      if (!this.historySeqFailureReported) {
+        this.historySeqFailureReported = true;
+        console.error(
+          `[Metadata] Could not read \`${this.historyTableName}\` to determine the next \`event_seq\` \u2014 the history entry for ${type}/${name} was NOT written, and further entries are being skipped while this persists. The metadata write itself SUCCEEDED, so the server keeps looking healthy while its change history silently develops holes: version timelines and rollback targets will be incomplete. The entry is skipped deliberately \u2014 numbering it from 1 (what this code did before #4825) would collide with existing rows and make \`event_seq\` ordering wrong rather than merely incomplete, which nothing detects and no restart repairs. Fix the datasource/driver error below (connection, timeout, privileges); the next metadata write retries and reports recovery.`,
+          error
+        );
+      }
+      return;
+    }
+    if (this.historySeqFailureReported) {
+      this.historySeqFailureReported = false;
+      console.info(
+        `[Metadata] \`${this.historyTableName}\` is readable again \u2014 \`event_seq\` numbering recovered and change history is being recorded again. Entries skipped during the outage are not backfilled.`
+      );
+    }
     const historyRecord = {
       id: historyId,
       name,
@@ -875,13 +1032,33 @@ var DatabaseLoader = class {
     }
   }
   /**
-   * Convert a database row to a metadata payload.
-   * Parses the JSON `metadata` column back into an object.
+   * 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`.
    */
   rowToData(row) {
     if (!row || !row.metadata) return null;
     const payload = typeof row.metadata === "string" ? JSON.parse(row.metadata) : row.metadata;
-    return payload;
+    const singular = PLURAL_TO_SINGULAR[row.type] ?? row.type;
+    if (singular === "flow") return payload;
+    return applyConversionsToStoredItem(singular, payload, {
+      onNotice: (n) => {
+        const key = `${n.conversionId}|${singular}|${String(row.name ?? "")}`;
+        if (this.storedConversionWarned.has(key)) return;
+        this.storedConversionWarned.add(key);
+        console.warn(
+          `[DatabaseLoader] stored ${singular}/${String(row.name ?? "<unnamed>")} carries a pre-protocol shape; ${n.message}`
+        );
+      }
+    });
   }
   /**
    * Convert a database row to a MetadataRecord-like object.
@@ -1275,6 +1452,17 @@ function generateId() {
 }
 
 // src/metadata-manager.ts
+function generateEventUuid() {
+  const c = globalThis.crypto;
+  if (c && typeof c.randomUUID === "function") {
+    return c.randomUUID();
+  }
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (ch) => {
+    const r = Math.random() * 16 | 0;
+    const v = ch === "x" ? r : r & 3 | 8;
+    return v.toString(16);
+  });
+}
 var _MetadataManager = class _MetadataManager {
   constructor(config) {
     this.loaders = /* @__PURE__ */ new Map();
@@ -1395,6 +1583,60 @@ var _MetadataManager = class _MetadataManager {
     this.realtimeService = service;
     this.logger.info("RealtimeService configured for metadata events");
   }
+  /**
+   * 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.
+   */
+  async publishRealtimeMetadataEvent(action, type, name, opts = {}) {
+    if (!this.realtimeService) return;
+    const eventType = `metadata.${type}.${action}`;
+    if (!MetadataEventType.options.includes(eventType)) {
+      this.logger.debug(
+        `Metadata type '${type}' has no declared realtime event type (MetadataEventType) \u2014 skipping publish`,
+        { eventType, name }
+      );
+      return;
+    }
+    try {
+      const event = MetadataEventSchema.parse({
+        id: generateEventUuid(),
+        type: eventType,
+        metadataType: type,
+        name,
+        ...typeof opts.packageId === "string" ? { packageId: opts.packageId } : {},
+        ...opts.definition !== void 0 ? { definition: opts.definition } : {},
+        ...opts.userId ? { userId: opts.userId } : {},
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      const envelope = {
+        type: event.type,
+        object: type,
+        payload: { ...event },
+        timestamp: event.timestamp
+      };
+      await this.realtimeService.publish(envelope);
+      this.logger.debug(`Published ${eventType} event`, { name });
+    } catch (error) {
+      this.logger.warn(`Failed to publish metadata event`, { type, name, error });
+    }
+  }
   /**
    * Register a new metadata loader (data source)
    */
@@ -1438,25 +1680,11 @@ var _MetadataManager = class _MetadataManager {
         await loader.save(type, name, data);
       }
     }
-    if (this.realtimeService) {
-      const event = {
-        type: `metadata.${type}.created`,
-        object: type,
-        payload: {
-          metadataType: type,
-          name,
-          definition: data,
-          packageId: data?.packageId
-        },
-        timestamp: (/* @__PURE__ */ new Date()).toISOString()
-      };
-      try {
-        await this.realtimeService.publish(event);
-        this.logger.debug(`Published metadata.${type}.created event`, { name });
-      } catch (error) {
-        this.logger.warn(`Failed to publish metadata event`, { type, name, error });
-      }
-    }
+    await this.publishRealtimeMetadataEvent(existed ? "updated" : "created", type, name, {
+      definition: data,
+      packageId: data?.packageId,
+      userId: options?.userId
+    });
     if (options?.notify !== false) {
       this.notifyWatchers(type, {
         type: existed ? "changed" : "added",
@@ -1570,23 +1798,9 @@ var _MetadataManager = class _MetadataManager {
         }
       }
     }
-    if (this.realtimeService) {
-      const event = {
-        type: `metadata.${type}.deleted`,
-        object: type,
-        payload: {
-          metadataType: type,
-          name
-        },
-        timestamp: (/* @__PURE__ */ new Date()).toISOString()
-      };
-      try {
-        await this.realtimeService.publish(event);
-        this.logger.debug(`Published metadata.${type}.deleted event`, { name });
-      } catch (error) {
-        this.logger.warn(`Failed to publish metadata event`, { type, name, error });
-      }
-    }
+    await this.publishRealtimeMetadataEvent("deleted", type, name, {
+      userId: options?.userId
+    });
     if (options?.notify !== false) {
       this.notifyWatchers(type, {
         type: "deleted",
@@ -2296,19 +2510,44 @@ var _MetadataManager = class _MetadataManager {
   /**
    * 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.
    */
   async load(type, name, options) {
+    return (await this.loadDiagnosed(type, name, options)).data;
+  }
+  /**
+   * `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.
+   */
+  async loadDiagnosed(type, name, options) {
+    const errors = [];
     for (const loader of this.loaders.values()) {
       try {
         const result = await loader.load(type, name, options);
         if (result.data) {
-          return result.data;
+          return { data: result.data, degraded: false, errors };
         }
       } catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        errors.push(`${loader.contract.name}: ${message}`);
         this.logger.warn(`Loader ${loader.contract.name} failed to load ${type}:${name}`, { error: e });
       }
     }
-    return null;
+    return { data: null, degraded: errors.length > 0, errors };
   }
   /**
    * Load multiple metadata items from loaders.
@@ -3256,6 +3495,20 @@ var MetadataPlugin = class {
     this.name = "com.objectstack.metadata";
     this.type = "standard";
     this.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.
+     */
+    this.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).
+     */
+    this.optionalDependencies = ["com.objectstack.engine.objectql"];
     this.init = async (ctx) => {
       ctx.logger.info("Initializing Metadata Manager", {
         root: this.options.rootDir || process.cwd(),
@@ -3295,27 +3548,27 @@ var MetadataPlugin = class {
         bootstrap: mode,
         artifactSource: src?.mode ?? "none"
       });
+      if (src && src.mode !== "local-file") {
+        const bad = src.mode;
+        throw new Error(
+          `[MetadataPlugin] artifactSource.mode '${bad}' is not supported` + (bad === "artifact-api" ? " \u2014 the 'artifact-api' source was removed (#4246). 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") {
-        if (src?.mode === "local-file") {
+        if (src) {
           await this._loadFromLocalFile(ctx, src.path, src.fetchTimeoutMs);
-        } else if (src?.mode === "artifact-api") {
-          await this._loadFromArtifactApi(ctx, src);
         } else {
           throw new Error("[MetadataPlugin] bootstrap=artifact-only requires options.artifactSource to be set");
         }
       } else if (mode === "lazy") {
-        if (src?.mode === "local-file") {
-          await this._loadFromLocalFile(ctx, src.path, src.fetchTimeoutMs);
-        } else if (src?.mode === "artifact-api") {
-          await this._loadFromArtifactApi(ctx, src);
+        if (src) {
+          await this._loadFromLocalFile(ctx, src.path, src.fetchTimeoutMs, { optional: true });
         } else {
           ctx.logger.info("[MetadataPlugin] lazy bootstrap \u2014 skipping filesystem priming; metadata loads on demand");
         }
       } else {
-        if (src?.mode === "local-file") {
-          await this._loadFromLocalFile(ctx, src.path, src.fetchTimeoutMs);
-        } else if (src?.mode === "artifact-api") {
-          await this._loadFromArtifactApi(ctx, src);
+        if (src) {
+          await this._loadFromLocalFile(ctx, src.path, src.fetchTimeoutMs, { optional: true });
         } else {
           await this._loadFromFileSystem(ctx);
         }
@@ -3357,7 +3610,14 @@ var MetadataPlugin = class {
         });
       }
       try {
-        const httpServer = ctx.getService("http-server") ?? ctx.getService("http.server");
+        const readServer = (name) => {
+          try {
+            return ctx.getService(name);
+          } catch {
+            return void 0;
+          }
+        };
+        const httpServer = readServer("http.server") ?? readServer("http-server");
         if (httpServer && typeof httpServer.getRawApp === "function") {
           const { registerMetadataHmrRoutes: registerMetadataHmrRoutes2 } = await Promise.resolve().then(() => (init_hmr_routes(), hmr_routes_exports));
           const hub = registerMetadataHmrRoutes2(httpServer.getRawApp(), this.manager);
@@ -3470,14 +3730,13 @@ var MetadataPlugin = class {
   /**
    * Fetch JSON content from a URL with configurable timeout.
    */
-  async _fetchJson(url, fetchTimeoutMs, token) {
+  async _fetchJson(url, fetchTimeoutMs) {
     const envTimeout = Number(process.env.OS_ARTIFACT_FETCH_TIMEOUT_MS);
     const timeoutMs = fetchTimeoutMs ?? (Number.isFinite(envTimeout) && envTimeout > 0 ? envTimeout : void 0) ?? 6e4;
     const controller = new AbortController();
     const timer = timeoutMs > 0 ? setTimeout(() => controller.abort(), timeoutMs) : void 0;
     try {
       const headers = { Accept: "application/json, */*;q=0.5" };
-      if (token) headers.Authorization = `Bearer ${token}`;
       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();
@@ -3597,14 +3856,26 @@ var MetadataPlugin = class {
    * logged but never blocks the reload.
    */
   async _reloadAndAnnounce(ctx, src, changed) {
-    await this._loadFromLocalFile(ctx, src.path, src.fetchTimeoutMs);
+    await this._loadFromLocalFile(ctx, src.path, src.fetchTimeoutMs, { optional: true });
     try {
       await ctx.trigger("metadata:reloaded", { changed, metadata: this.lastParsedMetadata });
     } catch (e) {
       ctx.logger.warn("[MetadataPlugin] metadata:reloaded subscriber failed", { error: e?.message });
     }
   }
-  async _loadFromLocalFile(ctx, filePath, fetchTimeoutMs) {
+  /**
+   * @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.
+   */
+  async _loadFromLocalFile(ctx, filePath, fetchTimeoutMs, opts = {}) {
     const isUrl = /^https?:\/\//i.test(filePath);
     ctx.logger.info(
       `[MetadataPlugin] Loading metadata from ${isUrl ? "remote URL" : "local artifact file"}`,
@@ -3619,34 +3890,17 @@ var MetadataPlugin = class {
         raw = JSON.parse(content);
       }
     } catch (e) {
+      if (opts.optional && !isUrl && e?.code === "ENOENT") {
+        ctx.logger.info(
+          "[MetadataPlugin] no compiled artifact yet \u2014 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);
   }
-  /**
-   * P2: Load metadata from the cloud artifact API endpoint.
-   */
-  async _loadFromArtifactApi(ctx, src) {
-    const environmentId = this.options.environmentId;
-    if (!environmentId) {
-      throw new Error("[MetadataPlugin] artifact-api source requires options.environmentId to be set");
-    }
-    let artifactUrl = src.url.replace(/\/+$/, "");
-    if (!/\/api\/v\d+\/cloud\/projects\//i.test(artifactUrl)) {
-      artifactUrl = `${artifactUrl}/api/v1/cloud/environments/${environmentId}/artifact`;
-    }
-    if (src.commitId) {
-      artifactUrl += `${artifactUrl.includes("?") ? "&" : "?"}commit=${encodeURIComponent(src.commitId)}`;
-    }
-    ctx.logger.info("[MetadataPlugin] Loading metadata from artifact API", { url: artifactUrl });
-    let raw;
-    try {
-      raw = await this._fetchJson(artifactUrl, src.fetchTimeoutMs, src.token);
-    } catch (e) {
-      throw new Error(`[MetadataPlugin] Cannot load artifact from API "${artifactUrl}": ${e.message}`);
-    }
-    await this._parseAndRegisterArtifact(ctx, raw, artifactUrl);
-  }
   async _loadFromFileSystem(ctx) {
     ctx.logger.info("Loading metadata from file system...");
     const sortedTypes = [...DEFAULT_METADATA_TYPE_REGISTRY].sort((a, b) => a.loadOrder - b.loadOrder);