@afora/core 0.0.8 → 0.0.11

package/dist/core/application/schema.js

@@ -0,0 +1,398 @@
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function sorted(value) {
+  if (Array.isArray(value))
+    return value.map(sorted);
+  if (!isObject(value))
+    return value;
+  return Object.fromEntries(Object.keys(value).filter((key) => !key.startsWith("~") && value[key] !== undefined).sort().map((key) => [key, sorted(value[key])]));
+}
+function evolutionOf(property, description, found = {}, depth = 0) {
+  if (property === undefined || depth > 64)
+    return found;
+  const resolved = "ref" in property ? description.properties[property.ref] : property;
+  const lineage = resolved?.lineage;
+  if (lineage === undefined || lineage.kind === "factory")
+    return found;
+  if (lineage.kind === "refined") {
+    const { fill, renamedFrom } = lineage.options;
+    if (!("fill" in found) && fill !== undefined)
+      found.fill = fill;
+    if (found.renamedFrom === undefined && typeof renamedFrom === "string") {
+      found.renamedFrom = renamedFrom;
+    }
+  }
+  return evolutionOf(lineage.base, description, found, depth + 1);
+}
+function fieldsOf(fields, description) {
+  if (fields === undefined)
+    return;
+  return Object.fromEntries(Object.keys(fields).sort().map((key) => [
+    key,
+    lockFieldOf(fields[key], description)
+  ]));
+}
+function lockFieldOf(field, description) {
+  switch (field.kind) {
+    case "property": {
+      const property = "ref" in field ? description.properties[field.ref] : field;
+      const evolution = evolutionOf("ref" in field ? { ref: field.ref } : field, description);
+      return {
+        schema: sorted(property?.schema ?? {}),
+        optional: field.optional,
+        ...property?.unique ? { unique: true } : {},
+        ..."fill" in evolution ? { fill: sorted(evolution.fill) } : {},
+        ...evolution.renamedFrom === undefined ? {} : { renamedFrom: evolution.renamedFrom }
+      };
+    }
+    case "list": {
+      const item = lockFieldOf(field.item, description);
+      return {
+        schema: sorted({
+          type: "array",
+          items: item.schema,
+          minItems: field.minItems,
+          maxItems: field.maxItems
+        }),
+        optional: field.optional,
+        ...item.fields === undefined ? {} : { fields: item.fields }
+      };
+    }
+    case "blueprint": {
+      const fields = "ref" in field ? description.blueprints[field.ref]?.fields : field.fields;
+      return {
+        schema: { type: "object" },
+        optional: field.optional,
+        fields: fieldsOf(fields, description) ?? {}
+      };
+    }
+    case "record": {
+      const fields = description.records[field.ref]?.fields;
+      return {
+        schema: { type: "object" },
+        optional: field.optional,
+        fields: fieldsOf(fields, description) ?? {}
+      };
+    }
+    case "variant":
+      return {
+        schema: { discriminator: field.key, type: "object" },
+        optional: field.optional,
+        fields: Object.fromEntries(Object.keys(field.variants).sort().map((tag) => [
+          tag,
+          {
+            ...lockFieldOf(field.variants[tag], description),
+            optional: true
+          }
+        ]))
+      };
+    case "entity":
+      return {
+        schema: { entity: field.ref, type: "string" },
+        optional: field.optional
+      };
+  }
+}
+function lockEntityOf(entity, description) {
+  const declared = fieldsOf(entity.fields, description) ?? {};
+  const unique = new Set(entity.options.unique.filter((key) => key !== "id"));
+  for (const [key, field] of Object.entries(declared)) {
+    if (field.unique)
+      unique.add(key);
+  }
+  const fields = Object.fromEntries(Object.entries(declared).map(([key, field]) => [
+    key,
+    unique.has(key) ? { ...field, unique: true } : field
+  ]));
+  return {
+    schemaVersion: entity.schemaVersion ?? 1,
+    previousNames: [...entity.previousNames ?? []].sort(),
+    unique: [...unique].sort(),
+    fields,
+    ...entity.upgrade === undefined || entity.upgrade.length === 0 ? {} : { upgrade: [...entity.upgrade].sort((a, b) => a - b) }
+  };
+}
+export function schemaLockOf(description) {
+  return {
+    lockVersion: 1,
+    entities: sorted(Object.fromEntries(Object.keys(description.entities).map((name) => [
+      name,
+      lockEntityOf(description.entities[name], description)
+    ])))
+  };
+}
+const METADATA = new Set([
+  "title",
+  "description",
+  "examples",
+  "default",
+  "deprecated",
+  "readOnly",
+  "writeOnly",
+  "$comment"
+]);
+const UPPER = new Set([
+  "maximum",
+  "exclusiveMaximum",
+  "maxLength",
+  "maxItems",
+  "maxProperties"
+]);
+const LOWER = new Set([
+  "minimum",
+  "exclusiveMinimum",
+  "minLength",
+  "minItems",
+  "minProperties"
+]);
+const NARROWING = new Set([
+  "pattern",
+  "format",
+  "multipleOf",
+  "allOf",
+  "const"
+]);
+const same = (a, b) => JSON.stringify(sorted(a)) === JSON.stringify(sorted(b));
+function literalsOf(schema) {
+  if (Array.isArray(schema.enum)) {
+    return schema.enum.map((value) => JSON.stringify(value));
+  }
+  if (Array.isArray(schema.anyOf) && schema.anyOf.every((item) => isObject(item) && ("const" in item))) {
+    return schema.anyOf.map((item) => JSON.stringify(item.const));
+  }
+  return;
+}
+function compareSchemas(previous, next) {
+  if (same(previous, next))
+    return "same";
+  const strip = (schema) => Object.fromEntries(Object.entries(schema).filter(([key]) => !METADATA.has(key)));
+  const [a, b] = [strip(previous), strip(next)];
+  if (same(a, b))
+    return "metadata";
+  if (!same(a.type, b.type) || !same(a.entity, b.entity))
+    return "type-changed";
+  const [before, after] = [literalsOf(a), literalsOf(b)];
+  let loosened = false;
+  let tightened = false;
+  if (before !== undefined || after !== undefined) {
+    if (before === undefined || after === undefined)
+      return "type-changed";
+    const kept = before.every((value) => after.includes(value));
+    const gained = after.some((value) => !before.includes(value));
+    if (!kept)
+      tightened = true;
+    if (gained)
+      loosened = true;
+  }
+  const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+  for (const key of keys) {
+    if (["type", "entity", "enum", "anyOf"].includes(key))
+      continue;
+    if (same(a[key], b[key]))
+      continue;
+    const [x, y] = [a[key], b[key]];
+    if (key === "items") {
+      const items = compareSchemas(isObject(x) ? x : {}, isObject(y) ? y : {});
+      if (items === "type-changed")
+        return "type-changed";
+      if (items === "tightened")
+        tightened = true;
+      if (items === "loosened")
+        loosened = true;
+    } else if (UPPER.has(key) || LOWER.has(key)) {
+      if (x === undefined)
+        tightened = true;
+      else if (y === undefined)
+        loosened = true;
+      else if (typeof x !== "number" || typeof y !== "number")
+        return "type-changed";
+      else if (UPPER.has(key) ? y > x : y < x)
+        loosened = true;
+      else
+        tightened = true;
+    } else if (NARROWING.has(key)) {
+      if (y === undefined)
+        loosened = true;
+      else
+        tightened = true;
+    } else {
+      return "type-changed";
+    }
+  }
+  if (tightened)
+    return "tightened";
+  return loosened ? "loosened" : "metadata";
+}
+function push(context, change, klass, satisfied, extra = {}) {
+  context.changes.push({
+    entity: context.entity,
+    ...extra.key === undefined ? {} : { key: extra.key },
+    change,
+    class: klass,
+    satisfied,
+    destructive: extra.destructive ?? false,
+    ...extra.from === undefined ? {} : { from: extra.from },
+    ...extra.detail === undefined ? {} : { detail: extra.detail }
+  });
+}
+const STEP = "an upgrade step (bump schemaVersion and add upgrade[n])";
+function diffFields(context, previous, next, path) {
+  const join = (key) => path ? `${path}.${key}` : key;
+  const renamedFrom = new Map;
+  for (const [key, field] of Object.entries(next)) {
+    const from = field.renamedFrom;
+    if (from !== undefined && !(key in previous) && from in previous && !(from in next)) {
+      renamedFrom.set(key, from);
+    }
+  }
+  const moved = new Set(renamedFrom.values());
+  const keys = [...new Set([...Object.keys(previous), ...Object.keys(next)])].filter((key) => !moved.has(key)).sort();
+  for (const key of keys) {
+    const was = previous[key];
+    const is = next[key];
+    if (is === undefined) {
+      push(context, "removed", "automatic", true, {
+        key: join(key),
+        destructive: true,
+        detail: "Left out on read; a backfill removes it only with destructive: true. Rename it with renamedFrom to keep the data."
+      });
+      continue;
+    }
+    const from = renamedFrom.get(key);
+    if (from !== undefined) {
+      push(context, "renamed", "declared", true, {
+        key: join(key),
+        from: join(from)
+      });
+      diffField(context, previous[from], is, join(key));
+      continue;
+    }
+    if (was === undefined) {
+      if (is.optional) {
+        push(context, "added-optional", "automatic", true, { key: join(key) });
+      } else {
+        const satisfied = "fill" in is || context.stepped;
+        push(context, "added-required", "declared", satisfied, {
+          key: join(key),
+          ...satisfied ? {} : {
+            detail: `Needs a fill (.with({ fill })) or ${STEP} that sets it.`
+          }
+        });
+      }
+      continue;
+    }
+    diffField(context, was, is, join(key));
+  }
+}
+function diffField(context, was, is, key) {
+  const compared = compareSchemas(was.schema, is.schema);
+  if (compared === "type-changed") {
+    push(context, "type-changed", "declared", context.stepped, {
+      key,
+      ...context.stepped ? {} : { detail: `Needs ${STEP} that converts the stored values.` }
+    });
+  } else if (compared === "tightened") {
+    const satisfied = context.stepped || "fill" in is;
+    push(context, "tightened", "declared", satisfied, {
+      key,
+      detail: satisfied ? "Run app.migrate({ mode: 'check' }) to list the rows that violate it." : `Needs ${STEP} or a fill; app.migrate({ mode: 'check' }) lists the rows that violate it.`
+    });
+  } else if (compared === "loosened") {
+    push(context, "loosened", "automatic", true, { key });
+  } else if (compared === "metadata") {
+    push(context, "metadata", "automatic", true, { key });
+  }
+  if (was.optional && !is.optional) {
+    const satisfied = context.stepped || "fill" in is;
+    push(context, "made-required", "declared", satisfied, {
+      key,
+      ...satisfied ? {} : {
+        detail: `Needs a fill (.with({ fill })) or ${STEP} for the rows without it.`
+      }
+    });
+  } else if (!was.optional && is.optional) {
+    push(context, "made-optional", "automatic", true, { key });
+  }
+  if (!was.unique && is.unique) {
+    push(context, "unique-added", "check", true, {
+      key,
+      detail: "Run app.migrate({ mode: 'check' }) and look for duplicates before it is enforced."
+    });
+  } else if (was.unique && !is.unique) {
+    push(context, "unique-removed", "automatic", true, { key });
+  }
+  if (was.fields !== undefined || is.fields !== undefined) {
+    diffFields(context, was.fields ?? {}, is.fields ?? {}, key);
+  }
+}
+function diffEntity(entity, from, to, changes) {
+  const stepped = to.schemaVersion > from.schemaVersion && (to.upgrade ?? []).some((version) => version > from.schemaVersion && version <= to.schemaVersion);
+  const context = { entity, from, to, stepped, changes };
+  diffFields(context, from.fields, to.fields, "");
+}
+export function diffSchemas(lock, current) {
+  const changes = [];
+  const claimed = new Set;
+  for (const name of Object.keys(current.entities).sort()) {
+    const to = current.entities[name];
+    let from = lock.entities[name];
+    if (from === undefined) {
+      const previous = to.previousNames.find((old) => lock.entities[old] !== undefined && !current.entities[old]);
+      if (previous === undefined) {
+        changes.push({
+          entity: name,
+          change: "entity-added",
+          class: "automatic",
+          satisfied: true,
+          destructive: false
+        });
+        continue;
+      }
+      claimed.add(previous);
+      from = lock.entities[previous];
+      changes.push({
+        entity: name,
+        change: "entity-renamed",
+        class: "declared",
+        satisfied: true,
+        destructive: true,
+        from: previous,
+        detail: "app.migrate moves its rows; it removes them from the previous name only with destructive: true."
+      });
+    }
+    diffEntity(name, from, to, changes);
+  }
+  for (const name of Object.keys(lock.entities).sort()) {
+    if (current.entities[name] !== undefined || claimed.has(name))
+      continue;
+    changes.push({
+      entity: name,
+      change: "entity-removed",
+      class: "declared",
+      satisfied: false,
+      destructive: true,
+      detail: `No entity is named "${name}": list it in the previousNames of the entity that replaces it, or remove it from the lock if it is gone.`
+    });
+  }
+  return changes;
+}
+export function schemaLockProblemsOf(lock, current) {
+  const problems = [];
+  const renamed = new Map;
+  for (const [name, entity] of Object.entries(current.entities)) {
+    for (const old of entity.previousNames) {
+      if (!renamed.has(old))
+        renamed.set(old, name);
+    }
+  }
+  for (const name of Object.keys(lock.entities).sort()) {
+    const locked = lock.entities[name];
+    const now = current.entities[name] === undefined ? renamed.get(name) : name;
+    const entity = now === undefined ? undefined : current.entities[now];
+    if (entity === undefined) {
+      problems.push(`The lock holds the entity "${name}", which no entity is named or lists in previousNames.`);
+    } else if (entity.schemaVersion < locked.schemaVersion) {
+      problems.push(`The schemaVersion of "${now}" (${entity.schemaVersion}) is lower than the lock's (${locked.schemaVersion}).`);
+    }
+  }
+  return problems;
+}

