@dxos/echo 0.8.4-main.fd6878d → 0.8.4-staging.60fe92afc8

package/src/internal/common/types/entity.ts

@@ -0,0 +1,133 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+// NOTE: String literals are used instead of unique symbols for both KindId and SchemaKindId.
+//   Unique symbols cause TS4023 "cannot be named" errors when external packages
+//   try to export types that reference this key (e.g., `export const Graph = ...`).
+//   TypeScript cannot emit declaration files that reference unique symbols from
+//   external modules. Using a string literal allows the type to be inlined in
+//   declaration files, making the API portable across package boundaries.
+
+/**
+ * String key used to identify the kind of an entity instance (object or relation).
+ */
+export const KindId = '~@dxos/echo/Kind' as const;
+export type KindId = typeof KindId;
+
+/**
+ * String key used to identify the kind of a schema (object schema or relation schema).
+ * Parallels KindId which identifies instance kinds.
+ */
+export const SchemaKindId = '~@dxos/echo/SchemaKind' as const;
+export type SchemaKindId = typeof SchemaKindId;
+
+/**
+ * String key used to brand snapshot types.
+ * Snapshots have SnapshotKindId instead of KindId, making them
+ * distinguishable from reactive objects at the type level.
+ */
+export const SnapshotKindId = '~@dxos/echo/SnapshotKind' as const;
+export type SnapshotKindId = typeof SnapshotKindId;
+
+/**
+ * Hidden slot on a static `Type.Type` entity that holds the source Effect
+ * Schema. `Type.getSchema(...)` reads this for static types; persisted types
+ * rebuild from `jsonSchema` instead. Stored as a string key for declaration
+ * portability (see KindId comment above).
+ */
+export const StaticTypeSchemaSlot = '~@dxos/echo/Type.StaticSchema' as const;
+export type StaticTypeSchemaSlot = typeof StaticTypeSchemaSlot;
+
+/**
+ * Read the hidden `StaticTypeSchemaSlot` off any value that may carry one.
+ * Returns `undefined` for raw schemas (no slot) and non-object inputs.
+ * Single point-of-cast for the slot lookup.
+ */
+export const getStaticTypeSchema = (value: unknown): Schema.Schema.AnyNoContext | undefined => {
+  if (value == null || typeof value !== 'object') {
+    return undefined;
+  }
+  return (value as { [StaticTypeSchemaSlot]?: Schema.Schema.AnyNoContext })[StaticTypeSchemaSlot];
+};
+
+/**
+ * Read the `[SchemaKindId]` brand off a value. Returns `undefined` for raw
+ * schemas (which don't carry the brand on their static type) and non-object
+ * inputs. Single point-of-cast for the brand lookup.
+ */
+export const getSchemaKind = (value: unknown): EntityKind | undefined => {
+  if (value == null || typeof value !== 'object') {
+    return undefined;
+  }
+  return (value as { [SchemaKindId]?: EntityKind })[SchemaKindId];
+};
+
+/**
+ * Read the `[KindId]` brand off a value. Returns `undefined` for raw schemas
+ * and non-object inputs. Companion to {@link getSchemaKind}.
+ */
+export const getEntityKindBrand = (value: unknown): EntityKind | undefined => {
+  if (value == null || typeof value !== 'object') {
+    return undefined;
+  }
+  return (value as { [KindId]?: EntityKind })[KindId];
+};
+
+/**
+ * Phantom string key on `Type<A>` entities that carries the instance type `A`.
+ * Lets internal helpers (`makeObject`, `createObject`, etc.) pattern-match the
+ * instance type from an entity input without importing from the top-level
+ * `Type` module. Mirrors `Type.InstancePhantomId` (declared in `Type.ts`).
+ *
+ * Stored as a string key so declarations remain portable across packages
+ * (see KindId comment above).
+ */
+export const InstancePhantomId = '~@dxos/echo/Type.Instance' as const;
+export type InstancePhantomId = typeof InstancePhantomId;
+
+/**
+ * Nominal brand carried by the well-known "any object" / "any relation"
+ * schemas (`Obj.Unknown`, `Relation.Unknown`). The brand lets `Ref.Ref`,
+ * `Filter.type`, and `Query.type` accept these schemas in addition to
+ * `Type.Type` entities, without opening the door to arbitrary raw schemas.
+ *
+ * Stored as a string key so declarations remain portable across packages
+ * (see KindId comment above).
+ */
+export const UnknownTypeSchemaBrandId = '~@dxos/echo/UnknownTypeSchemaBrand' as const;
+export type UnknownTypeSchemaBrandId = typeof UnknownTypeSchemaBrandId;
+
+/**
+ * Schema-side companion to `Type.Type` entities for the "any object" /
+ * "any relation" cases. Branded so `Ref.Ref` / `Filter.type` / `Query.type`
+ * can pattern-match on it; arbitrary `Schema.Schema` values do not satisfy
+ * this shape.
+ */
+export interface UnknownTypeSchema<A, K extends EntityKind> extends Schema.Schema<A, any, never> {
+  readonly [UnknownTypeSchemaBrandId]: K;
+}
+
+/**
+ * Kinds of entities stored in ECHO: objects, relations, and types.
+ */
+export enum EntityKind {
+  Object = 'object',
+  Relation = 'relation',
+  Type = 'type',
+}
+
+export const EntityKindSchema = Schema.Enums(EntityKind);
+
+/**
+ * Typename for generic object references (Type.Obj / Ref.Ref(Obj.Unknown)).
+ * Used when referencing any object without a specific schema.
+ */
+export const ANY_OBJECT_TYPENAME = 'org.dxos.schema.anyObject';
+
+/**
+ * Version for generic object references.
+ */
+export const ANY_OBJECT_VERSION = '0.0.0';

