@dxos/echo 0.8.3 → 0.8.4-main.1068cf700f

package/dist/lib/neutral/chunk-MXQJZCPY.mjs

@@ -0,0 +1,51 @@
+import {
+  __export
+} from "./chunk-J5LGTIGS.mjs";
+
+// src/Err.ts
+var Err_exports = {};
+__export(Err_exports, {
+  GetReactiveError: () => GetReactiveError,
+  ObjectNotFoundError: () => ObjectNotFoundError,
+  SchemaNotFoundError: () => SchemaNotFoundError
+});
+import { BaseError } from "@dxos/errors";
+var SchemaNotFoundError = class extends BaseError.extend("SchemaNotFoundError", "Schema not found") {
+  constructor(schema, options) {
+    super({
+      context: {
+        schema
+      },
+      ...options
+    });
+  }
+};
+var ObjectNotFoundError = class extends BaseError.extend("ObjectNotFoundError", "Object not found") {
+  constructor(dxn, options) {
+    super({
+      context: {
+        dxn
+      },
+      ...options
+    });
+  }
+};
+var GetReactiveError = class extends BaseError.extend("GetReactiveError", "Failed to get reactive object from snapshot") {
+  constructor(options) {
+    super({
+      context: {
+        reason: options.reason,
+        snapshotId: options.snapshotId
+      },
+      ...options
+    });
+  }
+};
+
+export {
+  SchemaNotFoundError,
+  ObjectNotFoundError,
+  GetReactiveError,
+  Err_exports
+};
+//# sourceMappingURL=chunk-MXQJZCPY.mjs.map

package/dist/lib/neutral/chunk-MXQJZCPY.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/Err.ts"],
+  "sourcesContent": ["//\n// Copyright 2025 DXOS.org\n//\n\nimport { BaseError, type BaseErrorOptions } from '@dxos/errors';\nimport { type DXN } from '@dxos/keys';\n\nexport class SchemaNotFoundError extends BaseError.extend('SchemaNotFoundError', 'Schema not found') {\n  constructor(schema: string, options?: BaseErrorOptions) {\n    super({ context: { schema }, ...options });\n  }\n}\n\nexport class ObjectNotFoundError extends BaseError.extend('ObjectNotFoundError', 'Object not found') {\n  constructor(dxn: DXN, options?: BaseErrorOptions) {\n    super({ context: { dxn }, ...options });\n  }\n}\n\n/**\n * Reason why getting a reactive object from a snapshot failed.\n * - `no-database`: The snapshot is not associated with a database.\n * - `object-not-found`: The object was removed or does not exist in the database.\n */\nexport type GetReactiveErrorReason = 'no-database' | 'object-not-found';\n\n/**\n * Error thrown when a reactive object cannot be resolved from a snapshot.\n * Extends `BaseError` with a `reason` and optional `snapshotId` in its context.\n */\nexport class GetReactiveError extends BaseError.extend(\n  'GetReactiveError',\n  'Failed to get reactive object from snapshot',\n) {\n  constructor(options: { reason: GetReactiveErrorReason; snapshotId?: string } & BaseErrorOptions) {\n    super({ context: { reason: options.reason, snapshotId: options.snapshotId }, ...options });\n  }\n}\n"],
+  "mappings": ";;;;;AAAA;;;;;;AAIA,SAASA,iBAAwC;AAG1C,IAAMC,sBAAN,cAAkCC,UAAUC,OAAO,uBAAuB,kBAAA,EAAA;EAC/E,YAAYC,QAAgBC,SAA4B;AACtD,UAAM;MAAEC,SAAS;QAAEF;MAAO;MAAG,GAAGC;IAAQ,CAAA;EAC1C;AACF;AAEO,IAAME,sBAAN,cAAkCL,UAAUC,OAAO,uBAAuB,kBAAA,EAAA;EAC/E,YAAYK,KAAUH,SAA4B;AAChD,UAAM;MAAEC,SAAS;QAAEE;MAAI;MAAG,GAAGH;IAAQ,CAAA;EACvC;AACF;AAaO,IAAMI,mBAAN,cAA+BP,UAAUC,OAC9C,oBACA,6CAAA,EAAA;EAEA,YAAYE,SAAqF;AAC/F,UAAM;MAAEC,SAAS;QAAEI,QAAQL,QAAQK;QAAQC,YAAYN,QAAQM;MAAW;MAAG,GAAGN;IAAQ,CAAA;EAC1F;AACF;",
+  "names": ["BaseError", "SchemaNotFoundError", "BaseError", "extend", "schema", "options", "context", "ObjectNotFoundError", "dxn", "GetReactiveError", "reason", "snapshotId"]
+}

package/dist/lib/neutral/chunk-N2QNHMT5.mjs

@@ -0,0 +1,73 @@
+import {
+  Currency,
+  CurrencyAnnotationId,
+  DecimalPrecision,
+  Email,
+  Format,
+  FormatAnnotation,
+  FormatAnnotationId,
+  FormatEnums,
+  Formula,
+  GeoLocation,
+  GeoPoint,
+  Hostname,
+  JSON,
+  Markdown,
+  OptionsAnnotation,
+  OptionsAnnotationId,
+  PropertyKind,
+  Regex,
+  SelectOption,
+  Text,
+  TypeEnum,
+  TypeFormat,
+  URL,
+  UUID,
+  formatToType,
+  getFormatAnnotation,
+  getOptionsAnnotation,
+  getTypeEnum,
+  typeToFormat
+} from "./chunk-7WE7SBA2.mjs";
+import {
+  __export
+} from "./chunk-J5LGTIGS.mjs";
+
+// src/Format.ts
+var Format_exports = {};
+__export(Format_exports, {
+  Currency: () => Currency,
+  CurrencyAnnotationId: () => CurrencyAnnotationId,
+  DecimalPrecision: () => DecimalPrecision,
+  Email: () => Email,
+  Format: () => Format,
+  FormatAnnotation: () => FormatAnnotation,
+  FormatAnnotationId: () => FormatAnnotationId,
+  FormatEnums: () => FormatEnums,
+  Formula: () => Formula,
+  GeoLocation: () => GeoLocation,
+  GeoPoint: () => GeoPoint,
+  Hostname: () => Hostname,
+  JSON: () => JSON,
+  Markdown: () => Markdown,
+  OptionsAnnotation: () => OptionsAnnotation,
+  OptionsAnnotationId: () => OptionsAnnotationId,
+  PropertyKind: () => PropertyKind,
+  Regex: () => Regex,
+  SelectOption: () => SelectOption,
+  Text: () => Text,
+  TypeEnum: () => TypeEnum,
+  TypeFormat: () => TypeFormat,
+  URL: () => URL,
+  UUID: () => UUID,
+  formatToType: () => formatToType,
+  getFormatAnnotation: () => getFormatAnnotation,
+  getOptionsAnnotation: () => getOptionsAnnotation,
+  getTypeEnum: () => getTypeEnum,
+  typeToFormat: () => typeToFormat
+});
+
+export {
+  Format_exports
+};
+//# sourceMappingURL=chunk-N2QNHMT5.mjs.map

