@dxos/echo 0.10.0 → 0.11.1

package/dist/lib/chunk-Database.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk-Database.mjs","names":[],"sources":["../../src/internal/common/types/model-symbols.ts","../../src/internal/common/types/typename.ts","../../src/internal/Annotation/annotations.ts","../../src/internal/Entity/util.ts","../../src/internal/Entity/api.ts","../../src/internal/Entity/type-uri.ts","../../src/internal/Query/query-result-effect.ts","../../src/Database.ts"],"sourcesContent":["//\n// Copyright 2025 DXOS.org\n//\n\n// TODO(rename): These internal entity-wide symbols/types still use the `Object*` prefix but apply\n// to all entities (objects AND relations). Rename to `Entity*` in a follow-up pass (deferred from the\n// EchoURI→EID / ObjectId→EntityId / ObjectMeta→EntityMeta rename, which covered only public SDK API):\n//   ObjectCore, ObjectInternals, ObjectVersion, ObjectVersionId, ObjectDeletedId, ObjectDatabaseId,\n//   ObjectLoader, ObjectDocumentLoaded, ObjectUnavailable.\n// (ObjectMigration / ObjectMigrationContext intentionally excluded — object-only, not entity-wide.)\n\n/**\n * Internal symbol/string constants for the echo object model.\n * Defined in common/ so proxy/ can use them without importing from Entity/.\n * Entity/ re-exports these for external consumers.\n */\n\n/**\n * Property name for the object's own URI when serialized to JSON.\n */\nexport const ATTR_SELF_URI = '@uri';\n\n/**\n * @deprecated Legacy JSON property name accepted on read for backward compat.\n */\nexport const ATTR_SELF_URI_LEGACY = '@dxn';\n\n/**\n * Symbol carrying the object's own URI on live entities.\n */\nexport const SelfURIId = Symbol.for('@dxos/echo/URI');\n\n/**\n * Property name for deleted when object is serialized to JSON.\n */\nexport const ATTR_DELETED = '@deleted';\n\n/**\n * Deletion marker.\n */\nexport const ObjectDeletedId = Symbol.for('@dxos/echo/Deleted');\n\n/**\n * Object version accessor symbol.\n */\nexport const ObjectVersionId: unique symbol = Symbol.for('@dxos/echo/Version');\n\n/**\n * Object database accessor symbol.\n */\nexport const ObjectDatabaseId = Symbol.for('@dxos/echo/Database');\n\n/**\n * Branch accessor symbol. Resolves to the branch name this object instance is bound to (`'main'` for\n * the canonical object, or the branch of a `db.branch()` independent instance). Read via `Obj.getBranch`.\n */\nexport const ObjectBranchId = Symbol.for('@dxos/echo/Branch');\n\n/**\n * Property name for relation source when object is serialized to JSON.\n */\nexport const ATTR_RELATION_SOURCE = '@relationSource';\n\n/**\n * Used to access relation source ref on live ECHO objects.\n */\nexport const RelationSourceId: unique symbol = Symbol.for('@dxos/echo/RelationSource');\n\n/**\n * Used to access relation source DXN on live ECHO objects.\n */\nexport const RelationSourceDXNId: unique symbol = Symbol.for('@dxos/echo/RelationSourceDXN');\n\n/**\n * Property name for relation target when object is serialized to JSON.\n */\nexport const ATTR_RELATION_TARGET = '@relationTarget';\n\n/**\n * Used to access relation target ref on live ECHO objects.\n */\nexport const RelationTargetId: unique symbol = Symbol.for('@dxos/echo/RelationTarget');\n\n/**\n * Used to access relation target DXN on live ECHO objects.\n */\nexport const RelationTargetDXNId: unique symbol = Symbol.for('@dxos/echo/RelationTargetDXN');\n\n/**\n * Symbol carrying the entity metadata (EntityMeta) on live ECHO entities.\n * Must be importable by both meta.ts (which depends on the Ref schema) and\n * Entity/api.ts (which is transitively imported by the Ref schema), so it\n * cannot live in either of those files without creating an import cycle.\n */\nexport const MetaId = Symbol.for('@dxos/echo/Meta');\n","//\n// Copyright 2024 DXOS.org\n//\n\nimport type * as Schema from 'effect/Schema';\n\n/**\n * Property name for typename when object is serialized to JSON.\n */\nexport const ATTR_TYPE = '@type';\n\n/**\n * DXN to the object type.\n */\nexport const TypeId = Symbol.for('@dxos/echo/Type');\n\n/**\n * Reference to the object schema.\n */\nexport const SchemaId = Symbol.for('@dxos/echo/Schema');\n\n/**\n * Property name for parent when object is serialized to JSON.\n */\nexport const ATTR_PARENT = '@parent';\n\n/**\n * Reference to the object parent.\n */\nexport const ParentId = Symbol.for('@dxos/echo/Parent');\n\n/**\n * Reference to the object's type entity (`Type.Obj`, `Type.Relation`, or\n * `Type.Type`). Set at instance creation by `createObject` / `makeObject`\n * when the entity is known. Public read-back via `Obj.getType` / `Relation.getType`\n * / `Entity.getType`.\n */\nexport const TypeEntityId = Symbol.for('@dxos/echo/TypeEntity');\n\n/**\n * Returns the Effect Schema for the given object if one is defined.\n *\n * @internal\n * Internal callers needing schema-side validation read from `SchemaId`.\n * Public callers should use `Type.getSchema(Obj.getType(obj))` instead.\n */\n// TODO(dmaretskyi): For echo objects, this always returns the root schema.\nexport const getSchema = (obj: unknown | undefined): Schema.Schema.AnyNoContext | undefined => {\n  if (obj) {\n    return (obj as any)[SchemaId];\n  }\n};\n\n/**\n * @internal\n */\nexport const setSchema = (obj: any, schema: Schema.Schema.AnyNoContext): void => {\n  Object.defineProperty(obj, SchemaId, {\n    value: schema,\n    writable: false,\n    enumerable: false,\n    configurable: false,\n  });\n};\n\n/**\n * Returns the type entity (`Type.AnyEntity`) for the given instance.\n * Set at instance creation; every entity has a type. Defensive: returns\n * undefined for null/undefined input so callers can safely probe arbitrary\n * values via this helper.\n *\n * @internal Re-exported via `Obj.getType` / `Relation.getType` / `Entity.getType`.\n */\nexport const getType = (obj: unknown): unknown => {\n  if (obj == null) {\n    return undefined;\n  }\n  return (obj as any)[TypeEntityId];\n};\n\n/**\n * @internal\n */\nexport const setType = (obj: any, type: unknown): void => {\n  Object.defineProperty(obj, TypeEntityId, {\n    value: type,\n    writable: false,\n    enumerable: false,\n    configurable: true,\n  });\n};\n","//\n// Copyright 2024 DXOS.org\n//\n\nimport * as Function from 'effect/Function';\nimport * as Option from 'effect/Option';\nimport * as Schema from 'effect/Schema';\nimport * as SchemaAST from 'effect/SchemaAST';\n\nimport { SchemaEx } from '@dxos/effect';\nimport { assertArgument, invariant } from '@dxos/invariant';\nimport { DXN, URI } from '@dxos/keys';\nimport { type Primitive } from '@dxos/util';\n\nimport type * as Annotation from '../../Annotation';\nimport { type Mutable } from '../common/proxy';\nimport { type AnyProperties, EntityKind, TypeId, getSchema } from '../common/types';\nimport { createAnnotationHelper } from './util';\n\nconst ANNOTATION_TYPE_ID: Annotation.TypeId = '~@dxos/echo/Annotation' as const;\n\n/**\n * @internal\n */\nexport const FIELD_PATH_ANNOTATION = 'path';\n\n/**\n * Sets the path for the field.\n * @param path Data source path in the json path format. This is the field path in the source object.\n */\n// TODO(burdon): Field, vs. path vs. property.\nexport const FieldPath = (path: string) => PropertyMeta(FIELD_PATH_ANNOTATION, path);\n\n//\n// Type\n//\n\n/**\n * ECHO identifier (for a stored schema).\n * Must be an `echo:` URI.\n */\nexport const TypeIdentifierAnnotationId = Symbol.for('@dxos/schema/annotation/TypeIdentifier');\n\nexport const getTypeIdentifierAnnotation = (schema: Schema.Schema.All) =>\n  Function.flow(\n    SchemaAST.getAnnotation<string>(TypeIdentifierAnnotationId),\n    Option.getOrElse(() => undefined),\n  )(schema.ast);\n\n/**\n * @returns The schema's type identifier URI — whichever URI fits.\n *\n * - Stored (dynamic) schemas: the schema-as-object's EID, so loaded objects ride\n *   along with their schema as a strong dependency.\n * - Non-stored (static) schemas: the typename DXN built from `TypeAnnotation`.\n *\n * This URI is what gets written to an object's `system.type`; queries that filter by\n * type also use it (see `Filter.type` / `getTypeURIFromSpecifier`), so both sides\n * stay symmetric without per-schema branching.\n */\nexport const getSchemaURI = (schema: Schema.Schema.All): URI.URI | undefined => {\n  assertArgument(Schema.isSchema(schema), 'schema', 'invalid schema');\n  const id = getTypeIdentifierAnnotation(schema);\n  if (id) {\n    return URI.make(id);\n  }\n  const objectAnnotation = getTypeAnnotation(schema);\n  if (objectAnnotation) {\n    return DXN.make(objectAnnotation.typename, objectAnnotation.version);\n  }\n  return undefined;\n};\n\n//\n// TypeAnnotation\n//\n\n/**\n * Fully qualified globally unique typename.\n * Example: `org.dxos.type.message`\n */\n// TODO(wittjosiah): Factor out to DXN spec.\nexport const TypenameSchema = Schema.String.pipe(\n  Schema.pattern(\n    /^[a-zA-Z]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+(\\.[a-zA-Z]([a-zA-Z0-9]{0,62})?)$/,\n  ),\n).annotations({\n  description: 'Fully qualified globally unique typename in reverse-DNS form.',\n  example: 'org.dxos.type.message',\n});\n\n/**\n * Semantic version format: `major.minor.patch`\n * Example: `1.0.0`\n */\nexport const VersionSchema = Schema.String.pipe(Schema.pattern(/^\\d+.\\d+.\\d+$/)).annotations({\n  description: 'Semantic version format: `major.minor.patch`',\n  example: '1.0.0',\n});\n\nexport const TypeMeta = Schema.Struct({\n  typename: TypenameSchema,\n  version: VersionSchema,\n});\n\nexport interface TypeMeta extends Schema.Schema.Type<typeof TypeMeta> {}\n\n/**\n * Entity type.\n */\nexport const TypeAnnotationId = Symbol.for('@dxos/schema/annotation/Type');\n\n/**\n * Payload stored under {@link TypeAnnotationId}.\n */\nexport const TypeAnnotation = Schema.extend(\n  TypeMeta,\n  Schema.Struct({\n    kind: Schema.Enums(EntityKind),\n\n    /**\n     * If this is a relation, the schema of the source object.\n     * Must be present if entity kind is {@link EntityKind.Relation}.\n     */\n    sourceSchema: Schema.optional(DXN.Schema),\n\n    /**\n     * If this is a relation, the schema of the target object.\n     * Must be present if entity kind is {@link EntityKind.Relation}.\n     */\n    targetSchema: Schema.optional(DXN.Schema),\n  }),\n);\n\nexport interface TypeAnnotation extends Schema.Schema.Type<typeof TypeAnnotation> {}\n\n/**\n * @returns {@link TypeAnnotation} from a schema.\n * Schema must have been created with {@link TypedObject} or {@link TypedLink} or manually assigned an appropriate annotation.\n */\nexport const getTypeAnnotation = (schema: Schema.Schema.All): TypeAnnotation | undefined => {\n  assertArgument(schema != null && schema.ast != null, 'schema', 'invalid schema');\n  return Function.flow(\n    SchemaAST.getAnnotation<TypeAnnotation>(TypeAnnotationId),\n    Option.getOrElse(() => undefined),\n  )(schema.ast);\n};\n\n/**\n * @returns {@link EntityKind} from a schema.\n */\nexport const getEntityKind = (schema: Schema.Schema.All): EntityKind | undefined => getTypeAnnotation(schema)?.kind;\n\n/**\n * @internal\n * @returns Schema typename (without dxn: prefix or version number).\n */\nexport const getSchemaTypename = (schema: Schema.Schema.All): string | undefined => getTypeAnnotation(schema)?.typename;\n\n/**\n * @internal\n * @returns Schema version in semver format.\n */\nexport const getSchemaVersion = (schema: Schema.Schema.All): string | undefined => getTypeAnnotation(schema)?.version;\n\n/**\n * Gets the typename of the object without the version.\n * Returns only the name portion, not the DXN.\n * @example \"org.example.type.contact\"\n *\n * @internal (use Obj.getTypename)\n */\nexport const getTypename = (obj: AnyProperties): string | undefined => {\n  const schema = getSchema(obj);\n  if (schema != null) {\n    // Try to extract typename from DXN.\n    return getSchemaTypename(schema);\n  } else {\n    // `obj` may be an arbitrary value (e.g. from `isInstanceOf`); read TypeId\n    // directly so we return undefined for non-entities instead of throwing.\n    const type = (obj as any)?.[TypeId];\n    // Parse the URI string to extract typename.\n    if (DXN.isDXN(type)) {\n      const parsed = DXN.tryMake(type);\n      return parsed && DXN.getName(parsed);\n    }\n    return undefined;\n  }\n};\n\n/**\n * @internal (use Type.setTypename)\n */\n// TODO(dmaretskyi): Rename setTypeDXN.\nexport const setTypename = (obj: any, typename: URI.URI): void => {\n  assertArgument(typeof typename === 'string', 'typename', 'Invalid type.');\n  Object.defineProperty(obj, TypeId, {\n    value: typename,\n    writable: false,\n    enumerable: false,\n    configurable: false,\n  });\n};\n\n/**\n * @returns Object type URI — either a typename {@link DXN} or an `echo:` reference to a stored Schema object.\n * @returns undefined if the object has no registered type URI (e.g. unresolved query result).\n * @example `dxn:com.example.type.person:1.0.0`\n * @example `echo:/01KKKG2FHWCMTR0BY00GJSVT1X` (stored schema)\n *\n * @internal (use Obj.getTypeURI)\n */\nexport const getTypeURI = (obj: AnyProperties): URI.URI | undefined => {\n  if (obj == null) {\n    return undefined;\n  }\n  const type = (obj as any)[TypeId];\n  if (type == null) {\n    return undefined;\n  }\n  invariant(URI.isURI(type), 'Invalid object.');\n  return type;\n};\n\n//\n// PropertyMeta\n//\n\n/**\n * PropertyMeta (metadata for dynamic schema properties).\n * For user-defined annotations.\n */\nexport const PropertyMetaAnnotationId = Symbol.for('@dxos/schema/annotation/PropertyMeta');\n\nexport type PropertyMetaValue = Primitive | Record<string, Primitive> | Primitive[];\n\nexport type PropertyMetaAnnotation = {\n  [name: string]: PropertyMetaValue;\n};\n\n// TODO(wittjosiah): Align with other annotations.\n// TODO(wittjosiah): Why is this separate from FormatAnnotation?\n/**\n * Apply property-level metadata to an Effect schema. Only accepts\n * `Schema.Schema.Any` — apply BEFORE wrapping the schema with\n * `Type.makeObject` / `Type.makeRelation`. To read property meta off a\n * `Type.Type` entity, unwrap it first with `Type.getSchema(entity)`.\n */\nexport const PropertyMeta = (name: string, value: PropertyMetaValue) => {\n  return <A, I, R>(self: Schema.Schema<A, I, R>): Schema.Schema<A, I, R> => {\n    const existingMeta = self.ast.annotations[PropertyMetaAnnotationId] as PropertyMetaAnnotation;\n    return self.annotations({\n      [PropertyMetaAnnotationId]: {\n        ...existingMeta,\n        [name]: value,\n      },\n    });\n  };\n};\n\nexport const getPropertyMetaAnnotation = <T>(prop: SchemaAST.PropertySignature, name: string) =>\n  Function.pipe(\n    SchemaAST.getAnnotation<PropertyMetaAnnotation>(PropertyMetaAnnotationId)(prop.type),\n    Option.map((meta) => meta[name] as T),\n    Option.getOrElse(() => undefined),\n  );\n\n//\n// Reference\n//\n\n/**\n * Schema reference.\n */\nexport const ReferenceAnnotationId = Symbol.for('@dxos/schema/annotation/Reference');\nexport type ReferenceAnnotationValue = TypeAnnotation;\nexport const ReferenceAnnotation = createAnnotationHelper<ReferenceAnnotationValue>(ReferenceAnnotationId);\n\n/**\n * SchemaMeta.\n */\nexport const SchemaMetaSymbol = Symbol.for('@dxos/schema/SchemaMeta');\nexport type SchemaMeta = TypeMeta & { id: string };\n\n/**\n * Identifies a schema as hidden from user-facing surfaces (like dotfiles — visible only via an advanced setting).\n */\nexport const HiddenAnnotationId = Symbol.for('@dxos/schema/annotation/Hidden');\nexport const HiddenAnnotation = createAnnotationHelper<boolean>(HiddenAnnotationId);\n\n/**\n * Identifies label property or JSON path expression.\n * Either a string or an array of strings representing field accessors each matched in priority order.\n */\nexport const LabelAnnotationId = Symbol.for('@dxos/schema/annotation/Label');\nexport const LabelAnnotation = createAnnotationHelper<string[]>(LabelAnnotationId);\n\n/**\n * Returns the label for a given object based on {@link LabelAnnotationId}.\n * Lower-level version that requires explicit schema parameter.\n * Skips empty strings and whitespace-only strings, continuing to the next field.\n */\n// TODO(burdon): Convert to SchemaEx.JsonPath?\nexport const getLabelWithSchema = <S extends Schema.Schema.Any>(\n  schema: S,\n  object: Schema.Schema.Type<S>,\n): string | undefined => {\n  const annotation = LabelAnnotation.get(schema).pipe(Option.getOrElse(() => ['name']));\n  for (const accessor of annotation) {\n    assertArgument(\n      typeof accessor === 'string',\n      'accessor',\n      'Label annotation must be a string or an array of strings',\n    );\n    const value = SchemaEx.getField(object, accessor as SchemaEx.JsonPath);\n    switch (typeof value) {\n      case 'string': {\n        const trimmed = value.trim();\n        if (trimmed.length > 0) {\n          return value;\n        }\n        continue;\n      }\n      case 'number':\n      case 'boolean':\n      case 'bigint':\n      case 'symbol':\n        return value.toString();\n      case 'undefined':\n      case 'object':\n      case 'function':\n        continue;\n    }\n  }\n\n  return undefined;\n};\n\n/**\n * Sets the label for a given object based on {@link LabelAnnotationId}.\n * Lower-level version that requires explicit schema parameter.\n */\nexport const setLabelWithSchema = <S extends Schema.Schema.Any>(\n  schema: S,\n  object: Schema.Schema.Type<S>,\n  label: string,\n) => {\n  const annotation = LabelAnnotation.get(schema).pipe(\n    Option.map((field) => field[0]),\n    Option.getOrElse(() => 'name'),\n  );\n  object[annotation] = label;\n};\n\n/**\n * Identifies description property or JSON path expression.\n * A string representing field accessor.\n */\nexport const DescriptionAnnotationId = Symbol.for('@dxos/schema/annotation/Description');\nexport const DescriptionAnnotation = createAnnotationHelper<string>(DescriptionAnnotationId);\n\n/**\n * Returns the description for a given object based on {@link DescriptionAnnotationId}.\n * Lower-level version that requires explicit schema parameter.\n */\n// TODO(burdon): Convert to SchemaEx.JsonPath?\nexport const getDescriptionWithSchema = <S extends Schema.Schema.Any>(\n  schema: S,\n  object: Schema.Schema.Type<S>,\n): string | undefined => {\n  const accessor = DescriptionAnnotation.get(schema).pipe(Option.getOrElse(() => 'description'));\n  assertArgument(typeof accessor === 'string', 'accessor', 'Description annotation must be a string');\n  const value = SchemaEx.getField(object, accessor as SchemaEx.JsonPath);\n  switch (typeof value) {\n    case 'string':\n    case 'number':\n    case 'boolean':\n    case 'bigint':\n    case 'symbol':\n      return value.toString();\n    case 'undefined':\n    case 'object':\n    case 'function':\n    default:\n      return undefined;\n  }\n};\n\n/**\n * Sets the description for a given object based on {@link DescriptionAnnotationId}.\n * Lower-level version that requires explicit schema parameter.\n */\nexport const setDescriptionWithSchema = <S extends Schema.Schema.Any>(\n  schema: S,\n  object: Schema.Schema.Type<S>,\n  description: string,\n) => {\n  const accessorOpt = DescriptionAnnotation.get(schema);\n  if (Option.isNone(accessorOpt)) {\n    return;\n  }\n  object[accessorOpt.value] = description;\n};\n\n/**\n * Identifies if a property should be included in a form or not.\n * By default, all properties are included in forms, so this is opt-out.\n */\nexport const FormInputAnnotationId = Symbol.for('@dxos/schema/annotation/FormInput');\nexport const FormInputAnnotation = createAnnotationHelper<boolean>(FormInputAnnotationId);\n\n/**\n * When set on a `Ref` property, the form renders the referenced object's own\n * fields inline (a nested form bound to the target) instead of a picker.\n */\nexport const FormInlineAnnotationId = Symbol.for('@dxos/schema/annotation/FormInline');\nexport const FormInlineAnnotation = createAnnotationHelper<boolean>(FormInlineAnnotationId);\n\n/**\n * When set on a `Ref` (or array-of-`Ref`) property, the form OWNS the referenced target(s): \"add\" creates a\n * new object of the annotation's typename (instead of opening the existing-object picker) and each target is\n * rendered inline — its own fields — like {@link FormInlineAnnotation}. The target typename is carried here\n * (rather than inferred from the element type) so the field can stay `Ref.Ref(Obj.Unknown)` and avoid pulling\n * the target's type (e.g. query-AST-laden `Trigger`) into the schema's emitted declaration.\n */\nexport const FormCreateAnnotationId = Symbol.for('@dxos/schema/annotation/FormCreate');\nexport const FormCreateAnnotation = createAnnotationHelper<string>(FormCreateAnnotationId);\n\n/**\n * When set on an array property, the form renders it as an ordered,\n * drag-to-reorder list (drag handles per row). Element order is meaningful and\n * user-controllable; reordering rewrites the array.\n */\nexport const FormOrderedAnnotationId = Symbol.for('@dxos/schema/annotation/FormOrdered');\nexport const FormOrderedAnnotation = createAnnotationHelper<boolean>(FormOrderedAnnotationId);\n\n/**\n * Annotation carrying one or more named layout DSL templates that control how a\n * form arranges a schema's fields (consumed by `@dxos/react-ui-form`'s\n * `Form.Layout` / `Form.FieldSet`). Callers select a variant by name; the\n * implicit name is `DEFAULT_LAYOUT_NAME` (`'default'`).\n *\n * Templates use a minimal XML grammar. Example:\n *\n *   FormLayoutAnnotation.set({\n *     default: `\n *       <grid cols=\"2\">\n *         <field name=\"origin\"/>\n *         <field name=\"destination\"/>\n *         <field name=\"provider\" span=\"2\"/>\n *       </grid>\n *     `,\n *     card: `\n *       <grid cols=\"1\">\n *         <field name=\"provider\"/>\n *         <field name=\"number\"/>\n *       </grid>\n *     `,\n *   })\n */\nexport const FormLayoutAnnotationId = Symbol.for('@dxos/react-ui-form/annotation/Layout');\n\nexport type FormLayoutMap = Record<string, string>;\n\nexport const FormLayoutAnnotation = createAnnotationHelper<FormLayoutMap>(FormLayoutAnnotationId);\n\n/** Name used when no explicit form-layout variant is requested. */\nexport const DEFAULT_LAYOUT_NAME = 'default';\n\n/**\n * Default field to be used on referenced schema to lookup the value.\n */\nexport const FieldLookupAnnotationId = Symbol.for('@dxos/schema/annotation/FieldLookup');\n\n/**\n * Generate test data.\n */\nexport const GeneratorAnnotationId = Symbol.for('@dxos/schema/annotation/Generator');\n\nexport type GeneratorAnnotationValue =\n  | string\n  | {\n      generator: string;\n      args?: any[];\n      probability?: number;\n    };\n\nexport const GeneratorAnnotation = createAnnotationHelper<GeneratorAnnotationValue>(GeneratorAnnotationId);\n\ninterface MakeAnnoationsProps<T> {\n  id: string;\n  schema: Schema.Schema<T, any, never>;\n}\n\n// Annotation ids use the same NSID / reverse-DNS format as TypenameSchema —\n// dot-separated segments, middle segments may be hyphenated, final segment may be camelCase.\n// At least 3 segments are required (e.g. org.dxos.annotation.example).\nexport const makeUserAnnotation = <T>(props: MakeAnnoationsProps<T>): Annotation.Annotation<T> => {\n  assertArgument(\n    /^[a-zA-Z]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?){2,}(\\.[a-zA-Z]([a-zA-Z0-9]{0,62})?)?$/.test(\n      props.id,\n    ),\n    'id',\n    'Annotation id must be in the FQN format (org.dxos.annotation.example or org.dxos.space.rootCollection).',\n  );\n\n  const annotation: Annotation.Annotation<T> = {\n    [ANNOTATION_TYPE_ID]: { _Type: {} as T },\n    key: props.id as Annotation.Key,\n    schema: props.schema,\n    get: (schema) => getFromAst(schema.ast, annotation),\n    getFromAst: (ast) => getFromAst(ast, annotation),\n    set: (value) =>\n      PropertyMeta(props.id, Schema.encodeSync(props.schema)(value)) as <S extends Schema.Schema.Any>(schema: S) => S,\n  };\n\n  return annotation;\n};\n\nconst IconAnnotationSchema = Schema.Struct({\n  /**\n   * Phosphor icon name (e.g., 'ph--user--regular', 'ph--cube--regular', 'ph--link--regular ', etc.)\n   */\n  icon: Schema.String.pipe(Schema.pattern(/^ph--[a-z-]+--[a-z]+$/)),\n\n  /**\n   * Color name.\n   *\n   * List of colors:\n   *  - 'red'\n   *  - 'orange'\n   *  - 'amber'\n   *  - 'yellow'\n   *  - 'lime'\n   *  - 'green'\n   *  - 'emerald'\n   *  - 'teal'\n   *  - 'cyan'\n   *  - 'violet'\n   *  - 'purple'\n   *  - 'fuchsia'\n   *  - 'pink'\n   *  - 'rose'\n   */\n  hue: Schema.optional(Schema.String),\n});\n\nexport interface IconAnnotation extends Schema.Schema.Type<typeof IconAnnotationSchema> {}\n\n/**\n * Icon to render in the UI.\n */\nexport const IconAnnotation = makeUserAnnotation<IconAnnotation>({\n  id: 'org.dxos.annotation.icon',\n  schema: IconAnnotationSchema,\n});\n\n/**\n * Indicates that this entity's icon should be resolved from a property whose value is a `Ref`\n * to another entity. Consumers (e.g. graph node builders) resolve the ref target and use that\n * target's schema `IconAnnotation` in place of the static one declared on this schema.\n *\n * Useful for wrapper schemas that delegate their visual identity to a referenced sub-entity\n * (e.g. a generic `Game` whose icon should come from its `variant` ref's typed state).\n */\nexport const IconFromRefAnnotation = makeUserAnnotation<string>({\n  id: 'org.dxos.annotation.icon.from-ref',\n  schema: Schema.String,\n});\n\n/**\n * Options for {@link getLabel}.\n */\nexport type GetLabelOptions = {\n  /**\n   * Strategy for deriving a label when the entity has no `LabelAnnotation` value.\n   * - `'typename'`: use the entity's typename (e.g. `org.dxos.type.table`).\n   *   Useful for Card.Title chrome that must always display something, even\n   *   for unlabeled objects.\n   */\n  fallback?: 'typename';\n};\n\n/**\n * Get the label of an entity.\n * Accepts both reactive entities and snapshots.\n *\n * If `options.fallback === 'typename'` and no label is set, returns the\n * entity's typename instead.\n */\nexport const getLabel = (entity: AnyProperties, options?: GetLabelOptions): string | undefined => {\n  const schema = getSchema(entity);\n  const label = schema != null ? getLabelWithSchema(schema, entity) : undefined;\n  if (label != null) {\n    return label;\n  }\n  if (options?.fallback === 'typename') {\n    return getTypename(entity);\n  }\n  return undefined;\n};\n\n/**\n * Set the label of an entity.\n * Must be called within an Obj.update or Relation.update callback.\n */\nexport const setLabel = (entity: Mutable<AnyProperties>, label: string) => {\n  const schema = getSchema(entity);\n  if (schema != null) {\n    setLabelWithSchema(schema, entity, label);\n  }\n};\n\n/**\n * Returns the primary label property key for an entity.\n * Reads the first accessor from {@link LabelAnnotation}, defaulting to 'name'.\n */\nexport const getLabelProperty = (entity: AnyProperties): string => {\n  const schema = getSchema(entity);\n  if (schema == null) {\n    return 'name';\n  }\n  return LabelAnnotation.get(schema).pipe(\n    Option.flatMap((fields) => Option.fromNullable(fields[0])),\n    Option.getOrElse(() => 'name'),\n  );\n};\n\n/**\n * Get the description of an entity.\n * Accepts both reactive entities and snapshots.\n */\nexport const getDescription = (entity: AnyProperties): string | undefined => {\n  const schema = getSchema(entity);\n  if (schema != null) {\n    return getDescriptionWithSchema(schema, entity);\n  }\n};\n\n/**\n * Get the icon annotation for an entity, resolved via its type-level `IconAnnotation`.\n * Accepts both reactive entities and snapshots.\n *\n * Returns the full `{ icon, hue }` annotation so callers can use both the phosphor icon\n * name and the suggested colour. Callers wanting just the icon name typically write\n * `Obj.getIcon(obj)?.icon ?? 'ph--cube--regular'`.\n *\n * Note: this is the \"static\" icon from the object's own schema. It does not follow\n * `IconFromRefAnnotation` delegation — call sites needing that (e.g. app-graph node\n * builders) should resolve the ref themselves.\n */\nexport const getIcon = (entity: AnyProperties): IconAnnotation | undefined => {\n  const schema = getSchema(entity);\n  if (schema == null) {\n    return undefined;\n  }\n  return Option.getOrUndefined(IconAnnotation.get(schema));\n};\n\n/**\n * Set the description of an entity.\n * Must be called within an Obj.update or Relation.update callback.\n */\nexport const setDescription = (entity: Mutable<AnyProperties>, description: string) => {\n  const schema = getSchema(entity);\n  if (schema != null) {\n    setDescriptionWithSchema(schema, entity, description);\n  }\n};\n\nexport { Dictionary, Key, getDictionary, setDictionary } from './dictionary';\n\nexport const getFromAst = <T>(ast: SchemaAST.AST, annotation: Annotation.Annotation<T>): Option.Option<T> => {\n  return SchemaAST.getAnnotation<PropertyMetaAnnotation>(PropertyMetaAnnotationId)(ast).pipe(\n    Option.flatMap((meta) => Option.fromNullable(meta[annotation.key])),\n    Option.map(Schema.decodeUnknownSync(annotation.schema)),\n  );\n};\n","//\n// Copyright 2024 DXOS.org\n//\n\nimport * as Schema from 'effect/Schema';\n\nimport { assertArgument, invariant } from '@dxos/invariant';\nimport { EID, EntityId } from '@dxos/keys';\nimport { assumeType } from '@dxos/util';\n\nimport { type InternalObjectProps, SelfURIId } from './model';\n\n/**\n * Returns the EID of an object.\n *\n * @internal\n */\nexport const getObjectEchoUri = (object: any): EID.EID | undefined => {\n  invariant(!Schema.isSchema(object), 'schema not allowed in this function');\n  assertArgument(typeof object === 'object' && object != null, 'object', 'expected object');\n  assumeType<InternalObjectProps>(object);\n\n  if (object[SelfURIId]) {\n    invariant(EID.isEID(object[SelfURIId]), 'Invalid object model: invalid self dxn');\n    return EID.parse(object[SelfURIId]);\n  }\n\n  if (!EntityId.isValid(object.id)) {\n    throw new TypeError('Object id is not valid.');\n  }\n\n  return EID.make({ entityId: object.id });\n};\n","//\n// Copyright 2025 DXOS.org\n//\n\nimport { invariant } from '@dxos/invariant';\nimport { DXN, EID, type SpaceId, URI } from '@dxos/keys';\nimport { assumeType } from '@dxos/util';\n\nimport type { AnyEntity } from '../common/types';\nimport { MetaId } from '../common/types/model-symbols';\nimport { type InternalObjectProps, ObjectBranchId, ObjectDatabaseId } from './model';\nimport { getObjectEchoUri } from './util';\n\n/**\n * Controls the URI form returned by `getUri` and the public `*.getURI` helpers.\n *\n * - `'named'`    — Registry key URI (`dxn:<meta.key>`) when the entity has a key in its meta;\n *                  falls back to the default EID.\n * - `'absolute'` — Fully-qualified EID with space id (`echo://<spaceId>/<entityId>`);\n *                  falls back when no space is available.\n * - `'relative'` — Local EID without space id (`echo:/<entityId>`).\n *\n * Omitting `prefer` preserves the existing behaviour.\n */\nexport type GetURIOptions = {\n  prefer?: 'named' | 'absolute' | 'relative';\n};\n\n/**\n * Get the URI of an entity.\n * Accepts both reactive entities and snapshots.\n */\nexport const getUri = (entity: AnyEntity, options?: GetURIOptions): URI.URI => {\n  const prefer = options?.prefer;\n\n  if (prefer === 'named') {\n    const key = (entity as any)[MetaId]?.key;\n    if (key) {\n      return (DXN.tryMake(`dxn:${key}`) ?? URI.make(key)) as URI.URI;\n    }\n    const uri = getObjectEchoUri(entity);\n    invariant(uri != null, 'Invalid entity.');\n    return uri;\n  }\n\n  if (prefer === 'relative') {\n    const eid = getObjectEchoUri(entity);\n    invariant(eid != null, 'Invalid entity.');\n    const entityId = EID.getEntityId(eid);\n    return entityId ? EID.make({ entityId }) : eid;\n  }\n\n  if (prefer === 'absolute') {\n    const eid = getObjectEchoUri(entity);\n    invariant(eid != null, 'Invalid entity.');\n    const entityId = EID.getEntityId(eid);\n    if (!entityId) {\n      return eid;\n    }\n    assumeType<InternalObjectProps>(entity);\n    const spaceId: SpaceId | undefined = entity[ObjectDatabaseId]?.spaceId ?? EID.getSpaceId(eid);\n    return spaceId ? EID.make({ spaceId, entityId }) : eid;\n  }\n\n  const uri = getObjectEchoUri(entity);\n  invariant(uri != null, 'Invalid entity.');\n  return uri;\n};\n\n/**\n * Get the database the entity belongs to.\n * Accepts both reactive entities and snapshots.\n */\nexport const getDatabase = (entity: AnyEntity): any | undefined => {\n  assumeType<InternalObjectProps>(entity);\n  return entity[ObjectDatabaseId];\n};\n\n/**\n * Get the branch this entity instance is bound to (`'main'` for the canonical object, or the branch\n * of a `db.branch()` independent instance). Reads the branch off the instance, so two instances of the\n * same object id on different branches report their own branch.\n */\nexport const getBranch = (entity: AnyEntity): string => {\n  assumeType<InternalObjectProps>(entity);\n  return entity[ObjectBranchId] ?? 'main';\n};\n","//\n// Copyright 2024 DXOS.org\n//\n\nimport * as Schema from 'effect/Schema';\n\nimport { raise } from '@dxos/debug';\nimport { assertArgument } from '@dxos/invariant';\nimport { DXN, EID, URI } from '@dxos/keys';\n\nimport { getSchemaURI, getTypename } from '../Annotation/annotations';\nimport { type AnyEntity, InstancePhantomId, KindId, TypeId, getStaticTypeSchema } from '../common/types';\nimport { getUri as getUriFromEntity } from './api';\n\n/**\n * @param input schema, `Type.Type` entity, or a type URI (an `echo:` EID or a `dxn:` DXN).\n * @return type identifier URI — see {@link getSchemaURI}. A URI is returned verbatim. For a\n * `Type.Type` entity, the URI of the schema it declares, symmetric with what\n * `Obj.make(typeEntity, ...)` stamps on `system.type`: a static declaration resolves to its\n * typename DXN, a persisted entity to its local `echo:/<objectId>`.\n */\nexport const getTypeURIFromSpecifier = (input: Schema.Schema.All | AnyEntity | URI.URI): URI.URI => {\n  if (Schema.isSchema(input)) {\n    return getSchemaURI(input) ?? raise(new TypeError('Schema has no URI'));\n  }\n  // Type entities are normally proxy objects, but class-declared types from\n  // `Type.makeObject` are functions whose prototype chain reaches the entity, so accept functions too.\n  if (input !== null && (typeof input === 'object' || typeof input === 'function') && KindId in input) {\n    // `Type.Type` entity. Both in-memory and persisted forms expose the schema\n    // they declare via `StaticTypeSchemaSlot`, whose URI is exactly what\n    // `Obj.make` stamps on `system.type` — a static declaration carries\n    // `TypeAnnotation` (→ typename DXN), a persisted entity's rebuilt schema\n    // carries `TypeIdentifierAnnotation` (→ local `echo:/<objectId>`).\n    const schema = getStaticTypeSchema(input);\n    if (schema != null) {\n      // Static types carry TypeAnnotation → DXN; persisted db types carry\n      // TypeIdentifierAnnotation → echo EID. In-memory makeObjectFromJsonSchema\n      // entities have neither (plain JSON Schema), so fall through to the EID path.\n      const uri = getSchemaURI(schema);\n      if (uri != null) {\n        return uri;\n      }\n    }\n    return getUriFromEntity(input as AnyEntity);\n  }\n  // A string specifier is already a branded URI — an `echo:` EID or a `dxn:` DXN.\n  assertArgument(EID.isEID(input) || DXN.isDXN(input), 'input', 'expected a type URI (EID or DXN)');\n  return input;\n};\n\n/**\n * Checks if the object is an instance of the schema.\n * Only typename is compared, the schema version is ignored.\n *\n * The following cases are considered to mean that the object is an instance of the schema:\n *  - Object was created with this exact schema.\n *  - Object was created with a different version of this schema.\n *  - Object was created with a different schema (maybe dynamic) that has the same typename.\n */\n// TODO(burdon): Can we use `Schema.is`?\nexport const isInstanceOf = <S>(\n  schemaOrType: S extends Schema.Schema.AnyNoContext ? S : Schema.Schema.AnyNoContext | AnyEntity,\n  object: any,\n): object is S extends Schema.Schema.AnyNoContext\n  ? Schema.Schema.Type<S>\n  : S extends { readonly [InstancePhantomId]?: infer A }\n    ? A\n    : unknown => {\n  if (object == null) {\n    return false;\n  }\n\n  const schemaURI = getTypeURIFromSpecifier(schemaOrType);\n\n  // `object` is arbitrary input — read TypeId directly (it may be missing on\n  // non-entities) rather than via `getTypeURI` which asserts the URI is set.\n  const type = (object as any)[TypeId];\n  if (URI.isURI(type) && type === schemaURI) {\n    return true;\n  }\n\n  const typename = getTypename(object);\n  if (!typename) {\n    return false;\n  }\n\n  if (!DXN.isDXN(schemaURI)) {\n    // EID-based schema URI — no typename match possible.\n    return false;\n  }\n\n  const parsed = DXN.tryMake(schemaURI);\n  return parsed != null && DXN.getName(parsed) === typename;\n};\n","//\n// Copyright 2025 DXOS.org\n//\n\nimport * as Effect from 'effect/Effect';\nimport * as Effectable from 'effect/Effectable';\nimport * as Option from 'effect/Option';\n\nimport type * as QueryResult from '../../QueryResult';\n\n/**\n * Wraps an effect that produces a {@link QueryResult.QueryResult} into a\n * {@link QueryResult.QueryResultEffect}, exposing `.run` and `.first` shorthands that execute the\n * query once. Shared by `Database.query` and `Feed.query` so both surfaces chain identically.\n */\nexport const makeQueryResultEffect = <T, E, R>(\n  eff: Effect.Effect<QueryResult.QueryResult<T>, E, R>,\n): QueryResult.QueryResultEffect<T, E, R> => {\n  return {\n    run: Effect.flatMap(eff, (result) => Effect.promise(() => result.run())),\n    first: Effect.flatMap(eff, (result) =>\n      Effect.promise(async () => Option.fromNullable(await result.firstOrUndefined())),\n    ),\n\n    // Effect internals: the result is itself an Effect, so it carries the commit prototype.\n    ...Effectable.CommitPrototype,\n    commit() {\n      return eff;\n    },\n    // Cast required: Effect's commit protocol is supplied at runtime via `CommitPrototype` and\n    // cannot be expressed by the object literal's static type.\n  } as any;\n};\n","//\n// Copyright 2025 DXOS.org\n//\n\nimport * as Context from 'effect/Context';\nimport * as Effect from 'effect/Effect';\nimport * as Layer from 'effect/Layer';\nimport * as Schema from 'effect/Schema';\nimport * as Stream from 'effect/Stream';\n\nimport type { CleanupFn } from '@dxos/async';\nimport { invariant } from '@dxos/invariant';\nimport { type SpaceId, type URI } from '@dxos/keys';\n\nimport type * as Blob from './Blob';\nimport type * as Entity from './Entity';\nimport * as Err from './Err';\nimport type * as Feed from './Feed';\nimport type * as Filter from './Filter';\nimport type * as Hypergraph from './Hypergraph';\nimport { type AnyProperties, EntityKind, KindId } from './internal/common/types';\n// Deep import (not the `./internal/Entity` barrel) to avoid a cycle:\n// Database → internal/Entity → entity → JsonSchema → Ref → Database.\nimport { isInstanceOf } from './internal/Entity/type-uri';\nimport * as queryInternal from './internal/Query';\nimport type { Ref } from './internal/Ref/ref';\nimport type * as Obj from './Obj';\nimport type * as Query from './Query';\nimport type * as QueryResult from './QueryResult';\nimport type * as Registry from './Registry';\nimport type * as Type from './Type';\n\n/**\n * `query` API function declaration.\n */\n// TODO(burdon): Reconcile Query and Filter (should only have one root type).\nexport interface QueryFn {\n  <Q extends Query.Any>(query: Q): QueryResult.QueryResult<Query.Type<Q>>;\n  <F extends Filter.Any>(filter: F): QueryResult.QueryResult<Filter.Type<F>>;\n}\n\n/**\n * Common interface for Database, Feed, and Hypergraph.\n */\nexport interface Queryable {\n  query: QueryFn;\n}\n\nexport type GetObjectByIdOptions = {\n  deleted?: boolean;\n};\n\nexport type ObjectPlacement = 'root-doc' | 'linked-doc';\n\nexport type AddOptions = {\n  /**\n   * Where to place the object in the Automerge document tree.\n   * Root document is always loaded with the space.\n   * Linked documents are loaded lazily.\n   * Placing large number of objects in the root document may slow down the initial load.\n   *\n   * @default 'linked-doc'\n   */\n  placeIn?: ObjectPlacement;\n\n  /**\n   * Append the object to this feed instead of the automerge-backed space database. The object is\n   * returned synchronously (a live feed object) and persisted in the background — confirm the write\n   * completed with {@link Database.flush}. Synchronous alternative to the async\n   * {@link Database.appendToFeed}; `placeIn` is ignored when set.\n   */\n  to?: Feed.Feed;\n};\n\n/**\n * Rejects Type entities from {@link Database.add} at compile time via their `[KindId]` brand. Used\n * as `T & RejectTypeEntity<T>` to preserve inference of `T`. Bounding `add` on\n * `Obj.Unknown | Relation.Unknown` instead would reject broadly-typed instance adds (e.g.\n * `Entity.Any`, `Obj.OfShape<T>`), forcing casts repo-wide.\n */\nexport type RejectTypeEntity<T> = T extends { readonly [KindId]: EntityKind.Type }\n  ? { __error: 'Type entities must be persisted via db.addType(), not db.add().' }\n  : T;\n\nexport type FlushOptions = {\n  /**\n   * Write any pending changes to disk.\n   * @default true\n   */\n  disk?: boolean;\n\n  /**\n   * Wait for pending index updates.\n   * @default true\n   */\n  indexes?: boolean;\n\n  /**\n   * Flush pending updates to objects and queries.\n   * @default false\n   */\n  updates?: boolean;\n};\n\n/**\n * A caller-owned, writable **independent instance** of one object bound to one branch: a distinct\n * object instance (not a UI surface), separate from the device-global canonical object.\n * @see Database.branch\n */\nexport type BranchBinding<T extends Obj.Unknown = Obj.Unknown> = {\n  /** Live object bound to the branch document (`'main'` -> the canonical live object). */\n  readonly object: T;\n  /** Release the binding (drops the doc-handle listener; never deletes the branch document). */\n  dispose(): void;\n};\n\n/**\n * Identifier denoting an ECHO Database.\n */\nexport const TypeId = Symbol.for('@dxos/echo/Database');\nexport type TypeId = typeof TypeId;\n\n/**\n * ECHO Database interface.\n */\nexport interface Database extends Queryable {\n  readonly [TypeId]: TypeId;\n\n  get spaceId(): SpaceId;\n\n  get graph(): Hypergraph.Hypergraph;\n\n  /**\n   * Registry for this database. Delegates type lookups to the shared hypergraph registry.\n   * To persist a schema so it replicates to other clients, add the type entity with\n   * {@link addType} (e.g. `await db.addType(Type.makeObjectFromJsonSchema(...))`).\n   */\n  readonly registry: Registry.Registry;\n\n  toJSON(): object;\n\n  /**\n   * Return object by local ID.\n   * @deprecated Use `db.query(Filter.id(id)).runSync()[0]` for a working-set lookup, or resolve via a {@link Ref}.\n   */\n  getObjectById<T extends Obj.Unknown = Obj.OfShape<AnyProperties>>(\n    id: string,\n    opts?: GetObjectByIdOptions,\n  ): T | undefined;\n\n  /**\n   * Query objects.\n   */\n  query: QueryFn;\n\n  /**\n   * Creates a reference to an existing object in the database.\n   *\n   * NOTE: The reference may be dangling if the object is not present in the database.\n   * NOTE: Difference from `Ref.fromURI`\n   * `Ref.fromURI(dxn)` returns an unhydrated reference. The `.load` and `.target` APIs will not work.\n   * `db.makeRef(dxn)` is preferable in cases with access to the database.\n   */\n  makeRef<T extends Entity.Unknown = Entity.Unknown>(uri: URI.URI): Ref<T>;\n\n  /**\n   * Adds an object or relation to the database.\n   *\n   * Only Object and Relation entities are accepted. To persist a Type definition use\n   * {@link addType} — passing a Type entity is rejected at compile time (and at runtime).\n   *\n   * Pass `{ to: feed }` to append to a feed instead (synchronous; confirm with {@link flush}).\n   */\n  add<T extends Entity.Unknown = Entity.Unknown>(obj: T & RejectTypeEntity<T>, opts?: AddOptions): T;\n\n  /**\n   * Persists a Type definition (clones/forks the entity) so it replicates to other peers.\n   *\n   * Runs a conflict query first: if a type with the same typename + version already exists in\n   * this space, the existing persisted entity is returned and no duplicate is created. This is\n   * the only supported way to add Type entities — {@link add} rejects them.\n   */\n  addType<T extends Type.AnyEntity>(type: T): Promise<T>;\n\n  /**\n   * Removes object from the database.\n   */\n  // TODO(burdon): Return true if removed (currently throws if not present).\n  remove(obj: Entity.Unknown): void;\n\n  /**\n   * Appends entities to a feed.\n   *\n   * The feed must already be stored in the database (added via {@link add}); its underlying\n   * queue is addressed by the feed object's URI.\n   */\n  appendToFeed(feed: Feed.Feed, entities: Entity.Unknown[]): Promise<void>;\n\n  /**\n   * Removes entities from a feed.\n   */\n  deleteFromFeed(feed: Feed.Feed, entities: Entity.Unknown[]): Promise<void>;\n\n  /**\n   * Wait for all pending changes to be saved to disk.\n   * Optionaly waits for changes to be propagated to indexes and event handlers.\n   */\n  flush(opts?: FlushOptions): Promise<void>;\n\n  //\n  // Branching. A branch is a writable alternate timeline of an object subtree (same object ids,\n  // shared automerge history, true CRDT merge-back). The registry is synced on the space root;\n  // the currently-viewed branch stays device-local.\n  //\n\n  /**\n   * The device-global current branch for an object id (`'main'` by default).\n   * @deprecated Prefer `Obj.getBranch(obj)` — it takes the object and reports the branch of that\n   * specific instance (including `db.branch()` independent instances), not just the device selection.\n   */\n  getCurrentBranch(objectId: string): string;\n\n  /**\n   * An immutable snapshot of the object at the given historical heads — a detached instance, not a\n   * pin on the live object. Prefer `Obj.getVersion(obj, heads)`.\n   */\n  getVersion<T extends Obj.Unknown>(obj: T, heads: readonly string[]): Obj.Snapshot<T>;\n\n  /** All branch names available for an object, including the implicit `'main'` (always first). */\n  listBranches(objectId: string): string[];\n\n  /**\n   * Fork the object and its referenced subtree into a new branch (does not switch to it).\n   * @param opts.fromHeads Fork from a historical frontier instead of the tip (a bare heads array\n   *   applies to the root only; a map forks each member from its own frontier).\n   */\n  createBranch(\n    rootObjectId: string,\n    name: string,\n    opts?: { fromHeads?: readonly string[] | Record<string, readonly string[]> },\n  ): Promise<void>;\n\n  /** Switch the object's subtree to a branch (or back to `'main'`). Device-local; cascades to children. */\n  switchBranch(rootObjectId: string, name: string): Promise<void>;\n\n  /** Merge a branch back into main across the subtree, then switch back to main. */\n  mergeBranch(rootObjectId: string, name: string, opts?: { deleteAfter?: boolean }): Promise<void>;\n\n  /** Fold main's changes into a branch across the subtree (the reverse of {@link mergeBranch}). */\n  syncBranch(rootObjectId: string, name: string): Promise<void>;\n\n  /** Delete a branch (its documents lose their sync reference). Cannot delete `'main'`. */\n  deleteBranch(rootObjectId: string, name: string): void;\n\n  /**\n   * Create a caller-owned, writable binding to one branch of one object — a live object whose reads\n   * resolve the branch document and whose writes land on the branch document only. Multiple bindings\n   * to different branches of the same object may coexist; the device-global current branch and other\n   * bindings are unaffected. Binding to `'main'` returns the canonical live object. Bindings are\n   * ephemeral and never persisted — the caller must `dispose()`.\n   */\n  branch<T extends Obj.Unknown>(obj: T, name: string): Promise<BranchBinding<T>>;\n\n  /**\n   * Removes feed items by ID.\n   */\n  removeFeedItemsByIds(feed: Feed.Feed, ids: string[]): Promise<void>;\n\n  /**\n   * Syncs a feed with the server.\n   */\n  syncFeed(feed: Feed.Feed, options?: Feed.SyncOptions): Promise<void>;\n\n  /**\n   * Returns queue replication backlog for the feed's namespace.\n   */\n  getFeedSyncState(feed: Feed.Feed): Promise<Feed.SyncState>;\n\n  /**\n   * Disposes and drops the in-memory handle (live working-set / core cache) for a feed, so the next\n   * access re-reads it cold. Advanced cache-control; primarily used by tests to model a spawned\n   * process reading the feed with an empty in-memory cache. Public (not `_`-prefixed) so it survives\n   * declaration stripping for cross-package test use.\n   */\n  evictFeedHandle(feed: Feed.Feed): Promise<void>;\n\n  /**\n   * Hashes and uploads `bytes` via the chosen storage backend, returning an un-added Blob object.\n   * Rejects with `Err.BlobTooLargeError` (over inline storage's fixed cap, or the backend's own\n   * `maxSize`), `Err.BlobWriteError` (backend upload failure), or `Err.BlobNotAvailableError`\n   * (`reason: 'backend-not-registered'` — the requested storage name has no registered backend).\n   */\n  createBlob(bytes: Uint8Array, options?: { type?: string; storage?: string }): Promise<Blob.Blob>;\n\n  /**\n   * Loads a blob's bytes. Rejects with `Err.BlobNotAvailableError` if the backend for the blob's\n   * storage scheme is not registered, offline, or cannot find the bytes.\n   */\n  readBlob(blob: Blob.Blob): Promise<Uint8Array>;\n\n  /**\n   * Checks whether a blob's bytes are currently available.\n   */\n  blobExists(blob: Blob.Blob): Promise<boolean>;\n\n  /**\n   * Returns a renderable URL for the blob, if one can be produced.\n   */\n  getBlobUrl(blob: Blob.Blob): Promise<string | undefined>;\n\n  /**\n   * Get the current combined (automerge documents + feed blocks) sync state, reported against a\n   * single remote peer.\n   */\n  getSyncState(options?: GetSyncStateOptions): Promise<SyncState>;\n\n  /**\n   * Subscribe to combined sync state changes.\n   */\n  subscribeToSyncState(cb: (state: SyncState) => void, options?: GetSyncStateOptions): CleanupFn;\n}\n\nexport const isDatabase = (obj: unknown): obj is Database => {\n  return obj ? typeof obj === 'object' && TypeId in obj && obj[TypeId] === TypeId : false;\n};\n\nexport const Database: Schema.Schema<Database> = Schema.Any.pipe(Schema.filter((space) => isDatabase(space)));\n\n/**\n * Effect service tag for Database dependency injection.\n */\nexport class Service extends Context.Tag('@dxos/echo/Database/Service')<\n  Service,\n  {\n    readonly db: Database;\n  }\n>() {}\n\n/**\n * Layer that provides a Database service that throws when accessed.\n * Useful as a default layer when no database is available.\n */\nexport const notAvailable = Layer.succeed(Service, {\n  get db(): Database {\n    throw new Error('Database not available');\n  },\n});\n\n/**\n * Creates a Database service instance from a Database.\n */\nexport const makeService = (db: Database): Context.Tag.Service<Service> => {\n  return {\n    get db() {\n      return db;\n    },\n  };\n};\n\n/**\n * Creates a Layer that provides the Database service.\n */\nexport const layer = (db: Database): Layer.Layer<Service> => {\n  return Layer.succeed(Service, makeService(db));\n};\n\n/**\n * Returns the space ID of the database.\n */\nexport const spaceId = Effect.gen(function* () {\n  const { db } = yield* Service;\n  return db.spaceId;\n});\n\n/**\n * Resolves an object by its DXN.\n */\nexport const resolve: {\n  // No type check.\n  (ref: URI.URI | Ref<any>): Effect.Effect<Entity.Unknown, never, Service>;\n  // Check matches schema.\n  <S extends Type.AnyEntity>(\n    ref: URI.URI | Ref<any>,\n    schema: S,\n  ): Effect.Effect<Type.InstanceType<S>, Err.EntityNotFoundError, Service>;\n} = (<S extends Type.AnyEntity>(\n  ref: URI.URI | Ref<any>,\n  schema?: S,\n): Effect.Effect<Type.InstanceType<S>, Err.EntityNotFoundError, Service> =>\n  Effect.gen(function* () {\n    const { db } = yield* Service;\n    const dxn = typeof ref === 'string' ? ref : ref.uri;\n    const object = yield* Effect.promise(() =>\n      db.graph\n        .createRefResolver({\n          context: {\n            space: db.spaceId,\n          },\n        })\n        .resolveLegacy(dxn),\n    );\n\n    if (!object) {\n      return yield* Effect.fail(new Err.EntityNotFoundError(dxn));\n    }\n    // `isInstanceOf` uses a conditional generic that TS can't resolve through\n    // the local `S extends Type.AnyEntity` parameter — runtime accepts it fine.\n    invariant(!schema || isInstanceOf(schema as any, object), 'Object type mismatch.');\n    return object as any;\n  }).pipe(Effect.withSpan('Database.resolve'))) as any;\n\n/**\n * Loads an object reference.\n *\n * Catching not found error:\n *\n * ```ts\n * yield* load(ref).pipe(Effect.catchTag('EntityNotFoundError', () => Effect.succeed(undefined)));\n * ```\n *\n */\nexport const load: <T>(ref: Ref<T>) => Effect.Effect<T, Err.EntityNotFoundError, never> = Effect.fn('Database.load')(\n  function* (ref) {\n    const object = yield* Effect.promise(() => ref.tryLoad());\n    if (!object) {\n      return yield* Effect.fail(new Err.EntityNotFoundError(ref.uri));\n    }\n    return object;\n  },\n);\n\n/**\n * Adds an object or relation to the database.\n * @see {@link Database.add}\n */\n// The Effect wrapper intentionally omits the method's `opts` (e.g. `{ to: feed }`): it is applied\n// point-free (`Effect.forEach(Database.add)`), where a second parameter would collide with the\n// iteratee index. Effect-style feed appends go through `Database.appendToFeed` / `Feed.append`.\nexport const add = <T extends Entity.Unknown>(obj: T & RejectTypeEntity<T>): Effect.Effect<T, never, Service> =>\n  Service.pipe(Effect.map(({ db }) => db.add<T>(obj))).pipe(Effect.withSpan('Database.add'));\n\n/**\n * Persists a Type definition to the database.\n * @see {@link Database.addType}\n */\nexport const addType = <T extends Type.AnyEntity>(type: T): Effect.Effect<T, never, Service> =>\n  Service.pipe(Effect.flatMap(({ db }) => Effect.promise(() => db.addType(type)))).pipe(\n    Effect.withSpan('Database.addType'),\n  );\n\n/**\n * Removes an object from the database.\n * @see {@link Database.remove}\n */\nexport const remove = <T extends Entity.Unknown>(obj: T): Effect.Effect<void, never, Service> =>\n  Service.pipe(Effect.map(({ db }) => db.remove(obj))).pipe(Effect.withSpan('Database.remove'));\n\n/**\n * Appends entities to a feed.\n * @see {@link Database.appendToFeed}\n */\nexport const appendToFeed = (feed: Feed.Feed, entities: Entity.Unknown[]): Effect.Effect<void, never, Service> =>\n  Service.pipe(Effect.flatMap(({ db }) => Effect.promise(() => db.appendToFeed(feed, entities)))).pipe(\n    Effect.withSpan('Database.appendToFeed'),\n  );\n\n/**\n * Removes entities from a feed.\n * @see {@link Database.deleteFromFeed}\n */\nexport const deleteFromFeed = (feed: Feed.Feed, entities: Entity.Unknown[]): Effect.Effect<void, never, Service> =>\n  Service.pipe(Effect.flatMap(({ db }) => Effect.promise(() => db.deleteFromFeed(feed, entities)))).pipe(\n    Effect.withSpan('Database.deleteFromFeed'),\n  );\n\n/**\n * Flushes pending changes to disk.\n * @see {@link Database.flush}\n */\nexport const flush = (opts?: FlushOptions) =>\n  Service.pipe(Effect.flatMap(({ db }) => Effect.promise(() => db.flush(opts)))).pipe(\n    Effect.withSpan('Database.flush'),\n  );\n\n/**\n * Creates a `QueryResult` object that can be subscribed to.\n */\nexport const query: {\n  <Q extends Query.Any>(query: Q): QueryResult.QueryResultEffect<Query.Type<Q>, never, Service>;\n  <F extends Filter.Any>(filter: F): QueryResult.QueryResultEffect<Filter.Type<F>, never, Service>;\n} = (queryOrFilter: Query.Any | Filter.Any) =>\n  Service.pipe(\n    Effect.map(({ db }) => db.query(queryOrFilter as any) as QueryResult.QueryResult<any>),\n    Effect.withSpan('Database.query'),\n    queryInternal.makeQueryResultEffect,\n  );\n\n/**\n * Sync state of the database in relation to EDGE.\n */\nexport interface SyncState {\n  //\n  // Automerge\n  //\n\n  /**\n   * Total number of documents locally.\n   */\n  readonly localDocumentCount: number;\n  /**\n   * Total number of documents on the remote peer.\n   */\n  readonly remoteDocumentCount: number;\n  /**\n   * Total number of documents across this peer and the remote peer.\n   */\n  readonly totalDocumentCount: number;\n  /**\n   * Total number of documents that are not synced.\n   * Includes documents that are present only locally, only on the remote peer, or whether the peers have different versions.\n   */\n  readonly unsyncedDocumentCount: number;\n\n  //\n  // Feeds.\n  //\n\n  /**\n   * Blocks still to pull from remote. 0 when caught up.\n   */\n  readonly blocksToPull: string;\n  /**\n   * Unpositioned blocks still to push to remote. 0 when caught up.\n   */\n  readonly blocksToPush: string;\n  /**\n   * Total blocks stored locally for this namespace in the space.\n   */\n  readonly totalBlocks: string;\n}\n\n/**\n * Options for reading combined sync state.\n */\nexport interface GetSyncStateOptions {\n  /**\n   * Peer to report the automerge document backlog against. Defaults to the EDGE peer.\n   * Provide explicitly in local/test topologies where there is no EDGE peer.\n   */\n  readonly peerId?: string;\n}\n\n/**\n * Get the current sync state.\n */\nexport const getSyncState = (options?: GetSyncStateOptions): Effect.Effect<SyncState, never, Service> =>\n  Service.pipe(Effect.flatMap(({ db }) => Effect.promise(() => db.getSyncState(options))));\n\n/**\n * Subscribe to sync state changes.\n */\nexport const subscribeToSyncState = (options?: GetSyncStateOptions): Stream.Stream<SyncState, never, Service> =>\n  Stream.asyncScoped((emit) =>\n    Effect.gen(function* () {\n      const { db } = yield* Service;\n      const cleanup = db.subscribeToSyncState((state) => emit.single(state), options);\n      yield* Effect.addFinalizer(() => Effect.sync(cleanup));\n    }),\n  );\n"],"mappings":"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"}

