@dxos/compute 0.10.0 → 0.11.1

package/src/Trace.ts

@@ -10,9 +10,10 @@ import * as Layer from 'effect/Layer';
 import * as Schema from 'effect/Schema';
 
 import { Annotation, DXN, Obj, Ref, Type } from '@dxos/echo';
+import { EID } from '@dxos/keys';
 import { log } from '@dxos/log';
 
-import * as Trigger from './Trigger';
+import * as Trigger from './types/Trigger';
 
 /**
  * Writes ephemeral or persistent events to the trace.
@@ -70,6 +71,7 @@ export const Event = Schema.Struct({
   data: Schema.Unknown, // Type-specific payload;
 });
 export type Event = Schema.Schema.Type<typeof Event>;
+
 /**
  * Checks if an event is of a given type.
  */
@@ -132,6 +134,7 @@ export const Meta = Schema.Struct({
   runtimeName: Schema.optional(RuntimeName),
 });
 export type Meta = Schema.Schema.Type<typeof Meta>;
+
 /**
  * Checks if a runtime is an edge runtime.
  */
@@ -145,17 +148,18 @@ export const isEdgeRuntime = (name: RuntimeName): boolean =>
  */
 export const MessageData = Schema.Struct({
   meta: Meta,
-
   isEphemeral: Schema.Boolean,
   events: Schema.Array(Event),
 });
 export type MessageData = Schema.Schema.Type<typeof MessageData>;
+
 export class Message extends Type.makeObject<Message>(DXN.make('org.dxos.type.traceMessage', '0.1.0'))(
   MessageData.pipe(
     Annotation.IconAnnotation.set({ icon: 'ph--note--regular', hue: 'rose' }),
     Annotation.HiddenAnnotation.set(true),
   ),
 ) {}
