elanous 0.2.9 → 0.2.11

package/src/execution-loop/launch-gate.ts

@@ -0,0 +1,100 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { debug } from '../debug/log.js';
+import { extractVerbatimOriginalAsk } from '../self-implement/goal-author.js';
+import { loadRunLedger } from '../self-implement/run-ledger.js';
+import { queryRunningRuns, type QueriedRunningRunsResult } from '../self-implement/running-runs.js';
+import type { BudgetDecision } from '../self-implement/budget-gate.js';
+
+export type ActiveRunsForGoal = readonly string[] | 'unknown';
+
+/** Match an un-authored CLI request to the verbatim ask recorded in an authored run. */
+export function launchRequestId(text: string): string {
+  return `request-${createHash('sha256').update(text).digest('hex').slice(0, 32)}`;
+}
+
+export interface ActiveRunsForGoalDeps {
+  queryRuns?: () => QueriedRunningRunsResult;
+  loadLedger?: typeof loadRunLedger;
+  readGoalDocument?: (path: string) => string;
+}
+
+/** Only a live process with an exact goal ID or verbatim authored ask is a duplicate. Incomplete observation is not absence. */
+export function activeRunsForGoal(goalId: string, deps: ActiveRunsForGoalDeps = {}): ActiveRunsForGoal {
+  try {
+    const observation = (deps.queryRuns ?? (() => queryRunningRuns({ includeTest: true, caller: 'execution-loop.launch-gate', noCache: true })))();
+    const loadLedger = deps.loadLedger ?? loadRunLedger;
+    const readGoalDocument = deps.readGoalDocument ?? ((path: string) => readFileSync(path, 'utf8'));
+    let unknown = observation.completeness !== 'complete' || observation.pty.unreadable.length > 0;
+    const active = new Set<string>();
+    for (const run of observation.entries) {
+      if (run.status === 'ended-unclosed') continue;
+      if (run.ledgerDirectories.length === 0) { unknown = true; continue; }
+      let identified = false;
+      for (const directory of run.ledgerDirectories) {
+        try {
+          const ledger = loadLedger(run.runId, directory);
+          if (ledger === null) { unknown = true; continue; }
+          const ids = new Set(ledger.flatMap((entry) => entry.goalId ? [entry.goalId] : []));
+          if (ids.size !== 1) { unknown = true; continue; }
+          identified = true;
+          let matches = ids.has(goalId);
+          if (!matches && goalId.startsWith('request-') && run.status === 'running' && run.ptyRefs.length > 0) {
+            const document = ledger.find((entry) => entry.event === 'start')?.data.goalFile;
+            if (typeof document === 'string') {
+              try {
+                const ask = extractVerbatimOriginalAsk(readGoalDocument(document));
+                matches = ask?.range !== undefined && launchRequestId(ask.ask) === goalId;
+              } catch { unknown = true; }
+            }
+          }
+          if (matches) {
+            if (run.status === 'running' && run.ptyRefs.length > 0) active.add(run.runId);
+            else unknown = true;
+          }
+        } catch { unknown = true; }
+      }
+      if (!identified) unknown = true;
+    }
+    // Positive evidence wins even if a different process or store is unreadable.
+    return active.size > 0 ? [...active].sort() : unknown ? 'unknown' : [];
+  } catch {
+    return 'unknown';
+  }
+}
+
+export interface PreLaunchGateInput {
+  goalId: string;
+  budget?: BudgetDecision | 'unknown';
+  forceLaunch?: boolean;
+}
+
+export interface PreLaunchGateDeps extends ActiveRunsForGoalDeps {
+  activeRuns?: (goalId: string) => ActiveRunsForGoal;
+}
+
+export interface PreLaunchGateDecision {
+  action: 'proceed' | 'blocked-duplicate' | 'blocked-budget' | 'wait-reset';
+  sameGoalActiveRuns: ActiveRunsForGoal;
+  budget: BudgetDecision | 'unknown';
+  reason: string;
+}
+
+/** Force bypasses only a duplicate observation, never an exhausted budget. */
+export function preLaunchGate(input: PreLaunchGateInput, deps: PreLaunchGateDeps = {}): PreLaunchGateDecision {
+  const decision = decidePreLaunch(input, deps);
+  debug.log('execution-loop.launch-gate', 'decision', { goalId: input.goalId, action: decision.action, sameGoalActiveRuns: decision.sameGoalActiveRuns, budget: decision.budget === 'unknown' ? 'unknown' : decision.budget.action, forceLaunch: input.forceLaunch === true, reason: decision.reason });
+  return decision;
+}
+
+function decidePreLaunch(input: PreLaunchGateInput, deps: PreLaunchGateDeps): PreLaunchGateDecision {
+  const sameGoalActiveRuns = (deps.activeRuns ?? ((goalId) => activeRunsForGoal(goalId, deps)))(input.goalId);
+  const budget = input.budget ?? 'unknown';
+  if (budget !== 'unknown' && (budget.action === 'stop' || budget.action === 'wait-reset')) {
+    return { action: budget.action === 'stop' ? 'blocked-budget' : 'wait-reset', sameGoalActiveRuns, budget, reason: budget.reasons.join(' · ') || `budget: ${budget.action}` };
+  }
+  if (sameGoalActiveRuns !== 'unknown' && sameGoalActiveRuns.length > 0 && !input.forceLaunch) {
+    return { action: 'blocked-duplicate', sameGoalActiveRuns, budget, reason: `same-goal active runs: ${sameGoalActiveRuns.join(', ')}` };
+  }
+  return { action: 'proceed', sameGoalActiveRuns, budget, reason: sameGoalActiveRuns === 'unknown' ? 'active runs unknown' : input.forceLaunch && sameGoalActiveRuns.length > 0 ? 'duplicate overridden by force-launch' : 'no confirmed duplicate' };
+}

