@dxos/pipeline-transcription 0.0.0

package/src/dispatch.test.ts

@@ -0,0 +1,37 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { afterEach, beforeEach, describe, test } from 'vitest';
+
+import { Feed, Ref } from '@dxos/echo';
+import { EchoTestBuilder } from '@dxos/echo-client/testing';
+import { EffectEx } from '@dxos/effect';
+import { type ContentBlock, Transcript } from '@dxos/types';
+
+import { makeEchoCommit } from './dispatch';
+import { StageWrite } from './Stage';
+
+describe('makeEchoCommit', () => {
+  let builder: EchoTestBuilder;
+  beforeEach(async () => {
+    builder = await new EchoTestBuilder().open();
+  });
+  afterEach(async () => {
+    await builder.close();
+  });
+
+  test('applies block patches to the window and summary to the transcript', async ({ expect }) => {
+    const { db } = await builder.createDatabase({ types: [Transcript.Transcript, Feed.Feed] });
+    const feed = db.add(Feed.make());
+    const transcript = db.add(Transcript.make(Ref.make(feed)));
+    const commit = makeEchoCommit(transcript);
+
+    const block: ContentBlock.Transcript = { _tag: 'transcript', started: 's', text: 'hi there' };
+    await EffectEx.runPromise(commit(StageWrite.blocks([{ index: 0, corrected: 'Hi there.' }]), [block]));
+    expect(block.corrected).toEqual('Hi there.');
+
+    await EffectEx.runPromise(commit(StageWrite.transcript({ summary: 'A short summary.' }), []));
+    expect(transcript.summary).toEqual('A short summary.');
+  });
+});

package/src/dispatch.ts

@@ -0,0 +1,56 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Obj } from '@dxos/echo';
+import { type ContentBlock, type Transcript } from '@dxos/types';
+
+import { type CommitFn } from './PipelineRuntime';
+import { type StageWrite } from './Stage';
+
+/**
+ * In-memory commit sink: records every {@link StageWrite} for assertions and testbench rendering.
+ */
+export type CaptureCommit = {
+  readonly commit: CommitFn;
+  readonly writes: StageWrite[];
+};
+
+export const captureCommit = (): CaptureCommit => {
+  const writes: StageWrite[] = [];
+  const commit: CommitFn = (write) =>
+    Effect.sync(() => {
+      writes.push(write);
+    });
+  return { commit, writes };
+};
+
+/**
+ * ECHO commit: applies a stage's output to live objects. Block patches are applied to the block
+ * objects in the window slice the stage was invoked with (the runtime passes that slice); the
+ * transcript patch is applied to the `Transcript` object. Mutating a live ECHO object propagates
+ * via reactivity; a containing `Obj.update` transaction (when present) batches the writes.
+ */
+export const makeEchoCommit =
+  (transcript: Transcript.Transcript): CommitFn =>
+  (write, window) =>
+    Effect.sync(() => {
+      for (const update of write.blockUpdates ?? []) {
+        const block: ContentBlock.Transcript | undefined = window[update.index];
+        if (!block) {
+          continue;
+        }
+        const { index: _index, ...patch } = update;
+        // Live ECHO objects must be mutated inside Obj.update; plain blocks (testbench) assign directly.
+        if (Obj.isObject(block)) {
+          Obj.update(block, (block) => Object.assign(block, patch));
+        } else {
+          Object.assign(block, patch);
+        }
+      }
+      if (write.transcriptUpdate) {
+        Obj.update(transcript, (transcript) => Object.assign(transcript, write.transcriptUpdate));
+      }
+    });

package/src/index.ts

@@ -0,0 +1,14 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './TranscriptEvent';
+export * from './Stage';
+export * from './lookup';
+export * from './PipelineConfig';
+export * from './model-routing';
+export * from './PipelineRuntime';
+export * from './live';
+export * from './asr';
+export * from './dispatch';
+export * from './stages';

package/src/live.test.ts

