@forgeax/engine-assets-runtime 0.1.2

package/dist/index.mjs

@@ -0,0 +1,1240 @@
+import { ok, err, AssetError, ASSET_ERROR_HINTS } from '@forgeax/engine-types';
+
+// src/asset-kind.ts
+function defineAssetKind(kind) {
+  return Object.freeze({ kind });
+}
+function createCatalogSource(options) {
+  const entries = options.entries;
+  return {
+    async enumerate() {
+      if (entries !== void 0) {
+        if (options.expectedRevision === void 0) return ok(entries);
+        const actualRevisions = entries.flatMap(
+          (entry) => entry.revision === void 0 ? [] : [entry.revision]
+        );
+        const matches = actualRevisions.length > 0 && actualRevisions.every(
+          (revision) => revision.digest === options.expectedRevision?.digest && revision.observedAt === options.expectedRevision?.observedAt && revision.rootId === options.expectedRevision?.rootId
+        );
+        if (!matches) {
+          return err(
+            new AssetError({
+              code: "asset-parse-failed",
+              expected: "static catalog entries to carry the expected producer revision",
+              hint: "restore a verified catalog revision before applying the source",
+              detail: { expectedRevision: options.expectedRevision, actualRevisions }
+            })
+          );
+        }
+        return ok(entries);
+      }
+      if (options.url === void 0) {
+        return err(
+          new AssetError({
+            code: "catalog-source-unconfigured",
+            expected: "a configured catalog source",
+            hint: ASSET_ERROR_HINTS["catalog-source-unconfigured"]
+          })
+        );
+      }
+      const response = await (options.fetch ?? globalThis.fetch)(options.url);
+      if (!response.ok) {
+        return err(
+          new AssetError({
+            code: "asset-fetch-failed",
+            expected: "the configured Catalog URL to return HTTP 200",
+            hint: "verify the producer Catalog URL and republish the current snapshot",
+            detail: { sourcePath: options.url }
+          })
+        );
+      }
+      let raw;
+      try {
+        raw = await response.json();
+      } catch {
+        return err(
+          new AssetError({
+            code: "asset-parse-failed",
+            expected: "the configured Catalog URL to return JSON",
+            hint: "repair the producer Catalog before loading the current publication"
+          })
+        );
+      }
+      const rows = scopedRows(raw, options.expectedScope);
+      if (!rows.ok) return rows;
+      const result = rows.value.map((row) => ({ ...row }));
+      return ok(result);
+    },
+    subscribe(listener) {
+      return options.subscribe?.(listener) ?? (() => {
+      });
+    },
+    ...options.expectedScope === void 0 ? {} : { expectedScope: options.expectedScope }
+  };
+}
+function scopedRows(raw, expectedScope) {
+  if (Array.isArray(raw)) return ok(raw);
+  if (raw === null || typeof raw !== "object") return parseRowsError("Catalog JSON rows");
+  const snapshot = raw;
+  if (!Array.isArray(snapshot.entries)) return parseRowsError("Catalog JSON entries");
+  if (expectedScope !== void 0) {
+    if (snapshot.scopeId !== expectedScope.scopeId || snapshot.generation !== expectedScope.generation || snapshot.authority !== "authoritative") {
+      return err(
+        new AssetError({
+          code: "asset-parse-failed",
+          expected: "the Catalog snapshot to match the active scope and generation",
+          hint: "restore the authoritative producer Catalog for the active runtime scope",
+          detail: {
+            expectedScope,
+            actualScope: { scopeId: snapshot.scopeId, generation: snapshot.generation }
+          }
+        })
+      );
+    }
+  }
+  return ok(snapshot.entries);
+}
+function parseRowsError(expected) {
+  return err(
+    new AssetError({
+      code: "asset-parse-failed",
+      expected,
+      hint: "repair the producer Catalog before loading the current publication"
+    })
+  );
+}
+
+// src/internal/artifact-cache.ts
+var ArtifactCache = class {
+  values = /* @__PURE__ */ new Map();
+  pending = /* @__PURE__ */ new Map();
+  hits = 0;
+  misses = 0;
+  read(contentAddress, reader) {
+    const value = this.values.get(contentAddress);
+    if (value !== void 0) {
+      this.hits += 1;
+      return Promise.resolve({ ok: true, value: new Uint8Array(value) });
+    }
+    const pending = this.pending.get(contentAddress);
+    if (pending !== void 0) {
+      this.hits += 1;
+      return pending;
+    }
+    this.misses += 1;
+    const request = Promise.resolve().then(reader).then((result) => {
+      if (result.ok) this.values.set(contentAddress, new Uint8Array(result.value));
+      return result;
+    }).finally(() => {
+      if (this.pending.get(contentAddress) === request) this.pending.delete(contentAddress);
+    });
+    this.pending.set(contentAddress, request);
+    return request;
+  }
+  clear(contentAddress) {
+    if (contentAddress === void 0) {
+      this.values.clear();
+      this.pending.clear();
+      return;
+    }
+    this.values.delete(contentAddress);
+    this.pending.delete(contentAddress);
+  }
+  snapshot() {
+    return Object.freeze({
+      entries: this.values.size,
+      pending: this.pending.size,
+      hits: this.hits,
+      misses: this.misses
+    });
+  }
+};
+
+// src/internal/immutable-payload.ts
+function freezeRuntimePayload(value) {
+  const seen = /* @__PURE__ */ new WeakSet();
+  return freeze(value, seen);
+}
+function freeze(value, seen) {
+  if (value === null || typeof value !== "object") return value;
+  if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) return value;
+  if (seen.has(value)) return value;
+  seen.add(value);
+  for (const child of Object.values(value)) freeze(child, seen);
+  return Object.freeze(value);
+}
+
+// src/internal/asset-graph.ts
+function cancelled(guid) {
+  return {
+    code: "asset-load-cancelled",
+    expected: "the request AbortSignal to remain live until asset closure completes",
+    hint: "retry with a live AbortSignal when the request is still needed",
+    detail: { guid }
+  };
+}
+function disposed(scopeId = "asset-runtime") {
+  return {
+    code: "asset-runtime-disposed",
+    expected: "an active asset runtime scope",
+    hint: "obtain a new Registry from the current realm",
+    detail: { scopeId }
+  };
+}
+function superseded(guid, generation) {
+  return {
+    code: "asset-superseded",
+    expected: "the load ticket to remain current until promotion",
+    hint: "load the current publication after the Catalog change",
+    detail: { guid, generation }
+  };
+}
+function thrown(guid) {
+  return {
+    code: "asset-decode-failed",
+    expected: "the graph reader to return a Result",
+    hint: "repair the owner reader and retry the current publication",
+    detail: { guid, kind: "asset-graph-reader" }
+  };
+}
+function freezeSnapshot(snapshot) {
+  return Object.freeze({
+    ...snapshot,
+    ready: Object.freeze([...snapshot.ready]),
+    sccs: Object.freeze(snapshot.sccs.map((scc) => Object.freeze([...scc]))),
+    counters: Object.freeze({ ...snapshot.counters })
+  });
+}
+var AssetGraph = class {
+  read;
+  limit;
+  ready = /* @__PURE__ */ new Map();
+  forward = /* @__PURE__ */ new Map();
+  reverse = /* @__PURE__ */ new Map();
+  reads = /* @__PURE__ */ new Map();
+  requests = /* @__PURE__ */ new Map();
+  listeners = /* @__PURE__ */ new Set();
+  sccs = [];
+  activeReads = 0;
+  readWaiters = [];
+  disposed = false;
+  epoch = 0;
+  counters = {
+    loads: 0,
+    cacheHits: 0,
+    readErrors: 0,
+    noChange: 0,
+    listenerFailures: 0
+  };
+  currentSnapshot;
+  constructor(options) {
+    this.read = options.read;
+    this.limit = Math.max(1, Math.floor(options.maxConcurrentReads ?? 8));
+    this.currentSnapshot = freezeSnapshot({
+      epoch: 0,
+      ready: [],
+      pending: 0,
+      resources: 0,
+      sccs: [],
+      counters: this.counters
+    });
+  }
+  load(guid, signal = new AbortController().signal) {
+    const canonicalGuid = guid.toLowerCase();
+    if (this.disposed) return Promise.resolve(err(disposed()));
+    if (signal.aborted) return Promise.resolve(err(cancelled(canonicalGuid)));
+    const cached = this.ready.get(canonicalGuid);
+    if (cached !== void 0) {
+      this.counters = {
+        ...this.counters,
+        cacheHits: this.counters.cacheHits + 1,
+        noChange: this.counters.noChange + 1
+      };
+      this.publish();
+      return Promise.resolve(ok(cached));
+    }
+    const existing = this.requests.get(canonicalGuid);
+    if (existing !== void 0) {
+      this.counters = { ...this.counters, cacheHits: this.counters.cacheHits + 1 };
+      return existing;
+    }
+    this.counters = { ...this.counters, loads: this.counters.loads + 1 };
+    const ticketEpoch = this.epoch;
+    const request = this.loadClosure(canonicalGuid, signal, ticketEpoch).finally(() => {
+      if (this.requests.get(canonicalGuid) === request) this.requests.delete(canonicalGuid);
+      this.publish();
+    });
+    this.requests.set(canonicalGuid, request);
+    this.publish();
+    return request;
+  }
+  invalidate(guid) {
+    const affected = this.collectAffected([guid.toLowerCase()]);
+    this.drop(affected);
+    this.epoch += 1;
+    this.publish();
+    return [...affected].sort();
+  }
+  invalidateForCatalogChange(guids) {
+    if (this.disposed) return;
+    const affected = guids === void 0 || guids.length === 0 ? /* @__PURE__ */ new Set([...this.ready.keys(), ...this.requests.keys(), ...this.reads.keys()]) : this.collectAffected(guids.map((item) => item.toLowerCase()));
+    this.drop(affected);
+    this.epoch += 1;
+    this.publish();
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  snapshot() {
+    return this.currentSnapshot;
+  }
+  lookup(guid) {
+    return this.ready.get(guid.toLowerCase())?.value;
+  }
+  guidOf(value) {
+    for (const [guid, entry] of this.ready) {
+      if (entry.value === value) return guid;
+    }
+    return void 0;
+  }
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.epoch += 1;
+    this.ready.clear();
+    this.forward.clear();
+    this.reverse.clear();
+    this.reads.clear();
+    const waiters = this.readWaiters;
+    this.readWaiters = [];
+    for (const resolve of waiters) resolve();
+    this.publish();
+  }
+  async loadClosure(root, signal, ticketEpoch) {
+    const values = /* @__PURE__ */ new Map();
+    const visiting = /* @__PURE__ */ new Set();
+    const visited = /* @__PURE__ */ new Set();
+    const group = /* @__PURE__ */ new Set();
+    const result = await this.visit(root, signal, visiting, visited, values, group);
+    if (!result.ok) return result;
+    if (this.disposed) return err(disposed());
+    if (signal.aborted) return err(cancelled(root));
+    if (ticketEpoch !== this.epoch) return err(superseded(root, ticketEpoch));
+    for (const [guid, value] of values) this.promote(guid, value);
+    this.recordScc();
+    return ok(values.get(root));
+  }
+  async visit(guid, signal, visiting, visited, values, group) {
+    if (visiting.has(guid)) {
+      group.add(guid);
+      return ok({ value: void 0, refs: [] });
+    }
+    if (visited.has(guid)) return ok(values.get(guid));
+    const cached = this.ready.get(guid);
+    if (cached !== void 0) {
+      values.set(guid, cached);
+      visited.add(guid);
+      return ok(cached);
+    }
+    visiting.add(guid);
+    const read = await this.readOnce(guid, signal);
+    if (!read.ok) {
+      visiting.delete(guid);
+      return read;
+    }
+    values.set(guid, read.value);
+    group.add(guid);
+    this.link(guid, read.value.refs);
+    for (const ref of read.value.refs) {
+      const child = await this.visit(ref, signal, visiting, visited, values, group);
+      if (!child.ok) {
+        visiting.delete(guid);
+        return err({
+          code: "asset-dependency-failed",
+          expected: "every referenced asset to load successfully",
+          hint: "repair the dependency publication and retry the root asset",
+          detail: { guid, dependencyGuid: ref }
+        });
+      }
+    }
+    visiting.delete(guid);
+    visited.add(guid);
+    return ok(read.value);
+  }
+  readOnce(guid, signal) {
+    const existing = this.reads.get(guid);
+    if (existing !== void 0) return existing;
+    const request = this.withPermit(async () => {
+      if (this.disposed) return err(disposed());
+      if (signal.aborted) return err(cancelled(guid));
+      try {
+        const result = await this.read(guid, signal);
+        if (signal.aborted) return err(cancelled(guid));
+        if (!result.ok)
+          this.counters = { ...this.counters, readErrors: this.counters.readErrors + 1 };
+        return result;
+      } catch {
+        this.counters = { ...this.counters, readErrors: this.counters.readErrors + 1 };
+        return err(thrown(guid));
+      }
+    });
+    this.reads.set(guid, request);
+    void request.finally(() => {
+      if (this.reads.get(guid) === request) this.reads.delete(guid);
+    });
+    return request;
+  }
+  async withPermit(operation) {
+    if (this.activeReads >= this.limit) {
+      await new Promise((resolve) => this.readWaiters.push(resolve));
+    }
+    this.activeReads += 1;
+    try {
+      return await operation();
+    } finally {
+      this.activeReads -= 1;
+      this.readWaiters.shift()?.();
+    }
+  }
+  link(guid, refs) {
+    const previous = this.forward.get(guid) ?? /* @__PURE__ */ new Set();
+    for (const ref of previous) this.reverse.get(ref)?.delete(guid);
+    const next = new Set(refs.map((ref) => ref.toLowerCase()));
+    this.forward.set(guid, next);
+    for (const ref of next) {
+      const dependents = this.reverse.get(ref) ?? /* @__PURE__ */ new Set();
+      dependents.add(guid);
+      this.reverse.set(ref, dependents);
+    }
+  }
+  collectAffected(guids) {
+    const affected = /* @__PURE__ */ new Set();
+    const queue = [...guids];
+    while (queue.length > 0) {
+      const current = queue.shift();
+      if (current === void 0 || affected.has(current)) continue;
+      affected.add(current);
+      for (const dependent of this.reverse.get(current) ?? []) queue.push(dependent);
+    }
+    return affected;
+  }
+  drop(affected) {
+    for (const item of affected) {
+      for (const ref of this.forward.get(item) ?? []) this.reverse.get(ref)?.delete(item);
+      for (const dependent of this.reverse.get(item) ?? []) {
+        this.forward.get(dependent)?.delete(item);
+      }
+    }
+    for (const item of affected) {
+      this.ready.delete(item);
+      this.requests.delete(item);
+      this.reads.delete(item);
+      this.forward.delete(item);
+      this.reverse.delete(item);
+    }
+    this.sccs.splice(0, this.sccs.length);
+  }
+  promote(guid, value) {
+    if (value === void 0) return;
+    this.ready.set(
+      guid,
+      Object.freeze({
+        ...value,
+        value: freezeRuntimePayload(value.value),
+        refs: Object.freeze([...value.refs])
+      })
+    );
+  }
+  recordScc() {
+    const indexByGuid = /* @__PURE__ */ new Map();
+    const lowByGuid = /* @__PURE__ */ new Map();
+    const stack = [];
+    const onStack = /* @__PURE__ */ new Set();
+    let nextIndex = 0;
+    const components = [];
+    const visit = (guid) => {
+      indexByGuid.set(guid, nextIndex);
+      lowByGuid.set(guid, nextIndex);
+      nextIndex += 1;
+      stack.push(guid);
+      onStack.add(guid);
+      for (const ref of this.forward.get(guid) ?? []) {
+        if (!indexByGuid.has(ref)) {
+          visit(ref);
+          lowByGuid.set(guid, Math.min(lowByGuid.get(guid) ?? 0, lowByGuid.get(ref) ?? 0));
+        } else if (onStack.has(ref)) {
+          lowByGuid.set(guid, Math.min(lowByGuid.get(guid) ?? 0, indexByGuid.get(ref) ?? 0));
+        }
+      }
+      if (lowByGuid.get(guid) !== indexByGuid.get(guid)) return;
+      const component = [];
+      let member;
+      do {
+        member = stack.pop();
+        if (member === void 0) break;
+        onStack.delete(member);
+        component.push(member);
+      } while (member !== guid);
+      if (component.length > 1 || this.forward.get(guid)?.has(guid) === true)
+        components.push(component.sort());
+    };
+    for (const guid of this.forward.keys()) if (!indexByGuid.has(guid)) visit(guid);
+    this.sccs.splice(
+      0,
+      this.sccs.length,
+      ...components.map((component) => Object.freeze(component))
+    );
+  }
+  publish() {
+    this.currentSnapshot = freezeSnapshot({
+      epoch: this.epoch,
+      ready: [...this.ready.keys()].sort(),
+      pending: this.requests.size + this.reads.size,
+      resources: this.ready.size,
+      sccs: this.sccs,
+      counters: this.counters
+    });
+    for (const listener of [...this.listeners]) {
+      try {
+        listener(this.currentSnapshot);
+      } catch {
+        this.counters = {
+          ...this.counters,
+          listenerFailures: Math.min(1024, this.counters.listenerFailures + 1)
+        };
+        this.currentSnapshot = freezeSnapshot({
+          ...this.currentSnapshot,
+          counters: this.counters
+        });
+      }
+    }
+  }
+};
+function invalidRow(guid, reason) {
+  return err({
+    code: "asset-package-invalid",
+    expected: "one complete current runtime Catalog row",
+    hint: "rebuild the producer Catalog and publish one Pack v2 tuple",
+    detail: { guid, reason }
+  });
+}
+function validateRuntimeRow(row) {
+  if (row === null || typeof row !== "object") return invalidRow("", "row");
+  const candidate = row;
+  const guid = typeof candidate.guid === "string" ? candidate.guid : "";
+  if (guid.trim().length === 0) return invalidRow(guid, "guid");
+  if (typeof candidate.kind !== "string" || candidate.kind.trim().length === 0)
+    return invalidRow(guid, "kind");
+  if (typeof candidate.packageUrl !== "string" || candidate.packageUrl.trim().length === 0)
+    return invalidRow(guid, "packageUrl");
+  if (typeof candidate.sourcePath !== "string" || candidate.sourcePath.trim().length === 0)
+    return invalidRow(guid, "sourcePath");
+  if (!Number.isSafeInteger(candidate.publication?.generation))
+    return invalidRow(guid, "publication generation");
+  if (candidate.publication === void 0) return invalidRow(guid, "publication");
+  const publication = candidate.publication;
+  if (publication.schemaVersion !== "asset-publication/1" || typeof publication.sourcePath !== "string" || publication.sourcePath.trim().length === 0 || typeof publication.sourceRevision !== "string" || publication.sourceRevision.trim().length === 0 || publication.generation < 0 || typeof publication.digest !== "string" || publication.digest.trim().length === 0 || typeof publication.outputSetDigest !== "string" || publication.outputSetDigest.trim().length === 0 || !Array.isArray(publication.outputs) || publication.receipt === null || typeof publication.receipt !== "object" || !Array.isArray(publication.externalEvidence)) {
+    return invalidRow(guid, "publication tuple");
+  }
+  return ok(Object.freeze({ ...candidate, guid, publication }));
+}
+
+// src/internal/catalog-session.ts
+function runtimeError(code, guid, detail) {
+  if (code === "catalog-discontinuous") {
+    return {
+      code,
+      expected: "an ordered catalog revision window",
+      hint: "reconcile the current Catalog before consuming this delta",
+      detail: {
+        scopeId: String(detail.scopeId ?? "unknown"),
+        expectedGeneration: Number(detail.expectedGeneration ?? 0),
+        actualGeneration: Number(detail.actualGeneration ?? 0)
+      }
+    };
+  }
+  return {
+    code: "asset-package-invalid",
+    expected: "a verified Catalog source",
+    hint: "repair the producer Catalog and retry with the current publication",
+    detail: { guid, reason: String(detail.reason ?? "catalog source failed") }
+  };
+}
+function freezeSnapshot2(snapshot) {
+  return Object.freeze({
+    ...snapshot,
+    entries: Object.freeze([...snapshot.entries]),
+    changed: Object.freeze([...snapshot.changed]),
+    removed: Object.freeze([...snapshot.removed]),
+    diagnostics: Object.freeze([...snapshot.diagnostics])
+  });
+}
+function sameEntry(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+function key(guid) {
+  return guid.toLowerCase();
+}
+var CatalogSession = class {
+  source;
+  scopeId;
+  generation;
+  entries = /* @__PURE__ */ new Map();
+  listeners = /* @__PURE__ */ new Set();
+  unsubscribe;
+  baselinePromise;
+  reconcilePromise;
+  pending = [];
+  currentSnapshot;
+  revision;
+  diagnostics = [];
+  listenerFailures = 0;
+  changed = /* @__PURE__ */ new Set();
+  removed = /* @__PURE__ */ new Set();
+  epoch = 0;
+  stale = false;
+  staleGeneration = 0;
+  started = false;
+  disposed = false;
+  constructor(source, options = {}) {
+    this.source = source;
+    this.scopeId = options.scopeId ?? source.expectedScope?.scopeId ?? "asset-runtime";
+    this.generation = options.generation ?? source.expectedScope?.generation ?? 0;
+    this.currentSnapshot = freezeSnapshot2({
+      scopeId: this.scopeId,
+      generation: this.generation,
+      epoch: 0,
+      entries: [],
+      changed: [],
+      removed: [],
+      diagnostics: [],
+      listenerFailures: 0,
+      stale: false
+    });
+  }
+  start() {
+    if (this.baselinePromise !== void 0) return this.baselinePromise;
+    if (this.disposed) return Promise.resolve(err(this.disposedError()));
+    this.unsubscribe = this.source.subscribe((delta) => this.receive(delta));
+    const promise = this.source.enumerate().then((result) => {
+      if (!result.ok) {
+        this.markStale();
+        this.publish();
+        return err(runtimeError("asset-package-invalid", "", { reason: result.error.code }));
+      }
+      this.entries.clear();
+      for (const entry of result.value) {
+        const validated = validateRuntimeRow(entry);
+        if (!validated.ok) {
+          this.markStale();
+          this.publish();
+          return err(validated.error);
+        }
+        this.entries.set(key(validated.value.guid), validated.value);
+      }
+      this.started = true;
+      this.stale = false;
+      this.staleGeneration = this.generation;
+      this.diagnostics = [];
+      for (const delta of this.pending) this.fold(delta, false);
+      this.pending = [];
+      this.publish();
+      return ok(this.currentSnapshot);
+    }).catch((cause) => {
+      this.markStale();
+      this.addDiagnostic("catalog-degraded-rows", "Catalog enumeration must resolve a Result");
+      this.publish();
+      return err(
+        runtimeError("asset-package-invalid", "", {
+          reason: cause instanceof Error ? cause.message : String(cause)
+        })
+      );
+    });
+    this.baselinePromise = promise;
+    void promise.then(
+      (result) => {
+        if (!result.ok) this.baselinePromise = void 0;
+      },
+      () => {
+        this.baselinePromise = void 0;
+      }
+    );
+    return promise;
+  }
+  reconcile() {
+    if (this.disposed) return Promise.resolve(err(this.disposedError()));
+    if (this.reconcilePromise !== void 0) return this.reconcilePromise;
+    this.unsubscribe?.();
+    this.unsubscribe = void 0;
+    this.started = false;
+    this.pending = [];
+    this.baselinePromise = void 0;
+    this.epoch += 1;
+    const promise = this.start();
+    this.reconcilePromise = promise;
+    void promise.then(
+      () => {
+        if (this.reconcilePromise === promise) this.reconcilePromise = void 0;
+      },
+      () => {
+        if (this.reconcilePromise === promise) this.reconcilePromise = void 0;
+      }
+    );
+    return promise;
+  }
+  current(guid) {
+    return this.entries.get(key(guid));
+  }
+  snapshot() {
+    return this.currentSnapshot;
+  }
+  discontinuity() {
+    if (!this.stale) return void 0;
+    return {
+      code: "catalog-discontinuous",
+      expected: "an ordered, authoritative catalog revision window",
+      hint: "reconcile the Catalog source and retry the current publication",
+      detail: {
+        scopeId: this.scopeId,
+        expectedGeneration: this.generation,
+        actualGeneration: this.staleGeneration
+      }
+    };
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.unsubscribe?.();
+    this.unsubscribe = void 0;
+    this.pending = [];
+    this.listeners.clear();
+  }
+  receive(delta) {
+    if (this.disposed) return;
+    if (!this.started) {
+      this.pending.push(delta);
+      return;
+    }
+    this.fold(delta, true);
+  }
+  fold(delta, publish) {
+    if (delta.scopeId !== void 0 && delta.scopeId !== this.scopeId || delta.generation !== void 0 && delta.generation !== this.generation) {
+      this.markStale(delta.generation);
+      this.addDiagnostic("catalog-scope-mismatch", "delta scope does not match the session");
+      if (publish) this.publish();
+      return;
+    }
+    if (delta.authority === "degraded") {
+      this.markStale(delta.generation);
+      this.addDiagnostic("catalog-degraded-rows", "degraded rows are not identity-bearing");
+      if (publish) this.publish();
+      return;
+    }
+    if (delta.revisions !== void 0) {
+      const baseline = delta.revisions.baseline;
+      const current = delta.revisions.current;
+      const valid = baseline.length === current.length && current.every((point) => {
+        const prior = baseline.find((item) => item.rootId === point.rootId);
+        return prior !== void 0 && point.revision === prior.revision + 1;
+      });
+      if (!valid) {
+        this.markStale(delta.generation);
+        this.addDiagnostic("catalog-gap", "delta revision window is not contiguous");
+        if (publish) this.publish();
+        return;
+      }
+    }
+    let changed = false;
+    for (const entry of [...delta.added, ...delta.changed]) {
+      const validated = validateRuntimeRow(entry);
+      if (!validated.ok) {
+        this.markStale(delta.generation);
+        this.addDiagnostic("catalog-degraded-rows", "delta contains an invalid runtime row");
+        if (publish) this.publish();
+        return;
+      }
+      const entryKey = key(validated.value.guid);
+      const prior = this.entries.get(entryKey);
+      if (prior === void 0 || !sameEntry(prior, validated.value)) {
+        this.entries.set(entryKey, validated.value);
+        this.changed.add(entryKey);
+        changed = true;
+        if (validated.value.revision !== void 0) this.revision = validated.value.revision;
+      }
+    }
+    for (const guid of delta.removed) {
+      const entryKey = key(guid);
+      if (this.entries.delete(entryKey)) {
+        this.removed.add(entryKey);
+        changed = true;
+      }
+    }
+    if (changed) this.epoch += 1;
+    if (publish) this.publish();
+  }
+  addDiagnostic(code, expected) {
+    if (this.diagnostics.some((diagnostic) => diagnostic.code === code)) return;
+    this.diagnostics.push({
+      code,
+      severity: "blocking",
+      expected,
+      hint: "reconcile the Catalog before loading the affected publication",
+      authority: "catalog"
+    });
+  }
+  markStale(actualGeneration = this.generation) {
+    this.stale = true;
+    this.staleGeneration = actualGeneration;
+    this.epoch += 1;
+  }
+  publish() {
+    this.currentSnapshot = freezeSnapshot2({
+      scopeId: this.scopeId,
+      generation: this.generation,
+      epoch: this.epoch,
+      ...this.revision === void 0 ? {} : { revision: this.revision },
+      entries: [...this.entries.values()].sort(
+        (left, right) => key(left.guid).localeCompare(key(right.guid))
+      ),
+      changed: [...this.changed].sort(),
+      removed: [...this.removed].sort(),
+      diagnostics: this.diagnostics,
+      listenerFailures: this.listenerFailures,
+      stale: this.stale
+    });
+    this.changed.clear();
+    this.removed.clear();
+    for (const listener of [...this.listeners]) {
+      try {
+        listener(this.currentSnapshot);
+      } catch {
+        this.listenerFailures = Math.min(1024, this.listenerFailures + 1);
+        this.currentSnapshot = freezeSnapshot2({
+          ...this.currentSnapshot,
+          listenerFailures: this.listenerFailures
+        });
+      }
+    }
+  }
+  disposedError() {
+    return runtimeError("asset-runtime-disposed", "", { scopeId: this.scopeId });
+  }
+};
+var DecoderRegistry = class {
+  dispatch = /* @__PURE__ */ new Map();
+  scopeId;
+  disposed = false;
+  constructor(options = {}) {
+    this.scopeId = options.scopeId ?? "asset-runtime";
+  }
+  install(kind, decoder) {
+    if (this.disposed) throw new TypeError("asset runtime decoder registry is disposed");
+    const normalizedDecoder = decoder;
+    const existing = this.dispatch.get(kind.kind);
+    if (existing !== void 0) {
+      if (existing.decoder !== normalizedDecoder) {
+        throw new TypeError(`duplicate decoder kind "${kind.kind}"`);
+      }
+      existing.references += 1;
+      return this.createLease(kind.kind, existing);
+    }
+    const identity = Symbol(kind.kind);
+    const entry = {
+      identity,
+      decoder: normalizedDecoder,
+      decode: (input) => decoder.decode(input),
+      references: 1
+    };
+    this.dispatch.set(kind.kind, entry);
+    return this.createLease(kind.kind, entry);
+  }
+  createLease(kind, entry) {
+    let released = false;
+    return {
+      kind,
+      dispose: () => {
+        if (released) return;
+        released = true;
+        entry.references -= 1;
+        if (entry.references === 0 && this.dispatch.get(kind)?.identity === entry.identity) {
+          this.dispatch.delete(kind);
+        }
+      }
+    };
+  }
+  has(kind) {
+    return this.dispatch.has(kind.kind);
+  }
+  load(kind, input) {
+    return this.decode(kind, input);
+  }
+  loadByKind(kind, input) {
+    if (this.disposed) return Promise.resolve(err(disposedError(this.scopeId)));
+    const entry = this.dispatch.get(kind);
+    if (entry === void 0) {
+      return Promise.resolve(
+        err({
+          code: "asset-decoder-missing",
+          expected: `an active decoder for kind "${kind}"`,
+          hint: "install the owner decoder lease before loading this kind",
+          detail: { kind }
+        })
+      );
+    }
+    return this.decodeEntry(kind, entry, input);
+  }
+  async decode(kind, input) {
+    if (this.disposed) return err(disposedError(this.scopeId));
+    if (input.signal.aborted) return err(cancelledError(input.envelope.guid));
+    const entry = this.dispatch.get(kind.kind);
+    if (entry === void 0) {
+      return err({
+        code: "asset-decoder-missing",
+        expected: `an active decoder for kind "${kind.kind}"`,
+        hint: "install the owner decoder lease before loading this kind",
+        detail: { kind: kind.kind }
+      });
+    }
+    return await this.decodeEntry(kind.kind, entry, input);
+  }
+  async decodeEntry(kind, entry, input) {
+    if (this.disposed) return err(disposedError(this.scopeId));
+    if (input.signal.aborted) return err(cancelledError(input.envelope.guid));
+    try {
+      const result = await entry.decode(input);
+      if (this.disposed) return err(disposedError(this.scopeId));
+      if (this.dispatch.get(kind)?.identity !== entry.identity) {
+        return err(supersededError(input.envelope.guid, kind));
+      }
+      if (input.signal.aborted) return err(cancelledError(input.envelope.guid));
+      return result.ok ? ok(freezeRuntimePayload(result.value)) : result;
+    } catch {
+      return err({
+        code: "asset-decode-failed",
+        expected: `decoder for kind "${kind}" to return a Result`,
+        hint: "inspect the owner decoder and retry the current publication",
+        detail: { guid: input.envelope.guid, kind }
+      });
+    }
+  }
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.dispatch.clear();
+  }
+};
+function cancelledError(guid) {
+  return {
+    code: "asset-load-cancelled",
+    expected: "the request AbortSignal to remain live until decode completes",
+    hint: "retry with a live AbortSignal when the request is still needed",
+    detail: { guid }
+  };
+}
+function disposedError(scopeId) {
+  return {
+    code: "asset-runtime-disposed",
+    expected: "an active asset runtime decoder scope",
+    hint: "obtain a new Registry from the current realm",
+    detail: { scopeId }
+  };
+}
+function supersededError(guid, kind) {
+  return {
+    code: "asset-superseded",
+    expected: `the decoder lease for kind "${kind}" to remain current until decode completes`,
+    hint: "retry the current publication after reinstalling its owner decoder",
+    detail: { guid, generation: 0 }
+  };
+}
+function invalid(guid, reason) {
+  return err({
+    code: "asset-package-invalid",
+    expected: "a verified Pack v2 envelope with complete runtime artifacts",
+    hint: "re-cook the Pack v2 publication and retry the current tuple",
+    detail: { guid, reason }
+  });
+}
+function frozen(value) {
+  if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const child of Object.values(value)) frozen(child);
+  }
+  return value;
+}
+function sameTuple(left, right) {
+  return left.scopeId === right.scopeId && left.generation === right.generation && left.digest === right.digest && left.outputSetDigest === right.outputSetDigest;
+}
+var PackReader = class {
+  fetcher;
+  verified = /* @__PURE__ */ new Map();
+  pending = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    this.fetcher = options.fetcher?.bind(globalThis);
+  }
+  async read(packageUrl, expected, signal) {
+    if (signal.aborted) return err(this.cancelled(packageUrl));
+    const key2 = this.key(packageUrl, expected);
+    const cached = this.verified.get(key2);
+    if (cached !== void 0) return ok(cached);
+    const active = this.pending.get(key2);
+    if (active !== void 0) return active;
+    const request = this.fetchAndVerify(packageUrl, expected, signal);
+    this.pending.set(key2, request);
+    const result = await request;
+    this.pending.delete(key2);
+    if (result.ok) this.verified.set(key2, result.value);
+    return result;
+  }
+  async fetchAndVerify(packageUrl, expected, signal) {
+    let response;
+    try {
+      const fetcher = this.fetcher ?? globalThis.fetch.bind(globalThis);
+      response = await fetcher(packageUrl, { signal });
+    } catch (_cause) {
+      if (signal.aborted) return err(this.cancelled(packageUrl));
+      return err({
+        code: "asset-fetch-failed",
+        expected: "HTTP 200 for the current Pack URL",
+        hint: "verify the package locator and republish the Pack",
+        detail: { guid: packageUrl, packageUrl }
+      });
+    }
+    if (!response.ok) {
+      return err({
+        code: "asset-fetch-failed",
+        expected: "HTTP 200 for the current Pack URL",
+        hint: "verify the package locator and republish the Pack",
+        detail: { guid: packageUrl, packageUrl }
+      });
+    }
+    let value;
+    try {
+      value = await response.json();
+    } catch {
+      return invalid(packageUrl, "invalid JSON");
+    }
+    return this.verify(value, expected);
+  }
+  key(packageUrl, tuple) {
+    return `${packageUrl}\0${tuple.scopeId}\0${tuple.generation}\0${tuple.digest}\0${tuple.outputSetDigest}`;
+  }
+  verify(value, expected) {
+    if (value === null || typeof value !== "object") return invalid("", "Pack is not an object");
+    const pack = value;
+    if (pack.schemaVersion !== "2.0.0" || pack.kind !== "internal-text-package") {
+      return invalid("", "schemaVersion or kind");
+    }
+    if (typeof pack.scopeId !== "string" || !Number.isSafeInteger(pack.generation) || typeof pack.digest !== "string" || typeof pack.outputSetDigest !== "string" || !sameTuple(pack, expected)) {
+      return invalid("", "publication tuple mismatch");
+    }
+    if (!Array.isArray(pack.assets)) return invalid("", "assets");
+    const guids = /* @__PURE__ */ new Set();
+    for (const raw of pack.assets) {
+      const asset = raw;
+      const guid = typeof asset.guid === "string" ? asset.guid : "";
+      if (guid.length === 0 || guids.has(guid.toLowerCase()))
+        return invalid(guid, "duplicate guid");
+      guids.add(guid.toLowerCase());
+      if (typeof asset.kind !== "string" || asset.payload === void 0 || !Array.isArray(asset.refs) || asset.refs.some((ref) => typeof ref !== "string") || asset.artifacts === null || typeof asset.artifacts !== "object") {
+        return invalid(guid, "asset envelope fields");
+      }
+      for (const [artifactKey, descriptor] of Object.entries(asset.artifacts)) {
+        if (!this.validArtifact(guid, artifactKey, descriptor)) {
+          return invalid(guid, `artifact ${artifactKey}`);
+        }
+      }
+    }
+    return ok(frozen(pack));
+  }
+  validArtifact(_guid, key2, value) {
+    if (value === null || typeof value !== "object") return false;
+    const descriptor = value;
+    const integrity = descriptor.integrity;
+    return key2.length > 0 && typeof descriptor.path === "string" && descriptor.path.length > 0 && typeof descriptor.mediaType === "string" && descriptor.mediaType.length > 0 && (descriptor.contentEncoding === "identity" || descriptor.contentEncoding === "zstd") && Number.isSafeInteger(descriptor.byteLength) && Number(descriptor.byteLength) >= 0 && integrity !== null && typeof integrity === "object" && integrity.algorithm === "sha256" && typeof integrity.digest === "string" && /^sha256:[0-9a-f]{64}$/i.test(String(integrity.digest));
+  }
+  cancelled(guid) {
+    return {
+      code: "asset-load-cancelled",
+      expected: "the request AbortSignal to remain live while reading the Pack",
+      hint: "retry with a live AbortSignal when the request is still needed",
+      detail: { guid }
+    };
+  }
+};
+
+// src/internal/load-asset.ts
+var REGISTRY_RESOLVER = /* @__PURE__ */ Symbol.for("forgeax.assets-runtime.registry-resolver");
+function missing(guid) {
+  return {
+    code: "asset-not-found",
+    expected: `the current Catalog to contain GUID "${guid}"`,
+    hint: "inspect the producer Catalog and rebuild the missing publication",
+    detail: { guid }
+  };
+}
+function mismatch(guid, expectedKind, actualKind) {
+  return {
+    code: "asset-kind-mismatch",
+    expected: `Catalog kind "${actualKind}" to match "${expectedKind}"`,
+    hint: "pass the Catalog kind or the matching custom AssetKind token",
+    detail: { guid, expectedKind, actualKind }
+  };
+}
+function artifactError(guid, reason) {
+  return {
+    code: "asset-integrity-failed",
+    expected: "the verified artifact byte length and digest",
+    hint: "verify the artifact digest and recook the Pack",
+    detail: {
+      guid,
+      artifactKey: reason,
+      expectedDigest: "descriptor integrity",
+      actualDigest: reason
+    }
+  };
+}
+var ASSET_GUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function invalidGuid(guid) {
+  return {
+    code: "asset-guid-invalid",
+    expected: "a 36-character dash-form asset GUID",
+    hint: "pass the producer GUID from the current Catalog row",
+    detail: { guid }
+  };
+}
+function createAssetRegistry(options) {
+  const session = new CatalogSession(options.catalog, options);
+  const reader = new PackReader(options.fetcher === void 0 ? {} : { fetcher: options.fetcher });
+  const cache = new ArtifactCache();
+  const decoders = new DecoderRegistry(
+    options.scopeId === void 0 ? {} : { scopeId: options.scopeId }
+  );
+  const graph = new AssetGraph({
+    ...options.maxConcurrentReads === void 0 ? {} : { maxConcurrentReads: options.maxConcurrentReads },
+    read: async (guid, signal) => {
+      const row = session.current(guid);
+      if (row === void 0) return err(missing(guid));
+      const validated = validateRuntimeRow(row);
+      if (!validated.ok) return validated;
+      const publication = validated.value.publication;
+      const tuple = {
+        scopeId: session.snapshot().scopeId,
+        generation: publication.generation,
+        digest: publication.digest,
+        outputSetDigest: publication.outputSetDigest
+      };
+      const pack = await reader.read(row.packageUrl, tuple, signal);
+      if (!pack.ok) return pack;
+      const envelope = pack.value.assets.find(
+        (asset) => asset.guid.toLowerCase() === guid.toLowerCase()
+      );
+      if (envelope === void 0) return err(missing(guid));
+      const artifacts = {
+        read: (descriptor) => {
+          const integrity = descriptor.integrity;
+          if (integrity === void 0)
+            return Promise.resolve(err(artifactError(guid, descriptor.path)));
+          const key2 = `${tuple.scopeId}:${tuple.generation}:${tuple.outputSetDigest}:${integrity.digest}`;
+          return cache.read(key2, async () => {
+            const url = resolveArtifactUrl(row.packageUrl, descriptor.path);
+            let response;
+            try {
+              response = await (options.fetcher ?? globalThis.fetch)(url, { signal });
+            } catch {
+              return err(artifactError(guid, descriptor.path));
+            }
+            if (!response.ok) return err(artifactError(guid, descriptor.path));
+            const bytes = new Uint8Array(await response.arrayBuffer());
+            if (descriptor.byteLength === void 0 || bytes.byteLength !== descriptor.byteLength) {
+              return err(artifactError(guid, descriptor.path));
+            }
+            const actualDigest = await sha256(bytes);
+            if (actualDigest !== descriptor.integrity?.digest.toLowerCase()) {
+              return err(artifactError(guid, `${descriptor.path}:${actualDigest}`));
+            }
+            return ok(bytes);
+          });
+        }
+      };
+      const input = { envelope, artifacts, signal };
+      const decoded = await decoders.loadByKind(envelope.kind, input);
+      if (!decoded.ok) return decoded;
+      return ok({ value: freezeRuntimePayload(decoded.value), refs: envelope.refs });
+    }
+  });
+  let catalogEpoch = session.snapshot().epoch;
+  const unsubscribeCatalog = session.subscribe((snapshot) => {
+    if (snapshot.epoch === catalogEpoch) return;
+    catalogEpoch = snapshot.epoch;
+    graph.invalidateForCatalogChange(
+      snapshot.stale ? void 0 : [...snapshot.changed, ...snapshot.removed]
+    );
+  });
+  const registry = {
+    installDecoder: (kind, decoder) => decoders.install(kind, decoder),
+    load: (async (guid, kind, loadOptions = {}) => {
+      if (!ASSET_GUID_PATTERN.test(guid)) return err(invalidGuid(guid));
+      const expectedKind = typeof kind === "string" ? kind : kind.kind;
+      const started = await session.start();
+      if (!started.ok) return err(started.error);
+      if (session.snapshot().stale) {
+        const reconciled = await session.reconcile();
+        if (!reconciled.ok) return err(reconciled.error);
+        const discontinuity = session.discontinuity();
+        if (discontinuity !== void 0) return err(discontinuity);
+      }
+      const row = session.current(guid);
+      if (row === void 0) return err(missing(guid));
+      if (row.kind !== expectedKind) return err(mismatch(guid, expectedKind, row.kind));
+      const result = await graph.load(guid, loadOptions.signal);
+      return result.ok ? ok(result.value.value) : result;
+    }),
+    snapshot: () => graph.snapshot(),
+    subscribe: (listener) => graph.subscribe(listener),
+    dispose: () => {
+      graph.dispose();
+      unsubscribeCatalog();
+      decoders.dispose();
+      cache.clear();
+      session.dispose();
+    }
+  };
+  const resolver = {
+    get epoch() {
+      return graph.snapshot().epoch;
+    },
+    lookup: (guid) => graph.lookup(guid),
+    guidOf: (asset) => graph.guidOf(asset)
+  };
+  Object.defineProperty(registry, REGISTRY_RESOLVER, {
+    value: resolver,
+    enumerable: false
+  });
+  return registry;
+}
+async function sha256(bytes) {
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+  return `sha256:${Array.from(
+    new Uint8Array(digest),
+    (byte) => byte.toString(16).padStart(2, "0")
+  ).join("")}`;
+}
+function resolveArtifactUrl(packageUrl, path) {
+  const separator = packageUrl.lastIndexOf("/");
+  const packageDirectory = separator < 0 ? "" : packageUrl.slice(0, separator + 1);
+  try {
+    return new URL(path, packageDirectory).toString();
+  } catch {
+    return `${packageDirectory}${path.replace(/^\//, "")}`;
+  }
+}
+
+export { createAssetRegistry, createCatalogSource, defineAssetKind };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map