package/src/internal/common/types/index.ts

@@ -0,0 +1,15 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './base';
+export * from './entity';
+// NOTE: `./meta` is intentionally NOT re-exported here. It depends on the Ref schema (`Ref/ref`),
+// which transitively pulls in `Annotation` + `Database`; re-exporting it from this low-level barrel
+// — imported by `Annotation/util`, `Annotation/annotations`, `Entity/type-uri`, and `Ref/ref` —
+// would create an eval-order cycle (TDZ on `createAnnotationHelper`). Import meta from `./meta`
+// directly, or from the top-level `@dxos/echo/internal` barrel (re-exported there after Ref loads).
+export * from './model-symbols';
+export * from './typename';
+export * from './version';
+export * from './well-known-types';

package/src/internal/common/types/meta.ts

@@ -0,0 +1,109 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { type EncodedReference, ForeignKey } from '@dxos/echo-protocol';
+import { invariant } from '@dxos/invariant';
+import { DXN } from '@dxos/keys';
+import { type Comparator, intersection } from '@dxos/util';
+
+import type * as Tag from '../../../Tag';
+import { Dictionary } from '../../Annotation/dictionary';
+// `meta` is no longer re-exported from the `common/types` barrel (see ./index.ts), so importing the
+// Ref schema builder here no longer forms an eval-order cycle with `Annotation`/`Database`.
+import { type Ref, createEchoReferenceSchema } from '../../Ref/ref';
+import { type AnyProperties } from './base';
+import { MetaId } from './model-symbols';
+import { TagTypeDXN } from './well-known-types';
+
+/**
+ * Property name for meta when object is serialized to JSON.
+ */
+export const ATTR_META = '@meta';
+
+//
+// EntityMeta
+//
+
+/**
+ * Schema for references to {@link Tag} objects stored in {@link EntityMetaSchema.tags}.
+ *
+ * Built from the shared {@link createEchoReferenceSchema} (the same builder `Ref.Ref` uses) via
+ * `Schema.suspend`, so it reuses the canonical ref codec rather than duplicating it. The Tag type
+ * identity comes from the shared {@link TagTypeDXN} constant; `suspend` defers construction until
+ * first use, and `Tag` is referenced type-only, so no `Tag` value import is needed.
+ */
+const TagRefSchema = Schema.suspend(
+  (): Schema.Schema<Ref<Tag.Tag>, EncodedReference> =>
+    // The factory yields a loosely-typed `Ref<any>` schema; narrow it to the Tag-typed ref.
+    createEchoReferenceSchema(undefined, DXN.getName(TagTypeDXN), DXN.getVersion(TagTypeDXN)) as Schema.Schema<
+      Ref<Tag.Tag>,
+      EncodedReference
+    >,
+);
+
+export const EntityMetaSchema = Schema.Struct({
+  keys: Schema.Array(ForeignKey),
+
+  /**
+   * Tags applied to this entity, as references to {@link Tag} objects.
+   */
+  tags: Schema.Array(TagRefSchema),
+
+  /**
+   * Fully-qualified registry key for the object (FQN format, e.g. `org.example.type.foo`).
+   * Identifies the canonical registry entry the object instance was created from.
+   */
+  key: Schema.optional(Schema.String),
+
+  /**
+   * Semantic version of the registry entry the object was created from.
+   * Must be a valid semver string (e.g. `1.2.3`).
+   */
+  version: Schema.optional(Schema.String),
+
+  /**
+   * Dictionary of annotations to this entity.
+   */
+  annotations: Dictionary,
+
+  /**
+   * Unix ms timestamp when this entity was created.
+   * Read-only; sourced from the system section of the automerge document — not stored in meta.
+   */
+  createdAt: Schema.optional(Schema.Number),
+
+  /**
+   * Unix ms timestamp of the last automerge change on this entity's document.
+   * Read-only; derived from the automerge change graph — not stored in meta.
+   */
+  updatedAt: Schema.optional(Schema.Number),
+});
+
+export type EntityMeta = Schema.Schema.Type<typeof EntityMetaSchema>;
+
+/*
+ * Get metadata from object.
+ * Only callable on the object root.
+ *
+ * @internal (use Obj.getMeta or Relation.getMeta)
+ */
+// TODO(burdon): Refine type to BaseObj.
+export const getMeta = (obj: AnyProperties): EntityMeta => {
+  const metadata = (obj as any)[MetaId];
+  invariant(metadata, 'EntityMeta not found.');
+  return metadata;
+};
+
+//
+// Foreign keys
+//
+
+export const foreignKey = (source: string, id: string): ForeignKey => ({ source, id });
+export const foreignKeyEquals = (a: ForeignKey, b: ForeignKey) => a.source === b.source && a.id === b.id;
+
+// TODO(dmaretskyi): Move to echo-schema.
+export const compareForeignKeys: Comparator<AnyProperties> = (a: AnyProperties, b: AnyProperties) =>
+  intersection(getMeta(a).keys, getMeta(b).keys, foreignKeyEquals).length > 0;