@@ -0,0 +1,63 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { captureCommit } from './dispatch';
+import { runLivePipeline } from './live';
+import { makeCorrectionStage } from './stages';
+
+describe('runLivePipeline', () => {
+  test('drives per-block stages from pushed blocks and drains on end', async ({ expect }) => {
+    const { commit, writes } = captureCommit();
+    const live = runLivePipeline({ stages: [makeCorrectionStage()], commit });
+    live.block({ _tag: 'transcript', started: 's', text: 'so i think we should ship munich on friday' });
+    live.block({ _tag: 'transcript', started: 's', text: 'and review the docs next week' });
+    await live.end();
+
+    const corrected = writes.flatMap((write) => write.blockUpdates ?? []).map((update) => update.corrected);
+    expect(corrected.length).toBeGreaterThanOrEqual(2);
+  });
+
+  test('end resolves with no events pushed', async ({ expect }) => {
+    const { commit, writes } = captureCommit();
+    const live = runLivePipeline({ stages: [makeCorrectionStage()], commit });
+    await live.end();
+    expect(writes).toHaveLength(0);
+  });
+
+  // Headless equivalent of the file-transcription story: Whisper-style fragments (cut mid-sentence
+  // across chunk windows) streamed through correction. Guards the deterministic correction output —
+  // notably that a fragment ending in a comma does not become "Years,.".
+  test('corrects a fragmented transcript without punctuation artifacts', async ({ expect }) => {
+    const { commit, writes } = captureCommit();
+    const live = runLivePipeline({ stages: [makeCorrectionStage()], commit });
+    const fragments = [
+      "I've been living in London for about",
+      'Years,',
+      'maybe a bit longer',
+      "I've lived kind of mostly in",
+      'and east London, so I moved to Camden originally',
+      'and now I live in Hackney, which is probably',
+      'the kind of trendiest area of London',
+    ];
+    for (const text of fragments) {
+      live.block({ _tag: 'transcript', started: 's', text });
+    }
+    await live.end();
+
+    const corrected = writes
+      .flatMap((write) => write.blockUpdates ?? [])
+      .map((update) => update.corrected)
+      .filter((text): text is string => typeof text === 'string');
+
+    expect(corrected.length).toBeGreaterThan(0);
+    for (const text of corrected) {
+      // Every corrected block ends with terminal punctuation and never a "comma + period" artifact.
+      expect(text).toMatch(/[.!?]$/);
+      expect(text).not.toMatch(/[,;:]\.$/);
+    }
+    expect(corrected).toContain('Years.');
+  });
+});

package/src/live.ts

@@ -0,0 +1,56 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Queue from 'effect/Queue';
+import * as Stream from 'effect/Stream';
+
+import { EffectEx } from '@dxos/effect';
+import { type ContentBlock } from '@dxos/types';
+
+import { PipelineRuntime, type RunOptions } from './PipelineRuntime';
+import { TranscriptEvent } from './TranscriptEvent';
+
+/**
+ * Imperative handle to a running pipeline fed by a live ASR source. The source pushes events as they
+ * arrive rather than yielding a pre-materialized stream.
+ */
+export type LivePipeline = {
+  /** Append a transcript block produced by the ASR source. */
+  block: (block: ContentBlock.Transcript) => void;
+  /** Report that the speaker has been silent for `sinceMs` (triggers on-silence stages). */
+  silence: (sinceMs: number) => void;
+  /** Emit a periodic tick (triggers periodic stages). */
+  tick: () => void;
+  /** Close the source; resolves once the stream ends and all in-flight stages have drained. */
+  end: () => Promise<void>;
+};
+
+// A sentinel terminates the source after all queued events are consumed, so the run drains rather
+// than dropping in-flight blocks (Queue.shutdown would discard anything not yet pulled).
+const END = Symbol('end');
+type Item = TranscriptEvent | typeof END;
+
+/**
+ * Drives {@link PipelineRuntime} from a live ASR source: blocks pushed via the returned handle are
+ * enqueued onto the runtime's source stream; `end` closes the stream so the run drains and resolves.
+ * This is the single orchestration entry point for live capture — callers supply only the stages,
+ * commit sink, and (optional) lookup, mirroring a scripted `PipelineRuntime.run`.
+ */
+export const runLivePipeline = (options: Omit<RunOptions, 'source'>): LivePipeline => {
+  const queue = Effect.runSync(Queue.unbounded<Item>());
+  const source = Stream.fromQueue(queue).pipe(Stream.takeWhile((item): item is TranscriptEvent => item !== END));
+  const done = EffectEx.runPromise(PipelineRuntime.run({ ...options, source }));
+  const offer = (item: Item) => Effect.runSync(Queue.offer(queue, item));
+  return {
+    block: (block) => offer(TranscriptEvent.block(block)),
+    silence: (sinceMs) => offer(TranscriptEvent.silence(sinceMs)),
+    tick: () => offer(TranscriptEvent.tick()),
+    end: async () => {
+      offer(END);
+      await done;
+      Effect.runSync(Queue.shutdown(queue));
+    },
+  };
+};