+
 /**
  * Flattened representation of a signle event in a trace message.
  * Events are stored in batched messages for efficiency, but flat representation is more convenient for consumption.
@@ -176,6 +180,185 @@ export const flatten = (message: Message): FlatEvent[] => {
   }));
 };
 
+//
+// Swarm broadcast (DX-1125).
+//
+// Ephemeral trace messages produced on a remote runtime are broadcast over the space swarm and
+// projected into the client's progress UI. The publisher tags each message with a flat key:value list
+// derived from its meta; subscribers register a coarse tag (OR match at the swarm) and re-apply the
+// exact filter (AND) client-side.
+//
+
+/**
+ * `google.protobuf.Any` type URL for a trace message broadcast over the swarm.
+ */
+export const TRACE_MESSAGE_TYPE_URL = 'dxos.compute.TraceMessage';
+
+/**
+ * Declarative, serializable filter over trace messages. All present fields are ANDed. `type` matches
+ * against event types within the message; the rest match against {@link Meta} fields. Refs
+ * (`conversation`, `trigger`) are matched by their DXN string.
+ */
+export interface Filter {
+  readonly type?: string;
+  readonly pid?: string;
+  readonly parentPid?: string;
+  readonly conversation?: string;
+  readonly trigger?: string;
+  readonly space?: string;
+  readonly runtimeName?: string;
+  readonly toolCallId?: string;
+}
+
+/**
+ * Derive the flat broadcast tag list for a message (DX-1125). The publisher emits all applicable tags;
+ * subscribers match a subset (logical OR).
+ */
+export const messageToTags = (message: Pick<MessageData, 'meta' | 'events'>): string[] => {
+  const { meta } = message;
+  const tags: string[] = [];
+  for (const event of message.events) {
+    tags.push(`type:${event.type}`);
+  }
+  if (meta.pid) {
+    tags.push(`pid:${meta.pid}`);
+  }
+  if (meta.parentPid) {
+    tags.push(`parentPid:${meta.parentPid}`);
+  }
+  if (meta.conversation) {
+    tags.push(`conversation:${meta.conversation.uri.toString()}`);
+  }
+  if (meta.trigger) {
+    tags.push(`trigger:${meta.trigger.uri.toString()}`);
+  }
+  if (meta.space) {
+    tags.push(`space:${meta.space}`);
+  }
+  if (meta.runtimeName) {
+    tags.push(`runtime:${meta.runtimeName}`);
+  }
+  if (meta.toolCallId) {
+    tags.push(`toolCall:${meta.toolCallId}`);
+  }
+  return tags;
+};
+
+/**
+ * Pick the coarse subscription tag for a filter (DX-1125). The swarm cuts traffic to a superset of the
+ * filter using its most selective present dimension; the client re-applies the exact filter.
+ */
+export const subscriptionTagForFilter = (filter: Filter): string | undefined => {
+  if (filter.conversation !== undefined) {
+    return `conversation:${filter.conversation}`;
+  }
+  if (filter.trigger !== undefined) {
+    return `trigger:${filter.trigger}`;
+  }
+  if (filter.parentPid !== undefined) {
+    return `parentPid:${filter.parentPid}`;
+  }
+  if (filter.pid !== undefined) {
+    return `pid:${filter.pid}`;
+  }
+  if (filter.space !== undefined) {
+    return `space:${filter.space}`;
+  }
+  if (filter.type !== undefined) {
+    return `type:${filter.type}`;
+  }
+  return undefined;
+};
+
+/**
+ * Exact (AND) filter match applied client-side after the coarse swarm subscription.
+ */
+export const matchesFilter = (message: Pick<MessageData, 'meta' | 'events'>, filter: Filter): boolean => {
+  const { meta } = message;
+  if (filter.type !== undefined && !message.events.some((event) => event.type === filter.type)) {
+    return false;
+  }
+  if (filter.pid !== undefined && meta.pid !== filter.pid) {
+    return false;
+  }
+  if (filter.parentPid !== undefined && meta.parentPid !== filter.parentPid) {
+    return false;
+  }
+  if (filter.conversation !== undefined && meta.conversation?.uri.toString() !== filter.conversation) {
+    return false;
+  }
+  if (filter.trigger !== undefined && meta.trigger?.uri.toString() !== filter.trigger) {
+    return false;
+  }
+  if (filter.space !== undefined && meta.space !== filter.space) {
+    return false;
+  }
+  if (filter.runtimeName !== undefined && meta.runtimeName !== filter.runtimeName) {
+    return false;
+  }
+  if (filter.toolCallId !== undefined && meta.toolCallId !== filter.toolCallId) {
+    return false;
+  }
+  return true;
+};
+
+/**
+ * Wire-safe subset of {@link Meta} for broadcast. Ref fields (`conversation`, `trigger`) are not
+ * carried in the payload — they are represented only as envelope tags — so the decoded message never
+ * attempts ref resolution on the consumer.
+ */
+const encodeMetaForWire = (meta: Meta): Meta => ({
+  pid: meta.pid,
+  parentPid: meta.parentPid,
+  processName: meta.processName,
+  space: meta.space,
+  toolCallId: meta.toolCallId,
+  runtimeName: meta.runtimeName,
+});
+
+/**
+ * Encode a trace message for the broadcast envelope's `google.protobuf.Any.value` (DX-1125).
+ * The wire format is UTF-8 JSON of the message data (ref fields dropped — see {@link encodeMetaForWire}).
+ */
+export const encodeTraceMessage = (message: Pick<MessageData, 'meta' | 'isEphemeral' | 'events'>): Uint8Array =>
+  new TextEncoder().encode(
+    JSON.stringify({
+      meta: encodeMetaForWire(message.meta),
+      isEphemeral: message.isEphemeral,
+      events: message.events,
+    }),
+  );
+
+/**
+ * Decode a broadcast trace message back into a {@link Message} object (DX-1125). The wire payload
+ * drops both ref meta fields (see {@link encodeMetaForWire}), so `tags` — the broadcast envelope's
+ * tag list — is required to restore them: `trigger` addresses work for cancellation, and
+ * `conversation` is what {@link matchesFilter} compares, so a subscription filtered by it matches
+ * nothing without this. Restored refs are address-only (`.uri`); they are never resolved.
+ */
+export const decodeTraceMessage = (bytes: Uint8Array, tags?: readonly string[]): Message => {
+  const parsed = JSON.parse(new TextDecoder().decode(bytes)) as Partial<MessageData>;
+  const meta = parsed.meta ?? {};
+  const conversation = meta.conversation ?? refFromTags<Obj.Unknown>(tags, 'conversation:');
+  const trigger = meta.trigger ?? refFromTags<Trigger.Trigger>(tags, 'trigger:');
+  return Obj.make(Message, {
+    meta: {
+      ...meta,
+      ...(conversation ? { conversation } : {}),
+      ...(trigger ? { trigger } : {}),
+    },
+    isEphemeral: parsed.isEphemeral ?? true,
+    events: parsed.events ?? [],
+  });
+};
+
+/** The ref carried on a broadcast envelope's `<prefix><uri>` tag, when present and parseable. */
+const refFromTags = <T>(tags: readonly string[] | undefined, prefix: string): Ref.Ref<T> | undefined => {
+  const uri = tags?.find((tag) => tag.startsWith(prefix))?.slice(prefix.length);
+  const eid = uri !== undefined ? EID.tryParse(uri) : undefined;
+  return eid !== undefined ? Ref.fromURI(eid) : undefined;
+};
+
 /**
  * Sink for complete trace messages.
  */