package/dist/lib/chunk-atom-snapshot.mjs

@@ -0,0 +1,249 @@
+import { d as SnapshotKindId, l as KindId } from "./chunk-util.mjs";
+import { Gt as MetaId } from "./chunk-Database.mjs";
+import { h as change, o as createEchoReferenceSchema } from "./chunk-ref.mjs";
+import { ForeignKey } from "@dxos/echo-protocol";
+import { DXN } from "@dxos/keys";
+import * as Function from "effect/Function";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import { assertArgument, invariant } from "@dxos/invariant";
+import { intersection } from "@dxos/util";
+//#region src/internal/Annotation/dictionary.ts
+/**
+* Unique identifier for an annotation.
+*/
+var Key = Schema.String.pipe(Schema.brand("~@dxos/echo/AnnotationKey"));
+/**
+* Set of annotation values stored on entity meta or nested in schemas.
+*/
+var Dictionary = Schema.Record({
+	key: Key,
+	value: Schema.Unknown
+});
+/**
+* Get the value of an annotation from a dictionary.
+*/
+var getDictionary = (values, annotation) => {
+	if (!(annotation.key in values)) return Option.none();
+	return Function.pipe(values[annotation.key], Schema.decodeUnknownSync(annotation.schema), Option.some);
+};
+/**
+* Set the value of an annotation in a dictionary.
+*/
+var setDictionary = (values, annotation, value) => {
+	values[annotation.key] = Schema.encodeSync(annotation.schema)(value);
+};
+//#endregion
+//#region src/internal/common/types/well-known-types.ts
+/**
+* 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.
+*/
+var TagTypeDXN = DXN.make("org.dxos.type.tag", "0.1.0");
+//#endregion
+//#region src/internal/common/types/meta.ts
+var __dxlog_file$1 = "/__w/dxos/dxos/packages/core/echo/echo/src/internal/common/types/meta.ts";
+/**
+* Property name for meta when object is serialized to JSON.
+*/
+var ATTR_META = "@meta";
+/**
+* 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.
+*/
+var TagRefSchema = Schema.suspend(() => createEchoReferenceSchema(void 0, DXN.getName(TagTypeDXN), DXN.getVersion(TagTypeDXN)));
+var 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)
+});
+var getMeta = (obj) => {
+	const metadata = obj[MetaId];
+	invariant(metadata, "EntityMeta not found.", {
+		"~LogMeta": "~LogMeta",
+		F: __dxlog_file$1,
+		L: 96,
+		S: void 0,
+		A: ["metadata", "'EntityMeta not found.'"]
+	});
+	return metadata;
+};
+var foreignKey = (source, id) => ({
+	source,
+	id
+});
+var foreignKeyEquals = (a, b) => a.source === b.source && a.id === b.id;
+var compareForeignKeys = (a, b) => intersection(getMeta(a).keys, getMeta(b).keys, foreignKeyEquals).length > 0;
+//#endregion
+//#region src/internal/common/api/meta.ts
+var __dxlog_file = "/__w/dxos/dxos/packages/core/echo/echo/src/internal/common/api/meta.ts";
+function getMetaChecked(entity) {
+	assertArgument(entity, "entity", "Should be an entity.");
+	const meta = getMeta(entity);
+	invariant(meta != null, "Invalid entity.", {
+		"~LogMeta": "~LogMeta",
+		F: __dxlog_file,
+		L: 37,
+		S: this,
+		A: ["meta != null", "'Invalid entity.'"]
+	});
+	return meta;
+}
+/**
+* @returns Foreign keys for the entity from the specified source.
+* Accepts both reactive entities and snapshots.
+*/
+var getKeys = (entity, source) => {
+	assertArgument(entity, "entity", "Should be an entity.");
+	const meta = getMetaChecked(entity);
+	invariant(meta != null, "Invalid entity.", {
+		"~LogMeta": "~LogMeta",
+		F: __dxlog_file,
+		L: 48,
+		S: void 0,
+		A: ["meta != null", "'Invalid entity.'"]
+	});
+	return meta.keys.filter((key) => key.source === source);
+};
+/**
+* Delete all keys from the entity for the specified source.
+* Must be called within an Obj.update or Relation.update callback.
+*/
+var deleteKeys = (entity, source) => {
+	const meta = getMetaChecked(entity);
+	for (let i = 0; i < meta.keys.length; i++) if (meta.keys[i].source === source) {
+		meta.keys.splice(i, 1);
+		i--;
+	}
+};
+/**
+* Add a tag (a reference to a {@link Tag} object) to the entity. Idempotent.
+* Must be called within an Obj.update or Relation.update callback.
+*/
+var addTag = (entity, tag) => {
+	const meta = getMetaChecked(entity);
+	if (!meta.tags.some((existing) => existing.uri === tag.uri)) meta.tags.push(tag);
+};
+/**
+* Remove a tag (a reference to a {@link Tag} object) from the entity. No-op when not present.
+* Must be called within an Obj.update or Relation.update callback.
+*/
+var removeTag = (entity, tag) => {
+	const meta = getMetaChecked(entity);
+	for (let i = 0; i < meta.tags.length; i++) if (meta.tags[i].uri === tag.uri) {
+		meta.tags.splice(i, 1);
+		i--;
+	}
+};
+//#endregion
+//#region src/internal/Entity/guard.ts
+/**
+* Returns true if the value is an ECHO entity instance (object or relation).
+*/
+var isEntity = (value) => {
+	if (value == null || typeof value !== "object" && typeof value !== "function") return false;
+	return value[KindId] !== void 0;
+};
+/**
+* Returns true if the value is an ECHO entity snapshot.
+*/
+var isSnapshot = (value) => {
+	if (typeof value !== "object" || value === null) return false;
+	return value[SnapshotKindId] !== void 0;
+};
+//#endregion
+//#region src/internal/Annotation/entity-dictionary.ts
+/**
+* Get the value of an annotation from an entity instance or snapshot.
+*
+* The value is read-only (schema types are readonly by default). To mutate it, use {@link update}
+* (which reads it as mutable inside a change transaction); the reactive proxy rejects mutation of the
+* live value outside an `Obj.update`. Snapshots return a decoded detached copy.
+*/
+var get = (target, annotation) => {
+	if (isSnapshot(target)) return getDictionary(getMetaChecked(target).annotations, annotation);
+	if (isEntity(target)) {
+		const annotations = getMetaChecked(target).annotations;
+		return annotation.key in annotations ? Option.some(annotations[annotation.key]) : Option.none();
+	}
+	throw new TypeError("Target is not an annotation target.");
+};
+/**
+* Set the value of an annotation on an entity instance.
+* Must be called with a mutable entity — i.e. inside an `Obj.update` callback.
+*
+* The value is assigned directly to the reactive meta dictionary; the proxy encodes nested Refs and
+* links their unsaved targets on write (matching ordinary property assignment), so no manual
+* encode/persist step is needed.
+*/
+var set = (target, annotation, value) => {
+	if (isEntity(target)) {
+		Schema.validateSync(annotation.schema)(value);
+		getMetaChecked(target).annotations[annotation.key] = value;
+	} else throw new TypeError("Target is not an annotation target.");
+};
+/**
+* Mutate an existing annotation value in place via a callback, wrapping the mutation in a change
+* transaction (like `Obj.update`). Use when only an annotation needs to change. No-op when absent.
+*/
+var update = (target, annotation, mutator) => {
+	change(target, (mutable) => {
+		const current = get(mutable, annotation);
+		if (Option.isSome(current)) {
+			const value = current.value;
+			mutator(value);
+			Schema.validateSync(annotation.schema)(value);
+		}
+	});
+};
+//#endregion
+//#region src/internal/common/atom-snapshot.ts
+/**
+* Snapshot a value to create a new reference for atom change-detection and React dependency tracking.
+* Objects and arrays are shallow-copied (a fresh reference each read, so an in-place mutation is
+* observed); primitives are returned as-is (so they dedupe via `!==`). Shared by the object-property
+* and annotation atom families.
+*/
+var snapshotForComparison = (value) => {
+	if (Array.isArray(value)) return [...value];
+	if (value !== null && typeof value === "object") return { ...value };
+	return value;
+};
+//#endregion
+export { TagTypeDXN as _, isEntity as a, getDictionary as b, getKeys as c, ATTR_META as d, EntityMetaSchema as f, getMeta as g, foreignKeyEquals as h, update as i, getMetaChecked as l, foreignKey as m, get as n, addTag as o, compareForeignKeys as p, set as r, deleteKeys as s, snapshotForComparison as t, removeTag as u, Dictionary as v, setDictionary as x, Key as y };
+
+//# sourceMappingURL=chunk-atom-snapshot.mjs.map