package/src/lookup.test.ts

@@ -0,0 +1,41 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { afterEach, beforeEach, describe, test } from 'vitest';
+
+import { Obj, Type } from '@dxos/echo';
+import { EchoTestBuilder } from '@dxos/echo-client/testing';
+import { Organization, Person } from '@dxos/types';
+
+import { makeDatabaseLookup } from './lookup';
+
+describe('makeDatabaseLookup', () => {
+  let builder: EchoTestBuilder;
+  beforeEach(async () => {
+    builder = await new EchoTestBuilder().open();
+  });
+  afterEach(async () => {
+    await builder.close();
+  });
+
+  test('restricts candidates to the requested types', async ({ expect }) => {
+    const { db } = await builder.createDatabase({ types: [Organization.Organization, Person.Person] });
+    // Both an organization and a person share the surface noun.
+    db.add(Obj.make(Organization.Organization, { name: 'Mercury' }));
+    db.add(Obj.make(Person.Person, { fullName: 'Mercury' }));
+    await db.flush({ indexes: true });
+
+    const lookup = makeDatabaseLookup(db);
+
+    // Unconstrained: both types match.
+    const all = await lookup('Mercury');
+    expect(all.length).toBeGreaterThanOrEqual(2);
+
+    // Constrained to organizations: only the organization matches.
+    const organizations = await lookup('Mercury', { types: [Type.getTypename(Organization.Organization)!] });
+    expect(organizations).toHaveLength(1);
+    const match = await organizations[0].ref.load();
+    expect(Obj.instanceOf(Organization.Organization, match)).toBe(true);
+  });
+});

package/src/lookup.ts

@@ -0,0 +1,60 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Database, Filter, Obj, Query, Ref } from '@dxos/echo';
+
+/**
+ * A candidate match for a surface noun: the matched object's id, a ref consumers can persist, and a
+ * relevance `score` (higher = better) from the search backend's match rank.
+ */
+export type EntityMatch = {
+  id: string;
+  ref: Ref.Ref<any>;
+  score: number;
+};
+
+/**
+ * Additional context that narrows a lookup. Grows over time (e.g. the conversation window, an
+ * expected role); backends ignore fields they do not support.
+ */
+export type LookupContext = {
+  /** Restrict matches to these typenames (e.g. the typename of `Person` / `Organization`). */
+  types?: string[];
+};
+
+/**
+ * Resolves a surface noun to its candidate matches, ranked best-first, backed by an index. The
+ * pipeline depends only on this function — not on ECHO/the database directly — so the backend
+ * (full-text, vector, a remote service, …) is an injected concern. Returning candidates (rather than
+ * a single match) lets a context-aware resolver disambiguate using the surrounding conversation.
+ * Empty when nothing matches.
+ */
+export type EntityLookup = (noun: string, context?: LookupContext) => Promise<EntityMatch[]>;
+
+export type DatabaseLookupOptions = {
+  /** Search backend. Full-text matches proper nouns precisely; vector matches semantically. */
+  searchKind?: 'full-text' | 'vector';
+  /** Maximum candidates returned per noun. */
+  limit?: number;
+};
+
+/** An {@link EntityLookup} backed by an ECHO database query (full-text by default). */
+export const makeDatabaseLookup =
+  (db: Database.Database, { searchKind = 'full-text', limit = 5 }: DatabaseLookupOptions = {}): EntityLookup =>
+  async (noun, context) => {
+    // `runEntries` exposes each match's relevance rank; `run` would discard it.
+    const entries = await db.query(Query.select(Filter.text(noun, { type: searchKind }))).runEntries();
+    // Type narrowing is applied here rather than in the query: the executor rejects a text-search
+    // filter combined with a type filter ("query too complex").
+    const types = context?.types;
+    return entries
+      .flatMap((entry) => {
+        if (!entry.result || (types?.length && !types.includes(Obj.getTypename(entry.result) ?? ''))) {
+          return [];
+        }
+        return [{ id: entry.id, ref: Ref.make(entry.result), score: entry.match?.rank ?? 0 }];
+      })
+      .sort((a, b) => b.score - a.score)
+      .slice(0, limit);
+  };