package/dist/core/application/start.js

@@ -0,0 +1,162 @@
+import { InvalidCommandDeclaration } from "../command/exceptions.js";
+import {
+  isEnvironment,
+  loadEnvironments
+} from "../environment/environment.js";
+import { Kind } from "../symbols/kind.js";
+import {
+  ApplicationNotStarted,
+  InvalidApplicationDeclaration
+} from "./exceptions.js";
+export function providerFrom(environmentDependencies, create) {
+  if (typeof environmentDependencies === "function" && create === undefined) {
+    return Object.freeze({
+      [Kind]: "provider-factory",
+      environments: Object.freeze([]),
+      create: environmentDependencies,
+      withContext: true
+    });
+  }
+  const list = isEnvironment(environmentDependencies) ? [environmentDependencies] : Array.isArray(environmentDependencies) ? [...environmentDependencies] : [null];
+  if (!list.every(isEnvironment) || new Set(list).size !== list.length || typeof create !== "function") {
+    throw new InvalidApplicationDeclaration({
+      source: "providerFrom",
+      details: {
+        reason: "Expected distinct environments made by environmentOf and a create function."
+      }
+    });
+  }
+  return Object.freeze({
+    [Kind]: "provider-factory",
+    environments: Object.freeze(list),
+    create,
+    withContext: false
+  });
+}
+export function logFrom(create) {
+  if (typeof create !== "function") {
+    throw new InvalidApplicationDeclaration({
+      source: "logFrom",
+      details: { reason: "Expected logFrom to take a create function." }
+    });
+  }
+  return Object.freeze({ [Kind]: "log-factory", create });
+}
+export function isLogFactory(value) {
+  return typeof value === "object" && value !== null && value[Kind] === "log-factory";
+}
+export function isProviderFactory(value) {
+  return typeof value === "object" && value !== null && value[Kind] === "provider-factory";
+}
+const deferred = new WeakMap;
+const METHODS = [
+  "findOne",
+  "findMany",
+  "insert",
+  "update",
+  "remove",
+  "count"
+];
+export function deferredProvider(factory, application) {
+  const state = {
+    factory,
+    application,
+    provider: undefined,
+    starting: undefined
+  };
+  const real = (method) => {
+    const { provider } = state;
+    if (!provider) {
+      throw new ApplicationNotStarted({
+        source: application,
+        details: { application }
+      });
+    }
+    if (typeof provider[method] !== "function") {
+      throw new InvalidApplicationDeclaration({
+        source: application,
+        details: {
+          reason: `The provider made on start has no "${method}".`
+        }
+      });
+    }
+    return provider;
+  };
+  const proxy = {};
+  for (const method of [...METHODS, "increment"]) {
+    proxy[method] = (...args) => real(method)[method]?.(...args);
+  }
+  proxy.transaction = (run) => real("transaction").transaction(run);
+  proxy.migrate = async (...args) => {
+    const { provider } = state;
+    if (!provider)
+      real("migrate");
+    return provider?.migrate?.(...args);
+  };
+  Object.defineProperty(proxy, "capabilities", {
+    get: () => state.provider?.capabilities,
+    enumerable: true
+  });
+  Object.freeze(proxy);
+  deferred.set(proxy, state);
+  return proxy;
+}
+export function isDeferredProvider(provider) {
+  return typeof provider === "object" && provider !== null && deferred.has(provider);
+}
+export function deferredEnvironments(provider) {
+  return (typeof provider === "object" && provider !== null ? deferred.get(provider)?.factory.environments : undefined) ?? [];
+}
+export function startDeferred(provider, context) {
+  const state = deferred.get(provider);
+  if (!state)
+    return;
+  state.starting ??= (async () => {
+    const made = await state.factory.create(state.factory.withContext ? context : loadEnvironments(state.factory.environments));
+    if (typeof made !== "object" || made === null) {
+      state.starting = undefined;
+      throw new InvalidApplicationDeclaration({
+        source: state.application,
+        details: {
+          reason: "Expected providerFrom's create to give a repository provider."
+        }
+      });
+    }
+    state.provider = made;
+    return made;
+  })();
+  return state.starting;
+}
+export async function stopProvider(provider) {
+  const state = deferred.get(provider);
+  if (!state) {
+    await provider.close?.();
+    return;
+  }
+  const made = state.provider;
+  state.provider = undefined;
+  state.starting = undefined;
+  await made?.close?.();
+}
+export function checkTransactions(source, provider, commands) {
+  if (commands.length === 0)
+    return;
+  if (typeof provider.transaction !== "function" || provider.capabilities?.transactions === false) {
+    throw new InvalidCommandDeclaration({
+      source,
+      details: {
+        reason: `The provider made on start does not support transactions, which ${commands.join(", ")} declare.`
+      }
+    });
+  }
+}
+export function checkCapabilities(source, provider, repositories) {
+  if (repositories.length === 0 || provider.capabilities?.keyset === true)
+    return;
+  throw new InvalidApplicationDeclaration({
+    source,
+    details: {
+      reason: `The provider made on start does not read by cursor (capabilities.keyset), which the findCursor of ${repositories.join(", ")} needs.`
+    }
+  });
+}