package/dist/lib/neutral/chunk-N2QNHMT5.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/Format.ts"],
+  "sourcesContent": ["//\n// Copyright 2025 DXOS.org\n//\n\nimport { type TypeFormat as Format } from './internal';\n\nexport * from './internal/formats';\n\nexport type { Format };\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;",
+  "names": []
+}

package/dist/lib/neutral/chunk-OMUPQMLR.mjs

@@ -0,0 +1,7 @@
+// src/QueryResult.ts
+var QueryResult_exports = {};
+
+export {
+  QueryResult_exports
+};
+//# sourceMappingURL=chunk-OMUPQMLR.mjs.map

package/dist/lib/neutral/chunk-OMUPQMLR.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/QueryResult.ts"],
+  "sourcesContent": ["//\n// Copyright 2025 DXOS.org\n//\n\nimport { type CleanupFn } from '@dxos/async';\n\nimport type * as Entity from './Entity';\n\n/**\n * Individual query result entry.\n */\nexport type Entry<T> = {\n  id: string;\n\n  /**\n   * May not be present for remote results.\n   */\n  result?: T;\n\n  match?: {\n    // TODO(dmaretskyi): text positional info.\n\n    /**\n     * Higher means better match.\n     */\n    rank: number;\n  };\n\n  /**\n   * Query resolution metadata.\n   */\n  // TODO(dmaretskyi): Rename to meta?\n  resolution?: {\n    // TODO(dmaretskyi): Make this more generic.\n    source: 'remote' | 'local' | 'index';\n\n    /**\n     * Query resolution time in milliseconds.\n     */\n    time: number;\n  };\n};\n\n/**\n * Invidual query result entry for a database Entity.\n */\nexport type EntityEntry<T extends Entity.Unknown = Entity.Unknown> = Entry<T>;\n\nexport type RunOptions = {\n  timeout?: number;\n};\n\nexport type SubscriptionOptions = {\n  /**\n   * Fire the callback immediately.\n   */\n  fire?: boolean;\n};\n\n// TODO(burdon): Should T be constrained to Entity.Any?\nexport interface QueryResult<T> {\n  /**\n   * Currently available results along with their match metadata.\n   */\n  readonly entries: Entry<T>[];\n\n  /**\n   * Currently available results.\n   */\n  readonly results: T[];\n\n  /**\n   * Returns all known results.\n   */\n  run(opts?: RunOptions): Promise<T[]>;\n\n  /**\n   * Returns all known results along with their match metadata.\n   */\n  runEntries(opts?: RunOptions): Promise<Entry<T>[]>;\n\n  /**\n   * Returns currently available results synchronously.\n   */\n  runSync(): T[];\n\n  /**\n   * Returns currently available results synchronously along with their match metadata.\n   */\n  runSyncEntries(): Entry<T>[];\n\n  /**\n   * Returns first result.\n   */\n  first(opts?: RunOptions): Promise<T>;\n\n  /**\n   * Returns first result if there is one.\n   */\n  firstOrUndefined(opts?: RunOptions): Promise<T | undefined>;\n\n  /**\n   * Subscribes to changes in query results.\n   */\n  subscribe(callback?: (query: QueryResult<T>) => void, opts?: SubscriptionOptions): CleanupFn;\n}\n"],
+  "mappings": ";AAAA;",
+  "names": []
+}

package/dist/lib/neutral/chunk-RCBBZLVM.mjs