package/src/model-routing.ts

@@ -0,0 +1,25 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { DXN } from '@dxos/echo';
+
+import { DEFAULT_STAGE_MODEL, type StageConfig } from './PipelineConfig';
+import { type Stage } from './Stage';
+
+/**
+ * Resolve the model for a stage invocation. Precedence: per-stage config override → the stage's own
+ * default → the preset/pipeline default → the global {@link DEFAULT_STAGE_MODEL}.
+ *
+ * `StageConfig.model` is a validated NSID name in the schema (its format is checked, but it is not
+ * pinned to the current model catalog); it is parsed to a model DXN here for the `AiService` call.
+ */
+export const resolveModel = (
+  stageConfig: StageConfig | undefined,
+  stage: Stage<any, any>,
+  presetDefault?: DXN.DXN,
+): DXN.DXN =>
+  (stageConfig?.model ? DXN.tryMake(stageConfig.model) : undefined) ??
+  stage.model ??
+  presetDefault ??
+  DEFAULT_STAGE_MODEL;

package/src/pipeline-integration.test.ts

@@ -0,0 +1,70 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Stream from 'effect/Stream';
+import { afterEach, beforeEach, describe, test } from 'vitest';
+
+import { Obj } from '@dxos/echo';
+import { EchoTestBuilder } from '@dxos/echo-client/testing';
+import { EffectEx } from '@dxos/effect';
+import { type ContentBlock, Organization, Person } from '@dxos/types';
+
+import { makeDatabaseLookup } from './lookup';
+import { PipelineRuntime } from './PipelineRuntime';
+import { type CommitFn } from './PipelineRuntime';
+import { makeCorrectionStage, makeExtractionStage } from './stages';
+import { TranscriptEvent } from './TranscriptEvent';
+
+// Reproduces the Pipeline testbench path: correction + extraction through the runtime, asserting that
+// recognized entities are linked in the final corrected text (regardless of stage commit ordering).
+describe('pipeline integration (correction + extraction)', () => {
+  let builder: EchoTestBuilder;
+  beforeEach(async () => {
+    builder = await new EchoTestBuilder().open();
+  });
+  afterEach(async () => {
+    await builder.close();
+  });
+
+  test('links seeded entities in corrected text', async ({ expect }) => {
+    const { db } = await builder.createDatabase({ types: [Organization.Organization, Person.Person] });
+    db.add(Obj.make(Organization.Organization, { name: 'DXOS' }));
+    db.add(Obj.make(Person.Person, { fullName: 'Sarah Johnson' }));
+    await db.flush({ indexes: true });
+
+    const blocks: ContentBlock.Transcript[] = [
+      { _tag: 'transcript', started: 's0', text: 'So I caught up with Sarah Johnson this morning' },
+      { _tag: 'transcript', started: 's1', text: 'We discussed the DXOS roadmap' },
+    ];
+    const source = Stream.fromIterable([
+      ...blocks.map((block) => TranscriptEvent.block(block)),
+      TranscriptEvent.silence(5_000),
+    ]);
+
+    // Mutate the window blocks in place (mirrors the story commit).
+    const commit: CommitFn = (write, window) =>
+      Effect.sync(() => {
+        for (const update of write.blockUpdates ?? []) {
+          const block = window[update.index];
+          if (block) {
+            const { index: _index, ...patch } = update;
+            Object.assign(block, patch);
+          }
+        }
+      });
+
+    await EffectEx.runPromise(
+      PipelineRuntime.run({
+        source,
+        stages: [makeCorrectionStage(), makeExtractionStage()],
+        lookup: makeDatabaseLookup(db),
+        commit,
+      }),
+    );
+
+    expect(blocks[0].corrected).toMatch(/\[Sarah Johnson\]\(echo:\/[^)]+\)/);
+    expect(blocks[1].corrected).toMatch(/\[DXOS\]\(echo:\/[^)]+\)/);
+  });
+});

package/src/stages/correction-llm.test.ts