package/src/internal/common/types/model-symbols.ts

@@ -0,0 +1,89 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// TODO(rename): These internal entity-wide symbols/types still use the `Object*` prefix but apply
+// to all entities (objects AND relations). Rename to `Entity*` in a follow-up pass (deferred from the
+// EchoURI→EID / ObjectId→EntityId / ObjectMeta→EntityMeta rename, which covered only public SDK API):
+//   ObjectCore, ObjectInternals, ObjectVersion, ObjectVersionId, ObjectDeletedId, ObjectDatabaseId,
+//   ObjectLoader, ObjectDocumentLoaded, ObjectUnavailable.
+// (ObjectMigration / ObjectMigrationContext intentionally excluded — object-only, not entity-wide.)
+
+/**
+ * Internal symbol/string constants for the echo object model.
+ * Defined in common/ so proxy/ can use them without importing from Entity/.
+ * Entity/ re-exports these for external consumers.
+ */
+
+/**
+ * Property name for the object's own URI when serialized to JSON.
+ */
+export const ATTR_SELF_URI = '@uri';
+
+/**
+ * @deprecated Legacy JSON property name accepted on read for backward compat.
+ */
+export const ATTR_SELF_URI_LEGACY = '@dxn';
+
+/**
+ * Symbol carrying the object's own URI on live entities.
+ */
+export const SelfURIId = Symbol.for('@dxos/echo/URI');
+
+/**
+ * Property name for deleted when object is serialized to JSON.
+ */
+export const ATTR_DELETED = '@deleted';
+
+/**
+ * Deletion marker.
+ */
+export const ObjectDeletedId = Symbol.for('@dxos/echo/Deleted');
+
+/**
+ * Object version accessor symbol.
+ */
+export const ObjectVersionId: unique symbol = Symbol.for('@dxos/echo/Version');
+
+/**
+ * Object database accessor symbol.
+ */
+export const ObjectDatabaseId = Symbol.for('@dxos/echo/Database');
+
+/**
+ * Property name for relation source when object is serialized to JSON.
+ */
+export const ATTR_RELATION_SOURCE = '@relationSource';
+
+/**
+ * Used to access relation source ref on live ECHO objects.
+ */
+export const RelationSourceId: unique symbol = Symbol.for('@dxos/echo/RelationSource');
+
+/**
+ * Used to access relation source DXN on live ECHO objects.
+ */
+export const RelationSourceDXNId: unique symbol = Symbol.for('@dxos/echo/RelationSourceDXN');
+
+/**
+ * Property name for relation target when object is serialized to JSON.
+ */
+export const ATTR_RELATION_TARGET = '@relationTarget';
+
+/**
+ * Used to access relation target ref on live ECHO objects.
+ */
+export const RelationTargetId: unique symbol = Symbol.for('@dxos/echo/RelationTarget');
+
+/**
+ * Used to access relation target DXN on live ECHO objects.
+ */
+export const RelationTargetDXNId: unique symbol = Symbol.for('@dxos/echo/RelationTargetDXN');
+
+/**
+ * Symbol carrying the entity metadata (EntityMeta) on live ECHO entities.
+ * Must be importable by both meta.ts (which depends on the Ref schema) and
+ * Entity/api.ts (which is transitively imported by the Ref schema), so it
+ * cannot live in either of those files without creating an import cycle.
+ */
+export const MetaId = Symbol.for('@dxos/echo/Meta');

