@dxos/echo 0.9.0 → 0.9.1-main.c7dcc2e112

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/echo",
-  "version": "0.9.0",
+  "version": "0.9.1-main.c7dcc2e112",
   "description": "ECHO API",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -136,16 +136,16 @@
   "dependencies": {
     "@effect-atom/atom": "^0.5.3",
     "effect": "3.21.3",
-    "@dxos/debug": "0.9.0",
-    "@dxos/async": "0.9.0",
-    "@dxos/echo-protocol": "0.9.0",
-    "@dxos/effect": "0.9.0",
-    "@dxos/errors": "0.9.0",
-    "@dxos/keys": "0.9.0",
-    "@dxos/node-std": "0.9.0",
-    "@dxos/util": "0.9.0",
-    "@dxos/log": "0.9.0",
-    "@dxos/invariant": "0.9.0"
+    "@dxos/async": "0.9.1-main.c7dcc2e112",
+    "@dxos/echo-protocol": "0.9.1-main.c7dcc2e112",
+    "@dxos/effect": "0.9.1-main.c7dcc2e112",
+    "@dxos/errors": "0.9.1-main.c7dcc2e112",
+    "@dxos/keys": "0.9.1-main.c7dcc2e112",
+    "@dxos/invariant": "0.9.1-main.c7dcc2e112",
+    "@dxos/log": "0.9.1-main.c7dcc2e112",
+    "@dxos/node-std": "0.9.1-main.c7dcc2e112",
+    "@dxos/util": "0.9.1-main.c7dcc2e112",
+    "@dxos/debug": "0.9.1-main.c7dcc2e112"
   },
   "devDependencies": {
     "@types/node": "22.10.2"

package/src/Annotation.ts

@@ -9,6 +9,11 @@ export {
   FieldLookupAnnotationId,
   FormInputAnnotation,
   FormInlineAnnotation,
+  FormOrderedAnnotation,
+  FormLayoutAnnotation,
+  FormLayoutAnnotationId,
+  type FormLayoutMap,
+  DEFAULT_LAYOUT_NAME,
   GeneratorAnnotation,
   GeneratorAnnotationId,
   type GeneratorAnnotationValue,

package/src/Database.ts

@@ -17,6 +17,7 @@ import { type SpaceId, type URI } from '@dxos/keys';
 
 import type * as Entity from './Entity';
 import * as Err from './Err';
+import type * as Feed from './Feed';
 import type * as Filter from './Filter';
 import type * as Hypergraph from './Hypergraph';
 import { type AnyProperties, EntityKind, KindId } from './internal/common/types';
@@ -166,6 +167,19 @@ export interface Database extends Queryable {
   // TODO(burdon): Return true if removed (currently throws if not present).
   remove(obj: Entity.Unknown): void;
 
+  /**
+   * Appends entities to a feed.
+   *
+   * The feed must already be stored in the database (added via {@link add}); its underlying
+   * queue is addressed by the feed object's URI.
+   */
+  appendToFeed(feed: Feed.Feed, entities: Entity.Unknown[]): Promise<void>;
+
+  /**
+   * Removes entities from a feed.
+   */
+  deleteFromFeed(feed: Feed.Feed, entities: Entity.Unknown[]): Promise<void>;
+
   /**
    * Wait for all pending changes to be saved to disk.
    * Optionaly waits for changes to be propagated to indexes and event handlers.
@@ -250,7 +264,7 @@ export const resolve: {
             space: db.spaceId,
           },
         })
-        .resolve(dxn),
+        .resolveLegacy(dxn),
     );
 
     if (!object) {
@@ -305,6 +319,24 @@ export const addType = <T extends Type.AnyEntity>(type: T): Effect.Effect<T, nev
 export const remove = <T extends Entity.Unknown>(obj: T): Effect.Effect<void, never, Service> =>
   Service.pipe(Effect.map(({ db }) => db.remove(obj))).pipe(Effect.withSpan('Database.remove'));
 
+/**
+ * Appends entities to a feed.
+ * @see {@link Database.appendToFeed}
+ */
+export const appendToFeed = (feed: Feed.Feed, entities: Entity.Unknown[]): Effect.Effect<void, never, Service> =>
+  Service.pipe(
+    Effect.flatMap(({ db }) => EffectEx.promiseWithCauseCapture(() => db.appendToFeed(feed, entities))),
+  ).pipe(Effect.withSpan('Database.appendToFeed'));
+
+/**
+ * Removes entities from a feed.
+ * @see {@link Database.deleteFromFeed}
+ */
+export const deleteFromFeed = (feed: Feed.Feed, entities: Entity.Unknown[]): Effect.Effect<void, never, Service> =>
+  Service.pipe(
+    Effect.flatMap(({ db }) => EffectEx.promiseWithCauseCapture(() => db.deleteFromFeed(feed, entities))),
+  ).pipe(Effect.withSpan('Database.deleteFromFeed'));
+
 /**
  * Flushes pending changes to disk.
  * @see {@link Database.flush}

package/src/Entity.ts

@@ -190,7 +190,7 @@ export type AnyInput = Unknown | Snapshot;
  * @param options.prefer - Controls the URI form (see {@link internal.GetURIOptions}).
  */
 export const getURI = (entity: AnyInput, options?: internal.GetURIOptions): URI.URI =>
-  isTypeEntity(entity) ? Type.getURI(entity as Type.AnyEntity) : internal.getUri(entity as Unknown, options);
+  isTypeEntity(entity) ? Type.getURI(entity as Type.AnyEntity, options) : internal.getUri(entity as Unknown, options);
 
 /**
  * Get the DXN of an entity's type. For object/relation instances this is the URI
@@ -343,3 +343,5 @@ export const removeTag = (entity: Mutable<Unknown>, tag: Ref.Ref<Tag.Tag>): void
 //
 
 export const atom = objInternal.makeEntity;
+export const labelAtom = objInternal.makeLabelAtom;
+export const labelProperty = internal.getLabelProperty;

package/src/Feed.ts

@@ -245,6 +245,9 @@ export const remove = (feed: Feed, items: (Entity.Unknown | Obj.Snapshot)[]): Ef
 /**
  * Creates a reactive query over items in a feed.
  *
+ * In non-Effect code, query a feed directly through the database with a feed scope:
+ * `db.query(Query.select(filter).from(Scope.feed(Feed.getQueueUri(feed))))`.
+ *
  * @example
  * ```ts
  * const result = yield* Feed.query(feed, Filter.type(Person));

package/src/Obj.ts

@@ -926,3 +926,5 @@ export const version = (entity: Unknown | Snapshot): Version => internal.version
 export const atom = objInternal.makeAtom;
 export const atomReactive = objInternal.makeWithReactive;
 export const atomProperty = objInternal.makeProperty;
+export const labelAtom = objInternal.makeLabelAtom;
+export const labelProperty = internal.getLabelProperty;

package/src/Ref.ts

@@ -16,7 +16,7 @@ import * as refInternal from './internal/Ref';
 import type * as JsonSchema from './JsonSchema';
 import type * as Obj from './Obj';
 // eslint-disable-next-line @dxos/rules/import-as-namespace
-import type * as TypeNs from './Type';
+import type * as Type$ from './Type';
 
 /**
  * Instance type for a reference.
@@ -51,11 +51,11 @@ export type Unknown = refInternal.Ref<Obj.Unknown>;
  * ```
  */
 export const Ref: {
-  <S extends TypeNs.AnyObj | TypeNs.AnyRelation>(type: S): RefSchema<TypeNs.InstanceType<S> & Obj.Unknown>;
+  <S extends Type$.AnyObj | Type$.AnyRelation>(type: S): RefSchema<Type$.InstanceType<S> & Obj.Unknown>;
 
   // `Type.Type` entities (the meta-schema kind) can be referenced too — e.g. a
   // trigger that points to a stored function/workflow definition.
-  <T extends TypeNs.Type<any>>(type: T): RefSchema<TypeNs.InstanceType<T>>;
+  <T extends Type$.Type<any>>(type: T): RefSchema<Type$.InstanceType<T>>;
 
   // Schema-side overload for the well-known "any object" / "any relation" schemas.
   // Other raw `Schema.Schema` values are intentionally rejected — callers should

package/src/Tag.ts

@@ -72,6 +72,7 @@ export const findOrCreate = async (
       }
       return existing;
     }
+
     return db.add(Obj.make(Tag, { [Obj.Meta]: { keys: [key] }, label, ...withHue }));
   }
 

package/src/Type.ts

@@ -375,17 +375,31 @@ export type AnyRef = Schema.Schema<internal.Ref<any>, EncodedReference>;
  * - Persisted `Type.Type` instance (has `id`) → local `EID` (`echo:/<objectId>`).
  * - In-memory `Type.Type` draft (has `id`, no typename) → local `EID`.
  *
+ * When `options.prefer === 'named'` the result is forced to a DXN — for
+ * persisted type entities the typename + version from meta are used to
+ * construct the DXN; static types already return a DXN by default.
+ *
  * Only accepts `Type.AnyEntity` entities. Raw `Schema.Schema` values and the
  * branded `Obj.Unknown` / `Relation.Unknown` schemas are intentionally not
  * supported — use `internal.getSchemaURI` or the schema's typename annotation
  * directly when working at the schema level.
  */
-export const getURI = (input: AnyEntity): URI.URI => {
+export const getURI = (input: AnyEntity, options?: internal.GetURIOptions): URI.URI => {
   // For Type entities, route through `getTypeURIFromSpecifier` (id → EID,
   // typename/version → DXN). For Obj/Relation entities, unwrap to the source
   // Effect Schema first and read its annotations.
   if (isType(input)) {
-    return internal.getTypeURIFromSpecifier(input);
+    const uri = internal.getTypeURIFromSpecifier(input);
+    if (options?.prefer === 'named' && !DXN.isDXN(uri)) {
+      // Persisted type — the auto-detected URI is an EID, but caller wants a
+      // DXN. Construct from typename + version (both live in EntityMeta).
+      const typename = getTypename(input);
+      const version = getMeta(input).version;
+      if (typename && version) {
+        return DXN.make(typename, version);
+      }
+    }
+    return uri;
   }
   return internal.getSchemaURI(getSchema(input)) ?? raise(new TypeError('Type entity has no URI'));
 };

package/src/internal/Annotation/annotations.ts

@@ -413,6 +413,47 @@ export const FormInputAnnotation = createAnnotationHelper<boolean>(FormInputAnno
 export const FormInlineAnnotationId = Symbol.for('@dxos/schema/annotation/FormInline');
 export const FormInlineAnnotation = createAnnotationHelper<boolean>(FormInlineAnnotationId);
 
+/**
+ * When set on an array property, the form renders it as an ordered,
+ * drag-to-reorder list (drag handles per row). Element order is meaningful and
+ * user-controllable; reordering rewrites the array.
+ */
+export const FormOrderedAnnotationId = Symbol.for('@dxos/schema/annotation/FormOrdered');
+export const FormOrderedAnnotation = createAnnotationHelper<boolean>(FormOrderedAnnotationId);
+
+/**
+ * Annotation carrying one or more named layout DSL templates that control how a
+ * form arranges a schema's fields (consumed by `@dxos/react-ui-form`'s
+ * `Form.Layout` / `Form.FieldSet`). Callers select a variant by name; the
+ * implicit name is `DEFAULT_LAYOUT_NAME` (`'default'`).
+ *
+ * Templates use a minimal XML grammar. Example:
+ *
+ *   FormLayoutAnnotation.set({
+ *     default: `
+ *       <grid cols="2">
+ *         <field name="origin"/>
+ *         <field name="destination"/>
+ *         <field name="provider" span="2"/>
+ *       </grid>
+ *     `,
+ *     card: `
+ *       <grid cols="1">
+ *         <field name="provider"/>
+ *         <field name="number"/>
+ *       </grid>
+ *     `,
+ *   })
+ */
+export const FormLayoutAnnotationId = Symbol.for('@dxos/react-ui-form/annotation/Layout');
+
+export type FormLayoutMap = Record<string, string>;
+
+export const FormLayoutAnnotation = createAnnotationHelper<FormLayoutMap>(FormLayoutAnnotationId);
+
+/** Name used when no explicit form-layout variant is requested. */
+export const DEFAULT_LAYOUT_NAME = 'default';
+
 /**
  * Default field to be used on referenced schema to lookup the value.
  */
@@ -557,6 +598,21 @@ export const setLabel = (entity: Mutable<AnyProperties>, label: string) => {
   }
 };
 
+/**
+ * Returns the primary label property key for an entity.
+ * Reads the first accessor from {@link LabelAnnotation}, defaulting to 'name'.
+ */
+export const getLabelProperty = (entity: AnyProperties): string => {
+  const schema = getSchema(entity);
+  if (schema == null) {
+    return 'name';
+  }
+  return LabelAnnotation.get(schema).pipe(
+    Option.flatMap((fields) => Option.fromNullable(fields[0])),
+    Option.getOrElse(() => 'name'),
+  );
+};
+
 /**
  * Get the description of an entity.
  * Accepts both reactive entities and snapshots.

package/src/internal/Obj/atoms.ts

@@ -14,6 +14,7 @@ import type * as Entity from '../../Entity';
 import type * as Obj from '../../Obj';
 import type * as Ref from '../../Ref';
 import type * as Relation from '../../Relation';
+import { getLabel } from '../Annotation';
 import { subscribe } from '../common/proxy/reactive';
 import { isEntity, getDatabase } from '../Entity';
 import { RefTypeId } from '../Ref/ref';
@@ -242,3 +243,33 @@ export const makeRelation = <T extends Relation.Unknown>(relation: T): Atom.Atom
   assertArgument(isEntity(relation), 'relation', 'Must be a reactive ECHO relation');
   return relationFamily(relation);
 };
+
+/**
+ * Atom family for an entity's label string.
+ * Fires only when the computed label actually changes, not on every entity mutation.
+ */
+const labelAtomFamily = Atom.family(<T extends Entity.Unknown>(entity: T): Atom.Atom<string | undefined> => {
+  return Atom.make<string | undefined>((get) => {
+    let previous = getLabel(entity);
+
+    const unsubscribe = subscribe(entity, () => {
+      const next = getLabel(entity);
+      if (next !== previous) {
+        previous = next;
+        get.setSelf(next);
+      }
+    });
+
+    get.addFinalizer(() => unsubscribe());
+    return previous;
+  }).pipe(Atom.keepAlive);
+});
+
+/**
+ * Create a read-only atom for the label of a reactive ECHO entity.
+ * Re-evaluates on entity mutation; only propagates when the label string changes.
+ */
+export const makeLabelAtom = <T extends Entity.Unknown>(entity: T): Atom.Atom<string | undefined> => {
+  assertArgument(isEntity(entity), 'entity', 'Must be a reactive ECHO entity');
+  return labelAtomFamily(entity);
+};

package/src/internal/Obj/json-serializer.ts

@@ -129,8 +129,8 @@ export const objectFromJSON = async (
     const sourceDxn = jsonData[ATTR_RELATION_SOURCE] ?? raise(new TypeError('Missing relation source'));
     const targetDxn = jsonData[ATTR_RELATION_TARGET] ?? raise(new TypeError('Missing relation target'));
 
-    const source = (await refResolver?.resolve(sourceDxn)) as AnyEntity | undefined;
-    const target = (await refResolver?.resolve(targetDxn)) as AnyEntity | undefined;
+    const source = (await refResolver?.resolveLegacy(sourceDxn)) as AnyEntity | undefined;
+    const target = (await refResolver?.resolveLegacy(targetDxn)) as AnyEntity | undefined;
 
     defineHiddenProperty(obj, KindId, EntityKind.Relation);
     defineHiddenProperty(obj, RelationSourceDXNId, sourceDxn);
@@ -161,7 +161,7 @@ export const objectFromJSON = async (
 
   if (jsonData[ATTR_PARENT]) {
     const parentDxn = jsonData[ATTR_PARENT];
-    const resolvedParent = (await refResolver?.resolve(parentDxn)) as Obj.Unknown | undefined;
+    const resolvedParent = (await refResolver?.resolveLegacy(parentDxn)) as Obj.Unknown | undefined;
     defineHiddenProperty(obj, ParentId, resolvedParent);
   } else if (parent) {
     defineHiddenProperty(obj, ParentId, parent);

package/src/internal/Ref/index.ts

@@ -4,3 +4,4 @@
 
 export * from './ref';
 export * from './ref-array';
+export * from './strong-deps';

package/src/internal/Ref/ref.ts

@@ -81,7 +81,8 @@ export const getReferenceAst = (ast: SchemaAST.AST): RefereneAST | undefined =>
   };
 };
 
-export const RefTypeId: unique symbol = Symbol('@dxos/echo/internal/Ref');
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const RefTypeId: unique symbol = Symbol.for('@dxos/echo/internal/Ref') as any;
 
 /**
  * Reference Schema.
@@ -253,7 +254,7 @@ export declare namespace Ref {
 }
 
 Ref.isRef = (obj: any): obj is Ref<any> => {
-  return obj && typeof obj === 'object' && RefTypeId in obj;
+  return obj != null && typeof obj === 'object' && RefTypeId in obj;
 };
 
 Ref.hasEntityId = (id: EntityId) => (ref: Ref<any>) => {
@@ -278,7 +279,8 @@ Ref.make = <T extends AnyProperties>(obj: T): Ref<T> => {
   const id = obj.id;
   invariant(EntityId.isValid(id), 'Invalid object ID');
   const uri = EID.make({ entityId: id });
-  return new RefImpl(uri, obj);
+  const ref = new RefImpl(uri, obj);
+  return ref;
 };
 
 Ref.fromURI = (uri: URI.URI): Ref<any> => {
@@ -380,22 +382,79 @@ const getSchemaExpectedName = (ast: SchemaAST.Annotated): string | undefined =>
   );
 };
 
+/**
+ * Load-source ceiling for a resolution request. Cheaper tiers are always probed first; the
+ * ceiling caps how far a request is allowed to reach:
+ * - `working-set`: synchronous, in-memory only. A miss settles `unavailable` immediately.
+ * - `disk`: probe the working set, then local storage; never the network.
+ * - `network`: probe the working set, disk, then fetch from peers.
+ *
+ * `unavailable` is always relative to the requested ceiling (disk-unavailable ≠ network-unavailable).
+ */
+export type RefSource = 'working-set' | 'disk' | 'network';
+
+/**
+ * A stateful, closure-aware handle to an in-flight (or settled) reference resolution.
+ *
+ * `ready` means the entity is FULLY USABLE: its own body and its strong-dependency closure are all
+ * materialized. The body-vs-closure split is internal; `requesting` transparently covers "a
+ * dependency is still loading".
+ */
+export interface RefResolverRequest {
+  /**
+   * `pending` is a one-way entry state (never re-entered). `requesting` means the body and/or
+   * closure is still loading. `ready` means fully usable. `unavailable` means unreachable at the
+   * requested ceiling.
+   */
+  readonly state: 'pending' | 'requesting' | 'ready' | 'unavailable';
+
+  /**
+   * Fires (deferred to a microtask) whenever {@link state} changes.
+   */
+  readonly stateChanged: Event<void>;
+
+  /**
+   * Synchronous snapshot of the resolved entity; defined iff `state === 'ready'`.
+   */
+  getResult(): AnyProperties | undefined;
+
+  /**
+   * Settles when `state ∈ {ready, unavailable}`.
+   */
+  wait(): Promise<AnyProperties | undefined>;
+
+  /**
+   * Decrements the refcount on the shared load op(s); cancels the underlying IO at zero.
+   */
+  abort(): void;
+}
+
 export interface RefResolver {
+  /**
+   * Resolve a reference, returning a stateful handle. `source` is a required ceiling; cheaper
+   * tiers are always probed first.
+   */
+  resolve(uri: URI.URI, options: { source: RefSource }): RefResolverRequest;
+
   /**
    * Resolve ref synchronously from the objects in the working set.
    *
    * @param uri
    * @param load If true the resolver should attempt to load the object from disk.
    * @param onLoad Callback to call when the object is loaded.
+   * @deprecated Use {@link resolve} with `{ source: 'working-set' }`. Removed in Task 11.
    */
   resolveSync(uri: URI.URI, load: boolean, onLoad?: () => void): AnyProperties | undefined;
 
   /**
    * Resolver ref asynchronously.
+   * @deprecated Use {@link resolve} with `{ source: 'network' }`. Removed in Task 11.
    */
-  resolve(uri: URI.URI): Promise<AnyProperties | undefined>;
+  resolveLegacy(uri: URI.URI): Promise<AnyProperties | undefined>;
 
-  // TODO(dmaretskyi): Combine with `resolve`.
+  /**
+   * @deprecated Use {@link resolve} + `Type.getSchema`. Removed in Task 11.
+   */
   resolveSchema(uri: URI.URI): Promise<Schema.Schema.AnyNoContext | undefined>;
 
   /**
@@ -404,10 +463,26 @@ export interface RefResolver {
    * via `Obj.getType` / `Entity.getType`. Optional — resolvers that only
    * carry raw schemas may leave this unimplemented; the deserializer falls
    * back to leaving the type entity unset.
+   * @deprecated Use {@link resolve}. Removed in Task 11.
    */
   resolveType?(uri: URI.URI): Promise<unknown | undefined>;
 }
 
+/**
+ * A settled {@link RefResolverRequest} with a fixed `state` and `result`, used by resolvers
+ * whose backends are fully synchronous (e.g. {@link StaticRefResolver}).
+ */
+export const makeSettledRequest = (
+  state: RefResolverRequest['state'],
+  result: AnyProperties | undefined,
+): RefResolverRequest => ({
+  state,
+  stateChanged: new Event<void>(),
+  getResult: () => (state === 'ready' ? result : undefined),
+  wait: async () => (state === 'ready' ? result : undefined),
+  abort: () => {},
+});
+
 export class RefImpl<T> implements Ref<T> {
   #uri: URI.URI;
   #resolver?: RefResolver = undefined;
@@ -465,7 +540,7 @@ export class RefImpl<T> implements Ref<T> {
       return this.#target;
     }
     invariant(this.#resolver, 'Resolver is not set');
-    const obj = await this.#resolver.resolve(this.#uri);
+    const obj = await this.#resolver.resolveLegacy(this.#uri);
     if (obj == null) {
       throw new Error('Object not found');
     }
@@ -480,7 +555,7 @@ export class RefImpl<T> implements Ref<T> {
       return this.#target;
     }
     invariant(this.#resolver, 'Resolver is not set');
-    return (await this.#resolver.resolve(this.#uri)) as T | undefined;
+    return (await this.#resolver.resolveLegacy(this.#uri)) as T | undefined;
   }
 
   /**
@@ -624,27 +699,29 @@ export class StaticRefResolver implements RefResolver {
     return this;
   }
 
+  resolve(uri: URI.URI, _options: { source: RefSource }): RefResolverRequest {
+    const obj = this.#lookup(uri);
+    return makeSettledRequest(obj ? 'ready' : 'unavailable', obj);
+  }
+
   resolveSync(uri: URI.URI, _load: boolean, _onLoad?: () => void): AnyProperties | undefined {
-    const echoUri = EID.tryParse(uri);
-    const id = echoUri ? EID.getEntityId(echoUri) : undefined;
-    if (id == null) {
-      return undefined;
-    }
+    return this.#lookup(uri);
+  }
 
-    return this.objects.get(id);
+  async resolveLegacy(uri: URI.URI): Promise<AnyProperties | undefined> {
+    return this.#lookup(uri);
+  }
+
+  async resolveSchema(uri: URI.URI): Promise<Schema.Schema.AnyNoContext | undefined> {
+    return this.schemas.get(uri);
   }
 
-  async resolve(uri: URI.URI): Promise<AnyProperties | undefined> {
+  #lookup(uri: URI.URI): AnyProperties | undefined {
     const echoUri = EID.tryParse(uri);
     const id = echoUri ? EID.getEntityId(echoUri) : undefined;
     if (id == null) {
       return undefined;
     }
-
     return this.objects.get(id);
   }
-
-  async resolveSchema(uri: URI.URI): Promise<Schema.Schema.AnyNoContext | undefined> {
-    return this.schemas.get(uri);
-  }
 }

package/src/internal/Ref/strong-deps.ts

@@ -0,0 +1,107 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { EID, type SpaceId, type URI } from '@dxos/keys';
+
+import { EntityKind } from '../common/types/entity';
+import { RelationSourceDXNId, RelationTargetDXNId } from '../common/types/model-symbols';
+import { ParentId, TypeId } from '../common/types/typename';
+import { getObjectEchoUri } from '../Entity/util';
+
+/**
+ * Normalized view of the references that make up an entity's strong-dependency set, store-agnostic
+ * so it can be filled from an {@link ObjectCore} (db) or a decoded entity (queue item / snapshot).
+ */
+export interface StrongDepRefs {
+  /** Entity kind — relations additionally depend on their source/target. */
+  kind: EntityKind;
+  /** Type reference URI (`echo:` for a persisted stored schema, `dxn:` for a static/registry type). */
+  type?: URI.URI;
+  /** Relation source reference URI. */
+  source?: URI.URI;
+  /** Relation target reference URI. */
+  target?: URI.URI;
+  /** Parent reference URI. */
+  parent?: URI.URI;
+}
+
+/**
+ * Direct strong-dependency URIs of an entity: the schema (only when stored as an object), the
+ * relation source/target, and the parent. Returns URIs (cross-space `echo:` EIDs and queue-item
+ * EIDs included); a persisted schema is an `echo:` URI, a static/registry type is a `dxn:` URI.
+ *
+ * A static/registry type (`dxn:`) is intentionally NOT a strong dep: it is always synchronously
+ * available through the registry, so gating on it would needlessly delay surfacing. Only a
+ * persisted (db-backed) schema, addressed by an `echo:` URI, must load before its instances.
+ */
+export const getStrongDependencyUris = (refs: StrongDepRefs, owningSpaceId?: SpaceId): URI.URI[] => {
+  const res: URI.URI[] = [];
+
+  if (refs.type != null && EID.tryParse(refs.type) != null) {
+    res.push(qualifyToSpace(refs.type, owningSpaceId));
+  }
+
+  if (refs.kind === EntityKind.Relation) {
+    if (refs.source != null) {
+      res.push(qualifyToSpace(refs.source, owningSpaceId));
+    }
+    if (refs.target != null) {
+      res.push(qualifyToSpace(refs.target, owningSpaceId));
+    }
+  }
+
+  if (refs.parent != null) {
+    res.push(qualifyToSpace(refs.parent, owningSpaceId));
+  }
+
+  return res;
+};
+
+/**
+ * Qualifies a space-less (relative) `echo:` dependency URI with the space of the entity that owns it.
+ * Same-space references are persisted relative; resolution needs them absolute to route to a single
+ * space. Already-qualified URIs (cross-space) and non-`echo:` URIs (registry `dxn:`) pass through.
+ */
+const qualifyToSpace = (uri: URI.URI, owningSpaceId: SpaceId | undefined): URI.URI => {
+  if (owningSpaceId == null) {
+    return uri;
+  }
+  const eid = EID.tryParse(uri);
+  if (eid == null || !EID.isLocal(eid)) {
+    return uri;
+  }
+  const entityId = EID.getEntityId(eid);
+  return entityId != null ? EID.make({ spaceId: owningSpaceId, entityId }) : uri;
+};
+
+/**
+ * Direct strong-dependency URIs of a live (decoded) entity — a queue item, cross-space proxy, or
+ * snapshot. Reads the reference URIs off the entity's hidden model symbols. ECHO db cores compute
+ * the same set from their raw encoded references via {@link getStrongDependencyUris}.
+ */
+export const getStrongDependencies = (entity: unknown): URI.URI[] => {
+  if (entity == null || typeof entity !== 'object') {
+    return [];
+  }
+  const props = entity as Record<symbol, unknown>;
+  const kind =
+    props[RelationSourceDXNId] != null || props[RelationTargetDXNId] != null ? EntityKind.Relation : EntityKind.Object;
+  const parent = props[ParentId];
+
+  // The entity's own space qualifies any relative dependency URIs it carries.
+  const selfUri = getObjectEchoUri(entity);
+  const owningSpaceId = selfUri != null ? EID.getSpaceId(selfUri) : undefined;
+
+  return getStrongDependencyUris(
+    {
+      kind,
+      type: typeof props[TypeId] === 'string' ? (props[TypeId] as URI.URI) : undefined,
+      source: props[RelationSourceDXNId] as URI.URI | undefined,
+      target: props[RelationTargetDXNId] as URI.URI | undefined,
+      // A parent is held as the resolved entity; derive its absolute URI for the dependency edge.
+      parent: parent != null ? getObjectEchoUri(parent) : undefined,
+    },
+    owningSpaceId,
+  );
+};