@@ -0,0 +1,46 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as LanguageModel from '@effect/ai/LanguageModel';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Stream from 'effect/Stream';
+import { describe, test } from 'vitest';
+
+import { AiService } from '@dxos/ai';
+import { EffectEx } from '@dxos/effect';
+
+import { correctWithLanguageModel } from './correction-llm';
+
+/** Minimal `AiService` whose `generateObject` returns a fixed payload (no network). */
+const mockAiService = (object: unknown): Layer.Layer<AiService.AiService> =>
+  Layer.succeed(AiService.AiService, {
+    model: () =>
+      Layer.succeed(LanguageModel.LanguageModel, {
+        generateText: () => Effect.succeed({ text: '', content: [] }),
+        generateObject: () => Effect.succeed({ value: object, content: [] }),
+        streamText: () => Stream.empty,
+      } as any),
+  } as any);
+
+describe('correctWithLanguageModel', () => {
+  test('maps the model output to per-block corrections', async ({ expect }) => {
+    const blocks = [
+      { _tag: 'transcript' as const, started: 's', text: 'years,' },
+      { _tag: 'transcript' as const, started: 's', text: 'maybe a bit longer' },
+    ];
+    const layer = mockAiService({
+      blocks: [
+        { index: 0, corrected: 'Years.' },
+        { index: 1, corrected: 'Maybe a bit longer.' },
+      ],
+    });
+
+    const result = await EffectEx.runPromise(correctWithLanguageModel(blocks).pipe(Effect.provide(layer)));
+    expect(result).toEqual([
+      { index: 0, corrected: 'Years.' },
+      { index: 1, corrected: 'Maybe a bit longer.' },
+    ]);
+  });
+});

package/src/stages/correction-llm.ts

@@ -0,0 +1,40 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as LanguageModel from '@effect/ai/LanguageModel';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Schema from 'effect/Schema';
+
+import { AiService } from '@dxos/ai';
+import { DXN } from '@dxos/echo';
+import { type ContentBlock } from '@dxos/types';
+
+import { DEFAULT_STAGE_MODEL } from '../PipelineConfig';
+
+const CorrectionPayload = Schema.Struct({
+  blocks: Schema.Array(Schema.Struct({ index: Schema.Number, corrected: Schema.String })),
+});
+
+const PROMPT = `You repair raw speech-to-text fragments. For each numbered fragment, return a cleaned version: fix capitalization and terminal punctuation, join words split across fragment boundaries, and drop filler/garbage tokens — without changing the meaning. Return exactly one entry per input fragment, preserving its index.`;
+
+/**
+ * LLM-backed correction over a window of transcript blocks (the {@link makeCorrectionStage} seam).
+ * Returns an Effect requiring the {@link AiService} — the consumer provides its model layer and adapts
+ * the Effect to the stage's Promise-shaped `CorrectFn` (e.g. `EffectEx.runPromise(... .pipe(Effect.provide(layer)))`).
+ */
+export const correctWithLanguageModel = (
+  blocks: readonly ContentBlock.Transcript[],
+  model: DXN.DXN = DEFAULT_STAGE_MODEL,
+): Effect.Effect<ReadonlyArray<{ index: number; corrected: string }>, unknown, AiService.AiService> =>
+  Effect.gen(function* () {
+    const input = blocks.map((block, index) => `${index}: ${block.corrected ?? block.text}`).join('\n');
+    const response = yield* LanguageModel.generateObject({
+      schema: CorrectionPayload,
+      prompt: `${PROMPT}\n\n${input}`,
+    });
+    return response.value.blocks.map((block) => ({ index: block.index, corrected: block.corrected }));
+    // Model-layer construction failure is a fatal wiring fault (defect); transient LLM failures stay
+    // recoverable so callers can retry.
+  }).pipe(Effect.provide(AiService.model(DXN.getName(model)).pipe(Layer.orDie)));

package/src/stages/correction.test.ts

@@ -0,0 +1,26 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { correctText } from './correction';
+
+describe('correctText', () => {
+  test('capitalizes and adds terminal punctuation', ({ expect }) => {
+    expect(correctText('so we should ship')).toEqual('So we should ship.');
+  });
+
+  test('preserves existing terminal punctuation', ({ expect }) => {
+    expect(correctText('done!')).toEqual('Done!');
+  });
+
+  test('replaces a trailing comma rather than appending (no "Years,.")', ({ expect }) => {
+    expect(correctText('Years,')).toEqual('Years.');
+    expect(correctText('well, anyway,')).toEqual('Well, anyway.');
+  });
+
+  test('empty input stays empty', ({ expect }) => {
+    expect(correctText('   ')).toEqual('');
+  });
+});