package/src/internal/common/types/typename.ts

@@ -0,0 +1,91 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import type * as Schema from 'effect/Schema';
+
+/**
+ * Property name for typename when object is serialized to JSON.
+ */
+export const ATTR_TYPE = '@type';
+
+/**
+ * DXN to the object type.
+ */
+export const TypeId = Symbol.for('@dxos/echo/Type');
+
+/**
+ * Reference to the object schema.
+ */
+export const SchemaId = Symbol.for('@dxos/echo/Schema');
+
+/**
+ * Property name for parent when object is serialized to JSON.
+ */
+export const ATTR_PARENT = '@parent';
+
+/**
+ * Reference to the object parent.
+ */
+export const ParentId = Symbol.for('@dxos/echo/Parent');
+
+/**
+ * Reference to the object's type entity (`Type.Obj`, `Type.Relation`, or
+ * `Type.Type`). Set at instance creation by `createObject` / `makeObject`
+ * when the entity is known. Public read-back via `Obj.getType` / `Relation.getType`
+ * / `Entity.getType`.
+ */
+export const TypeEntityId = Symbol.for('@dxos/echo/TypeEntity');
+
+/**
+ * Returns the Effect Schema for the given object if one is defined.
+ *
+ * @internal
+ * Internal callers needing schema-side validation read from `SchemaId`.
+ * Public callers should use `Type.getSchema(Obj.getType(obj))` instead.
+ */
+// TODO(dmaretskyi): For echo objects, this always returns the root schema.
+export const getSchema = (obj: unknown | undefined): Schema.Schema.AnyNoContext | undefined => {
+  if (obj) {
+    return (obj as any)[SchemaId];
+  }
+};
+
+/**
+ * @internal
+ */
+export const setSchema = (obj: any, schema: Schema.Schema.AnyNoContext): void => {
+  Object.defineProperty(obj, SchemaId, {
+    value: schema,
+    writable: false,
+    enumerable: false,
+    configurable: false,
+  });
+};
+
+/**
+ * Returns the type entity (`Type.AnyEntity`) for the given instance.
+ * Set at instance creation; every entity has a type. Defensive: returns
+ * undefined for null/undefined input so callers can safely probe arbitrary
+ * values via this helper.
+ *
+ * @internal Re-exported via `Obj.getType` / `Relation.getType` / `Entity.getType`.
+ */
+export const getType = (obj: unknown): unknown => {
+  if (obj == null) {
+    return undefined;
+  }
+  return (obj as any)[TypeEntityId];
+};
+
+/**
+ * @internal
+ */
+export const setType = (obj: any, type: unknown): void => {
+  Object.defineProperty(obj, TypeEntityId, {
+    value: type,
+    writable: false,
+    enumerable: false,
+    configurable: true,
+  });
+};

package/src/internal/common/types/version.ts