package/src/field/field-media.ts

@@ -219,19 +219,22 @@ function uniqueName(dir: string, name: string, size: number, taken: Set<string>)
 
 export const FIELD_CAPTION_TAG = '#현장';
 
-/** 캡션에 독립 토큰 `#현장` 이 있으면 `{ event? }`, 없으면 null.
- *  `#현장 <slug>` — 바로 다음 토큰을 소문자로 바꿔 슬러그 규칙에 맞으면 행사 이름, 아니면 기본 행사. */
-export function parseFieldCaption(caption: string | undefined | null): { event?: string; text?: string } | null {
+/** 캡션에 독립 토큰 `#현장` 이 있으면 `{ event?, mode?, text? }`, 없으면 null.
+ *  `#현장 <slug>` — 모드 토큰을 건너뛴 바로 다음 토큰을 소문자로 바꿔 슬러그 규칙에 맞으면 행사 이름, 아니면 기본 행사. */
+export function parseFieldCaption(caption: string | undefined | null): { event?: string; mode?: 'instant'; text?: string } | null {
   if (!caption) return null;
   const tokens = caption.trim().split(/\s+/);
   const at = tokens.indexOf(FIELD_CAPTION_TAG);
   if (at < 0) return null;
-  const next = tokens[at + 1]?.toLowerCase();
+  const isInstant = (token: string) => token === '즉석' || token.toLowerCase() === 'instant';
+  const mode = tokens.some(isInstant) ? 'instant' : undefined;
+  const eventAt = at + 1 + (tokens[at + 1] && isInstant(tokens[at + 1]) ? 1 : 0);
+  const next = tokens[eventAt]?.toLowerCase();
   const hasEvent = !!next && isFieldSlug(next);
-  // 태그·행사 이름을 뺀 나머지가 «글»(자막) — 태그 앞에 쓴 글도 같이.
-  const rest = tokens.filter((_, i) => i !== at && !(hasEvent && i === at + 1)).join(' ');
+  // 태그·행사 이름·모드를 뺀 나머지가 «글»(자막) — 태그 앞에 쓴 글도 같이.
+  const rest = tokens.filter((token, i) => i !== at && !(hasEvent && i === eventAt) && !isInstant(token)).join(' ');
   const text = normalizeFieldCaption(rest);
-  return { ...(hasEvent ? { event: next } : {}), ...(text ? { text } : {}) };
+  return { ...(hasEvent ? { event: next } : {}), ...(mode ? { mode } : {}), ...(text ? { text } : {}) };
 }
 
 export const FIELD_CAPTIONS_FILE = 'captions.txt';

package/src/field/field-reel.ts

@@ -4,11 +4,13 @@ import { join, resolve } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { spawn, execFileSync } from 'node:child_process';
 import { debug } from '../debug/log.js';
+import { mergeCapturedPath } from '../shell-env-bootstrap.js';
 import { listFieldMedia } from './field-media.js';
 import { startFieldFeed, type FieldFeedStart } from './field-feed-auto.js';
+import { recordOutput } from '../outputs/ledger.js';
 
 export interface FieldReelResult { ok: boolean; file?: string; seconds: number; error?: string; feed?: FieldFeedStart }
-export type FieldReelRunner = (dir: string, opts: { title: string; sub: string }) => Promise<FieldReelResult>;
+export type FieldReelRunner = (dir: string, opts: { title: string; sub: string; mode?: 'standard' | 'instant' }) => Promise<FieldReelResult>;
 export interface FieldReelStatus {
   state: 'waiting' | 'rendering' | 'done' | 'failed';
   items: number;
@@ -23,6 +25,7 @@ export interface FieldReelOptions {
   quietMs?: number;
   title?: string;
   sub?: string;
+  mode?: 'standard' | 'instant';
   runner?: FieldReelRunner;
   onDone?: (result: FieldReelResult) => void | Promise<void>;
   /** 같은 수신자가 앨범 항목마다 예약해도 한 렌더당 한 번만 통지한다. */
@@ -96,10 +99,12 @@ export function readFieldReelStatus(dir: string): FieldReelStatus | null {
   }
 }
 
-export const defaultFieldReelRunner: FieldReelRunner = (dir, { title, sub }) => new Promise((finish) => {
+export const defaultFieldReelRunner = (dir: string, { title, sub, mode = 'standard' }: { title: string; sub: string; mode?: 'standard' | 'instant' }, spawnReel: typeof spawn = spawn): Promise<FieldReelResult> => new Promise((finish) => {
   const script = resolve(import.meta.dir, '../../skills/explainer-video/engine/reel.sh');
   const started = Date.now();
-  const child = spawn('zsh', [script, dir, '--title', title, '--sub', sub], { stdio: 'ignore' });
+  const env = { ...process.env };
+  mergeCapturedPath(env, { capture: true });
+  const child = spawnReel('zsh', [script, dir, '--title', title, '--sub', sub, ...(mode === 'instant' ? ['--instant'] : [])], { stdio: 'ignore', env });
   let settled = false;
   const done = (error?: string) => {
     if (settled) return;
@@ -133,6 +138,7 @@ async function render(dir: string, job: Job): Promise<void> {
   // 현재 렌더의 수신자 스냅샷. 렌더 중 업로드의 수신자는 다음 렌더로 넘긴다.
   const callbacks = job.callbacks;
   const renderOpts = job.opts;
+  let reelTitle = renderOpts.title || event;
   job.callbacks = new Map();
   writeStatus(dir, { state: 'rendering', items, startedAt });
   mkdirSync(join(dir, 'reel'), { recursive: true }); // 실행기 계약 — 산출 폴더는 있다(reel.sh 는 스스로 다시 만든다)
@@ -144,9 +150,11 @@ async function render(dir: string, job: Job): Promise<void> {
     let titleLines: string[] = [];
     try { titleLines = readFileSync(join(dir, 'title.txt'), 'utf8').split(/\r?\n/); }
     catch (err) { if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err; }
+    reelTitle = titleLines[0]?.trim() || renderOpts.title || event;
     result = await (renderOpts.runner ?? defaultFieldReelRunner)(dir, {
-      title: titleLines[0]?.trim() || renderOpts.title || event,
+      title: reelTitle,
       sub: titleLines[1]?.trim() || renderOpts.sub || sub,
+      ...(renderOpts.mode ? { mode: renderOpts.mode } : {}),
     });
   } catch (err) {
     result = { ok: false, seconds: 0, error: err instanceof Error ? err.message : String(err) };
@@ -158,12 +166,18 @@ async function render(dir: string, job: Job): Promise<void> {
   writeStatus(dir, { state: result.ok ? 'done' : 'failed', items, startedAt, finishedAt,
     seconds: result.seconds, ...(result.ok ? { file: result.file } : { error: result.error ?? 'render failed' }) });
   debug.log('field.reel', result.ok ? 'done' : 'failed', { event, items, seconds: result.seconds });
+  if (result.ok && result.file) recordOutput({ source: 'field-reel', sourceId: event, kind: 'video', title: reelTitle, path: result.file });
   if (result.ok) {
     // EV10b: 엔진이 timeline.json 에 남긴 비전 호출 수·성공·«현장 N» 강등·걸린 ms — codex 잔량과 겹치므로 관측한다(OP 10-01).
+    let cardsCache: 'hit' | 'miss' | 'n/a' = 'n/a';
     try {
-      const t = JSON.parse(readFileSync(join(dir, 'reel', 'timeline.json'), 'utf8')) as { vision?: Record<string, unknown>; music?: unknown };
+      const t = JSON.parse(readFileSync(join(dir, 'reel', 'timeline.json'), 'utf8')) as { vision?: Record<string, unknown>; music?: unknown; cardsCache?: 'hit' | 'miss' };
       if (t.vision) debug.log('field.reel', 'vision', { event, ...t.vision, music: t.music === true });
+      if (renderOpts.mode === 'instant' && (t.cardsCache === 'hit' || t.cardsCache === 'miss')) cardsCache = t.cardsCache;
     } catch { debug.log('field.reel', 'vision-unread', { event }); }
+    // A custom runner without an explicit mode may render any way — say «unknown» instead of guessing the default.
+    const mode = renderOpts.mode ?? (renderOpts.runner ? 'unknown' : 'standard');
+    debug.log('field.reel', 'rendered', { mode, seconds: result.seconds, cardsCache });
   }
   // 뒤이은 업로드로 다시 렌더할 예정이면(dirty) 피드는 그 마지막 렌더 뒤에 한 번만 띄운다.
   if (result.ok && !job.dirty) result = { ...result, feed: (renderOpts.startFeed ?? ((d: string) => startFieldFeed(d, { enabled: renderOpts.autoFeed })))(dir) };

package/src/field-note/index.ts

@@ -0,0 +1,201 @@
+export interface FieldPhoto {
+  file: string;
+  /** EXIF `YYYY:MM:DD HH:mm:ss`, ISO local time, or ISO time with an offset. */
+  exifTakenAt?: string | null;
+}
+
+export interface TranscriptEntry {
+  speaker: string;
+  timestamp: string;
+  text: string;
+}
+
+export interface FieldNoteOptions {
+  /** Minutes east of UTC for offset-free EXIF and transcript timestamps; KST by default. */
+  timeZoneOffsetMinutes?: number;
+  /** Minutes added to every dated photo after interpreting its EXIF timestamp. */
+  photoCorrectionMinutes?: number;
+  /** Maximum gap between consecutive photos in the same scene; 15 minutes by default. */
+  sceneGapMinutes?: number;
+}
+
+export interface TimedPhoto extends FieldPhoto {
+  takenAt: string;
+}
+
+export interface FieldScene {
+  start: string;
+  end: string;
+  photos: TimedPhoto[];
+  transcript: TranscriptEntry[];
+}
+
+export interface FieldTimeline {
+  scenes: FieldScene[];
+  undatedPhotos: FieldPhoto[];
+  /** Chronological entries when there are no dated photos to anchor a scene. */
+  transcriptWithoutPhotos: TranscriptEntry[];
+  timeZoneOffsetMinutes: number;
+}
+
+export interface FieldNoteLlm {
+  /** Only used for a raw transcript string; JSON entries bypass transcription. */
+  transcribe?: (source: string) => Promise<TranscriptEntry[]>;
+  summarize?: (entries: readonly TranscriptEntry[]) => Promise<string>;
+}
+
+const MINUTE = 60_000;
+
+function validOffset(minutes: number): boolean {
+  return Number.isInteger(minutes) && minutes >= -14 * 60 && minutes <= 14 * 60;
+}
+
+function parseTime(value: string, offsetMinutes: number): number | null {
+  const input = value.trim();
+  const local = /^(\d{4})[:-](\d{2})[:-](\d{2})[ T](\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,3}))?$/.exec(input);
+  const zoned = local ? null : /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,3}))?(?:Z|[+-]\d{2}:\d{2})$/.exec(input);
+  const match = local ?? zoned;
+  if (!match) return null;
+  const [, year, month, day, hour, minute, second, fraction] = match;
+  if (+year! < 100) return null;
+  const milliseconds = fraction ? Number(fraction.padEnd(3, '0')) : 0;
+  const utc = Date.UTC(+year!, +month! - 1, +day!, +hour!, +minute!, +second!, milliseconds);
+  const date = new Date(utc);
+  if (date.getUTCFullYear() !== +year! || date.getUTCMonth() + 1 !== +month! ||
+      date.getUTCDate() !== +day! || date.getUTCHours() !== +hour! ||
+      date.getUTCMinutes() !== +minute! || date.getUTCSeconds() !== +second!) return null;
+  if (local) return utc - offsetMinutes * MINUTE;
+  // Offset-bearing ISO timestamps are absolute instants, not local wall-clock readings.
+  const parsed = Date.parse(input);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function iso(ms: number): string {
+  return new Date(ms).toISOString();
+}
+
+/** Pure alignment: neither mutates its inputs nor consults the machine clock/timezone. */
+export function alignFieldNote(
+  photos: readonly FieldPhoto[],
+  transcript: readonly TranscriptEntry[],
+  options: FieldNoteOptions = {},
+): FieldTimeline {
+  const offset = options.timeZoneOffsetMinutes ?? 540;
+  const correction = options.photoCorrectionMinutes ?? 0;
+  const gap = options.sceneGapMinutes ?? 15;
+  if (!validOffset(offset) || !Number.isFinite(correction) || !Number.isFinite(gap) || gap < 0) {
+    throw new RangeError('Invalid field-note timezone, photo correction, or scene gap');
+  }
+  const dated: Array<{ photo: TimedPhoto; time: number; order: number }> = [];
+  const undatedPhotos: FieldPhoto[] = [];
+  photos.forEach((photo, order) => {
+    const parsed = photo.exifTakenAt ? parseTime(photo.exifTakenAt, offset) : null;
+    if (parsed === null) undatedPhotos.push({ ...photo });
+    else dated.push({ photo: { ...photo, takenAt: iso(parsed + correction * MINUTE) }, time: parsed + correction * MINUTE, order });
+  });
+  dated.sort((a, b) => a.time - b.time || a.order - b.order);
+
+  const groups: typeof dated[] = [];
+  for (const item of dated) {
+    const last = groups.at(-1);
+    if (!last || item.time - last[last.length - 1]!.time > gap * MINUTE) groups.push([item]);
+    else last.push(item);
+  }
+
+  const entries = transcript.map((entry, order) => {
+    const time = parseTime(entry.timestamp, offset);
+    if (time === null) throw new RangeError(`Invalid transcript timestamp at index ${order}: ${entry.timestamp}`);
+    return { entry: { ...entry }, time, order };
+  }).sort((a, b) => a.time - b.time || a.order - b.order);
+
+  // An utterance belongs to the scene whose photo span [first, last] is nearest in time (inside the span = distance 0);
+  // a tie goes to the earlier scene. So a 10:55 line next to an 11:00 photo joins the 11:00 scene, not 09:00.
+  const spans = groups.map((group) => ({ start: group[0]!.time, end: group[group.length - 1]!.time }));
+  const sceneEntries: Array<Array<(typeof entries)[number]>> = groups.map(() => []);
+  for (const item of entries) {
+    if (groups.length === 0) break;
+    let best = 0;
+    let bestDistance = Infinity;
+    spans.forEach((span, index) => {
+      const distance = item.time < span.start ? span.start - item.time : item.time > span.end ? item.time - span.end : 0;
+      if (distance < bestDistance) { best = index; bestDistance = distance; }
+    });
+    sceneEntries[best]!.push(item);
+  }
+  const scenes = groups.map((group, index) => {
+    const assigned = sceneEntries[index]!;
+    const times = [group[0]!.time, group[group.length - 1]!.time, ...assigned.map((item) => item.time)];
+    return {
+      start: iso(Math.min(...times)), end: iso(Math.max(...times)),
+      photos: group.map((item) => item.photo), transcript: assigned.map((item) => item.entry),
+    };
+  });
+  return {
+    scenes, undatedPhotos,
+    transcriptWithoutPhotos: groups.length === 0 ? entries.map((item) => item.entry) : [],
+    timeZoneOffsetMinutes: offset,
+  };
+}
+
+function localTime(instant: string, offset: number): string {
+  const shifted = new Date(Date.parse(instant) + offset * MINUTE).toISOString().slice(0, 16).replace('T', ' ');
+  const sign = offset >= 0 ? '+' : '-';
+  const hours = String(Math.floor(Math.abs(offset) / 60)).padStart(2, '0');
+  const minutes = String(Math.abs(offset) % 60).padStart(2, '0');
+  return `${shifted} UTC${sign}${hours}:${minutes}`;
+}
+
+function photoLine(photo: FieldPhoto, label: string): string {
+  const file = encodeURIComponent(photo.file).replace(/%2F/gi, '/').replace(/[()]/g, (char) => char === '(' ? '%28' : '%29');
+  const alt = photo.file.split(/[\\/]/).at(-1)?.replace(/\]/g, '\\]') ?? photo.file;
+  return `- ${label} ![${alt}](<${file}>)`;
+}
+
+/** Synchronous, side-effect-free Markdown rendering; summaries are optional placeholders. */
+export function renderFieldNote(timeline: FieldTimeline, summaries: readonly string[] = []): string {
+  if (summaries.length > timeline.scenes.length + (timeline.transcriptWithoutPhotos.length ? 1 : 0)) {
+    throw new RangeError('More summaries than transcript sections');
+  }
+  const lines = ['# 현장 노트', ''];
+  timeline.scenes.forEach((scene, i) => {
+    lines.push(`## 장면 ${i + 1} · ${localTime(scene.start, timeline.timeZoneOffsetMinutes)} – ${localTime(scene.end, timeline.timeZoneOffsetMinutes)}`);
+    lines.push('', '### 전사 요약', summaries[i]?.trim() || '_(전사 요약 자리)_', '', '### 사진');
+    for (const photo of scene.photos) lines.push(photoLine(photo, localTime(photo.takenAt, timeline.timeZoneOffsetMinutes)));
+    lines.push('');
+  });
+  if (timeline.transcriptWithoutPhotos.length) {
+    lines.push('## 사진 없는 전사', '', '### 전사 요약',
+      summaries[timeline.scenes.length]?.trim() || '_(전사 요약 자리)_', '', '### 시간순 전사');
+    for (const entry of timeline.transcriptWithoutPhotos) {
+      lines.push(`- ${entry.timestamp} · ${entry.speaker}: ${entry.text}`);
+    }
+    lines.push('');
+  }
+  if (timeline.undatedPhotos.length) {
+    lines.push('## 시각 없음', '');
+    for (const photo of timeline.undatedPhotos) lines.push(photoLine(photo, '시각 없음'));
+    lines.push('');
+  }
+  return lines.join('\n').trimEnd() + '\n';
+}
+
+/** LLM calls are supplied by the caller; JSON transcripts need no transcription call. */
+export async function generateFieldNote(
+  photos: readonly FieldPhoto[],
+  transcript: readonly TranscriptEntry[] | string,
+  llm: FieldNoteLlm = {},
+  options: FieldNoteOptions = {},
+): Promise<string> {
+  let entries: readonly TranscriptEntry[];
+  if (typeof transcript === 'string') {
+    if (!llm.transcribe) throw new Error('A transcribe dependency is required for raw transcript input');
+    entries = await llm.transcribe(transcript);
+  } else entries = transcript;
+  const timeline = alignFieldNote(photos, entries, options);
+  const sections = timeline.scenes.map((scene) => scene.transcript);
+  if (timeline.transcriptWithoutPhotos.length) sections.push(timeline.transcriptWithoutPhotos);
+  const summaries = llm.summarize
+    ? await Promise.all(sections.map((segment) => segment.length ? llm.summarize!(segment) : ''))
+    : [];
+  return renderFieldNote(timeline, summaries);
+}

package/src/field-note/transcribe.ts

@@ -0,0 +1,248 @@
+import type { TranscriptEntry } from './index';
+
+/** Mono, normalized PCM. The capture instant is required for NOTE1's absolute photo alignment. */
+export interface FieldAudio {
+  samples: Float32Array;
+  sampleRate: number;
+  recordedAt: string;
+}
+
+export interface AudioChunk {
+  samples: Float32Array;
+  sampleRate: number;
+  /** Offset from the first sample of the recording, in seconds. */
+  startSeconds: number;
+}
+
+export interface SpeechSegment {
+  /** Start and end in seconds relative to the supplied chunk. */
+  startSeconds: number;
+  endSeconds: number;
+  text: string;
+  speaker?: string;
+}
+
+export interface EngineRequest {
+  language: string;
+  /** Preserve source-language speech rather than translating it. */
+  task: 'transcribe';
+}
+
+export interface TranscriptionEngine {
+  transcribe(chunk: AudioChunk, request: EngineRequest): Promise<readonly SpeechSegment[]>;
+}
+
+/** The caller provides the local Whisper runtime; this module never downloads a model. */
+export interface LocalWhisperClient {
+  transcribe(input: {
+    audio: Float32Array;
+    sampleRate: number;
+    language: string;
+    task: 'transcribe';
+  }): Promise<readonly SpeechSegment[]>;
+}
+
+/** The caller provides authentication/transport; no network call occurs on construction. */
+export interface CloudSttClient {
+  transcribe(input: {
+    audio: Float32Array;
+    sampleRate: number;
+    language: string;
+    timestamps: true;
+    diarization: true;
+  }): Promise<readonly SpeechSegment[]>;
+}
+
+export function createLocalWhisperEngine(client: LocalWhisperClient): TranscriptionEngine {
+  return {
+    transcribe: (chunk, request) => client.transcribe({
+      audio: chunk.samples, sampleRate: chunk.sampleRate, language: request.language, task: request.task,
+    }),
+  };
+}
+
+export function createCloudSttEngine(client: CloudSttClient): TranscriptionEngine {
+  return {
+    transcribe: (chunk, request) => client.transcribe({
+      audio: chunk.samples, sampleRate: chunk.sampleRate, language: request.language,
+      timestamps: true, diarization: true,
+    }),
+  };
+}
+
+export interface TranscriptionOptions {
+  /** Default: ko. */
+  language?: string;
+  /** Default: 30 seconds. */
+  chunkSeconds?: number;
+  /** Default: 2 seconds. Must be shorter than chunkSeconds. */
+  overlapSeconds?: number;
+  /** Used only if an engine omits a speaker label. Otherwise the label remains 화자 미상. */
+  defaultSpeaker?: string;
+}
+
+function validateAudio(audio: FieldAudio): number {
+  if (!Number.isInteger(audio.sampleRate) || audio.sampleRate <= 0) {
+    throw new RangeError('Audio sampleRate must be a positive integer');
+  }
+  const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d{1,3})?(Z|[+-]\d{2}:\d{2})$/.exec(audio.recordedAt);
+  if (!match) throw new RangeError('Audio recordedAt must be an ISO timestamp with a timezone offset');
+  const [, year, month, day, hour, minute, second, zone] = match;
+  const calendar = new Date(Date.UTC(+year!, +month! - 1, +day!, +hour!, +minute!, +second!));
+  const recordedAt = Date.parse(audio.recordedAt);
+  if (calendar.getUTCFullYear() !== +year! || calendar.getUTCMonth() + 1 !== +month! ||
+      calendar.getUTCDate() !== +day! || calendar.getUTCHours() !== +hour! ||
+      calendar.getUTCMinutes() !== +minute! || calendar.getUTCSeconds() !== +second! ||
+      (zone !== 'Z' && (+zone!.slice(1, 3) > 23 || +zone!.slice(4) > 59)) ||
+      !Number.isFinite(recordedAt)) {
+    throw new RangeError('Invalid audio recordedAt timestamp');
+  }
+  return recordedAt;
+}
+
+/** Sample-index arithmetic avoids gaps and drift from repeated floating-point additions. */
+export function splitAudioIntoChunks(audio: FieldAudio, options: TranscriptionOptions = {}): AudioChunk[] {
+  validateAudio(audio);
+  const chunkSeconds = options.chunkSeconds ?? 30;
+  const overlapSeconds = options.overlapSeconds ?? 2;
+  if (!Number.isFinite(chunkSeconds) || !Number.isFinite(overlapSeconds) ||
+      chunkSeconds <= 0 || overlapSeconds < 0 || overlapSeconds >= chunkSeconds) {
+    throw new RangeError('Audio chunk length must exceed nonnegative overlap');
+  }
+  const size = Math.round(chunkSeconds * audio.sampleRate);
+  const overlap = Math.round(overlapSeconds * audio.sampleRate);
+  if (size <= 0 || overlap >= size) throw new RangeError('Audio chunk and overlap must span valid samples');
+  const chunks: AudioChunk[] = [];
+  for (let start = 0; start < audio.samples.length;) {
+    const end = Math.min(start + size, audio.samples.length);
+    chunks.push({ samples: audio.samples.subarray(start, end), sampleRate: audio.sampleRate,
+      startSeconds: start / audio.sampleRate });
+    if (end === audio.samples.length) break;
+    start = end - overlap;
+  }
+  return chunks;
+}
+
+function mergeOverlappingText(left: string, right: string): string | null {
+  if (left === right) return left;
+  if (left.includes(right)) return left;
+  if (right.includes(left)) return right;
+  for (let length = Math.min(left.length, right.length); length >= 2; length--) {
+    if (left.endsWith(right.slice(0, length))) return left + right.slice(length);
+  }
+  return null;
+}
+
+interface TimedSegment {
+  start: number;
+  end: number;
+  speaker: string;
+  text: string;
+  chunkIndex: number;
+}
+
+/** Return absolute ISO timestamps accepted by NOTE1, preserving speaker labels and chronological order. */
+export async function transcribeFieldAudio(
+  audio: FieldAudio,
+  engine: TranscriptionEngine,
+  options: TranscriptionOptions = {},
+): Promise<TranscriptEntry[]> {
+  const origin = validateAudio(audio);
+  const chunks = splitAudioIntoChunks(audio, options);
+  const segments: TimedSegment[] = [];
+  for (const [chunkIndex, chunk] of chunks.entries()) {
+    const result = await engine.transcribe(chunk, { language: options.language ?? 'ko', task: 'transcribe' });
+    const duration = chunk.samples.length / chunk.sampleRate;
+    for (const segment of result) {
+      if (!Number.isFinite(segment.startSeconds) || !Number.isFinite(segment.endSeconds) ||
+          segment.startSeconds < 0 || segment.endSeconds < segment.startSeconds ||
+          // Only floating-point slack — a segment may not end after the chunk's real audio (NOTE3a review must-fix).
+          segment.endSeconds > duration + 1e-9) {
+        throw new RangeError(`Invalid transcription segment times in chunk ${chunkIndex}`);
+      }
+      const text = segment.text.trim();
+      if (!text) continue;
+      segments.push({
+        start: chunk.startSeconds + segment.startSeconds,
+        end: chunk.startSeconds + segment.endSeconds,
+        text, speaker: segment.speaker?.trim() || options.defaultSpeaker?.trim() || '화자 미상',
+        chunkIndex,
+      });
+    }
+  }
+  segments.sort((a, b) => a.chunkIndex - b.chunkIndex || a.start - b.start);
+  const stitched: TimedSegment[] = [];
+  const center = (segment: TimedSegment) => {
+    const source = chunks[segment.chunkIndex]!;
+    return source.startSeconds + source.samples.length / source.sampleRate / 2;
+  };
+  // Engine speaker IDs are chunk-scoped. A later chunk's ID that matched an earlier chunk's speech in the overlap takes
+  // the earlier global label; an ID that never matched is qualified with its chunk so different people never share a label.
+  const unlabeled = new Set(['화자 미상', options.defaultSpeaker?.trim()].filter((label): label is string => !!label));
+  const qualify = (speaker: string, chunkIndex: number) => chunkIndex && !unlabeled.has(speaker) ? `${speaker} · 구간 ${chunkIndex + 1}` : speaker;
+  for (const [chunkIndex, chunk] of chunks.entries()) {
+    const incoming = segments.filter((segment) => segment.chunkIndex === chunkIndex);
+    const speakerMap = new Map<string, string>();
+    const previous = stitched.filter((segment) => segment.chunkIndex === chunkIndex - 1);
+    const sharedStart = chunk.startSeconds;
+    const sharedEnd = chunkIndex ? Math.min(chunk.startSeconds + chunk.samples.length / chunk.sampleRate,
+      chunks[chunkIndex - 1]!.startSeconds + chunks[chunkIndex - 1]!.samples.length / audio.sampleRate) : sharedStart;
+    const eligible = (segment: TimedSegment) => segment.start <= sharedEnd && segment.end >= sharedStart;
+    const consumedPrevious = new Set<TimedSegment>();
+    const consumedIncoming = new Set<TimedSegment>();
+    const replacements: TimedSegment[] = [];
+    // A chunk may split one sentence into several timed segments while its
+    // neighbor reports the entire sentence. Match contiguous groups on both sides.
+    while (sharedEnd > sharedStart) {
+      let best: { earlier: TimedSegment[]; later: TimedSegment[]; text: string } | undefined;
+      for (let a = 0; a < previous.length; a++) {
+        for (let b = a + 1; b <= previous.length; b++) {
+          const earlier = previous.slice(a, b);
+          if (earlier.some((item) => consumedPrevious.has(item) || !eligible(item))) break;
+          for (let c = 0; c < incoming.length; c++) {
+            for (let d = c + 1; d <= incoming.length; d++) {
+              const later = incoming.slice(c, d);
+              if (later.some((item) => consumedIncoming.has(item) || !eligible(item))) break;
+              // Speaker IDs are scoped to each engine call, not stable across chunks.
+              // Keep distinct speakers within a chunk separate, but use speech and time across chunks.
+              if (earlier.some((item) => item.speaker !== earlier[0]!.speaker) ||
+                  later.some((item) => item.speaker !== later[0]!.speaker)) continue;
+              const earlierStart = earlier[0]!.start;
+              const earlierEnd = Math.max(...earlier.map((item) => item.end));
+              const laterStart = later[0]!.start;
+              const laterEnd = Math.max(...later.map((item) => item.end));
+              if (earlier.some((item) => item.start > laterEnd || item.end < laterStart) ||
+                  later.some((item) => item.start > earlierEnd || item.end < earlierStart)) continue;
+              const text = mergeOverlappingText(earlier.map((item) => item.text).join(' '),
+                later.map((item) => item.text).join(' '));
+              if (text !== null && (!best || earlier.length + later.length > best.earlier.length + best.later.length)) {
+                best = { earlier, later, text };
+              }
+            }
+          }
+        }
+      }
+      if (!best) break;
+      for (const item of best.earlier) consumedPrevious.add(item);
+      for (const item of best.later) consumedIncoming.add(item);
+      const earlier = best.earlier[0]!;
+      const later = best.later[0]!;
+      const chosen = Math.abs((later.start + later.end) / 2 - center(later)) <
+        Math.abs((earlier.start + earlier.end) / 2 - center(earlier)) ? later : earlier;
+      // The earlier side already carries a global label; first match decides the mapping for this chunk-local ID.
+      for (const item of best.later) if (!speakerMap.has(item.speaker)) speakerMap.set(item.speaker, earlier.speaker);
+      replacements.push({ ...chosen, speaker: earlier.speaker, chunkIndex, text: best.text,
+        start: Math.min(...best.earlier.map((item) => item.start), ...best.later.map((item) => item.start)),
+        end: Math.max(...best.earlier.map((item) => item.end), ...best.later.map((item) => item.end)) });
+    }
+    for (let i = stitched.length - 1; i >= 0; i--) {
+      if (consumedPrevious.has(stitched[i]!)) stitched.splice(i, 1);
+    }
+    stitched.push(...incoming.filter((item) => !consumedIncoming.has(item))
+      .map((item) => ({ ...item, speaker: speakerMap.get(item.speaker) ?? qualify(item.speaker, chunkIndex) })), ...replacements);
+    stitched.sort((a, b) => a.start - b.start || a.chunkIndex - b.chunkIndex);
+  }
+  return stitched.map(({ start, speaker, text }) => ({
+    speaker, text, timestamp: new Date(origin + Math.round(start * 1000)).toISOString(),
+  }));
+}