package/src/stages/correction.ts

@@ -0,0 +1,72 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { type ContentBlock } from '@dxos/types';
+
+import { DEFAULT_STAGE_MODEL } from '../PipelineConfig';
+import { type Stage, StageWrite } from '../Stage';
+
+export type CorrectionInput = { window: ContentBlock.Transcript[] };
+
+/**
+ * Corrects a window of transcript blocks, returning a `{ index, corrected }` patch per block it
+ * changes. The deterministic default is used unless an LLM-backed corrector is injected (see
+ * `correctWithLanguageModel`); the consumer binds the AI service and adapts it to this Promise shape.
+ */
+export type CorrectFn = (
+  blocks: readonly ContentBlock.Transcript[],
+) => Promise<ReadonlyArray<{ index: number; corrected: string }>>;
+
+export type CorrectionOptions = {
+  /** Inject an LLM-backed corrector; omit for the deterministic per-block correction. */
+  correct?: CorrectFn;
+};
+
+/**
+ * Deterministic correction: trim, capitalize the first letter, ensure terminal punctuation.
+ * The LLM seam (see `run`) replaces this with cross-batch repair over the window.
+ */
+export const correctText = (text: string): string => {
+  const trimmed = text.trim();
+  if (trimmed.length === 0) {
+    return trimmed;
+  }
+  const capitalized = trimmed.charAt(0).toUpperCase() + trimmed.slice(1);
+  if (/[.!?]$/.test(capitalized)) {
+    return capitalized;
+  }
+  // Replace a trailing non-terminal mark (comma/semicolon/colon) with the period rather than
+  // appending — a Whisper fragment like "Years," would otherwise become "Years,.".
+  return `${capitalized.replace(/[,;:]+$/, '')}.`;
+};
+
+/**
+ * Stage ①: clean up the most recent transcript block (punctuation, capitalization).
+ * Windowed for cross-batch context; emits a correction for the newest block.
+ */
+export const makeCorrectionStage = ({ correct }: CorrectionOptions = {}): Stage<CorrectionInput> => ({
+  id: 'correct',
+  trigger: 'per-block',
+  window: { blocks: 8 },
+  concurrency: 'latest-wins',
+  model: DEFAULT_STAGE_MODEL,
+  run: ({ window }) =>
+    correct
+      ? // LLM seam: the injected corrector repairs the window (cross-batch word/punctuation fixes).
+        Effect.promise(() => correct(window)).pipe(
+          Effect.map((updates) => (updates.length > 0 ? StageWrite.blocks([...updates]) : StageWrite.empty())),
+        )
+      : Effect.sync(() => {
+          // Deterministic fallback: correct every not-yet-corrected block in the window. Robust under
+          // latest-wins — if earlier invocations were interrupted, the surviving run still covers their
+          // blocks; already-corrected blocks are skipped once the write is applied back (idempotent).
+          const updates = window
+            .map((block, index) => ({ block, index }))
+            .filter(({ block }) => block.corrected === undefined)
+            .map(({ block, index }) => ({ index, corrected: correctText(block.text) }));
+          return updates.length > 0 ? StageWrite.blocks(updates) : StageWrite.empty();
+        }),
+});

package/src/stages/diarization.ts

@@ -0,0 +1,24 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { type ContentBlock } from '@dxos/types';
+
+import { type Stage, StageWrite } from '../Stage';
+
+export type DiarizationInput = { window: ContentBlock.Transcript[] };
+
+/**
+ * Stage ◆ (interface only / deferred): label the speaker of the newest block.
+ * Conforms to the `Stage` contract and is inert until a diarization backend is wired.
+ */
+export const makeDiarizationStage = (): Stage<DiarizationInput> => ({
+  id: 'diarize',
+  trigger: 'per-block',
+  window: { blocks: 1 },
+  concurrency: 'latest-wins',
+  // TODO: implement diarization (assign speaker identity to the block).
+  run: () => Effect.succeed(StageWrite.empty()),
+});