package/dist/core/application/types/application.interface.d.ts

@@ -9,8 +9,12 @@ import type { AnyOutput, StageDescription } from "../../output/types/output.inte
 import type { RecordPluginDescriptor } from "../../record/types/plugin.interface.js";
 import type { ProviderDescription, RepositoryIndex, RepositoryScans } from "../../repository/types/query.interface.js";
 import type { AnyRepository, IRepositoryProvider } from "../../repository/types/repository.interface.js";
+import type { SchemaLock, SchemaMigrationOptions, SchemaMigrationReport } from "../../repository/types/schema.interface.js";
 import type { Kind } from "../../symbols/kind.js";
+import type { ITracer } from "../../tracing/tracing.js";
 import type { UseCaseStepDescription } from "../../use-case/steps/types/steps.interface.js";
+import type { AccessDeclaration } from "../../use-case/types/access.interface.js";
+import type { RouteDeclaration } from "../../use-case/types/route.interface.js";
 import type { AnyExceptionClass, AnyUseCaseClass, UseCaseInput, UseCaseResponse } from "../../use-case/use-case.js";
 import type { ProviderSlot, ProviderStorage } from "../providers.js";
 import type { LogFactory, ProviderFactory } from "../start.js";
@@ -98,6 +102,14 @@ export interface ApplicationSettings<Name extends string, Extended extends reado
      * it, the one of the last extended application that has one; none by default.
      */
     readonly log?: LogSettings | LogFactory;
