@dxos/compute 0.9.1-staging.ee54ba693a → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/compute",
-  "version": "0.9.1-staging.ee54ba693a",
+  "version": "0.11.0",
   "description": "Umbrella package for AI-aware DXOS compute primitives.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -16,22 +16,22 @@
     ".": {
       "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
-      "default": "./dist/lib/neutral/index.mjs"
+      "import": "./dist/lib/index.mjs"
     },
     "./AgentService": {
       "source": "./src/AgentService.ts",
       "types": "./dist/types/src/AgentService.d.ts",
-      "default": "./dist/lib/neutral/AgentService.mjs"
+      "import": "./dist/lib/AgentService.mjs"
     },
     "./StorageService": {
       "source": "./src/StorageService.ts",
       "types": "./dist/types/src/StorageService.d.ts",
-      "default": "./dist/lib/neutral/StorageService.mjs"
+      "import": "./dist/lib/StorageService.mjs"
     },
     "./testing": {
       "source": "./src/testing/index.ts",
       "types": "./dist/types/src/testing/index.d.ts",
-      "default": "./dist/lib/neutral/testing/index.mjs"
+      "import": "./dist/lib/testing.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
@@ -43,21 +43,22 @@
     "@effect-atom/atom": "^0.5.3",
     "@effect/platform": "0.96.2",
     "@effect/rpc": "0.75.1",
-    "@dxos/ai": "0.9.1-staging.ee54ba693a",
-    "@dxos/echo": "0.9.1-staging.ee54ba693a",
-    "@dxos/effect": "0.9.1-staging.ee54ba693a",
-    "@dxos/invariant": "0.9.1-staging.ee54ba693a",
-    "@dxos/keys": "0.9.1-staging.ee54ba693a",
-    "@dxos/errors": "0.9.1-staging.ee54ba693a",
-    "@dxos/log": "0.9.1-staging.ee54ba693a",
-    "@dxos/vendor-kbn-handlebars": "0.9.1-staging.ee54ba693a",
-    "@dxos/schema": "0.9.1-staging.ee54ba693a",
-    "@dxos/protocols": "0.9.1-staging.ee54ba693a"
+    "@dxos/ai": "0.11.0",
+    "@dxos/echo": "0.11.0",
+    "@dxos/effect": "0.11.0",
+    "@dxos/errors": "0.11.0",
+    "@dxos/invariant": "0.11.0",
+    "@dxos/keys": "0.11.0",
+    "@dxos/log": "0.11.0",
+    "@dxos/protocols": "0.11.0",
+    "@dxos/schema": "0.11.0",
+    "@dxos/types": "0.11.0",
+    "@dxos/vendor-kbn-handlebars": "0.11.0"
   },
   "devDependencies": {
     "effect": "3.21.4",
-    "vitest": "4.1.8",
-    "@dxos/echo-client": "0.9.1-staging.ee54ba693a"
+    "vitest": "4.1.10",
+    "@dxos/echo-client": "0.11.0"
   },
   "peerDependencies": {
     "effect": "3.21.4"

package/src/AgentIdentity.ts

@@ -0,0 +1,35 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+
+/**
+ * Identity of the actor authoring content within an operation. Today this is an agent (see
+ * `assistant-toolkit` `Agent.did`); it attributes content the operation authors — e.g. the
+ * `creator` of a suggestion branch — so it reads as its own author, distinct from the human user
+ * and from other agents. Provided by the agent runtime for the duration of a tool/operation call.
+ */
+export interface Identity {
+  /** Identity DID (e.g. an agent's `did:halo:` DID). */
+  readonly did: string;
+  /** Optional display name. */
+  readonly name?: string;
+  /** Optional palette hue. */
+  readonly hue?: string;
+}
+
+export class AgentIdentity extends Context.Tag('@dxos/compute/AgentIdentity')<AgentIdentity, Identity>() {}
+
+/**
+ * The current author DID, or `undefined` when no {@link AgentIdentity} is in scope (e.g. a human-
+ * initiated invocation). Reads optionally, so an operation that defaults its author from the agent
+ * identity does not add a hard service requirement.
+ */
+export const currentDid: Effect.Effect<string | undefined> = Effect.serviceOption(AgentIdentity).pipe(
+  Effect.map(Option.match({ onNone: () => undefined, onSome: (identity) => identity.did })),
+);

package/src/AgentService.ts

@@ -10,8 +10,10 @@ import type * as Stream from 'effect/Stream';
 
 import type { Database, Feed, Obj, Ref } from '@dxos/echo';
 import { DXN } from '@dxos/keys';
+import type { ContentBlock } from '@dxos/types';
 
 import type * as Trace from './Trace';
+import { Instructions } from './types';
 
 /**
  * Service interface for the agent session manager.
@@ -52,9 +54,9 @@ export interface Session {
   addContext: (context: Ref.Ref<Obj.Unknown>[]) => Effect.Effect<void, never, Database.Service>;
 
   /**
-   * Submits a prompt to the agent.
+   * Submit a turn: a plain user prompt, or pre-built content blocks (e.g. synthetic context + prompt).
    */
-  submitPrompt: (prompt: string) => Effect.Effect<void>;
+  submitPrompt: (prompt: string | ContentBlock.Any[]) => Effect.Effect<void>;
 
   /**
    * Wait until agent has completed its work.
@@ -87,4 +89,10 @@ export interface GetSessionOptions {
   // the model into the agent process — the id alone does not identify a resolver.
   readonly provider?: DXN.DXN;
   readonly systemPrompt?: string;
+  /**
+   * Instructions steering the conversation (typically the Chat's `instructions` ref), persisted as a
+   * spawn annotation so a re-hydrated process recovers it. Read at spawn only: repointing requires a
+   * process restart (same staleness model as `model`/`provider`).
+   */
+  readonly instructions?: Ref.Ref<Instructions.Instructions>;
 }