package/dist/lib/chunk-atom-snapshot.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk-atom-snapshot.mjs","names":[],"sources":["../../src/internal/Annotation/dictionary.ts","../../src/internal/common/types/well-known-types.ts","../../src/internal/common/types/meta.ts","../../src/internal/common/api/meta.ts","../../src/internal/Entity/guard.ts","../../src/internal/Annotation/entity-dictionary.ts","../../src/internal/common/atom-snapshot.ts"],"sourcesContent":["//\n// Copyright 2026 DXOS.org\n//\n\nimport * as Function from 'effect/Function';\nimport * as Option from 'effect/Option';\nimport * as Schema from 'effect/Schema';\nimport * as Types from 'effect/Types';\n\nimport type * as Annotation from '../../Annotation';\n\n/**\n * Unique identifier for an annotation.\n */\nexport const Key = Schema.String.pipe(Schema.brand('~@dxos/echo/AnnotationKey'));\nexport type Key = Schema.Schema.Type<typeof Key>;\n\n/**\n * Set of annotation values stored on entity meta or nested in schemas.\n */\nexport const Dictionary = Schema.Record({ key: Key, value: Schema.Unknown });\nexport interface Dictionary extends Schema.Schema.Type<typeof Dictionary> {}\n\n/**\n * Get the value of an annotation from a dictionary.\n */\nexport const getDictionary = <T>(\n  values: Annotation.Dictionary,\n  annotation: Annotation.Annotation<T>,\n): Option.Option<T> => {\n  if (!(annotation.key in values)) {\n    return Option.none();\n  }\n\n  return Function.pipe(values[annotation.key], Schema.decodeUnknownSync(annotation.schema), Option.some);\n};\n\n/**\n * Set the value of an annotation in a dictionary.\n */\nexport const setDictionary = <T>(\n  values: Types.Mutable<Annotation.Dictionary>,\n  annotation: Annotation.Annotation<T>,\n  value: T,\n): void => {\n  values[annotation.key] = Schema.encodeSync(annotation.schema)(value);\n};\n","//\n// Copyright 2026 DXOS.org\n//\n\nimport { DXN } from '@dxos/keys';\n\n/**\n * DXN identity of the system {@link Tag} type.\n *\n * Defined in this low-level leaf so it can be shared by the public `Tag` type (which brands the\n * schema with this DXN) and by `EntityMetaSchema.tags` (which builds a `Ref<Tag>` schema from it)\n * without either importing the other — `Tag` is top-level and `meta` is deep-internal, so a direct\n * dependency between them would form an eval-order cycle.\n */\nexport const TagTypeDXN = DXN.make('org.dxos.type.tag', '0.1.0');\n","//\n// Copyright 2024 DXOS.org\n//\n\nimport * as Schema from 'effect/Schema';\n\nimport { type EncodedReference, ForeignKey } from '@dxos/echo-protocol';\nimport { invariant } from '@dxos/invariant';\nimport { DXN } from '@dxos/keys';\nimport { type Comparator, intersection } from '@dxos/util';\n\nimport type * as Tag from '../../../Tag';\nimport { Dictionary } from '../../Annotation/dictionary';\n// `meta` is no longer re-exported from the `common/types` barrel (see ./index.ts), so importing the\n// Ref schema builder here no longer forms an eval-order cycle with `Annotation`/`Database`.\nimport { type Ref, createEchoReferenceSchema } from '../../Ref/ref';\nimport { type AnyProperties } from './base';\nimport { MetaId } from './model-symbols';\nimport { TagTypeDXN } from './well-known-types';\n\n/**\n * Property name for meta when object is serialized to JSON.\n */\nexport const ATTR_META = '@meta';\n\n//\n// EntityMeta\n//\n\n/**\n * Schema for references to {@link Tag} objects stored in {@link EntityMetaSchema.tags}.\n *\n * Built from the shared {@link createEchoReferenceSchema} (the same builder `Ref.Ref` uses) via\n * `Schema.suspend`, so it reuses the canonical ref codec rather than duplicating it. The Tag type\n * identity comes from the shared {@link TagTypeDXN} constant; `suspend` defers construction until\n * first use, and `Tag` is referenced type-only, so no `Tag` value import is needed.\n */\nconst TagRefSchema = Schema.suspend(\n  (): Schema.Schema<Ref<Tag.Tag>, EncodedReference> =>\n    // The factory yields a loosely-typed `Ref<any>` schema; narrow it to the Tag-typed ref.\n    createEchoReferenceSchema(undefined, DXN.getName(TagTypeDXN), DXN.getVersion(TagTypeDXN)) as Schema.Schema<\n      Ref<Tag.Tag>,\n      EncodedReference\n    >,\n);\n\nexport const EntityMetaSchema = Schema.Struct({\n  keys: Schema.Array(ForeignKey),\n\n  /**\n   * Tags applied to this entity, as references to {@link Tag} objects.\n   */\n  tags: Schema.Array(TagRefSchema),\n\n  /**\n   * Fully-qualified registry key for the object (FQN format, e.g. `org.example.type.foo`).\n   * Identifies the canonical registry entry the object instance was created from.\n   */\n  key: Schema.optional(Schema.String),\n\n  /**\n   * Semantic version of the registry entry the object was created from.\n   * Must be a valid semver string (e.g. `1.2.3`).\n   */\n  version: Schema.optional(Schema.String),\n\n  /**\n   * Dictionary of annotations to this entity.\n   */\n  annotations: Dictionary,\n\n  /**\n   * Unix ms timestamp when this entity was created.\n   * Read-only; sourced from the system section of the automerge document — not stored in meta.\n   */\n  createdAt: Schema.optional(Schema.Number),\n\n  /**\n   * Unix ms timestamp of the last automerge change on this entity's document.\n   * Read-only; derived from the automerge change graph — not stored in meta.\n   */\n  updatedAt: Schema.optional(Schema.Number),\n});\n\nexport type EntityMeta = Schema.Schema.Type<typeof EntityMetaSchema>;\n\n/*\n * Get metadata from object.\n * Only callable on the object root.\n *\n * @internal (use Obj.getMeta or Relation.getMeta)\n */\n// TODO(burdon): Refine type to BaseObj.\nexport const getMeta = (obj: AnyProperties): EntityMeta => {\n  const metadata = (obj as any)[MetaId];\n  invariant(metadata, 'EntityMeta not found.');\n  return metadata;\n};\n\n//\n// Foreign keys\n//\n\nexport const foreignKey = (source: string, id: string): ForeignKey => ({ source, id });\nexport const foreignKeyEquals = (a: ForeignKey, b: ForeignKey) => a.source === b.source && a.id === b.id;\n\n// TODO(dmaretskyi): Move to echo-schema.\nexport const compareForeignKeys: Comparator<AnyProperties> = (a: AnyProperties, b: AnyProperties) =>\n  intersection(getMeta(a).keys, getMeta(b).keys, foreignKeyEquals).length > 0;\n","//\n// Copyright 2025 DXOS.org\n//\n\nimport type { ForeignKey } from '@dxos/echo-protocol';\nimport { assertArgument, invariant } from '@dxos/invariant';\nimport type { DeepReadonly } from '@dxos/util';\n\nimport type * as Tag from '../../../Tag';\nimport type { Ref } from '../../Ref/ref';\nimport { type Mutable } from '../proxy';\nimport { type AnyProperties } from '../types';\nimport { type EntityMeta, getMeta as getMeta$ } from '../types/meta';\n\n/**\n * Deeply read-only version of EntityMeta.\n */\nexport type ReadonlyMeta = DeepReadonly<EntityMeta>;\n\n/**\n * Mutable meta type received in meta mutation callbacks.\n */\nexport type Meta = Mutable<EntityMeta>;\n\n/**\n * Get the metadata for an entity with validation.\n * Returns mutable meta when passed a mutable entity (inside change callback).\n * Returns read-only meta when passed a regular entity or snapshot.\n *\n * TODO(burdon): When passed a Snapshot, should return a snapshot of meta, not the live meta proxy.\n */\nexport function getMetaChecked(entity: Mutable<AnyProperties>): Meta;\nexport function getMetaChecked(entity: AnyProperties): ReadonlyMeta;\nexport function getMetaChecked(entity: AnyProperties): Meta | ReadonlyMeta {\n  assertArgument(entity, 'entity', 'Should be an entity.');\n  const meta = getMeta$(entity);\n  invariant(meta != null, 'Invalid entity.');\n  return meta;\n}\n\n/**\n * @returns Foreign keys for the entity from the specified source.\n * Accepts both reactive entities and snapshots.\n */\nexport const getKeys = (entity: AnyProperties, source: string): ForeignKey[] => {\n  assertArgument(entity, 'entity', 'Should be an entity.');\n  const meta = getMetaChecked(entity);\n  invariant(meta != null, 'Invalid entity.');\n  return meta.keys.filter((key) => key.source === source);\n};\n\n/**\n * Delete all keys from the entity for the specified source.\n * Must be called within an Obj.update or Relation.update callback.\n */\nexport const deleteKeys = (entity: Mutable<AnyProperties>, source: string) => {\n  const meta = getMetaChecked(entity);\n  for (let i = 0; i < meta.keys.length; i++) {\n    if (meta.keys[i].source === source) {\n      meta.keys.splice(i, 1);\n      i--;\n    }\n  }\n};\n\n/**\n * Add a tag (a reference to a {@link Tag} object) to the entity. Idempotent.\n * Must be called within an Obj.update or Relation.update callback.\n */\nexport const addTag = (entity: Mutable<AnyProperties>, tag: Ref<Tag.Tag>) => {\n  const meta = getMetaChecked(entity);\n  // Two refs to the same target are not `===`; dedupe by URI.\n  if (!meta.tags.some((existing) => existing.uri === tag.uri)) {\n    meta.tags.push(tag);\n  }\n};\n\n/**\n * Remove a tag (a reference to a {@link Tag} object) from the entity. No-op when not present.\n * Must be called within an Obj.update or Relation.update callback.\n */\nexport const removeTag = (entity: Mutable<AnyProperties>, tag: Ref<Tag.Tag>) => {\n  const meta = getMetaChecked(entity);\n  for (let i = 0; i < meta.tags.length; i++) {\n    if (meta.tags[i].uri === tag.uri) {\n      meta.tags.splice(i, 1);\n      i--;\n    }\n  }\n};\n","//\n// Copyright 2026 DXOS.org\n//\n\nimport type * as Entity from '../../Entity';\nimport { KindId, SnapshotKindId } from '../common/types';\n\n/**\n * Returns true if the value is an ECHO entity instance (object or relation).\n */\nexport const isEntity = (value: unknown): value is Entity.Unknown => {\n  // (some) type entities are functions since they are class declarations.\n  if (value == null || (typeof value !== 'object' && typeof value !== 'function')) {\n    return false;\n  }\n  return (value as any)[KindId] !== undefined;\n};\n\n/**\n * Returns true if the value is an ECHO entity snapshot.\n */\nexport const isSnapshot = (value: unknown): value is Entity.Snapshot => {\n  if (typeof value !== 'object' || value === null) {\n    return false;\n  }\n  return (value as any)[SnapshotKindId] !== undefined;\n};\n","//\n// Copyright 2026 DXOS.org\n//\n\nimport * as Option from 'effect/Option';\nimport * as Schema from 'effect/Schema';\n\nimport type * as Annotation from '../../Annotation';\nimport type * as Entity from '../../Entity';\nimport { getMetaChecked } from '../common/api/meta';\nimport { type Mutable, change } from '../common/proxy/reactive';\nimport { isEntity, isSnapshot } from '../Entity/guard';\nimport { getDictionary } from './dictionary';\n\n/**\n * Get the value of an annotation from an entity instance or snapshot.\n *\n * The value is read-only (schema types are readonly by default). To mutate it, use {@link update}\n * (which reads it as mutable inside a change transaction); the reactive proxy rejects mutation of the\n * live value outside an `Obj.update`. Snapshots return a decoded detached copy.\n */\nexport const get = <T>(\n  target: Entity.Unknown | Entity.Snapshot,\n  annotation: Annotation.Annotation<T>,\n): Option.Option<T> => {\n  if (isSnapshot(target)) {\n    return getDictionary(getMetaChecked(target).annotations, annotation);\n  }\n  if (isEntity(target)) {\n    const annotations = getMetaChecked(target).annotations;\n    // The dictionary slot is typed `unknown`; at runtime it holds the annotation's live value\n    // (the proxy codecs nested refs in both directions), so the read coerces to the declared type.\n    return annotation.key in annotations ? Option.some(annotations[annotation.key] as T) : Option.none();\n  }\n  throw new TypeError('Target is not an annotation target.');\n};\n\n/**\n * Set the value of an annotation on an entity instance.\n * Must be called with a mutable entity — i.e. inside an `Obj.update` callback.\n *\n * The value is assigned directly to the reactive meta dictionary; the proxy encodes nested Refs and\n * links their unsaved targets on write (matching ordinary property assignment), so no manual\n * encode/persist step is needed.\n */\nexport const set = <T>(target: Mutable<Entity.Unknown>, annotation: Annotation.Annotation<T>, value: T): void => {\n  if (isEntity(target)) {\n    // The dictionary slot is untyped, so the proxy can't validate against the annotation schema;\n    // validate here (without encoding — the proxy encodes nested refs and links targets on assignment).\n    Schema.validateSync(annotation.schema)(value);\n    getMetaChecked(target).annotations[annotation.key] = value;\n  } else {\n    throw new TypeError('Target is not an annotation target.');\n  }\n};\n\n/**\n * Mutate an existing annotation value in place via a callback, wrapping the mutation in a change\n * transaction (like `Obj.update`). Use when only an annotation needs to change. No-op when absent.\n */\nexport const update = <T>(\n  target: Entity.Unknown,\n  annotation: Annotation.Annotation<T>,\n  mutator: (value: Mutable<T>) => void,\n): void => {\n  change(target, (mutable) => {\n    const current = get(mutable, annotation);\n    if (Option.isSome(current)) {\n      // `get` returns the value read-only; inside this change transaction the live value is mutable.\n      const value = current.value as Mutable<T>;\n      mutator(value);\n      // Validate against the annotation's own schema — the dictionary slot is untyped, so the proxy\n      // can't. Schema validation checks ref structure only (not targets), so it is cycle-safe.\n      Schema.validateSync(annotation.schema)(value);\n    }\n  });\n};\n","//\n// Copyright 2026 DXOS.org\n//\n\n/**\n * Snapshot a value to create a new reference for atom change-detection and React dependency tracking.\n * Objects and arrays are shallow-copied (a fresh reference each read, so an in-place mutation is\n * observed); primitives are returned as-is (so they dedupe via `!==`). Shared by the object-property\n * and annotation atom families.\n */\nexport const snapshotForComparison = <V>(value: V): V => {\n  if (Array.isArray(value)) {\n    return [...value] as V;\n  }\n  if (value !== null && typeof value === 'object') {\n    return { ...value } as V;\n  }\n  return value;\n};\n"],"mappings":";;;;;;;;;;;;;;AAcA,IAAa,MAAM,OAAO,OAAO,KAAK,OAAO,MAAM,2BAA2B,CAAC;;;;AAM/E,IAAa,aAAa,OAAO,OAAO;CAAE,KAAK;CAAK,OAAO,OAAO;AAAQ,CAAC;;;;AAM3E,IAAa,iBACX,QACA,eACqB;CACrB,IAAI,EAAE,WAAW,OAAO,SACtB,OAAO,OAAO,KAAK;CAGrB,OAAO,SAAS,KAAK,OAAO,WAAW,MAAM,OAAO,kBAAkB,WAAW,MAAM,GAAG,OAAO,IAAI;AACvG;;;;AAKA,IAAa,iBACX,QACA,YACA,UACS;CACT,OAAO,WAAW,OAAO,OAAO,WAAW,WAAW,MAAM,CAAC,CAAC,KAAK;AACrE;;;;;;;;;;;AChCA,IAAa,aAAa,IAAI,KAAK,qBAAqB,OAAO;;;;;;;ACS/D,IAAa,YAAY;;;;;;;;;AAczB,IAAM,eAAe,OAAO,cAGxB,0BAA0B,KAAA,GAAW,IAAI,QAAQ,UAAU,GAAG,IAAI,WAAW,UAAU,CAAC,CAI5F;AAEA,IAAa,mBAAmB,OAAO,OAAO;CAC5C,MAAM,OAAO,MAAM,UAAU;;;;CAK7B,MAAM,OAAO,MAAM,YAAY;;;;;CAM/B,KAAK,OAAO,SAAS,OAAO,MAAM;;;;;CAMlC,SAAS,OAAO,SAAS,OAAO,MAAM;;;;CAKtC,aAAa;;;;;CAMb,WAAW,OAAO,SAAS,OAAO,MAAM;;;;;CAMxC,WAAW,OAAO,SAAS,OAAO,MAAM;AAC1C,CAAC;AAWD,IAAa,WAAW,QAAmC;CACzD,MAAM,WAAY,IAAY;CAC9B,UAAU,UAAU,yBAAsB;EAAA,YAAA;EAAA,GAAA;EAAA,GAAA;EAAA,GAAA,KAAA;EAAA,GAAA,CAAA,YAAA,yBAAA;CAAA,CAAC;CAC3C,OAAO;AACT;AAMA,IAAa,cAAc,QAAgB,QAA4B;CAAE;CAAQ;AAAG;AACpF,IAAa,oBAAoB,GAAe,MAAkB,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE;AAGtG,IAAa,sBAAiD,GAAkB,MAC9E,aAAa,QAAQ,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,CAAC,CAAC,MAAM,gBAAgB,CAAC,CAAC,SAAS;;;;AC3E5E,SAAgB,eAAe,QAA4C;CACzE,eAAe,QAAQ,UAAU,sBAAsB;CACvD,MAAM,OAAO,QAAS,MAAM;CAC5B,UAAU,QAAQ,MAAM,mBAAgB;EAAA,YAAA;EAAA,GAAA;EAAA,GAAA;EAAA,GAAA;EAAA,GAAA,CAAA,gBAAA,mBAAA;CAAA,CAAC;CACzC,OAAO;AACT;;;;;AAMA,IAAa,WAAW,QAAuB,WAAiC;CAC9E,eAAe,QAAQ,UAAU,sBAAsB;CACvD,MAAM,OAAO,eAAe,MAAM;CAClC,UAAU,QAAQ,MAAM,mBAAgB;EAAA,YAAA;EAAA,GAAA;EAAA,GAAA;EAAA,GAAA,KAAA;EAAA,GAAA,CAAA,gBAAA,mBAAA;CAAA,CAAC;CACzC,OAAO,KAAK,KAAK,QAAQ,QAAQ,IAAI,WAAW,MAAM;AACxD;;;;;AAMA,IAAa,cAAc,QAAgC,WAAmB;CAC5E,MAAM,OAAO,eAAe,MAAM;CAClC,KAAK,IAAI,IAAI,GAAG,IAAI,KAAK,KAAK,QAAQ,KACpC,IAAI,KAAK,KAAK,EAAE,CAAC,WAAW,QAAQ;EAClC,KAAK,KAAK,OAAO,GAAG,CAAC;EACrB;CACF;AAEJ;;;;;AAMA,IAAa,UAAU,QAAgC,QAAsB;CAC3E,MAAM,OAAO,eAAe,MAAM;CAElC,IAAI,CAAC,KAAK,KAAK,MAAM,aAAa,SAAS,QAAQ,IAAI,GAAG,GACxD,KAAK,KAAK,KAAK,GAAG;AAEtB;;;;;AAMA,IAAa,aAAa,QAAgC,QAAsB;CAC9E,MAAM,OAAO,eAAe,MAAM;CAClC,KAAK,IAAI,IAAI,GAAG,IAAI,KAAK,KAAK,QAAQ,KACpC,IAAI,KAAK,KAAK,EAAE,CAAC,QAAQ,IAAI,KAAK;EAChC,KAAK,KAAK,OAAO,GAAG,CAAC;EACrB;CACF;AAEJ;;;;;;AC/EA,IAAa,YAAY,UAA4C;CAEnE,IAAI,SAAS,QAAS,OAAO,UAAU,YAAY,OAAO,UAAU,YAClE,OAAO;CAET,OAAQ,MAAc,YAAY,KAAA;AACpC;;;;AAKA,IAAa,cAAc,UAA6C;CACtE,IAAI,OAAO,UAAU,YAAY,UAAU,MACzC,OAAO;CAET,OAAQ,MAAc,oBAAoB,KAAA;AAC5C;;;;;;;;;;ACLA,IAAa,OACX,QACA,eACqB;CACrB,IAAI,WAAW,MAAM,GACnB,OAAO,cAAc,eAAe,MAAM,CAAC,CAAC,aAAa,UAAU;CAErE,IAAI,SAAS,MAAM,GAAG;EACpB,MAAM,cAAc,eAAe,MAAM,CAAC,CAAC;EAG3C,OAAO,WAAW,OAAO,cAAc,OAAO,KAAK,YAAY,WAAW,IAAS,IAAI,OAAO,KAAK;CACrG;CACA,MAAM,IAAI,UAAU,qCAAqC;AAC3D;;;;;;;;;AAUA,IAAa,OAAU,QAAiC,YAAsC,UAAmB;CAC/G,IAAI,SAAS,MAAM,GAAG;EAGpB,OAAO,aAAa,WAAW,MAAM,CAAC,CAAC,KAAK;EAC5C,eAAe,MAAM,CAAC,CAAC,YAAY,WAAW,OAAO;CACvD,OACE,MAAM,IAAI,UAAU,qCAAqC;AAE7D;;;;;AAMA,IAAa,UACX,QACA,YACA,YACS;CACT,OAAO,SAAS,YAAY;EAC1B,MAAM,UAAU,IAAI,SAAS,UAAU;EACvC,IAAI,OAAO,OAAO,OAAO,GAAG;GAE1B,MAAM,QAAQ,QAAQ;GACtB,QAAQ,KAAK;GAGb,OAAO,aAAa,WAAW,MAAM,CAAC,CAAC,KAAK;EAC9C;CACF,CAAC;AACH;;;;;;;;;AClEA,IAAa,yBAA4B,UAAgB;CACvD,IAAI,MAAM,QAAQ,KAAK,GACrB,OAAO,CAAC,GAAG,KAAK;CAElB,IAAI,UAAU,QAAQ,OAAO,UAAU,UACrC,OAAO,EAAE,GAAG,MAAM;CAEpB,OAAO;AACT"}