+    /**
+     * What traces it: a span per command operation, use case and repository
+     * call made through a use case, nested as the calls are, with names and
+     * outcomes and never a value (see `docs/tracing.md`). `otelTracer()` of
+     * `@afora/otel` gives one for OpenTelemetry. Without it, the one of the
+     * last extended application that has one; none by default.
+     */
+    readonly trace?: ITracer;
     /**
      * Where event policies such as `publishEvents` publish, by key: a
      * WebSocket hub, a queue, a broker. Commands of the application find them
@@ -206,6 +218,17 @@ export interface IApplication<Name extends string, Collections extends Applicati
      * started application of the process.
      */
     stop(): Promise<void>;
+    /**
+     * Brings the stored rows of its entities up to their current shape,
+     * walking each provider directly: in `check` it only reports, in `apply`
+     * it gives each provider the plan of its entity (`provider.migrate`, the
+     * changes from `lock`), then rewrites the rows below the current
+     * `schemaVersion` or with a `fill` or `renamedFrom` pending, and moves the
+     * rows stored under `previousNames`. Keys no longer declared, and the
+     * rows of the previous names, are only removed with `destructive: true`.
+     * Idempotent and resumable.
+     */
+    migrate(options: SchemaMigrationOptions): Promise<SchemaMigrationReport>;
     /** The variables of an environment registered in the application. */
     get<Environment extends AnyEnvironment>(environment: Environment): EnvironmentValue<Environment>;
     /** The bound version of a command registered in the application. */