@@ -0,0 +1,19 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+/**
+ * Version type identifier.
+ */
+export const VersionTypeId = '~@dxos/echo/VersionTypeId' as const;
+export type VersionTypeId = typeof VersionTypeId;
+
+/**
+ * Represents the object version.
+ * May be backed by Automerge.
+ * Objects with no history are not versioned.
+ */
+export interface Version {
+  [VersionTypeId]: {};
+  automergeHeads?: string[];
+}

package/src/internal/common/types/well-known-types.ts

@@ -0,0 +1,15 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { DXN } from '@dxos/keys';
+
+/**
+ * DXN identity of the system {@link Tag} type.
+ *
+ * Defined in this low-level leaf so it can be shared by the public `Tag` type (which brands the
+ * schema with this DXN) and by `EntityMetaSchema.tags` (which builds a `Ref<Tag>` schema from it)
+ * without either importing the other — `Tag` is top-level and `meta` is deep-internal, so a direct
+ * dependency between them would form an eval-order cycle.
+ */
+export const TagTypeDXN = DXN.make('org.dxos.type.tag', '0.1.0');

package/src/internal/index.ts

@@ -0,0 +1,19 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './Annotation';
+export * from './common';
+export * from './Entity';
+export * from './Format';
+export * from './JsonSchema';
+// TODO(wittjosiah): Required to ensure types are portable (need to export all types required for downstream inference).
+export * from './Obj';
+export { prettyFilter, prettyQuery } from './Query/pretty';
+export * from './Ref';
+export * from './Type';
+
+// Re-exported here (not from the low-level `common/types` barrel) so consumers keep importing meta
+// from `@dxos/echo/internal`, while that barrel stays free of the Ref/Annotation eval cycle. Placed
+// after `./Ref` so the ref schema `meta` depends on is initialized first.
+export * from './common/types/meta';

package/src/testing/api.test.ts