package/src/Cancellation.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+
+/**
+ * Cooperative cancellation of the current operation run. The runtime that owns execution provides
+ * the service and fires the signal when the run is cancelled — the EDGE worker on a client cancel
+ * request, the local process runtime on terminate. Operations observe it via {@link signal}.
+ */
+// Tags unify by key string: a version-skewed bundle carrying two `@dxos/compute` instances (e.g. an
+// EDGE worker whose provider and handlers resolve different copies) must still share this service,
+// so the key must never change.
+export class Service extends Context.Tag('@dxos/compute/Cancellation')<Service, { readonly signal: AbortSignal }>() {}
+
+/**
+ * The current run's cancellation signal — e.g. for `Pipeline.abortWith` or `fetch`. Never fires when
+ * the runtime provided no cancellation channel.
+ */
+// A fresh signal per access: a shared never-firing singleton would accumulate listeners across runs.
+export const signal: Effect.Effect<AbortSignal> = Effect.serviceOption(Service).pipe(
+  Effect.map(
+    Option.match({
+      onNone: () => new AbortController().signal,
+      onSome: (service) => service.signal,
+    }),
+  ),
+);

package/src/Credential.ts

@@ -6,10 +6,19 @@
 
 import * as Context from 'effect/Context';
 import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
 import * as Redacted from 'effect/Redacted';
 
+import { type SpaceId } from '@dxos/keys';
+
 export type CredentialQuery = {
   service?: string;
+  /**
+   * Look up one specific `AccessToken` object instead of any credential for a service. Required
+   * wherever a space can hold several connections to the same service, since a by-service lookup
+   * picks among them arbitrarily.
+   */
+  accessTokenId?: string;
 };
 
 // TODO(dmaretskyi): Unify with other apis.
@@ -24,6 +33,42 @@ export type ServiceCredential = {
   account?: string;
 };
 