@@ -225,12 +248,25 @@ export interface IApplication<Name extends string, Collections extends Applicati
 export interface ApplicationStartOptions {
     /**
      * Become the started application of the process (what `useApplication()`
-     * gives). Default `true`; another one already started throws
-     * `ApplicationAlreadyStarted`.
+     * gives). Another one already started throws `ApplicationAlreadyStarted`.
+     *
+     * @default true
      */
     readonly register?: boolean;
-    /** Stop the started application of the process and take its place, e.g. on hot reload. Default `false`. */
+    /**
+     * Stop the started application of the process and take its place, e.g. on hot
+     * reload.
+     *
+     * @default false
+     */
     readonly replace?: boolean;
+    /**
+     * The committed schema lock (`afora.lock.json`): start throws
+     * `SchemaLockMismatch` when an entity of the lock is no longer named, and
+     * no entity lists it in `previousNames`, or when the `schemaVersion` of
+     * an entity is lower than the lock's.
+     */
+    readonly lock?: SchemaLock;
 }
 /** Any application. */
 export type AnyApplication = IApplication<string, any>;
@@ -290,7 +326,14 @@ export type FieldDescription = {
     readonly kind: "record" | "entity";
     readonly ref: string;
     readonly optional: boolean;
+} | {
+    /** One of several blueprints, told apart by the value of `key`, the name of the variant. */
+    readonly kind: "variant";
+    readonly key: string;
+    readonly optional: boolean;
+    readonly variants: Readonly<Record<string, FieldDescription>>;
 };
