Domain

--- title: Domain description: Domain DSL, schema composition, and context generation. ---

Domain

This section documents the domain system from @ekairos/domain.

Goals

• Make domain schemas first class.
• Compose subdomains safely with typed links.
• Provide a context representation for AI prompts.
• Load narrative documentation from DOMAIN.md.

Domain DSL

The core entrypoint is domain().

Example:

import { i } from "@instantdb/core";
import { domain } from "@ekairos/domain";

const appDomain = domain("app")
  .includes(otherDomain)
  .schema({
    entities: {
      project: i.entity({
        name: i.string().indexed(),
        status: i.string().optional(),
      }),
    },
    links: {
      project_owner: {
        forward: { on: "project", has: "one", label: "owner" },
        reverse: { on: "$users", has: "many", label: "projects" },
      },
    },
    rooms: {},
  });

Schema generation

• domain().schema() returns a DomainSchemaResult.
• DomainSchemaResult.toInstantSchema() returns the InstantDB schema.

Context generation

• domain().schema().context() produces a structured object.
• domain().schema().contextString() produces a prompt friendly string.
• Both may include DOMAIN.md narrative content if available.

DOMAIN.md loading

The runtime automatically reads DOMAIN.md from: 1) The app root (process.cwd()/DOMAIN.md) for the root domain. 2) An explicit rootDir when provided by the domain. 3) The package root for packageName or inferred @ekairos/<name>.

This is done by @ekairos/domain/runtime using a DomainDocLoader configured at startup.

Runtime config

The domain runtime is configured via:

import { configureRuntime } from "@ekairos/domain/runtime";

configureRuntime({
  domain: {
    domain: appDomain,
  },
  runtime: async (env, domain) => {
    // return { db } for this env + domain
  },
  threads: [],
});

Domain endpoint

When using withRuntime, a domain endpoint is generated at:

• /.well-known/ekairos/v1/domain

See runtime-and-apis.md for request/response details.