+/**
+ * Source for credentials EDGE custodies rather than replicating into the space (those stored as
+ * `MANAGED_ACCESS_TOKEN`).
+ *
+ * An implementation detail of {@link CredentialsService}, not a consumer-facing service: it exists
+ * as a tag only because the two surfaces reach EDGE differently — clients over authenticated HTTP,
+ * functions over a space-bound service binding. Implementations cache; pass `refresh` to bypass that
+ * cache after an authorization failure.
+ */
+export class AccessTokenResolver extends Context.Tag('@dxos/functions/AccessTokenResolver')<
+  AccessTokenResolver,
+  {
+    resolve: (request: { spaceId: SpaceId; accessTokenId: string; refresh?: boolean }) => Promise<string>;
+  }
+>() {
+  static resolve = (request: {
+    spaceId: SpaceId;
+    accessTokenId: string;
+    refresh?: boolean;
+  }): Effect.Effect<string, never, AccessTokenResolver> =>
+    Effect.gen(function* () {
+      const resolver = yield* AccessTokenResolver;
+      return yield* Effect.promise(() => resolver.resolve(request));
+    });
+
+  /**
+   * Fails on every managed token. The default where EDGE is unreachable (tests, offline CLI runs):
+   * a managed credential genuinely cannot be resolved there, and failing says so.
+   */
+  static notAvailable = Layer.succeed(AccessTokenResolver, {
+    resolve: async ({ accessTokenId }) => {
+      throw new Error(`No access token resolver configured; cannot resolve managed token: ${accessTokenId}`);
+    },
+  });
+}
+
 export class CredentialsService extends Context.Tag('@dxos/functions/CredentialsService')<
   CredentialsService,
   {
@@ -54,3 +99,10 @@ export class CredentialsService extends Context.Tag('@dxos/functions/Credentials
       return Redacted.make(credential.apiKey);
     });
 }
+
+/**
+ * The credential's API key as a plain string — what a caller passing it to an HTTP client needs.
+ * Resolves a server-custodied value transparently, so callers never branch on where it came from.
+ */
+export const getApiKeyValue = (query: CredentialQuery): Effect.Effect<string, never, CredentialsService> =>
+  Effect.map(CredentialsService.getApiKey(query), Redacted.value);

package/src/Operation.ts

@@ -4,6 +4,7 @@
 
 // @import-as-namespace
 
+import * as Cause from 'effect/Cause';
 import * as Context from 'effect/Context';
 import * as Effect from 'effect/Effect';
 import * as Layer from 'effect/Layer';
@@ -16,7 +17,7 @@ import type * as Types from 'effect/Types';
 import { Annotation, DXN, JsonSchema, type Key, Migration, Obj, Ref, Type } from '@dxos/echo';
 import type { URI } from '@dxos/keys';
 
-import type { NoHandlerError } from './errors';
+import { type NoHandlerError, RunAgainError } from './errors';
 import type { Operation } from './index';
 
 /**
@@ -324,7 +325,7 @@ export class PersistentOperation extends Type.makeObject<PersistentOperation>(
 
     /**
      * List of required services.
-     * Match the Context.Tag keys of the FunctionServices variants.
+     * Match the Context.Tag keys of the services the operation handler declares.
      */
     services: Schema$.optional(Schema$.Array(Schema$.String)),
 
@@ -473,6 +474,30 @@ export const NotifyOptionsAnnotation = Annotation.make({
   schema: NotifyOptions,
 });
 