@@ -0,0 +1,142 @@
+import {
+  EchoObjectSchema,
+  EchoRelationSchema,
+  EchoSchema,
+  PersistentSchema,
+  Ref,
+  isMutable,
+  toEffectSchema,
+  toJsonSchema
+} from "./chunk-VJ2H5MOJ.mjs";
+import {
+  getSchemaDXN,
+  getSchemaTypename,
+  getSchemaVersion,
+  getTypeAnnotation
+} from "./chunk-RIMHNJ3E.mjs";
+import {
+  ANY_OBJECT_TYPENAME,
+  ANY_OBJECT_VERSION,
+  EntityKind,
+  SchemaKindId
+} from "./chunk-KB7RIVLK.mjs";
+import {
+  __export
+} from "./chunk-J5LGTIGS.mjs";
+
+// src/Type.ts
+var Type_exports = {};
+__export(Type_exports, {
+  Entity: () => Entity,
+  Obj: () => Obj,
+  PersistentType: () => PersistentType,
+  Ref: () => Ref2,
+  Relation: () => Relation,
+  RuntimeType: () => EchoSchema,
+  getDXN: () => getDXN,
+  getMeta: () => getMeta,
+  getTypename: () => getTypename,
+  getVersion: () => getVersion,
+  isMutable: () => isMutable2,
+  isObjectSchema: () => isObjectSchema,
+  isRelationSchema: () => isRelationSchema,
+  object: () => object,
+  relation: () => relation,
+  toEffectSchema: () => toEffectSchema,
+  toJsonSchema: () => toJsonSchema
+});
+import * as Schema from "effect/Schema";
+import { invariant } from "@dxos/invariant";
+var __dxlog_file = "/__w/dxos/dxos/packages/core/echo/echo/src/Type.ts";
+var ObjSchema = Schema.Struct({
+  id: Schema.String
+}).pipe(Schema.extend(Schema.Record({
+  key: Schema.String,
+  value: Schema.Unknown
+})), EchoObjectSchema({
+  typename: ANY_OBJECT_TYPENAME,
+  version: ANY_OBJECT_VERSION
+}));
+var Obj = Object.assign(ObjSchema, {
+  [SchemaKindId]: ObjSchema[SchemaKindId]
+});
+var object = EchoObjectSchema;
+var PersistentType = PersistentSchema;
+var RelationSchema = Schema.Struct({
+  id: Schema.String
+}).pipe(Schema.extend(Schema.Record({
+  key: Schema.String,
+  value: Schema.Unknown
+})), EchoRelationSchema({
+  typename: "dxos.org/schema/AnyRelation",
+  version: "0.0.0",
+  source: ObjSchema,
+  target: ObjSchema
+}));
+var Relation = Object.assign(RelationSchema, {
+  [SchemaKindId]: RelationSchema[SchemaKindId]
+});
+var relation = EchoRelationSchema;
+(function(Entity2) {
+  Entity2.Any = Schema.Union(Obj, Relation);
+})(Entity || (Entity = {}));
+var isObjectSchema = (schema) => {
+  return schema[SchemaKindId] === EntityKind.Object;
+};
+var isRelationSchema = (schema) => {
+  return schema[SchemaKindId] === EntityKind.Relation;
+};
+var Ref2 = Ref;
+var getDXN = (schema) => {
+  return getSchemaDXN(schema);
+};
+var getTypename = (schema) => {
+  const typename = getSchemaTypename(schema);
+  invariant(typeof typename === "string" && !typename.startsWith("dxn:"), "Invalid typename", {
+    F: __dxlog_file,
+    L: 463,
+    S: void 0,
+    A: [
+      "typeof typename === 'string' && !typename.startsWith('dxn:')",
+      "'Invalid typename'"
+    ]
+  });
+  return typename;
+};
+var getVersion = (schema) => {
+  const version = getSchemaVersion(schema);
+  invariant(typeof version === "string" && version.match(/^\d+\.\d+\.\d+$/), "Invalid version", {
+    F: __dxlog_file,
+    L: 473,
+    S: void 0,
+    A: [
+      "typeof version === 'string' && version.match(/^\\d+\\.\\d+\\.\\d+$/)",
+      "'Invalid version'"
+    ]
+  });
+  return version;
+};
+var isMutable2 = isMutable;
+var getMeta = (schema) => {
+  return getTypeAnnotation(schema);
+};
+var Entity;
+
+export {
+  Obj,
+  object,
+  PersistentType,
+  Relation,
+  relation,
+  isObjectSchema,
+  isRelationSchema,
+  Ref2 as Ref,
+  getDXN,
+  getTypename,
+  getVersion,
+  isMutable2 as isMutable,
+  getMeta,
+  Entity,
+  Type_exports
+};
+//# sourceMappingURL=chunk-RCBBZLVM.mjs.map