@@ -0,0 +1,131 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { describe, test } from 'vitest';
+
+import { raise } from '@dxos/debug';
+
+import { Entity, Obj, Ref, Relation, Type } from '../index';
+import { TestSchema } from './test-schema';
+
+describe('Experimental API review', () => {
+  test('type checks', ({ expect }) => {
+    const contact = Obj.make(TestSchema.Person, { name: 'Test' });
+    const type = Obj.getType(contact) ?? raise(new Error('No type found'));
+
+    expect(Type.getTypename(type)).to.eq(Type.getTypename(TestSchema.Person));
+    expect(Type.getTypename(type)).to.eq('com.example.type.person');
+    expect(Type.getVersion(type)).to.eq('0.1.0');
+    // `Type.getMeta` returns `EntityMeta` (`{ keys, tags?, key?, version? }`) —
+    // the same shape `Obj.getMeta` and `Relation.getMeta` return. The
+    // schema-kind brand lives on `[SchemaKindId]`, not in meta.
+    expect(Type.getMeta(type)).to.deep.eq({
+      keys: [],
+      tags: [],
+      annotations: {},
+      key: 'com.example.type.person',
+      version: '0.1.0',
+    });
+    expect(Type.isObject(type)).to.be.true;
+  });
+
+  test('instance checks', ({ expect }) => {
+    const organization = Obj.make(TestSchema.Organization, { name: 'DXOS' });
+    const contact = Obj.make(TestSchema.Person, {
+      name: 'Test',
+      employer: Ref.make(organization),
+    });
+
+    expect(Schema.is(Type.getSchema(TestSchema.Person))(contact)).to.be.true;
+    expect(Obj.instanceOf(TestSchema.Person, contact)).to.be.true;
+    expect(Obj.instanceOf(TestSchema.Organization, organization)).to.be.true;
+
+    const isPerson = Obj.instanceOf(TestSchema.Person);
+    const x: any = {};
+    if (isPerson(x)) {
+      x.name;
+    }
+  });
+
+  test('default props', ({ expect }) => {
+    const message = Obj.make(TestSchema.Message, TestSchema.MessageStruct.make({}));
+    expect(message.timestamp).to.exist;
+  });
+
+  test('Obj.isObject', ({ expect }) => {
+    const guy = Obj.make(TestSchema.Person, { name: 'Test' });
+    expect(Obj.isObject(guy)).to.be.true;
+    expect(Obj.isObject(null)).to.be.false;
+    expect(Obj.isObject(undefined)).to.be.false;
+    expect(Obj.isObject(1)).to.be.false;
+    expect(Obj.isObject('string')).to.be.false;
+  });
+
+  test('create relation', ({ expect }) => {
+    const person = Obj.make(TestSchema.Person, { name: 'Test' });
+    const organization = Obj.make(TestSchema.Organization, { name: 'DXOS' });
+    const worksFor = Relation.make(TestSchema.EmployedBy, {
+      [Relation.Source]: person,
+      [Relation.Target]: organization,
+      role: 'CEO',
+    });
+    expect(Relation.getSource(worksFor)).to.eq(person);
+    expect(Relation.getTarget(worksFor)).to.eq(organization);
+  });
+
+  test('version', ({ expect }) => {
+    const person = Obj.make(TestSchema.Person, { name: 'Test' });
+    const version = Obj.version(person);
+    expect(Obj.isVersion(version)).to.be.true;
+    expect(Obj.versionValid(version)).to.be.false;
+  });
+
+  // TODO(burdon): Implement test.
+  test.skip('type narrowing', () => {
+    const any: Entity.Unknown = null as any;
+
+    {
+      if (Obj.isObject(any)) {
+        any;
+      } else {
+        any;
+      }
+    }
+
+    {
+      if (Relation.isRelation(any)) {
+        any;
+      } else {
+        any;
+      }
+    }
+  });
+
+  /**
+   * Test that Obj.make return types are clean and don't expose internal markers like OfKind.
+   * The return type of Obj.make(Schema, props) should be assignable to Obj.Obj<InstanceType>.
+   */
+  describe('Obj.make return type', () => {
+    test('Obj.make with custom schema should be assignable to Obj.Obj<Person>', ({ expect }) => {
+      {
+        const expando = Obj.make(TestSchema.Expando, { content: 'Test' });
+        expect(Obj.isObject(expando)).to.be.true;
+        expect(expando.content).to.eq('Test');
+
+        // This should work: assign to Obj.Obj of the schema's instance type
+        const _typed: Obj.OfShape<TestSchema.Expando> = expando;
+      }
+
+      {
+        const person = Obj.make(TestSchema.Person, { name: 'Test' });
+        expect(Obj.isObject(person)).to.be.true;
+        expect(person.name).to.eq('Test');
+
+        // This should work: assign to Obj.Obj of the schema's instance type
+        const _typed: Obj.OfShape<TestSchema.Person> = person;
+      }
+    });
+  });
+});

package/src/testing/index.ts

@@ -2,4 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-export * from './types';
+export * from './registry';
+export * from './test-data';
+export * from './test-schema';
+export * from './util';

package/src/testing/registry.ts

@@ -0,0 +1,44 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Atom from '@effect-atom/atom/Atom';
+import * as Layer from 'effect/Layer';
+
+import { Event } from '@dxos/async';
+
+import * as Registry from '../Registry';
+
+/**
+ * Noop `Registry.Service` layer for testing — always returns empty query results.
+ * Use this in test layer stacks that require `Registry.Service` but don't need
+ * actual registry contents.
+ */
+export const registryLayerNoop: Layer.Layer<Registry.Service> = Layer.succeed(Registry.Service, {
+  [Registry.TypeId]: Registry.TypeId,
+  id: 'noop-registry',
+  changed: new Event<void>(),
+  local: [],
+  add: () => {},
+  remove: () => false,
+  clear: () => {},
+  get: () => undefined,
+  getByURI: () => undefined,
+  list: () => [],
+  // QueryFn is an overloaded interface — a single generic function cannot satisfy both overload
+  // signatures without a cast. This is the intentional type-system boundary.
+  query: ((_queryOrFilter: unknown) => ({
+    results: [],
+    entries: [],
+    run: async () => [],
+    runEntries: async () => [],
+    runSync: () => [],
+    runSyncEntries: () => [],
+    first: async (): Promise<never> => {
+      throw new Error('registryLayerNoop: registry is empty');
+    },
+    firstOrUndefined: async () => undefined,
+    subscribe: () => () => {},
+    atom: Atom.make((): never[] => []),
+  })) as Registry.Registry['query'],
+} satisfies Registry.Registry);