+/**
+ * A serializable reference to an operation invocation — the target operation's key plus its input.
+ * Describes a deferred/late-bound invocation that must survive a serialization boundary (e.g. riding
+ * on a process-failure error, or persisted) where a live {@link Definition} cannot. Resolve the key
+ * with `OperationHandlerSet.getHandlerByKey` and hand the result to the invoker. Carries no functions,
+ * so `input` must itself be serializable.
+ */
+export interface SerializedInvocation {
+  /** Target operation key as a URI (a DXN, e.g. `dxn:org.dxos.plugin.deck.operation.open`). */
+  readonly operation: URI.URI;
+  /** Input passed to the operation; must be serializable. */
+  readonly input?: unknown;
+}
+
+/**
+ * Builds a {@link SerializedInvocation} from a live {@link Definition} and its input — the serializable
+ * counterpart to a direct `invoke`, for describing an invocation that must cross a serialization
+ * boundary (e.g. a deferred toast action). Resolve it later with `OperationHandlerSet.getHandlerByKey`.
+ */
+export const prepare = <I, O>(operation: Definition<I, O>, input: I): SerializedInvocation => ({
+  operation: operation.meta.key,
+  input,
+});
+
 /**
  * Options for operation invocation.
  */
@@ -496,6 +521,12 @@ export interface InvokeOptions {
    * Optional process-runtime tracing metadata (consumed by `@dxos/functions-runtime` when wired).
    */
   tracing?: unknown;
+
+  /**
+   * Specifies the runtime environment for the operation.
+   * By default, the operation is executed on the local runtime.
+   */
+  on?: 'edge' | 'local';
 }
 
 /**
@@ -560,6 +591,57 @@ export const visible = annotate(VisibleAnnotation, true);
 export const isVisible = (op: PersistentOperation): boolean =>
   Option.getOrElse(Annotation.get(op, VisibleAnnotation), () => false);
 
+/**
+ * Projection marker for an operation exposed as an MCP tool to external agents.
+ * See plugin-projects `MILESTONE-5.md` §7.4 for the full contract.
+ */
+export const McpTool = Schema$.Struct({
+  /** Tool name as exposed to MCP clients; camelCase, domain-prefixed (e.g. `taskCreate`). */
+  name: Schema$.String,
+  /** Model-facing description; falls back to the operation's own description when absent. */
+  description: Schema$.optional(Schema$.String),
+  /**
+   * Safety class the server maps to MCP tool hints: `read` is side-effect free (readOnlyHint),
+   * `write` mutates space data, `destructive` deletes or is otherwise irreversible.
+   */
+  safety: Schema$.Literal('read', 'write', 'destructive'),
+  /** Aspect/toolset, for server-side filtering (e.g. `/mcp?toolsets=tasks`). */
+  aspect: Schema$.optional(Schema$.String),
+});
+export type McpTool = Schema$.Schema.Type<typeof McpTool>;
+
+/**
+ * Annotation that opts an operation into MCP projection. The annotation rides through
+ * {@link serialize} into the persisted record, so a remote projector (edge mcp-space-service)
+ * discovers tools from the operation registry rather than a hand-maintained table.
+ *
+ * Projected operations must be remotely invocable: refs (not live objects) in, JSON snapshots
+ * out, schemas that survive serialization, and worker-safe handlers — MILESTONE-5.md §7.4.
+ */
+export const McpToolAnnotation = Annotation.make({
+  id: 'org.dxos.operation.mcp-tool',
+  schema: McpTool,
+});
+
+/**
+ * Pipeable combinator that opts an operation into MCP projection. Apply at the definition site:
+ * `Operation.make({ ... }).pipe(Operation.mcpTool({ name: 'taskComplete', safety: 'write' }))`.
+ */
+export const mcpTool = (props: McpTool) => annotate(McpToolAnnotation, props);
+
+/**
+ * Returns the MCP projection descriptor when the operation is annotated for it, else undefined.
+ * Reads from the persisted operation — the form the projector holds.
+ */
+export const getMcpTool = (op: PersistentOperation): McpTool | undefined =>
+  Option.getOrUndefined(Annotation.get(op, McpToolAnnotation));
+
+/**
+ * Pipeable combinator that marks an operation idempotent — see {@link IdempotentAnnotation}. Apply at
+ * the definition site: `Operation.make({ ... }).pipe(Operation.idempotent)`.
+ */
+export const idempotent = annotate(IdempotentAnnotation, true);
+
 /**
  * Operation service interface - provides unified access to operation invocation and scheduling.
  * This service is automatically provided to operation handlers.
@@ -651,6 +733,14 @@ export const schedule = <I, O>(
     Effect.withSpan('Operation.schedule'),
   );
 
+/**
+ * Call inside an operation to stop the current invocation and have the system re-run it (e.g. a capped
+ * sync run with more work left). Surfaces as a {@link RunAgainError} defect; the trigger dispatcher
+ * re-queues the same event FIFO to continue. A caller invoking via `Operation.invoke` directly gets the
+ * defect and does not auto-continue.
+ */
+export const runAgain = (): Effect.Effect<never, void> => Effect.failCauseSync(() => Cause.die(new RunAgainError()));
+
 /**
  * Provides additional invocation options to all invocations.
  */