package/dist/lib/neutral/chunk-RCBBZLVM.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/Type.ts"],
+  "sourcesContent": ["//\n// Copyright 2025 DXOS.org\n//\n\nimport * as Schema from 'effect/Schema';\n\nimport { type EncodedReference } from '@dxos/echo-protocol';\nimport { invariant } from '@dxos/invariant';\nimport { type DXN, type ObjectId } from '@dxos/keys';\nimport { type ToMutable } from '@dxos/util';\n\nimport type * as Entity$ from './Entity';\nimport {\n  ANY_OBJECT_TYPENAME,\n  ANY_OBJECT_VERSION,\n  type ATTR_RELATION_SOURCE,\n  type ATTR_RELATION_TARGET,\n  type AnyEntity,\n  type AnyProperties,\n  EchoObjectSchema,\n  EchoRelationSchema,\n  type EchoRelationSchemaOptions,\n  EchoSchema,\n  EntityKind,\n  PersistentSchema,\n  Ref as Ref$,\n  type RefFn,\n  type RefSchema,\n  SchemaKindId,\n  type TypeAnnotation,\n  type TypeMeta,\n  getSchemaDXN,\n  getSchemaTypename,\n  getSchemaVersion,\n  getTypeAnnotation,\n  isMutable as isMutable$,\n  toEffectSchema,\n  toJsonSchema,\n} from './internal';\nimport type * as Relation$ from './Relation';\n\n// TODO(burdon): Remove toEffectSchema, toJsonSchema (moved to JsonSchema export).\nexport { toEffectSchema, toJsonSchema };\n\n/**\n * Returns all properties of an object or relation except for the id and kind.\n */\nexport type Properties<T = any> = Omit<T, 'id' | Entity$.KindId | Relation$.Source | Relation$.Target>;\n\n//\n// Internal types (not exported)\n//\n\n/**\n * Type that marks a schema as an ECHO schema.\n * The value indicates the entity kind (Object or Relation).\n */\ntype EchoSchemaKind<K extends EntityKind = EntityKind> = {\n  readonly [SchemaKindId]: K;\n};\n\n/**\n * JSON-encoded properties for objects.\n */\ninterface ObjJsonProps {\n  id: string;\n}\n\n/**\n * JSON-encoded properties for relations.\n */\ninterface RelationJsonProps {\n  id: string;\n  [ATTR_RELATION_SOURCE]: string;\n  [ATTR_RELATION_TARGET]: string;\n}\n\n//\n// Obj - Runtime schema for any ECHO object\n//\n\n// Internal type for the Obj schema constant.\n// NOTE: The `any` in the type intersection is intentional - it makes this type bidirectionally\n//   assignable with specific object types (e.g., Type.Obj can be assigned to/from Meeting.Meeting).\n//   This is needed because operation schemas erase type information.\n// TODO(wittjosiah): Consider alternatives to the `any` intersection hack:\n//   - Generic operation schemas that preserve input type in output\n//   - Branded types that specific schemas also carry\n//   - Accept the limitation and require explicit type narrowing at call sites\ntype ObjSchemaType = Schema.Schema<\n  any & AnyEntity & Entity$.OfKind<typeof Entity$.Kind.Object> & AnyProperties,\n  { id: string } & AnyProperties\n> &\n  EchoSchemaKind<EntityKind.Object> &\n  TypeMeta;\n\n// Internal schema definition.\n// NOTE: The EchoObjectSchema annotation is required for Type.Ref(Type.Obj) to work.\n//   The typename/version only satisfy ECHO schema machinery for reference targets.\nconst ObjSchema = Schema.Struct({\n  id: Schema.String,\n}).pipe(\n  Schema.extend(Schema.Record({ key: Schema.String, value: Schema.Unknown })),\n  EchoObjectSchema({ typename: ANY_OBJECT_TYPENAME, version: ANY_OBJECT_VERSION }),\n);\n\n/**\n * Runtime Effect schema for any ECHO object.\n * Use for validation, parsing, or as a reference target for collections.\n *\n * NOTE: `Schema.is(Type.Obj)` does STRUCTURAL validation only (checks for `id` field).\n * Use `Obj.isObject()` for proper ECHO instance type guards that check the KindId brand.\n *\n * @example\n * ```ts\n * // Structural type guard (accepts any object with id field)\n * if (Schema.is(Type.Obj)(unknownValue)) { ... }\n *\n * // ECHO instance type guard (checks KindId brand)\n * if (Obj.isObject(unknownValue)) { ... }\n *\n * // Reference to any object type\n * const Collection = Schema.Struct({\n *   objects: Schema.Array(Type.Ref(Type.Obj)),\n * }).pipe(Type.object({ typename: 'Collection', version: '0.1.0' }));\n * ```\n */\n// TODO(wittjosiah): Investigate if Schema.filter can validate KindId on ECHO instances.\n//   Effect Schema normalizes proxy objects to plain objects before calling filter predicates.\n//   Possible approaches: custom Schema.declare, AST manipulation, or upstream contribution.\nexport const Obj: ObjSchemaType = Object.assign(ObjSchema, {\n  [SchemaKindId]: (ObjSchema as any)[SchemaKindId],\n}) as unknown as ObjSchemaType;\n\n/**\n * TypeScript type for an ECHO object schema.\n * `T` is the instance type produced by the schema.\n * `Fields` is the optional struct fields type for introspection.\n *\n * @example\n * ```ts\n * const PersonSchema: Type.Obj<Person> = Schema.Struct({\n *   name: Schema.String,\n * }).pipe(Type.object({ typename: 'Person', version: '0.1.0' }));\n *\n * // Access fields for introspection:\n * Object.keys(PersonSchema.fields); // ['name']\n * ```\n */\nexport interface Obj<T = any, Fields extends Schema.Struct.Fields = Schema.Struct.Fields>\n  extends TypeMeta,\n    EchoSchemaKind<EntityKind.Object>,\n    Schema.AnnotableClass<\n      Obj<T, Fields>,\n      Entity$.OfKind<typeof Entity$.Kind.Object> & T,\n      Schema.Simplify<ObjJsonProps & ToMutable<T>>,\n      never\n    > {\n  /**\n   * The fields defined in the original struct schema.\n   * Allows accessing field definitions for introspection.\n   */\n  readonly fields: Fields;\n}\n\n/**\n * Structural base type for any ECHO object schema.\n * Accepts both static schemas (created with Type.object()) and EchoSchema.\n * NOTE: Does not include the brand symbol to avoid TS4053 declaration portability issues.\n * Use Type.isObjectSchema() for runtime type guards.\n */\ntype ObjectSchemaBase = Schema.Schema.AnyNoContext & {\n  readonly typename: string;\n  readonly version: string;\n};\n\nexport namespace Obj {\n  /**\n   * Type that represents any ECHO object schema.\n   * Accepts both static schemas (Type.object()) and mutable schemas (EchoSchema).\n   */\n  export type Any = ObjectSchemaBase;\n}\n\n/**\n * Factory function to create an ECHO object schema.\n * Adds object metadata annotations to an Effect schema.\n *\n * @example\n * ```ts\n * const Person = Schema.Struct({\n *   name: Schema.String,\n * }).pipe(Type.object({ typename: 'example.com/type/Person', version: '0.1.0' }));\n * ```\n */\nexport const object: {\n  (opts: TypeMeta): <Self extends Schema.Schema.Any>(self: Self) => Obj<Schema.Schema.Type<Self>>;\n} = EchoObjectSchema as any;\n\n//\n// PersistentType (Schema stored in database)\n//\n\nexport const PersistentType: Obj<PersistentSchema> = PersistentSchema as any;\n\nexport interface PersistentType extends Schema.Schema.Type<typeof PersistentType> {}\n\nexport { EchoSchema as RuntimeType };\n\n//\n// Relation - Runtime schema for any ECHO relation\n//\n\n// Internal type for the Relation schema constant.\ntype RelationSchemaType = Schema.Schema<\n  { id: ObjectId } & Record<string, unknown>,\n  { id: string } & Record<string, unknown>\n> &\n  EchoSchemaKind<EntityKind.Relation> &\n  TypeMeta;\n\n// Internal schema definition.\n// NOTE: The EchoRelationSchema annotation is required for Type.Ref(Type.Relation) to work.\n//   The typename/version/source/target only satisfy ECHO schema machinery for reference targets.\nconst RelationSchema = Schema.Struct({\n  id: Schema.String,\n}).pipe(\n  Schema.extend(Schema.Record({ key: Schema.String, value: Schema.Unknown })),\n  EchoRelationSchema({\n    typename: 'dxos.org/schema/AnyRelation',\n    version: '0.0.0',\n    source: ObjSchema,\n    target: ObjSchema,\n  }),\n);\n\n/**\n * Runtime Effect schema for any ECHO relation.\n * Use for validation, parsing, or as a reference target for collections.\n * A relation has `id`, source, and target fields plus any additional properties.\n *\n * NOTE: `Schema.is(Type.Relation)` does STRUCTURAL validation only (checks for `id` field).\n * Use `Relation.isRelation()` for proper ECHO instance type guards that check the KindId brand.\n *\n * @example\n * ```ts\n * // Structural type guard (accepts any object with id field)\n * if (Schema.is(Type.Relation)(unknownValue)) { ... }\n *\n * // ECHO instance type guard (checks KindId brand)\n * if (Relation.isRelation(unknownValue)) { ... }\n * ```\n */\nexport const Relation: RelationSchemaType = Object.assign(RelationSchema, {\n  [SchemaKindId]: (RelationSchema as any)[SchemaKindId],\n}) as unknown as RelationSchemaType;\n\n/**\n * TypeScript type for an ECHO relation schema.\n * `T` is the instance type produced by the schema (excluding source/target).\n * `Source` and `Target` are the endpoint types.\n * `Fields` is the optional struct fields type for introspection.\n */\nexport interface Relation<\n  T = any,\n  Source = any,\n  Target = any,\n  Fields extends Schema.Struct.Fields = Schema.Struct.Fields,\n> extends TypeMeta,\n    EchoSchemaKind<EntityKind.Relation>,\n    Schema.AnnotableClass<\n      Relation<T, Source, Target, Fields>,\n      Entity$.OfKind<typeof Entity$.Kind.Relation> & Relation.Endpoints<Source, Target> & T,\n      Schema.Simplify<RelationJsonProps & ToMutable<T>>,\n      never\n    > {\n  /**\n   * The fields defined in the original struct schema.\n   * Allows accessing field definitions for introspection.\n   */\n  readonly fields: Fields;\n}\n\n/**\n * Structural base type for any ECHO relation schema.\n * Accepts static schemas (created with Type.relation()).\n * NOTE: Does not include the brand symbol to avoid TS4053 declaration portability issues.\n * Use Type.isRelationSchema() for runtime type guards.\n */\ntype RelationSchemaBase = Schema.Schema.AnyNoContext & {\n  readonly typename: string;\n  readonly version: string;\n};\n\nexport namespace Relation {\n  /**\n   * Type that represents any ECHO relation schema.\n   * Accepts static schemas (Type.relation()).\n   */\n  export type Any = RelationSchemaBase;\n\n  /**\n   * Get relation source type.\n   */\n  export type Source<A> = A extends Relation.Endpoints<infer S, infer _T> ? S : never;\n\n  /**\n   * Get relation target type.\n   */\n  export type Target<A> = A extends Relation.Endpoints<infer _S, infer T> ? T : never;\n\n  export type Endpoints<Source, Target> = {\n    [Relation$.Source]: Source;\n    [Relation$.Target]: Target;\n  };\n}\n\n/**\n * Factory function to create an ECHO relation schema.\n * Adds relation metadata annotations to an Effect schema.\n *\n * @example\n * ```ts\n * const WorksFor = Schema.Struct({\n *   role: Schema.String,\n * }).pipe(Type.relation({\n *   typename: 'example.com/type/WorksFor',\n *   version: '0.1.0',\n *   source: Person,\n *   target: Company,\n * }));\n * ```\n */\nexport const relation: {\n  <SourceSchema extends Schema.Schema.AnyNoContext, TargetSchema extends Schema.Schema.AnyNoContext>(\n    opts: EchoRelationSchemaOptions<SourceSchema, TargetSchema>,\n  ): <Self extends Schema.Schema.Any>(\n    self: Self,\n  ) => Relation<Schema.Schema.Type<Self>, Schema.Schema.Type<SourceSchema>, Schema.Schema.Type<TargetSchema>>;\n} = EchoRelationSchema as any;\n\n//\n// Entity - Entity schema types (union of Object | Relation)\n//\n\nexport namespace Entity {\n  /**\n   * Runtime Effect schema for any ECHO entity (object or relation).\n   * Use for validation, parsing, or type guards on unknown values.\n   *\n   * @example\n   * ```ts\n   * if (Schema.is(Type.Entity.Any)(unknownValue)) {\n   *   // unknownValue is an ECHO entity\n   * }\n   * ```\n   */\n  export const Any: Schema.Schema<\n    { id: ObjectId } & Record<string, unknown>,\n    { id: string } & Record<string, unknown>\n  > = Schema.Union(Obj, Relation);\n\n  /**\n   * Type alias for any ECHO entity schema (object or relation).\n   * Use this in type annotations for schema parameters.\n   */\n  export type Any = Obj.Any | Relation.Any;\n}\n\n/**\n * Type guard to check if a schema is an object schema.\n * NOTE: This checks SCHEMAS, not instances. Use Obj.isObject for instances.\n */\nexport const isObjectSchema = (schema: Entity.Any): schema is Obj.Any => {\n  return (schema as any)[SchemaKindId] === EntityKind.Object;\n};\n\n/**\n * Type guard to check if a schema is a relation schema.\n * NOTE: This checks SCHEMAS, not instances. Use Relation.isRelation for instances.\n */\nexport const isRelationSchema = (schema: Entity.Any): schema is Relation.Any => {\n  return (schema as any)[SchemaKindId] === EntityKind.Relation;\n};\n\n//\n// Ref\n//\n// NOTE: `Type.Ref` vs `Ref.Ref`:\n// - `Type.Ref<T>` is the SCHEMA type - a schema that produces `Ref.Ref<T>` instances.\n// - `Ref.Ref<T>` is the INSTANCE type - the actual runtime ref object.\n//\n// Example:\n//   const taskRef: Ref.Ref<Task> = Ref.make(task);  // Instance\n//   const schema: Type.Ref<Task> = Type.Ref(Task);  // Schema\n//\n\n/**\n * Return type of the `Ref` schema constructor.\n *\n * This typedef avoids `TS4023` error (name from external module cannot be used named).\n * See Effect's note on interface types.\n */\nexport interface ref<TargetSchema extends Schema.Schema.Any> extends RefSchema<Schema.Schema.Type<TargetSchema>> {}\n\n/**\n * Factory function to create a Ref schema for the given target schema.\n * Use this in schema definitions to declare reference fields.\n *\n * @example\n * ```ts\n * const Task = Schema.Struct({\n *   assignee: Type.Ref(Person),  // Creates a Ref schema\n * }).pipe(Type.object({ typename: 'Task', version: '0.1.0' }));\n * ```\n */\nexport const Ref: RefFn = Ref$;\n\n/**\n * TypeScript type for a Ref schema.\n * This is the type of the SCHEMA itself, not the runtime ref instance.\n * For the instance type, use `Ref.Ref<T>` from the Ref module.\n *\n * @example\n * ```ts\n * // Schema type annotation (rarely needed, usually inferred):\n * const refSchema: Type.Ref<Task> = Type.Ref(Task);\n *\n * // Instance type annotation (use Ref.Ref instead):\n * const refInstance: Ref.Ref<Task> = Ref.make(task);\n * ```\n */\nexport interface Ref<T> extends Schema.SchemaClass<Ref$<T>, EncodedReference> {}\n\nexport namespace Ref {\n  /**\n   * Type that represents any Ref schema (with unknown target type).\n   * This is a schema type, not an instance type.\n   */\n  export type Any = Schema.Schema<Ref$<any>, EncodedReference>;\n}\n\n//\n// Schema utility functions\n//\n\n/**\n * Gets the full DXN of the schema.\n * Will include the version if it's a `type` DXN.\n * @example \"dxn:example.com/type/Person:0.1.0\"\n * @example \"dxn:echo:SSSSSSSSSS:XXXXXXXXXXXXX\"\n */\nexport const getDXN = (schema: Entity.Any): DXN | undefined => {\n  return getSchemaDXN(schema);\n};\n\n/**\n * @param schema - Schema to get the typename from.\n * @returns The typename of the schema. Example: `example.com/type/Person`.\n */\nexport const getTypename = (schema: Entity.Any): string => {\n  const typename = getSchemaTypename(schema);\n  invariant(typeof typename === 'string' && !typename.startsWith('dxn:'), 'Invalid typename');\n  return typename;\n};\n\n/**\n * Gets the version of the schema.\n * @example 0.1.0\n */\nexport const getVersion = (schema: Entity.Any): string => {\n  const version = getSchemaVersion(schema);\n  invariant(typeof version === 'string' && version.match(/^\\d+\\.\\d+\\.\\d+$/), 'Invalid version');\n  return version;\n};\n\n/**\n * @returns True if the schema is mutable.\n */\nexport const isMutable = isMutable$;\n\n/**\n * ECHO type metadata.\n */\nexport type Meta = TypeAnnotation;\n\n/**\n * Gets the meta data of the schema.\n */\nexport const getMeta = (schema: Entity.Any): Meta | undefined => {\n  return getTypeAnnotation(schema);\n};\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;;;;;aAAAA;EAAA;;;;;;mBAAAC;EAAA;;;;;;;AAIA,YAAYC,YAAY;AAGxB,SAASC,iBAAiB;A;AA4F1B,IAAMC,YAAmBC,cAAO;EAC9BC,IAAWC;AACb,CAAA,EAAGC,KACMC,cAAcC,cAAO;EAAEC,KAAYJ;EAAQK,OAAcC;AAAQ,CAAA,CAAA,GACxEC,iBAAiB;EAAEC,UAAUC;EAAqBC,SAASC;AAAmB,CAAA,CAAA;AA2BzE,IAAMC,MAAqBC,OAAOC,OAAOjB,WAAW;EACzD,CAACkB,YAAAA,GAAgBlB,UAAkBkB,YAAAA;AACrC,CAAA;AA+DO,IAAMC,SAETT;AAMG,IAAMU,iBAAwCC;AAqBrD,IAAMC,iBAAwBC,cAAO;EACnCC,IAAWC;AACb,CAAA,EAAGC,KACMC,cAAcC,cAAO;EAAEC,KAAYJ;EAAQK,OAAcC;AAAQ,CAAA,CAAA,GACxEC,mBAAmB;EACjBC,UAAU;EACVC,SAAS;EACTC,QAAQC;EACRC,QAAQD;AACV,CAAA,CAAA;AAoBK,IAAME,WAA+BC,OAAOC,OAAOlB,gBAAgB;EACxE,CAACmB,YAAAA,GAAgBnB,eAAuBmB,YAAAA;AAC1C,CAAA;AA8EO,IAAMC,WAMTV;UAMaW,SAAAA;UAYFC,MAGFC,aAAMC,KAAKR,QAAAA;AAOxB,GAtBiBK,WAAAA,SAAAA,CAAAA,EAAAA;AA4BV,IAAMI,iBAAiB,CAACC,WAAAA;AAC7B,SAAQA,OAAeP,YAAAA,MAAkBQ,WAAWV;AACtD;AAMO,IAAMW,mBAAmB,CAACF,WAAAA;AAC/B,SAAQA,OAAeP,YAAAA,MAAkBQ,WAAWX;AACtD;AAiCO,IAAMa,OAAaC;AAoCnB,IAAMC,SAAS,CAACL,WAAAA;AACrB,SAAOM,aAAaN,MAAAA;AACtB;AAMO,IAAMO,cAAc,CAACP,WAAAA;AAC1B,QAAMf,WAAWuB,kBAAkBR,MAAAA;AACnCS,YAAU,OAAOxB,aAAa,YAAY,CAACA,SAASyB,WAAW,MAAA,GAAS,oBAAA;;;;;;;;;AACxE,SAAOzB;AACT;AAMO,IAAM0B,aAAa,CAACX,WAAAA;AACzB,QAAMd,UAAU0B,iBAAiBZ,MAAAA;AACjCS,YAAU,OAAOvB,YAAY,YAAYA,QAAQ2B,MAAM,iBAAA,GAAoB,mBAAA;;;;;;;;;AAC3E,SAAO3B;AACT;AAKO,IAAM4B,aAAYC;AAUlB,IAAMC,UAAU,CAAChB,WAAAA;AACtB,SAAOiB,kBAAkBjB,MAAAA;AAC3B;;",
+  "names": ["Ref", "isMutable", "Schema", "invariant", "ObjSchema", "Struct", "id", "String", "pipe", "extend", "Record", "key", "value", "Unknown", "EchoObjectSchema", "typename", "ANY_OBJECT_TYPENAME", "version", "ANY_OBJECT_VERSION", "Obj", "Object", "assign", "SchemaKindId", "object", "PersistentType", "PersistentSchema", "RelationSchema", "Struct", "id", "String", "pipe", "extend", "Record", "key", "value", "Unknown", "EchoRelationSchema", "typename", "version", "source", "ObjSchema", "target", "Relation", "Object", "assign", "SchemaKindId", "relation", "Entity", "Any", "Union", "Obj", "isObjectSchema", "schema", "EntityKind", "isRelationSchema", "Ref", "Ref$", "getDXN", "getSchemaDXN", "getTypename", "getSchemaTypename", "invariant", "startsWith", "getVersion", "getSchemaVersion", "match", "isMutable", "isMutable$", "getMeta", "getTypeAnnotation"]
+}