@@ -352,8 +535,24 @@ export const OperationOutput = EventType('operation.output', {
  */
 export const StatusUpdate = EventType('status.update', {
   schema: Schema.Struct({
-    /** Human-readable status message. */
-    message: Schema.String,
+    /** Human-readable status message.. */
+    message: Schema.optional(Schema.String),
+
+    progress: Schema.optional(
+      Schema.Struct({
+        /** Progress key. See {@link ProgressRegistry.key}. */
+        key: Schema.String,
+
+        /* Progress current item index. */
+        current: Schema.optional(Schema.Number),
+
+        /** Progress total item count. */
+        total: Schema.optional(Schema.Number),
+
+        /** Progress estimate of remaining time (ms). */
+        estimate: Schema.optional(Schema.Number),
+      }),
+    ),
   }),
   isEphemeral: true,
 });
@@ -361,5 +560,7 @@ export const StatusUpdate = EventType('status.update', {
 /**
  * Emit the current human-readable execution status to the trace.
  */
-export const emitStatus: (message: string) => Effect.Effect<void, never, TraceService> = (message) =>
-  write(StatusUpdate, { message });
+export const emitStatus: (
+  messageOrData: string | PayloadType<typeof StatusUpdate>,
+) => Effect.Effect<void, never, TraceService> = (message) =>
+  write(StatusUpdate, typeof message === 'string' ? { message } : message);

package/src/errors.ts

@@ -4,16 +4,20 @@
 
 import { BaseError, type BaseErrorOptions } from '@dxos/errors';
 
+/**
+ * Raised when a function wants to yield to the scheduler to not exceed platform limits.
+ * The scheduler will re-run the function after the yield.
+ * It is assumed that the function can be retried with the same input.
+ * The function might have produced side-effects on the first run.
+ */
+export class RunAgainError extends BaseError.extend('RunAgainError', 'Run again') {}
+
 // Errors from @dxos/operation.
 
 export class InvokerNotInitializedError extends BaseError.extend(
   'InvokerNotInitializedError',
   'Invoker not initialized',
-) {
-  constructor() {
-    super();
-  }
-}
+) {}
 
 export class NoHandlerError extends BaseError.extend('NoHandlerError', 'No handler found for operation. ') {
   constructor(operationKey: string) {

package/src/index.ts

@@ -3,12 +3,13 @@
 //
 
 export * from './errors';
+export * from './types';
 
+export * as AgentIdentity from './AgentIdentity';
 export * as AgentService from './AgentService';
-export * as Skill from './Skill';
+export * as Cancellation from './Cancellation';
 export * as Credential from './Credential';
 export * as Header from './Header';
-export * as Instructions from './Instructions';
 export * as LayerSpec from './LayerSpec';
 export * as McpServer from './McpServer';
 export * as Operation from './Operation';
@@ -16,10 +17,6 @@ export * as OperationHandlerSet from './OperationHandlerSet';
 export * as OperationRegistry from './OperationRegistry';
 export * as Process from './Process';
 export * as Runnable from './Runnable';
-export * as Script from './Script';
 export * as ServiceResolver from './ServiceResolver';
 export * as StorageService from './StorageService';
-export * as Template from './Template';
 export * as Trace from './Trace';
-export * as Trigger from './Trigger';
-export * as TriggerEvent from './TriggerEvent';

package/src/testing/index.ts

@@ -8,6 +8,7 @@ export { Fibonacci, Reply, Sleep } from './definitions';
 export { default as FibonacciHandler } from './fib';
 export { default as ReplyHandler } from './reply';
 export { default as SleepHandler } from './sleep';
+export * from './operation';
 
 export const ExampleHandlers = OperationHandlerSet.lazy(
   () => import('./fib'),

package/src/testing/operation.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import * as Operation from '../Operation';
+
+const operationServiceStub: Operation.OperationService = {
+  invoke: () => Effect.die('operationServiceLayerNoop: invoke is not implemented.'),
+  schedule: () => Effect.die('operationServiceLayerNoop: schedule is not implemented.'),
+  invokePromise: () =>
+    Promise.resolve({ error: new Error('operationServiceLayerNoop: invokePromise is not implemented.') }),
+};
+
+/** Noop `Operation.Service` for tests that must satisfy the type without invoking it. */
+export const operationServiceLayerNoop: Layer.Layer<Operation.Service> = Layer.succeed(
+  Operation.Service,
+  operationServiceStub,
+);

package/src/types/Instructions.test.ts

@@ -0,0 +1,18 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import * as Instructions from './Instructions';
+
+describe('Instructions', () => {
+  test('commands round-trip through make', ({ expect }) => {
+    const instructions = Instructions.make({
+      name: 'test',
+      commands: [{ sentinel: '$track', description: 'Track a follow-up', prompt: 'Append the item to TASKS.md.' }],
+    });
+    expect(instructions.commands?.length).toBe(1);
+    expect(instructions.commands?.[0].sentinel).toBe('$track');
+  });
+});

package/src/{Instructions.ts → types/Instructions.ts}

@@ -11,6 +11,14 @@ import { Text } from '@dxos/schema';
 
 import * as Skill from './Skill';
 
+/** A sentinel command the model recognizes in chat (e.g. `$track <text>`). */
+export const Command = Schema.Struct({
+  sentinel: Schema.String.annotations({ description: 'Token that invokes the command (e.g. "$track").' }),
+  description: Schema.optional(Schema.String),
+  prompt: Schema.String.annotations({ description: 'What the model should do when the sentinel appears.' }),
+});
+export type Command = Schema.Schema.Type<typeof Command>;
+
 /**
  * Prompt-based operation.
  * May reference skills and additional context.
@@ -37,6 +45,8 @@ export class Instructions extends Type.makeObject<Instructions>(DXN.make('org.dx
      * executes a routine through the agent prompt, not only triggered automations.
      */
     objects: Schema.Array(Ref.Ref(Obj.Unknown)).pipe(Schema.annotations({ title: 'Objects' }), Schema.optional),
+    /** Sentinel commands available to chat sessions running with these instructions. */
+    commands: Schema.Array(Command).pipe(Schema.annotations({ title: 'Commands' }), Schema.optional),
   }).pipe(
     Annotation.LabelAnnotation.set(['name']),
     Annotation.IconAnnotation.set({ icon: 'ph--scroll--regular', hue: 'sky' }),
@@ -52,10 +62,20 @@ export type MakeProps = {
   text?: string;
   skills?: Ref.Ref<Skill.Skill>[];
   objects?: Ref.Ref<Obj.Unknown>[];
+  commands?: Command[];
 };
 
 /** Creates an Instructions object with an owned Markdown `text` body (parented so it cascades and deep-clones). */
-export const make = ({ name, description, input, output, text, skills = [], objects }: MakeProps): Instructions => {
+export const make = ({
+  name,
+  description,
+  input,
+  output,
+  text,
+  skills = [],
+  objects,
+  commands,
+}: MakeProps): Instructions => {
   const body = Text.make({ content: text ?? '' });
   const instructions = Obj.make(Instructions, {
     name,
@@ -65,6 +85,7 @@ export const make = ({ name, description, input, output, text, skills = [], obje
     text: Ref.make(body),
     skills,
     objects,
+    commands,
   });
   // The body is owned by the instructions: it cascade-deletes with it and is cloned alongside it under
   // `Obj.clone(..., { deep: 'parent' })`.

package/src/types/Project.test.ts

@@ -0,0 +1,52 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { describe, test } from 'vitest';
+
+import { DXN, Obj, Ref, Type, URI } from '@dxos/echo';
+
+import * as Instructions from './Instructions';
+import * as Project from './Project';
+
+// Stand-in `Obj.Unknown` type for context objects, mirroring the ad-hoc test types used in
+// `AiContext.test.ts` — no database needed since `Ref.make` inlines the target.
+const TestObject = Type.makeObject(DXN.make('org.dxos.type.testObject', '0.1.0'))(Schema.Struct({}));
+
+describe('Project', () => {
+  test('typename, version, and defaults', ({ expect }) => {
+    expect(Type.getTypename(Project.Project)).toBe('org.dxos.type.project');
+    expect(Type.getVersion(Project.Project)).toBe('0.3.0');
+    const project = Project.make({ name: 'test' });
+    expect(Obj.instanceOf(Project.Project, project)).toBe(true);
+    expect(project.routines).toEqual([]);
+  });
+
+  test('contextBindings exposes skills and objects, not the instructions object itself', ({ expect }) => {
+    const skillRef = Ref.fromURI(URI.make('dxn:echo:@:skill-1'));
+    const doc = Obj.make(TestObject, {});
+    const instructions = Instructions.make({ text: 'Test', skills: [skillRef], objects: [Ref.make(doc)] });
+    const project = Project.make({ name: 'test' });
+    Obj.setParent(instructions, project);
+    Obj.update(project, (project) => {
+      project.instructions = Ref.make(instructions);
+    });
+
+    const bindings = Project.contextBindings(project);
+    expect(bindings.skills.map((ref) => ref.uri)).toEqual([skillRef.uri]);
+    // Instructions text reaches the prompt via Chat.instructions, not a binding.
+    expect(bindings.objects.map((ref) => ref.uri)).toEqual([Ref.make(doc).uri]);
+  });
+
+  test('contextBindings returns empty bindings when instructions is unresolved', ({ expect }) => {
+    const project = Project.make({ name: 'test' });
+    Obj.update(project, (project) => {
+      project.instructions = Ref.fromURI(URI.make('dxn:echo:@:instructions-1'));
+    });
+
+    const bindings = Project.contextBindings(project);
+    expect(bindings.skills).toEqual([]);
+    expect(bindings.objects).toEqual([]);
+  });
+});

package/src/types/Project.ts

@@ -0,0 +1,99 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import { Annotation, Collection, DXN, Obj, Ref, Type } from '@dxos/echo';
+import { FormInlineAnnotation, LabelAnnotation } from '@dxos/echo/Annotation';
+import { Outline, TaskSet } from '@dxos/types';
+
+import * as Instructions from './Instructions';
+import * as Routine from './Routine';
+import type * as Skill from './Skill';
+
+/** Lightweight inline goal: per-item status and addressability without document ceremony. */
+export const Goal = Schema.Struct({
+  id: Schema.String,
+  text: Schema.String,
+  status: Schema.optional(Schema.Literal('open', 'met', 'dropped')),
+});
+
+export type Goal = Schema.Schema.Type<typeof Goal>;
+
+/**
+ * A user-facing container for interactive, long-running work: instructions (skills + commands),
+ * routines, artifacts, and AI chat sessions in project context. Successor to `Topic`.
+ * Chats and agents attach via relations/queries (assistant-toolkit depends on compute, so no typed refs here).
+ */
+export class Project extends Type.makeObject<Project>(DXN.make('org.dxos.type.project', '0.3.0'))(
+  Schema.Struct({
+    name: Schema.optional(Schema.String),
+    description: Schema.optional(Schema.String),
+
+    /** Owned agent instructions (created + parented at the plugin layer). */
+    instructions: Schema.optional(Ref.Ref(Instructions.Instructions).pipe(FormInlineAnnotation.set(true))),
+
+    /** Routines created within the scope of this project. */
+    routines: Schema.Array(Ref.Ref(Routine.Routine)),
+
+    /** Owned collection of artifacts (documents, outliners, tables, ...) managed by the project. */
+    artifacts: Schema.optional(Ref.Ref(Collection.Collection)),
+
+    /** What done means for this project. */
+    goals: Schema.optional(Schema.Array(Goal)),
+
+    /** Ad hoc markdown checklist — the scratch surface; project chats write into it. */
+    outline: Schema.optional(Ref.Ref(Outline.Outline)),
+
+    /** Owned (or adopted synced) task container; membership is the ECHO parent edge. */
+    taskSet: Schema.optional(Ref.Ref(TaskSet.TaskSet)),
+  }).pipe(
+    Schema.annotations({ title: 'Project' }),
+    LabelAnnotation.set(['name']),
+    Annotation.IconAnnotation.set({ icon: 'ph--stack--regular', hue: 'amber' }),
+  ),
+) {}
+
+/** Factory wrapper around `Obj.make` for {@link Project}. */
+export const make = (
+  props: Omit<Partial<Obj.MakeProps<typeof Project>>, 'routines'> & {
+    routines?: ReadonlyArray<Ref.Ref<Routine.Routine>>;
+  } = {},
+): Project => Obj.make(Project, { ...props, routines: props.routines ?? [] });
+
+/** Bindings a chat session should receive when running in a project's context. */
+export type ContextBindings = {
+  skills: Ref.Ref<Skill.Skill>[];
+  objects: Ref.Ref<Obj.Unknown>[];
+};
+
+/**
+ * Bindings a chat session should receive when running in this project's context: the instructions'
+ * skills and context objects. The instructions object itself is NOT bound — its text/commands reach
+ * the system prompt through the chat's `instructions` ref, and a bound Instructions object would
+ * render as an inert context stub. Requires the instructions ref to be resolved (`.target`);
+ * unresolved refs contribute nothing.
+ */
+export const contextBindings = (project: Project): ContextBindings => {
+  const instructionsRef = project.instructions;
+  // `.target` throws when the ref has neither an inlined target nor a resolver attached
+  // (e.g. an unresolved ref outside a database context); guard with `isAvailable` first.
+  if (!instructionsRef?.isAvailable) {
+    return { skills: [], objects: [] };
+  }
+
+  const instructions = instructionsRef.target;
+  if (!instructions) {
+    return { skills: [], objects: [] };
+  }
+
+  // Refs are kept as-is (never re-wrapped via `Ref.make`): bindings persist to the conversation feed,
+  // and re-wrapping would drop the registry DXN of skills that have no space-DB identity.
+  return {
+    skills: [...instructions.skills],
+    objects: [...(instructions.objects ?? [])],
+  };
+};

package/src/types/Routine.test.ts

@@ -0,0 +1,18 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { Obj, Type } from '@dxos/echo';
+
+import * as Routine from './Routine';
+
+describe('Routine', () => {
+  test('typename and factory', ({ expect }) => {
+    expect(Type.getTypename(Routine.Routine)).toBe('org.dxos.type.routine');
+    const routine = Routine.make({ name: 'test' });
+    expect(Obj.instanceOf(Routine.Routine, routine)).toBe(true);
+    expect(routine.triggers).toEqual([]);
+  });
+});

package/src/types/Routine.ts

@@ -0,0 +1,85 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import { Annotation, DXN, Obj, Ref, Type } from '@dxos/echo';
+import { LabelAnnotation } from '@dxos/echo/internal';
+
+import type * as Operation from '../Operation';
+import * as Runnable from '../Runnable';
+import * as Instructions from './Instructions';
+import * as Trigger from './Trigger';
+
+const Kinds = ['runnable', 'instructions'] as const;
+export const Kind = Schema.Literal(...Kinds);
+export type Kind = (typeof Kinds)[number];
+
+const RunnableSpec = Schema.Struct({
+  kind: Schema.Literal('runnable'),
+  runnable: Ref.Ref(Runnable.Runnable),
+});
+
+const InstructionsSpec = Schema.Struct({
+  kind: Schema.Literal('instructions'),
+  instructions: Ref.Ref(Instructions.Instructions),
+});
+
+const RoutineSpec = Schema.Union(RunnableSpec, InstructionsSpec);
+
+/**
+ * User-facing routine: a thin aggregate of an action (`runnable`) and the triggers that fire it.
+ * App-level only — EDGE stays unaware of it (triggers point directly at the runnable).
+ */
+export class Routine extends Type.makeObject<Routine>(DXN.make('org.dxos.type.routine', '0.2.0'))(
+  Schema.Struct({
+    name: Schema.String.pipe(Schema.optional),
+    description: Schema.String.pipe(Schema.optional),
+
+    /**
+     * The action to run: either an Operation (`spec.runnable`, bound directly) or the routine's own owned
+     * Instructions (`spec.instructions`). For an Operation action the trigger's `runnable` points at this
+     * Operation. For an Instructions action `spec.instructions` is the owned Instructions object (the operation
+     * is implicitly the static RunInstructions, so no separate operation ref is stored), and the trigger's
+     * `runnable` is RunInstructions with this instructions bound as its input.
+     */
+    // TODO(burdon): Change to Array? Or handle that case with a ComputeGraph runnable.
+    spec: RoutineSpec.pipe(Schema.optional),
+
+    /**
+     * Explicit membership, bi-directional with `trigger.runnable → runnable`. Required (not derived by query)
+     * because the runnable may be a shared registry operation referenced by multiple automations, which would
+     * conflate triggers. MVP enforces length <= 1.
+     */
+    triggers: Schema.Array(Ref.Ref(Trigger.Trigger)),
+  }).pipe(
+    LabelAnnotation.set(['name']),
+    Annotation.IconAnnotation.set({ icon: 'ph--lightning--regular', hue: 'amber' }),
+  ),
+) {}
+
+/** Returns true when value is a Routine object. */
+export const instanceOf = (value: unknown): value is Routine => Obj.instanceOf(Routine, value);
+
+/**
+ * The owned Instructions ref of an instructions-action routine, or undefined for an operation action.
+ * Classification is explicit in `spec.kind`, so this needs no `.target` dereference; callers resolve the ref
+ * reactively (`useObject`) or asynchronously (`Database.load`) as appropriate.
+ */
+export const instructionsRef = (routine: Pick<Routine, 'spec'>): Ref.Ref<Instructions.Instructions> | undefined =>
+  routine.spec?.kind === 'instructions' ? routine.spec.instructions : undefined;
+
+// Return type de-aliased to `Operation.PersistentOperation` (what `Runnable.Runnable` aliases) so this
+// exported symbol's declaration names it directly — the reference that lets `tsc` emit the module's
+// `.d.ts` (avoids TS2742) without keeping an otherwise-unused `Operation` import.
+/** The Operation (runnable) ref of an operation-action routine, or undefined for an instructions action. */
+export const runnableRef = (routine: Pick<Routine, 'spec'>): Ref.Ref<Operation.PersistentOperation> | undefined =>
+  routine.spec?.kind === 'runnable' ? routine.spec.runnable : undefined;
+
+/** Factory wrapper around `Obj.make` for {@link Routine}. Trigger wiring lives in plugin-routine (`makeRoutine`). */
+export const make = (
+  props: Omit<Obj.MakeProps<typeof Routine>, 'triggers'> & { triggers?: ReadonlyArray<Ref.Ref<Trigger.Trigger>> },
+): Routine => Obj.make(Routine, { ...props, triggers: props.triggers ?? [] });