package/src/Process.ts

@@ -13,12 +13,14 @@ import type * as Exit from 'effect/Exit';
 import * as Option from 'effect/Option';
 import * as Schema from 'effect/Schema';
 import * as Scope from 'effect/Scope';
+import * as Stream from 'effect/Stream';
 import type * as Types from 'effect/Types';
 
 import { Annotation } from '@dxos/echo';
 import { assertArgument } from '@dxos/invariant';
 import { DXN, URI } from '@dxos/keys';
 import { log } from '@dxos/log';
+import type { SerializedError } from '@dxos/protocols';
 
 import * as Operation from './Operation';
 import * as OperationHandlerSet from './OperationHandlerSet';
@@ -171,6 +173,15 @@ export const NotifyAnnotation = Annotation.make({
   schema: Operation.NotifyOptions,
 });
 
+/**
+ * URI of the Instructions object steering the process's conversation. Persisted at spawn (like
+ * {@link TargetAnnotation}) so a re-hydrated process recovers its steering without reaching the Chat.
+ */
+export const InstructionsAnnotation = Annotation.make({
+  id: 'org.dxos.process.instructions',
+  schema: URI.Schema,
+});
+
 /**
  * Marks a process as the harness host for its conversation (discovery substrate).
  */
@@ -462,6 +473,12 @@ export interface Monitor {
    * Atom for the process tree.
    */
   processTreeAtom: Atom.Atom<readonly Info[]>;
+
+  /**
+   * Stream ephemeral trace messages matching `filter` (DX-1125), sourced from local in-process
+   * runtimes and remote runtimes broadcasting over the space swarm. Used to drive live progress UI.
+   */
+  subscribeToTraceMessages(filter: Trace.Filter): Stream.Stream<Trace.Message>;
 }
 
 export class ProcessMonitorService extends Context.Tag('@dxos/functions/ProcessMonitorService')<
