@dxos/echo 0.8.4-main.ef1bc66f44 → 0.8.4-main.effb148878

package/dist/types/src/Type.d.ts

@@ -1,77 +1,64 @@
 import * as Schema from 'effect/Schema';
+import type * as Types from 'effect/Types';
 import { type EncodedReference } from '@dxos/echo-protocol';
-import { type DXN, type ObjectId } from '@dxos/keys';
-import { type ToMutable } from '@dxos/util';
-import type * as Entity$ from './Entity';
-import { type ATTR_RELATION_SOURCE, type ATTR_RELATION_TARGET, type AnyEntity, type AnyProperties, type EchoRelationSchemaOptions, EchoSchema, EntityKind, PersistentSchema, Ref as Ref$, type RefFn, type RefSchema, SchemaKindId, type TypeAnnotation, type TypeMeta, toEffectSchema, toJsonSchema } from './internal';
-import type * as Relation$ from './Relation';
-export { toEffectSchema, toJsonSchema };
+import { DXN, type ObjectId, type URI } from '@dxos/keys';
+import type * as Database from './Database';
+import type * as EntityModule from './Entity';
+import * as internal from './internal';
+import * as typeInternal from './internal/Type';
+import type * as RelationModule from './Relation';
 /**
- * Returns all properties of an object or relation except for the id and kind.
+ * Structural base shared by the three sibling type-entity interfaces
+ * ({@link Obj}, {@link Relation}, {@link Type}). NOT exported — callers
+ * should constrain on {@link AnyEntity} when they want "any of the three"
+ * and on the specific kind interface otherwise.
  */