package/dist/lib/neutral/chunk-RIMHNJ3E.mjs

@@ -0,0 +1,296 @@
+import {
+  EntityKind,
+  createAnnotationHelper
+} from "./chunk-KB7RIVLK.mjs";
+
+// src/internal/types/typename.ts
+var ATTR_TYPE = "@type";
+var TypeId = Symbol.for("@dxos/echo/Type");
+var SchemaId = Symbol.for("@dxos/echo/Schema");
+var ATTR_PARENT = "@parent";
+var ParentId = Symbol.for("@dxos/echo/Parent");
+var getSchema = (obj) => {
+  if (obj) {
+    return obj[SchemaId];
+  }
+};
+var setSchema = (obj, schema) => {
+  Object.defineProperty(obj, SchemaId, {
+    value: schema,
+    writable: false,
+    enumerable: false,
+    configurable: false
+  });
+};
+
+// src/internal/annotations/annotations.ts
+import * as Function from "effect/Function";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as SchemaAST from "effect/SchemaAST";
+import { raise } from "@dxos/debug";
+import { getField } from "@dxos/effect";
+import { assertArgument, invariant } from "@dxos/invariant";
+import { DXN } from "@dxos/keys";
+var __dxlog_file = "/__w/dxos/dxos/packages/core/echo/echo/src/internal/annotations/annotations.ts";
+var FIELD_PATH_ANNOTATION = "path";
+var FieldPath = (path) => PropertyMeta(FIELD_PATH_ANNOTATION, path);
+var TypeIdentifierAnnotationId = Symbol.for("@dxos/schema/annotation/TypeIdentifier");
+var getTypeIdentifierAnnotation = (schema) => Function.flow(SchemaAST.getAnnotation(TypeIdentifierAnnotationId), Option.getOrElse(() => void 0))(schema.ast);
+var getSchemaDXN = (schema) => {
+  assertArgument(Schema.isSchema(schema), "schema", "invalid schema");
+  const id = getTypeIdentifierAnnotation(schema);
+  if (id) {
+    return DXN.parse(id);
+  }
+  const objectAnnotation = getTypeAnnotation(schema);
+  if (!objectAnnotation) {
+    return void 0;
+  }
+  return DXN.fromTypenameAndVersion(objectAnnotation.typename, objectAnnotation.version);
+};
+var getTypeDXNFromSpecifier = (input) => {
+  if (Schema.isSchema(input)) {
+    return getSchemaDXN(input) ?? raise(new TypeError("Schema has no DXN"));
+  } else {
+    assertArgument(typeof input === "string", "input");
+    assertArgument(!input.startsWith("dxn:"), "input");
+    return DXN.fromTypename(input);
+  }
+};
+var TypenameSchema = Schema.String.pipe(Schema.pattern(/^[a-zA-Z]\w+\.[a-zA-Z]\w{1,}\/[\w/_-]+$/)).annotations({
+  description: "Fully qualified globally unique typename",
+  example: "dxos.org/type/Message"
+});
+var VersionSchema = Schema.String.pipe(Schema.pattern(/^\d+.\d+.\d+$/)).annotations({
+  description: "Semantic version format: `major.minor.patch`",
+  example: "1.0.0"
+});
+var TypeMeta = Schema.Struct({
+  typename: TypenameSchema,
+  version: VersionSchema
+});
+var TypeAnnotationId = Symbol.for("@dxos/schema/annotation/Type");
+var TypeAnnotation = Schema.extend(TypeMeta, Schema.Struct({
+  kind: Schema.Enums(EntityKind),
+  /**
+   * If this is a relation, the schema of the source object.
+   * Must be present if entity kind is {@link EntityKind.Relation}.
+   */
+  sourceSchema: Schema.optional(DXN.Schema),
+  /**
+   * If this is a relation, the schema of the target object.
+   * Must be present if entity kind is {@link EntityKind.Relation}.
+   */
+  targetSchema: Schema.optional(DXN.Schema)
+}));
+var getTypeAnnotation = (schema) => {
+  assertArgument(schema != null && schema.ast != null, "schema", "invalid schema");
+  return Function.flow(SchemaAST.getAnnotation(TypeAnnotationId), Option.getOrElse(() => void 0))(schema.ast);
+};
+var getEntityKind = (schema) => getTypeAnnotation(schema)?.kind;
+var getSchemaTypename = (schema) => getTypeAnnotation(schema)?.typename;
+var getSchemaVersion = (schema) => getTypeAnnotation(schema)?.version;
+var getTypename = (obj) => {
+  const schema = getSchema(obj);
+  if (schema != null) {
+    return getSchemaTypename(schema);
+  } else {
+    const type = getTypeDXN(obj);
+    return type?.asTypeDXN()?.type;
+  }
+};
+var setTypename = (obj, typename) => {
+  invariant(typename instanceof DXN, "Invalid type.", {
+    F: __dxlog_file,
+    L: 198,
+    S: void 0,
+    A: [
+      "typename instanceof DXN",
+      "'Invalid type.'"
+    ]
+  });
+  Object.defineProperty(obj, TypeId, {
+    value: typename,
+    writable: false,
+    enumerable: false,
+    configurable: false
+  });
+};
+var getTypeDXN = (obj) => {
+  if (!obj) {
+    return void 0;
+  }
+  const type = obj[TypeId];
+  if (!type) {
+    return void 0;
+  }
+  invariant(type instanceof DXN, "Invalid object.", {
+    F: __dxlog_file,
+    L: 225,
+    S: void 0,
+    A: [
+      "type instanceof DXN",
+      "'Invalid object.'"
+    ]
+  });
+  return type;
+};
+var isInstanceOf = (schema, object) => {
+  if (object == null) {
+    return false;
+  }
+  const schemaDXN = getSchemaDXN(schema);
+  if (!schemaDXN) {
+    throw new Error("Schema must have an object annotation.");
+  }
+  const type = getTypeDXN(object);
+  if (type && DXN.equals(type, schemaDXN)) {
+    return true;
+  }
+  const typename = getTypename(object);
+  if (!typename) {
+    return false;
+  }
+  const typeDXN = schemaDXN.asTypeDXN();
+  if (!typeDXN) {
+    return false;
+  }
+  return typeDXN.type === typename;
+};
+var PropertyMetaAnnotationId = Symbol.for("@dxos/schema/annotation/PropertyMeta");
+var PropertyMeta = (name, value) => {
+  return (self) => {
+    const existingMeta = self.ast.annotations[PropertyMetaAnnotationId];
+    return self.annotations({
+      [PropertyMetaAnnotationId]: {
+        ...existingMeta,
+        [name]: value
+      }
+    });
+  };
+};
+var getPropertyMetaAnnotation = (prop, name) => Function.pipe(SchemaAST.getAnnotation(PropertyMetaAnnotationId)(prop.type), Option.map((meta) => meta[name]), Option.getOrElse(() => void 0));
+var ReferenceAnnotationId = Symbol.for("@dxos/schema/annotation/Reference");
+var ReferenceAnnotation = createAnnotationHelper(ReferenceAnnotationId);
+var SchemaMetaSymbol = Symbol.for("@dxos/schema/SchemaMeta");
+var SystemTypeAnnotationId = Symbol.for("@dxos/schema/annotation/SystemType");
+var SystemTypeAnnotation = createAnnotationHelper(SystemTypeAnnotationId);
+var LabelAnnotationId = Symbol.for("@dxos/schema/annotation/Label");
+var LabelAnnotation = createAnnotationHelper(LabelAnnotationId);
+var getLabelWithSchema = (schema, object) => {
+  const annotation = LabelAnnotation.get(schema).pipe(Option.getOrElse(() => [
+    "name"
+  ]));
+  for (const accessor of annotation) {
+    assertArgument(typeof accessor === "string", "accessor", "Label annotation must be a string or an array of strings");
+    const value = getField(object, accessor);
+    switch (typeof value) {
+      case "string":
+      case "number":
+      case "boolean":
+      case "bigint":
+      case "symbol":
+        return value.toString();
+      case "undefined":
+      case "object":
+      case "function":
+        continue;
+    }
+  }
+  return void 0;
+};
+var setLabelWithSchema = (schema, object, label) => {
+  const annotation = LabelAnnotation.get(schema).pipe(Option.map((field) => field[0]), Option.getOrElse(() => "name"));
+  object[annotation] = label;
+};
+var DescriptionAnnotationId = Symbol.for("@dxos/schema/annotation/Description");
+var DescriptionAnnotation = createAnnotationHelper(DescriptionAnnotationId);
+var getDescriptionWithSchema = (schema, object) => {
+  const accessor = DescriptionAnnotation.get(schema).pipe(Option.getOrElse(() => "description"));
+  assertArgument(typeof accessor === "string", "accessor", "Description annotation must be a string");
+  const value = getField(object, accessor);
+  switch (typeof value) {
+    case "string":
+    case "number":
+    case "boolean":
+    case "bigint":
+    case "symbol":
+      return value.toString();
+    case "undefined":
+    case "object":
+    case "function":
+    default:
+      return void 0;
+  }
+};
+var setDescriptionWithSchema = (schema, object, description) => {
+  const accessor = DescriptionAnnotation.get(schema).pipe(Option.getOrElse(() => "description"));
+  object[accessor] = description;
+};
+var FormInputAnnotationId = Symbol.for("@dxos/schema/annotation/FormInput");
+var FormInputAnnotation = createAnnotationHelper(FormInputAnnotationId);
+var FieldLookupAnnotationId = Symbol.for("@dxos/schema/annotation/FieldLookup");
+var GeneratorAnnotationId = Symbol.for("@dxos/schema/annotation/Generator");
+var GeneratorAnnotation = createAnnotationHelper(GeneratorAnnotationId);
+var makeUserAnnotation = (props) => {
+  assertArgument(/[a-zA-Z0-9]+\.[a-zA-Z.]+\/[a-zA-Z/]+/.test(props.id), "id", "Annotation id must be in the FQN format (dxos.org/annotation/Example).");
+  const getFromAst = (ast) => SchemaAST.getAnnotation(PropertyMetaAnnotationId)(ast).pipe(Option.map((meta) => meta[props.id]), Option.map(Schema.decodeUnknownSync(props.schema)));
+  return {
+    get: (schema) => getFromAst(schema.ast),
+    getFromAst: (ast) => getFromAst(ast),
+    set: (value) => PropertyMeta(props.id, Schema.encodeSync(props.schema)(value))
+  };
+};
+
+export {
+  ATTR_TYPE,
+  TypeId,
+  SchemaId,
+  ATTR_PARENT,
+  ParentId,
+  getSchema,
+  setSchema,
+  FIELD_PATH_ANNOTATION,
+  FieldPath,
+  TypeIdentifierAnnotationId,
+  getTypeIdentifierAnnotation,
+  getSchemaDXN,
+  getTypeDXNFromSpecifier,
+  TypenameSchema,
+  VersionSchema,
+  TypeMeta,
+  TypeAnnotationId,
+  TypeAnnotation,
+  getTypeAnnotation,
+  getEntityKind,
+  getSchemaTypename,
+  getSchemaVersion,
+  getTypename,
+  setTypename,
+  getTypeDXN,
+  isInstanceOf,
+  PropertyMetaAnnotationId,
+  PropertyMeta,
+  getPropertyMetaAnnotation,
+  ReferenceAnnotationId,
+  ReferenceAnnotation,
+  SchemaMetaSymbol,
+  SystemTypeAnnotationId,
+  SystemTypeAnnotation,
+  LabelAnnotationId,
+  LabelAnnotation,
+  getLabelWithSchema,
+  setLabelWithSchema,
+  DescriptionAnnotationId,
+  DescriptionAnnotation,
+  getDescriptionWithSchema,
+  setDescriptionWithSchema,
+  FormInputAnnotationId,
+  FormInputAnnotation,
+  FieldLookupAnnotationId,
+  GeneratorAnnotationId,
+  GeneratorAnnotation,
+  makeUserAnnotation
+};
+//# sourceMappingURL=chunk-RIMHNJ3E.mjs.map