@@ -491,10 +508,10 @@ export interface Info {
   readonly state: State;
 
   /**
-   * Error of the process.
-   * Only for process in FAILED state.
+   * How the process failed as a serializable {@link SerializedError} (its `context` carries any
+   * structured detail, e.g. a notify override), or `null` unless it is in FAILED state.
    */
-  readonly error: string | null;
+  readonly error: SerializedError | null;
 
   /**
    * UNIX timestamp in milliseconds.
@@ -579,7 +596,7 @@ export const prettyProcessTree = (tree: readonly Info[]): string => {
       parts.push(node.params.name);
     }
     if (node.error != null) {
-      parts.push(`(${node.error})`);
+      parts.push(`(${node.error.message ?? node.error.name ?? 'error'})`);
     }
     const { inputCount, outputCount, wallTime } = node.metrics;
     parts.push(`[in:${inputCount} out:${outputCount} wall:${Math.round(wallTime)}ms]`);

package/src/Trace.test.ts

@@ -0,0 +1,155 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { Ref } from '@dxos/echo';
+import { EID } from '@dxos/keys';
+
+import * as Trace from './Trace';
+
+// DX-1125: the swarm broadcast tag/filter/wire helpers. The tag format is a cross-repo contract —
+// the edge producer (functions-service) derives the same strings independently, so these lock it in.
+
+const message = (
+  meta: Trace.Meta,
+  events: { type: string; data?: unknown }[],
+  isEphemeral = true,
+): Pick<Trace.MessageData, 'meta' | 'events' | 'isEphemeral'> => ({
+  meta,
+  isEphemeral,
+  events: events.map((event) => ({ timestamp: 0, type: event.type, data: event.data ?? {} })),
+});
+
+describe('Trace.messageToTags', () => {
+  test('emits a type tag per event and a key:value tag per present meta field', ({ expect }) => {
+    const tags = Trace.messageToTags(
+      message(
+        {
+          pid: 'p1',
+          parentPid: 'p0',
+          space: 'SPACE1',
+          runtimeName: Trace.CommonRuntimeName.edgeIntrinsic,
+          toolCallId: 'tc1',
+        },
+        [{ type: 'status.update' }, { type: 'operation.input' }],
+      ),
+    );
+
+    expect(tags).toEqual(
+      expect.arrayContaining([
+        'type:status.update',
+        'type:operation.input',
+        'pid:p1',
+        'parentPid:p0',
+        'space:SPACE1',
+        `runtime:${Trace.CommonRuntimeName.edgeIntrinsic}`,
+        'toolCall:tc1',
+      ]),
+    );
+  });
+
+  test('omits absent meta fields', ({ expect }) => {
+    const tags = Trace.messageToTags(message({ pid: 'p1' }, [{ type: 'status.update' }]));
+    expect(tags).toEqual(['type:status.update', 'pid:p1']);
+  });
+});
+
+describe('Trace.matchesFilter', () => {
+  const msg = message({ pid: 'p1', space: 'SPACE1' }, [{ type: 'status.update' }]);
+
+  test('empty filter matches anything', ({ expect }) => {
+    expect(Trace.matchesFilter(msg, {})).toBe(true);
+  });
+
+  test('type matches when any event has the type', ({ expect }) => {
+    expect(Trace.matchesFilter(msg, { type: 'status.update' })).toBe(true);
+    expect(Trace.matchesFilter(msg, { type: 'operation.end' })).toBe(false);
+  });
+
+  test('ANDs all present fields', ({ expect }) => {
+    expect(Trace.matchesFilter(msg, { type: 'status.update', pid: 'p1', space: 'SPACE1' })).toBe(true);
+    // One mismatched dimension fails the whole filter.
+    expect(Trace.matchesFilter(msg, { type: 'status.update', pid: 'other' })).toBe(false);
+    expect(Trace.matchesFilter(msg, { space: 'SPACE2' })).toBe(false);
+  });
+});
+
+describe('Trace.subscriptionTagForFilter', () => {
+  test('picks the most selective present dimension', ({ expect }) => {
+    // Priority: conversation > trigger > parentPid > pid > space > type.
+    expect(Trace.subscriptionTagForFilter({ conversation: 'dxn:c', pid: 'p1', space: 's' })).toBe('conversation:dxn:c');
+    expect(Trace.subscriptionTagForFilter({ pid: 'p1', space: 's' })).toBe('pid:p1');
+    expect(Trace.subscriptionTagForFilter({ space: 's' })).toBe('space:s');
+    expect(Trace.subscriptionTagForFilter({ type: 'status.update' })).toBe('type:status.update');
+  });
+
+  test('returns undefined for an empty filter (matches nothing at the swarm)', ({ expect }) => {
+    expect(Trace.subscriptionTagForFilter({})).toBeUndefined();
+  });
+});
+
+describe('Trace.encodeTraceMessage / decodeTraceMessage', () => {
+  test('round-trips meta string fields, isEphemeral, and events', ({ expect }) => {
+    const original = message({ pid: 'p1', space: 'SPACE1', runtimeName: Trace.CommonRuntimeName.edgeIntrinsic }, [
+      { type: 'status.update', data: { message: 'Syncing', progress: { key: 'k1', current: 3, total: 10 } } },
+    ]);
+
+    const decoded = Trace.decodeTraceMessage(Trace.encodeTraceMessage(original));
+
+    expect(decoded.isEphemeral).toBe(true);
+    expect(decoded.meta.pid).toBe('p1');
+    expect(decoded.meta.space).toBe('SPACE1');
+    expect(decoded.meta.runtimeName).toBe(Trace.CommonRuntimeName.edgeIntrinsic);
+    expect(decoded.events).toHaveLength(1);
+    expect(decoded.events[0].type).toBe('status.update');
+    expect((decoded.events[0].data as any).progress.key).toBe('k1');
+    // The decoded value is a real Trace.Message and still matches its filter.
+    expect(Trace.matchesFilter(decoded, { type: 'status.update', space: 'SPACE1' })).toBe(true);
+  });
+
+  test('a decoded message re-derives the same tags the producer would emit', ({ expect }) => {
+    const original = message({ pid: 'p9', space: 'SPACE9' }, [{ type: 'status.update' }]);
+    const decoded = Trace.decodeTraceMessage(Trace.encodeTraceMessage(original));
+    expect(Trace.messageToTags(decoded)).toEqual(['type:status.update', 'pid:p9', 'space:SPACE9']);
+  });
+
+  // The wire payload deliberately drops ref meta fields (`trigger`) — they travel only as envelope
+  // tags. A consumer that needs the trigger (e.g. cancel addressing) must get it back at decode, or
+  // downstream guards silently no-op (the mailbox-sync cancel bug).
+  test('restores meta.trigger from the envelope tags the payload encoding drops', ({ expect }) => {
+    const trigger = Ref.fromURI(EID.make({ entityId: 'TRIGGER1' }));
+    const original = message({ pid: 'p1', space: 'SPACE1', trigger }, [{ type: 'status.update' }]);
+    const tags = Trace.messageToTags(original);
+
+    // The payload alone loses the trigger by design.
+    expect(Trace.decodeTraceMessage(Trace.encodeTraceMessage(original)).meta.trigger).toBeUndefined();
+
+    // The envelope tags restore it.
+    const decoded = Trace.decodeTraceMessage(Trace.encodeTraceMessage(original), tags);
+    expect(decoded.meta.trigger?.uri.toString()).toBe(trigger.uri.toString());
+    expect(Trace.matchesFilter(decoded, { trigger: trigger.uri.toString() })).toBe(true);
+  });
+
+  test('decode without a trigger tag leaves meta.trigger undefined', ({ expect }) => {
+    const original = message({ pid: 'p1', space: 'SPACE1' }, [{ type: 'status.update' }]);
+    const decoded = Trace.decodeTraceMessage(Trace.encodeTraceMessage(original), Trace.messageToTags(original));
+    expect(decoded.meta.trigger).toBeUndefined();
+  });
+
+  // `conversation` is the other ref the payload drops, and it is what `matchesFilter` compares — so a
+  // conversation-filtered subscription (the coarse tag `subscriptionTagForFilter` prefers) receives
+  // the broadcast and then discards it unless decode restores the ref.
+  test('restores meta.conversation from the envelope tags', ({ expect }) => {
+    const conversation = Ref.fromURI(EID.make({ entityId: 'CONVERSATION1' }));
+    const original = message({ pid: 'p1', space: 'SPACE1', conversation }, [{ type: 'status.update' }]);
+    const tags = Trace.messageToTags(original);
+
+    expect(Trace.decodeTraceMessage(Trace.encodeTraceMessage(original)).meta.conversation).toBeUndefined();
+
+    const decoded = Trace.decodeTraceMessage(Trace.encodeTraceMessage(original), tags);
+    expect(decoded.meta.conversation?.uri.toString()).toBe(conversation.uri.toString());
+    expect(Trace.matchesFilter(decoded, { conversation: conversation.uri.toString() })).toBe(true);
+  });
+});