-export type Properties<T = any> = Omit<T, 'id' | Entity$.KindId | Relation$.Source | Relation$.Target>;
-/**
- * Type that marks a schema as an ECHO schema.
- * The value indicates the entity kind (Object or Relation).
- */
-type EchoSchemaKind<K extends EntityKind = EntityKind> = {
-    readonly [SchemaKindId]: K;
-};
-/**
- * JSON-encoded properties for objects.
- */
-interface ObjJsonProps {
-    id: string;
-}
-/**
- * JSON-encoded properties for relations.
- */
-interface RelationJsonProps {
-    id: string;
-    [ATTR_RELATION_SOURCE]: string;
-    [ATTR_RELATION_TARGET]: string;
+interface BaseTypeEntity<A> {
+    /**
+     * Entity-kind brand of the type-entity value itself — always `EntityKind.Type`.
+     * The kind of instance the type *describes* lives on `[SchemaKindId]`
+     * (Object / Relation / Type). Lets `Obj.isObject` / `Relation.isRelation`
+     * reject type entities by a single `[KindId]` check.
+     */
+    readonly [internal.KindId]: internal.EntityKind.Type;
+    /**
+     * Object id. Like all ECHO entities, type entities always carry an id —
+     * stamped at construction for in-memory (static) declarations and assigned by
+     * the database once persisted. The id does NOT determine the entity's URI:
+     * static types resolve to their typename DXN, persisted types to `echo:/<id>`
+     * (see `getTypeURIFromSpecifier`).
+     */
+    readonly id: ObjectId;
+    readonly name?: string;
+    readonly jsonSchema: internal.JsonSchemaType;
+    readonly [InstancePhantomId]?: A;
 }
-type ObjSchemaType = Schema.Schema<any & AnyEntity & Entity$.OfKind<typeof Entity$.Kind.Object> & AnyProperties, {
-    id: string;
-} & AnyProperties> & EchoSchemaKind<EntityKind.Object> & TypeMeta;
 /**
- * Runtime Effect schema for any ECHO object.
- * Use for validation, parsing, or as a reference target for collections.
- *
- * NOTE: `Schema.is(Type.Obj)` does STRUCTURAL validation only (checks for `id` field).
- * Use `Obj.isObject()` for proper ECHO instance type guards that check the KindId brand.
- *
- * @example
- * ```ts
- * // Structural type guard (accepts any object with id field)
- * if (Schema.is(Type.Obj)(unknownValue)) { ... }
+ * TypeScript type for an ECHO object type — a `Type.Type<A>` entity.
  *
- * // ECHO instance type guard (checks KindId brand)
- * if (Obj.isObject(unknownValue)) { ... }
+ * `T` is the instance type produced by `Obj.make(Foo, props)`. `Fields` is
+ * retained as a structural hint (the runtime value still carries `.fields`),
+ * but consumers should derive instance/encoded types via `Type.InstanceType`.
  *
- * // Reference to any object type
- * const Collection = Schema.Struct({
- *   objects: Schema.Array(Type.Ref(Type.Obj)),
- * }).pipe(Type.object({ typename: 'Collection', version: '0.1.0' }));
- * ```
- */
-export declare const Obj: ObjSchemaType;
-/**
- * TypeScript type for an ECHO object schema.
- * `T` is the instance type produced by the schema.
- * `Fields` is the optional struct fields type for introspection.
+ * **Not a `Schema.Schema`.** `Foo.ast` / `Schema.Schema.Type<typeof Foo>` /
+ * `Schema.extend(Foo)` no longer typecheck — extract the Effect Schema via
+ * `Type.getSchema(Foo)` first, or derive instance types via
+ * `Type.InstanceType<typeof Foo>`.
  *
  * @example
  * ```ts
- * const PersonSchema: Type.Obj<Person> = Schema.Struct({
+ * const Person = Schema.Struct({
  *   name: Schema.String,
- * }).pipe(Type.object({ typename: 'Person', version: '0.1.0' }));
+ * }).pipe(Type.makeObject(DXN.make('com.example.type.person', '0.1.0')));
  *
- * // Access fields for introspection:
- * Object.keys(PersonSchema.fields); // ['name']
+ * type Person = Type.InstanceType<typeof Person>;
  * ```
  */
-export interface Obj<T = any, Fields extends Schema.Struct.Fields = Schema.Struct.Fields> extends TypeMeta, EchoSchemaKind<EntityKind.Object>, Schema.AnnotableClass<Obj<T, Fields>, Entity$.OfKind<typeof Entity$.Kind.Object> & T, Schema.Simplify<ObjJsonProps & ToMutable<T>>, never> {
+export interface Obj<T, Fields extends Schema.Struct.Fields = Schema.Struct.Fields> extends BaseTypeEntity<T & EntityModule.OfKind<typeof EntityModule.Kind.Object>> {
+    /** Schema-kind brand (object). */
+    readonly [internal.SchemaKindId]: internal.EntityKind.Object;
+    /** Source Effect Schema — used internally by `Type.getSchema(self)`. */
+    readonly [internal.StaticTypeSchemaSlot]: Schema.Schema.AnyNoContext;
     /**
      * The fields defined in the original struct schema.
      * Allows accessing field definitions for introspection.
@@ -79,70 +66,78 @@ export interface Obj<T = any, Fields extends Schema.Struct.Fields = Schema.Struc
     readonly fields: Fields;
 }
 /**
- * Structural base type for any ECHO object schema.
- * Accepts both static schemas (created with Type.object()) and EchoSchema.
- * NOTE: Does not include the brand symbol to avoid TS4053 declaration portability issues.
- * Use Type.isObjectSchema() for runtime type guards.
+ * Type that represents any ECHO object type — a `Type.Type` entity branded
+ * with the object entity kind, i.e. what `Type.makeObject(dxn)` produces.
  */
-type ObjectSchemaBase = Schema.Schema.AnyNoContext & {
-    readonly typename: string;
-    readonly version: string;
-};
-export declare namespace Obj {
-    /**
-     * Type that represents any ECHO object schema.
-     * Accepts both static schemas (Type.object()) and mutable schemas (EchoSchema).
-     */
-    type Any = ObjectSchemaBase;
-}
+export type AnyObj = Obj<unknown>;
 /**
- * Factory function to create an ECHO object schema.
- * Adds object metadata annotations to an Effect schema.
+ * Factory function to create an ECHO object type.
+ *
+ * Returns a `Type.Type` entity — a live, in-memory `TypeSchema` instance,
+ * NOT a `Schema.Schema`. Use `Type.InstanceType<typeof Foo>` for the instance
+ * type and `Type.getSchema(Foo)` to obtain the underlying Effect Schema.
  *
  * @example
  * ```ts
  * const Person = Schema.Struct({
  *   name: Schema.String,
- * }).pipe(Type.object({ typename: 'example.com/type/Person', version: '0.1.0' }));
+ * }).pipe(Type.makeObject(DXN.make('com.example.type.person', '0.1.0')));
  * ```
  */
-export declare const object: {
-    (opts: TypeMeta): <Self extends Schema.Schema.Any>(self: Self) => Obj<Schema.Schema.Type<Self>>;
+export declare const makeObject: {
+    (dxn: DXN.DXN): <Self extends Schema.Schema.Any>(self: Self) => Obj<Schema.Schema.Type<Self>>;
 };
-export declare const PersistentType: Obj<PersistentSchema>;
-export interface PersistentType extends Schema.Schema.Type<typeof PersistentType> {
-}
-export { EchoSchema as RuntimeType };
-type RelationSchemaType = Schema.Schema<{
-    id: ObjectId;
-} & Record<string, unknown>, {
-    id: string;
-} & Record<string, unknown>> & EchoSchemaKind<EntityKind.Relation> & TypeMeta;
-/**
- * Runtime Effect schema for any ECHO relation.
- * Use for validation, parsing, or as a reference target for collections.
- * A relation has `id`, source, and target fields plus any additional properties.
- *
- * NOTE: `Schema.is(Type.Relation)` does STRUCTURAL validation only (checks for `id` field).
- * Use `Relation.isRelation()` for proper ECHO instance type guards that check the KindId brand.
+/**
+ * ECHO meta-schema entity — stores `{ name?, typename, version, jsonSchema }`.
+ * Type-kind sibling of `Type.makeObject(...)` / `Type.makeRelation(...)` outputs.
+ * Stored types live under this entity; filter via `Filter.type(Type.Type)`.
+ */
+export declare const Type: Type<typeInternal.TypeSchema>;
+/**
+ * Common props shared by the type-kind factories. Typename and version are
+ * optional — drafts omit typename and default version to {@link DRAFT_VERSION}.
+ */
+type MakeTypeProps = {
+    jsonSchema: internal.JsonSchemaType;
+    typename?: string;
+    version?: string;
+    name?: string;
+    id?: ObjectId;
+};
+/**
+ * Construct a new object-kind type entity from raw metadata — for cases where
+ * an Effect Schema isn't available (e.g. JSON-Schema arriving over the network
+ * or from a UI editor). Parallel to {@link makeObject} but takes pre-built
+ * `jsonSchema` instead of piping through an Effect schema.
  *
- * @example
- * ```ts
- * // Structural type guard (accepts any object with id field)
- * if (Schema.is(Type.Relation)(unknownValue)) { ... }
+ * The returned entity is in-memory; persist it with `db.add(entity)`.
+ */
+export declare const makeObjectFromJsonSchema: (props: MakeTypeProps) => Type<typeInternal.TypeSchema>;
+/**
+ * Construct a new relation-kind type entity from raw metadata. Parallel to
+ * {@link makeRelation} but takes pre-built `jsonSchema` instead of piping
+ * through an Effect schema. `source` / `target` accept either a static
+ * `Type.Obj` entity or the well-known `Obj.Unknown` schema.
  *
- * // ECHO instance type guard (checks KindId brand)
- * if (Relation.isRelation(unknownValue)) { ... }
- * ```
+ * The returned entity is in-memory; persist it with `db.add(entity)`.
  */
-export declare const Relation: RelationSchemaType;
+export declare const makeRelationFromJsonSchema: (props: MakeTypeProps & {
+    source: AnyObj | internal.UnknownTypeSchema<any, typeof EntityModule.Kind.Object>;
+    target: AnyObj | internal.UnknownTypeSchema<any, typeof EntityModule.Kind.Object>;
+}) => Type<typeInternal.TypeSchema>;
 /**
- * TypeScript type for an ECHO relation schema.
- * `T` is the instance type produced by the schema (excluding source/target).
- * `Source` and `Target` are the endpoint types.
- * `Fields` is the optional struct fields type for introspection.
+ * TypeScript type for an ECHO relation type — a `Type.Type<A>` entity.
+ *
+ * `T` is the instance-property type produced by `Relation.make(...)` (excluding
+ * source/target endpoints). `Source` and `Target` are the endpoint types.
+ *
+ * **Not a `Schema.Schema`.** See {@link Obj}'s note.
  */
-export interface Relation<T = any, Source = any, Target = any, Fields extends Schema.Struct.Fields = Schema.Struct.Fields> extends TypeMeta, EchoSchemaKind<EntityKind.Relation>, Schema.AnnotableClass<Relation<T, Source, Target, Fields>, Entity$.OfKind<typeof Entity$.Kind.Relation> & Relation.Endpoints<Source, Target> & T, Schema.Simplify<RelationJsonProps & ToMutable<T>>, never> {
+export interface Relation<T, Source, Target, Fields extends Schema.Struct.Fields = Schema.Struct.Fields> extends BaseTypeEntity<RelationModule.Endpoints<Source, Target> & T & EntityModule.OfKind<typeof EntityModule.Kind.Relation>> {
+    /** Schema-kind brand (relation). */
+    readonly [internal.SchemaKindId]: internal.EntityKind.Relation;
+    /** Source Effect Schema — used internally by `Type.getSchema(self)`. */
+    readonly [internal.StaticTypeSchemaSlot]: Schema.Schema.AnyNoContext;
     /**
      * The fields defined in the original struct schema.
      * Allows accessing field definitions for introspection.
@@ -150,34 +145,10 @@ export interface Relation<T = any, Source = any, Target = any, Fields extends Sc
     readonly fields: Fields;
 }
 /**
- * Structural base type for any ECHO relation schema.
- * Accepts static schemas (created with Type.relation()).
- * NOTE: Does not include the brand symbol to avoid TS4053 declaration portability issues.
- * Use Type.isRelationSchema() for runtime type guards.
+ * Type that represents any ECHO relation type — a `Type.Type` entity branded
+ * with the relation entity kind, i.e. what `Type.makeRelation(...)` produces.
  */
-type RelationSchemaBase = Schema.Schema.AnyNoContext & {
-    readonly typename: string;
-    readonly version: string;
-};
-export declare namespace Relation {
-    /**
-     * Type that represents any ECHO relation schema.
-     * Accepts static schemas (Type.relation()).
-     */
-    type Any = RelationSchemaBase;
-    /**
-     * Get relation source type.
-     */
-    type Source<A> = A extends Relation.Endpoints<infer S, infer _T> ? S : never;
-    /**
-     * Get relation target type.
-     */
-    type Target<A> = A extends Relation.Endpoints<infer _S, infer T> ? T : never;
-    type Endpoints<Source, Target> = {
-        [Relation$.Source]: Source;
-        [Relation$.Target]: Target;
-    };
-}
+export type AnyRelation = Relation<unknown, unknown, unknown>;
 /**
  * Factory function to create an ECHO relation schema.
  * Adds relation metadata annotations to an Effect schema.
@@ -186,120 +157,268 @@ export declare namespace Relation {
  * ```ts
  * const WorksFor = Schema.Struct({
  *   role: Schema.String,
- * }).pipe(Type.relation({
- *   typename: 'example.com/type/WorksFor',
- *   version: '0.1.0',
+ * }).pipe(Type.makeRelation({
+ *   dxn: DXN.make('com.example.type.worksFor', '0.1.0'),
  *   source: Person,
  *   target: Company,
  * }));
  * ```
  */
-export declare const relation: {
-    <SourceSchema extends Schema.Schema.AnyNoContext, TargetSchema extends Schema.Schema.AnyNoContext>(opts: EchoRelationSchemaOptions<SourceSchema, TargetSchema>): <Self extends Schema.Schema.Any>(self: Self) => Relation<Schema.Schema.Type<Self>, Schema.Schema.Type<SourceSchema>, Schema.Schema.Type<TargetSchema>>;
+export declare const makeRelation: {
+    <SourceInstance, TargetInstance>(opts: {
+        dxn: DXN.DXN;
+        source: Obj<SourceInstance, any> | internal.UnknownTypeSchema<SourceInstance, typeof EntityModule.Kind.Object>;
+        target: Obj<TargetInstance, any> | internal.UnknownTypeSchema<TargetInstance, typeof EntityModule.Kind.Object>;
+    }): <Self extends Schema.Schema.Any>(self: Self) => Relation<Schema.Schema.Type<Self>, SourceInstance & EntityModule.OfKind<typeof EntityModule.Kind.Object>, TargetInstance & EntityModule.OfKind<typeof EntityModule.Kind.Object>>;
 };
-export declare namespace Entity {
-    /**
-     * Runtime Effect schema for any ECHO entity (object or relation).
-     * Use for validation, parsing, or type guards on unknown values.
-     *
-     * @example
-     * ```ts
-     * if (Schema.is(Type.Entity.Any)(unknownValue)) {
-     *   // unknownValue is an ECHO entity
-     * }
-     * ```
-     */
-    const Any: Schema.Schema<{
-        id: ObjectId;
-    } & Record<string, unknown>, {
-        id: string;
-    } & Record<string, unknown>>;
-    /**
-     * Type alias for any ECHO entity schema (object or relation).
-     * Use this in type annotations for schema parameters.
-     */
-    type Any = Obj.Any | Relation.Any;
-}
 /**
- * Type guard to check if a schema is an object schema.
- * NOTE: This checks SCHEMAS, not instances. Use Obj.isObject for instances.
+ * Type that represents any ECHO type-kind entity — a `Type.Type` meta-schema
+ * value (static `Type.Type` or a persisted draft from `db.add(...)`).
+ * Mirrors {@link AnyObj} / {@link AnyRelation} for the third sibling kind.
+ */
+export type AnyType = Type<unknown>;
+/**
+ * Any ECHO type-entity — one of the three sibling kinds: object-kind, relation-kind,
+ * or type-kind (the meta-schema). APIs that want "any ECHO type" use this union;
+ * the underlying Effect Schema is retrieved via `Type.getSchema`.
  */
-export declare const isObjectSchema: (schema: Entity.Any) => schema is Obj.Any;
+export type AnyEntity = AnyObj | AnyRelation | AnyType;
 /**
- * Type guard to check if a schema is a relation schema.
- * NOTE: This checks SCHEMAS, not instances. Use Relation.isRelation for instances.
+ * Type guard: narrows a `Type.AnyEntity` to an object-kind entity. Checks
+ * ENTITIES, not instances — use `Obj.isObject` for instances. Raw
+ * `Schema.Schema` values (including the branded `Obj.Unknown` companion)
+ * are intentionally not accepted; inspect their `TypeAnnotation` directly.
  */
-export declare const isRelationSchema: (schema: Entity.Any) => schema is Relation.Any;
+export declare const isObject: (entity: AnyEntity) => entity is AnyObj;
 /**
- * Return type of the `Ref` schema constructor.
+ * Type guard: narrows a `Type.AnyEntity` to a relation-kind entity. Checks
+ * ENTITIES, not instances — use `Relation.isRelation` for instances.
+ */
+export declare const isRelation: (entity: AnyEntity) => entity is AnyRelation;
+/**
+ * Type guard: narrows a `Type.AnyEntity` to the type-kind meta-schema
+ * (e.g. `Type.Type`). Mirrors {@link isObject} / {@link isRelation}.
+ */
+export declare const isTypeKindSchema: (entity: AnyEntity) => entity is Type;
+/**
+ * Narrow a `Type.AnyEntity` (e.g. one returned from `schemaRegistry.query(...)`)
+ * to `AnyObj`, throwing if it describes a relation or the type-kind
+ * meta-schema. Use at call sites that need to pass the value to `Obj.make`,
+ * `Filter.type`, or other object-only APIs.
+ */
+export declare const assertObject: (entity: AnyEntity) => AnyObj;
+/** Narrow a `Type.AnyEntity` to `AnyRelation`, throwing otherwise. */
+export declare const expectRelation: (entity: AnyEntity) => AnyRelation;
+/** Narrow a `Type.AnyEntity` to the `Type.Type` meta-schema, throwing otherwise. */
+export declare const expectTypeKind: (entity: AnyEntity) => Type;
+/**
+ * Type that represents any Ref schema (with unknown target type).
+ * This is a schema type, not an instance type.
+ */
+export type AnyRef = Schema.Schema<internal.Ref<any>, EncodedReference>;
+/**
+ * Returns the URI identifying a type entity. Always defined.
+ *
+ * - Static `Type.Obj` / `Type.Relation` → typename DXN (e.g. `dxn:com.example.type.person:0.1.0`).
+ * - Persisted `Type.Type` instance (has `id`) → local `EchoURI` (`echo:/<objectId>`).
+ * - In-memory `Type.Type` draft (has `id`, no typename) → local `EchoURI`.
  *
- * This typedef avoids `TS4023` error (name from external module cannot be used named).
- * See Effect's note on interface types.
+ * Only accepts `Type.AnyEntity` entities. Raw `Schema.Schema` values and the
+ * branded `Obj.Unknown` / `Relation.Unknown` schemas are intentionally not
+ * supported — use `internal.getSchemaURI` or the schema's typename annotation
+ * directly when working at the schema level.
  */
-export interface ref<TargetSchema extends Schema.Schema.Any> extends RefSchema<Schema.Schema.Type<TargetSchema>> {
-}
+export declare const getURI: (input: AnyEntity) => URI.URI;
 /**
- * Factory function to create a Ref schema for the given target schema.
- * Use this in schema definitions to declare reference fields.
+ * @returns The typename. Example: `com.example.type.person`.
  *
- * @example
- * ```ts
- * const Task = Schema.Struct({
- *   assignee: Type.Ref(Person),  // Creates a Ref schema
- * }).pipe(Type.object({ typename: 'Task', version: '0.1.0' }));
- * ```
+ * Persisted `Type.Type` entities carry typename in `ObjectMeta.key` (the
+ * canonical registry-provenance field); unnamed drafts fall back to the
+ * entity's object id so the helper always returns a string. Any `dxn:` or
+ * `echo:/` prefix is stripped — typename is a bare identifier, not a URI.
+ */
+export declare const getTypename: (input: AnyEntity) => string;
+/**
+ * Gets the version.
+ * @example 0.1.0
+ * @example 0.1.0-<heads> (in-database, versioned by automerge heads)
+ *
+ * The registry-provenance semver lives in `ObjectMeta.version`; unversioned
+ * drafts default to {@link DRAFT_VERSION} (`'0.0.0'`). In-database entities are
+ * additionally versioned by their automerge heads, which are exposed as the
+ * semver pre-release tag (`<semver>-<heads>`). In-memory declarations have no
+ * heads and surface the bare semver. Read the registry semver alone via
+ * `Type.getMeta(input).version`.
  */
-export declare const Ref: RefFn;
+export declare const getVersion: (input: AnyEntity) => string;
 /**
- * TypeScript type for a Ref schema.
- * This is the type of the SCHEMA itself, not the runtime ref instance.
- * For the instance type, use `Ref.Ref<T>` from the Ref module.
+ * Type predicate: true iff the value is any type-kind ECHO entity — a static
+ * `Type.Obj` / `Type.Relation` produced by `Type.makeObject` / `Type.makeRelation`, a
+ * static meta `Type.Type`, or a persisted `Type.Type` returned by the database.
  *
- * @example
- * ```ts
- * // Schema type annotation (rarely needed, usually inferred):
- * const refSchema: Type.Ref<Task> = Type.Ref(Task);
+ * All three branches stamp `[KindId] = Type`, so this is a single brand check.
+ * Use {@link isObject} / {@link isRelation} / {@link isTypeKindSchema}
+ * when you need to discriminate further; use {@link getDatabase} when you mean
+ * "is this a db-attached type" (vs. an in-memory declaration).
+ */
+export declare const isType: (value: unknown) => value is AnyEntity;
+/**
+ * Get the database the type entity belongs to, or `undefined` if it is an
+ * in-memory declaration (`Type.makeObject` / `Type.makeRelation` result) not
+ * yet attached to a database. Mirrors `Obj.getDatabase` / `Relation.getDatabase`.
  *
- * // Instance type annotation (use Ref.Ref instead):
- * const refInstance: Ref.Ref<Task> = Ref.make(task);
- * ```
+ * Database attachment is the canonical discriminator between in-memory and
+ * in-database type entities — both are live reactive `TypeSchema` instances and
+ * are otherwise indistinguishable.
  */
-export interface Ref<T> extends Schema.SchemaClass<Ref$<T>, EncodedReference> {
-}
-export declare namespace Ref {
-    /**
-     * Type that represents any Ref schema (with unknown target type).
-     * This is a schema type, not an instance type.
-     */
-    type Any = Schema.Schema<Ref$<any>, EncodedReference>;
+export declare const getDatabase: (input: AnyEntity) => Database.Database | undefined;
+/**
+ * Mutable meta type returned by `Type.getMeta` inside a `Type.update` callback.
+ * Mirrors `Obj.Meta` / `Relation.Meta` — `Type.Type` is an Entity like its
+ * siblings, so its meta is the same `ObjectMeta` record:
+ * `{ keys, tags?, key?, version? }`.
+ *
+ * `key` / `version` here are the canonical registry-provenance pair
+ * (typename + semver) on persisted Type.Type entities; they are absent on
+ * unnamed drafts. Use {@link getTypename} / {@link getVersion} when you want
+ * a non-`undefined` value with id / {@link DRAFT_VERSION} fallbacks.
+ */
+export type Meta = internal.Meta;
+/**
+ * Deeply read-only version of {@link Meta}.
+ * Prevents mutation at all nesting levels (e.g., `meta.keys.push()` is a TS error).
+ */
+export type ReadonlyMeta = internal.ReadonlyMeta;
+/**
+ * Returns the entity's `ObjectMeta`. Same semantics as `Obj.getMeta` /
+ * `Relation.getMeta` — `Type.Type` is an Entity and carries the canonical
+ * `ObjectMeta` directly. Returns mutable meta when passed a mutable type
+ * (inside a `Type.update` callback), read-only meta otherwise.
+ *
+ * For persisted Type entities, `meta.key` holds the typename and
+ * `meta.version` holds the semver. Use {@link getTypename} / {@link getVersion}
+ * if you want the helpers' id / {@link DRAFT_VERSION} fallbacks for drafts.
+ *
+ * Both persisted and in-memory type entities (`Type.makeObject` /
+ * `Type.makeRelation` results) carry their `ObjectMeta` via `[MetaId]`, so the
+ * lookup is uniform.
+ */
+export declare function getMeta(entity: internal.Mutable<AnyEntity>): Meta;
+export declare function getMeta(entity: Mutable): Meta;
+export declare function getMeta(entity: AnyEntity): ReadonlyMeta;
+/**
+ * String key used to phantom-carry the instance type produced by a `Type.Type`.
+ * Used by `Type.InstanceType<typeof Foo>` to recover the schema instance type
+ * since `Type.makeObject(dxn)` does not return a `Schema.Schema`.
+ *
+ * Re-exported from the internal types layer so both `Type.ts` and internal
+ * helpers (`makeObject`, `createObject`) reference the same phantom key.
+ */
+export declare const InstancePhantomId: "~@dxos/echo/Type.Instance";
+export type InstancePhantomId = internal.InstancePhantomId;
+/**
+ * Sibling of {@link Obj} / {@link Relation} for the third ECHO entity kind:
+ * **type-kind** entities (meta-schemas). The singleton {@link Type} const is
+ * the canonical example — it describes stored type definitions themselves.
+ *
+ * Not a `Schema.Schema`. Use `Type.getSchema(value)` to obtain the underlying
+ * Effect Schema and `Type.update(value, draft => ...)` to mutate.
+ *
+ * `A` is the instance-type phantom — what `Obj.make(value, ...)` would produce.
+ * Merged with the `Type` const value via TypeScript declaration merging.
+ */
+export interface Type<A = unknown> extends BaseTypeEntity<A & EntityModule.OfKind<typeof EntityModule.Kind.Type>> {
+    /** Schema-kind brand (type — the meta-schema kind). */
+    readonly [internal.SchemaKindId]: internal.EntityKind.Type;
+    /** Source Effect Schema — used internally by `Type.getSchema(self)`. */
+    readonly [internal.StaticTypeSchemaSlot]: Schema.Schema.AnyNoContext;
 }
 /**
- * Gets the full DXN of the schema.
- * Will include the version if it's a `type` DXN.
- * @example "dxn:example.com/type/Person:0.1.0"
- * @example "dxn:echo:SSSSSSSSSS:XXXXXXXXXXXXX"
+ * Instance type produced by a Type entity.
+ *
+ * Accepts ONLY {@link AnyEntity} inputs — `Type.Obj`, `Type.Relation`, or
+ * `Type.Type`. Raw Effect `Schema.Schema` values are rejected: for those, use
+ * `Schema.Schema.Type<typeof Foo>` directly. This separation keeps the type
+ * system honest about which values represent ECHO entities versus plain
+ * Effect schemas.
+ *
+ * Dispatches on the entity kind:
+ *  - `Relation<Props, S, T>` → `Endpoints<S,T> & Props & OfKind<Relation>`
+ *  - `Obj<A>`                → `A & OfKind<Object>`
+ *  - `Type<A>`               → `A & OfKind<Type>`
  */
-export declare const getDXN: (schema: Entity.Any) => DXN | undefined;
+export type InstanceType<T extends AnyEntity> = T extends Relation<infer Props, infer Source, infer Target, any> ? RelationModule.Endpoints<Source, Target> & Props & EntityModule.OfKind<typeof EntityModule.Kind.Relation> : T extends Obj<infer A, any> ? A & EntityModule.OfKind<typeof EntityModule.Kind.Object> : T extends Type<infer A> ? A & EntityModule.OfKind<typeof EntityModule.Kind.Type> : never;
 /**
- * @param schema - Schema to get the typename from.
- * @returns The typename of the schema. Example: `example.com/type/Person`.
+ * Returns the Effect Schema for a type entity.
+ *
+ * - For static `Type.Obj` / `Type.Relation` entities the source Effect Schema is
+ *   read from a hidden slot — these overloads preserve the instance type.
+ * - For `Type.Type` entities (the meta-schema kind) the schema is rebuilt from
+ *   `type.jsonSchema`; the instance type isn't statically knowable so the wide
+ *   `AnyEntity` overload widens to `Schema.Schema.AnyNoContext`.
+ *
+ * Always call this when you need to interact with the Effect Schema API
+ * (e.g. before passing to Effect.Schema functions). For ECHO-side APIs
+ * (`Obj.make`, `Filter.type`, `Ref`) pass the type entity directly.
+ *
+ * Only accepts `Type.AnyEntity` — raw `Schema.Schema` values can be used
+ * directly without unwrapping.
  */
-export declare const getTypename: (schema: Entity.Any) => string;
+export declare function getSchema<T extends AnyObj>(type: T): Schema.Schema<InstanceType<T>>;
+export declare function getSchema<T extends AnyRelation>(type: T): Schema.Schema<InstanceType<T>>;
+export declare function getSchema(type: AnyEntity): Schema.Schema.AnyNoContext;
 /**
- * Gets the version of the schema.
- * @example 0.1.0
+ * Mutable view of a `Type.Type` — the shape passed to the `Type.update` callback.
+ * Outside `Type.update`, `Type.Type` fields are read-only (both at the type level
+ * and at runtime — direct assignment throws). Use this to constrain mutation to
+ * the change context, analogous to `Obj.update(obj, (draft) => ...)`.
+ *
+ * NOTE: `typename` and `version` are intentionally absent — they live in
+ * `ObjectMeta` (`key` / `version` — the canonical registry-provenance pair).
+ * Read them via {@link getTypename} / {@link getVersion} / {@link getMeta};
+ * `typename` is treated as immutable on persisted entities.
+ *
+ * Unlike `Obj.update` — whose mutable view is inferred as `Mutable<A>` over the
+ * whole instance type because every data field is editable — a `Type.Type`
+ * exposes only `name` and `jsonSchema` for mutation. The rest of its shape
+ * (`id`, the `[KindId]` / `[SchemaKindId]` brands, and `typename` / `version`
+ * in meta) is immutable, so this view is declared explicitly rather than
+ * derived from `InstanceType<Type.Type>`.
+ */
+export interface Mutable {
+    name?: string;
+    jsonSchema: Types.DeepMutable<internal.JsonSchemaType>;
+}
+/**
+ * Perform mutations on a `Type.Type` within a change context.
+ *
+ * The callback receives a {@link Mutable} view of the type — direct mutation of
+ * a `Type.Type` outside `Type.update` throws at runtime, mirroring `Obj.update`.
+ * Delegates to the same automerge-transaction primitive `Obj.update(obj, cb)` uses.
+ */
+export declare const update: (type: AnyEntity, callback: (mutable: Mutable) => void) => void;
+/**
+ * Add fields to a persisted type's schema.
+ * @throws if the type is not persisted.
  */
-export declare const getVersion: (schema: Entity.Any) => string;
+export declare const addFields: (type: AnyEntity, fields: Schema.Struct.Fields) => void;
 /**
- * @returns True if the schema is mutable.
+ * Replace existing fields on a persisted type's schema.
+ * @throws if the type is not persisted.
  */
-export declare const isMutable: (schema: Schema.Schema.AnyNoContext) => schema is EchoSchema;
+export declare const updateFields: (type: AnyEntity, fields: Schema.Struct.Fields) => void;
 /**
- * ECHO type metadata.
+ * Rename a field on a persisted type's schema.
+ * @throws if the type is not persisted.
  */
-export type Meta = TypeAnnotation;
+export declare const updateFieldPropertyName: (type: Type, { before, after }: {
+    before: PropertyKey;
+    after: PropertyKey;
+}) => void;
 /**
- * Gets the meta data of the schema.
+ * Remove fields from a persisted type's schema.
+ * @throws if the type is not persisted.
  */
-export declare const getMeta: (schema: Entity.Any) => Meta | undefined;
+export declare const removeFields: (type: AnyEntity, fieldNames: string[]) => void;
+export {};
 //# sourceMappingURL=Type.d.ts.map