+/** The fields of a blueprint, record or entity in a description, by name. */
 export type FieldsDescription = Readonly<Record<string, FieldDescription>>;
 /** A record or an entity: its fields (an entity's identity and its plugins' keys left out), options and plugins. */
 export interface RecordDescription {
@@ -318,6 +361,12 @@ export interface RecordDescription {
      * `fields`) or `{ at: key }`. Present only when it has one.
      */
     readonly expires?: EntityExpires;
+    /** The `schemaVersion` of an entity; present only when declared. */
+    readonly schemaVersion?: number;
+    /** The versions the `upgrade` of an entity has a step to, ascending; present only when it has some. */
+    readonly upgrade?: readonly number[];
+    /** The `previousNames` of an entity; present only when it has some. */
+    readonly previousNames?: readonly string[];
 }
 /** What a use case depends on, by the name it has in the application. */
 export interface UseCaseDependencyDescription {
@@ -333,6 +382,10 @@ export interface UseCaseDescription {
     readonly description?: string;
     readonly tags: readonly string[];
     readonly deprecated: boolean;
+    /** Where it is served over HTTP, from the `route` setting or `@Route`. */
+    readonly route?: RouteDeclaration;
+    /** Who may call it, from the `access` setting or `@Access`. */
+    readonly access?: AccessDeclaration;
     readonly input: FieldsDescription;
     readonly response: FieldsDescription;
     readonly context?: FieldsDescription;
@@ -448,6 +501,10 @@ export interface ApplicationDescription {
     readonly log?: LogDescription | {
         readonly kind: "opaque";
     };
+    /** Present, and opaque, only when it has a `trace` (its own or inherited). */
+    readonly trace?: {
+        readonly kind: "opaque";
+    };
     /** Its publishers (inherited ones included), by key, with the application that declared each; present only when it has some. */
     readonly publishers?: Readonly<Record<string, {
         readonly from: string;