@quolu/lattice 0.37.0 → 0.38.1

package/src/todo-gantt-html.mjs

@@ -6,7 +6,7 @@ import { renderDiagramLegend, renderRightPane } from './todo-gantt-html-independ
 import { escapeHtmlAttribute, escapeHtmlText, refKey } from './todo-gantt-html-shared.mjs';
 import { CSS } from './todo-gantt-html-style.mjs';
 
-export const TODO_GANTT_RENDERER_VERSION = 'lattice.todo_gantt_renderer.v17';
+export const TODO_GANTT_RENDERER_VERSION = 'lattice.todo_gantt_renderer.v18';
 export const TODO_GANTT_PROSE_MAX_BYTES = 8 * 1024 * 1024;
 export const TODO_GANTT_HTML_MAX_BYTES = 24 * 1024 * 1024;
 
@@ -40,9 +40,12 @@ function digest(value) {
  * still read, because anchor verification needs them, and their size is still
  * bounded — but they are not rendered into the page.
  */
-function normalizeSections(readModel, narratives, anchorOutcomes) {
+function normalizeSections(readModel, narratives, anchorOutcomes, noteContexts) {
   const supplied = new Map(narratives.map((entry) => [refKey(entry.ref), entry]));
   const outcomes = new Map(anchorOutcomes.map((entry) => [refKey(entry.ref), entry]));
+  const notes = noteContexts === null ? null : new Map(noteContexts.map((entry) => [
+    refKey({ project_id: entry.project_id, plan_key: entry.plan_key, task_id: entry.task_id }), entry,
+  ]));
   const result = [];
   const counted = new Set();
   let proseBytes = 0;
@@ -69,7 +72,20 @@ function normalizeSections(readModel, narratives, anchorOutcomes) {
         ref, narrative_ref: narrativeRef, anchored: false, reason: 'anchor_missing',
         origin_line: task.narrative_anchor?.origin_line ?? null,
       };
-      result.push({ ref, task, state: states.get(task.task_id), narrativeRef, anchorOutcome });
+      const noteContext = notes?.get(refKey(ref)) ?? null;
+      if (noteContext !== null) {
+        proseBytes += noteContext.notes.reduce((bytes, note) => (
+          bytes + Buffer.byteLength(note.body, 'utf8')
+        ), 0);
+        if (proseBytes > TODO_GANTT_PROSE_MAX_BYTES) {
+          throw new TodoGanttRenderError('TODO_SCALE_EXCEEDED', 'todo gantt embedded prose limit exceeded', {
+            prose_bytes: proseBytes, prose_limit: TODO_GANTT_PROSE_MAX_BYTES,
+          });
+        }
+      }
+      result.push({
+        ref, task, state: states.get(task.task_id), narrativeRef, anchorOutcome, noteContext,
+      });
     }
   }
   return { sections: result, proseBytes };
@@ -132,19 +148,23 @@ const CONTROLLER = `
 
 export function renderTodoGanttHtml({
   readModel, layout, narratives = [], anchorOutcomes = [], presentation = null, metadata = {},
-  expandedLayout = null,
+  expandedLayout = null, noteContexts = null, noteWarnings = [],
 }) {
   if (readModel?.schema !== 'lattice.todo_store_read.v1' || !Array.isArray(readModel.members)) {
     throw new TypeError('readModel must be lattice.todo_store_read.v1');
   }
   if (!Array.isArray(narratives)) throw new TypeError('narratives must be an array');
   if (!Array.isArray(anchorOutcomes)) throw new TypeError('anchorOutcomes must be an array');
+  if (!(noteContexts === null || Array.isArray(noteContexts))) {
+    throw new TypeError('noteContexts must be null or an array');
+  }
+  if (!Array.isArray(noteWarnings)) throw new TypeError('noteWarnings must be an array');
   if (presentation !== null
     && (presentation?.schema !== 'lattice.todo_gantt_presentation_model.v1'
       || presentation.project_id !== readModel.project_id)) {
     throw new TypeError('presentation must be lattice.todo_gantt_presentation_model.v1');
   }
-  const normalized = normalizeSections(readModel, narratives, anchorOutcomes);
+  const normalized = normalizeSections(readModel, narratives, anchorOutcomes, noteContexts);
   const displayName = projectDisplayName(readModel, metadata);
   const svg = renderTodoGanttSvg(layout, { presentation });
   // The expanded diagram travels with the page so the badge can bring the
@@ -153,7 +173,9 @@ export function renderTodoGanttHtml({
   const diagrams = expandedSvg === ''
     ? `<div data-diagram="live">${svg}</div>`
     : `<div data-diagram="live">${svg}</div><div data-diagram="expanded" hidden>${expandedSvg}</div>`;
-  const rightPane = renderRightPane(normalized.sections, layout, presentation, readModel);
+  const rightPane = renderRightPane(
+    normalized.sections, layout, presentation, readModel, noteContexts !== null, noteWarnings,
+  );
   const staticData = serializeJsonForScript({
     renderer_version: TODO_GANTT_RENDERER_VERSION,
     metadata,

package/src/todo-note-store.mjs

@@ -0,0 +1,492 @@
+import { createHash, randomBytes } from 'node:crypto';
+import {
+  mkdir, open, readFile, readdir, rename, rm, stat,
+} from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  TODO_LIMITS,
+  TODO_NOTE_CONTEXT_SCHEMA,
+  TODO_NOTE_EVENT_SCHEMA,
+  canonicalizeTodoArtifact,
+  exactRecord,
+  isTodoDigest,
+  isTodoIdentifier,
+  todoSelfDigest,
+  validateTodoPlan,
+  validateTodoNoteContext,
+  validateTodoNoteEvent,
+} from './todo-contracts.mjs';
+import { validatePhaseTodoRevision, validateTodoRevision } from './todo-revision.mjs';
+
+const NOTE_ROOT_REF = '.lattice/todo/notes';
+const SEALED_NAME = /^(\d{12})-(\d{12})-([0-9a-f]{64})-([0-9a-f]{64})\.jsonl$/u;
+const ZERO_DIGEST = '0'.repeat(64);
+const MAX_SEGMENTS = 4_096;
+
+export class TodoNoteStoreError extends Error {
+  constructor(code, reason, detail = {}) {
+    super(reason);
+    this.name = 'TodoNoteStoreError';
+    this.code = code;
+    this.detail = { reason, ...detail };
+  }
+}
+
+function fail(code, reason, detail) {
+  throw new TodoNoteStoreError(code, reason, detail);
+}
+
+function sha256(bytes) {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+function canonicalLine(value) {
+  return Buffer.from(`${canonicalizeTodoArtifact(value)}\n`, 'utf8');
+}
+
+function notePaths(repoRoot, planKey) {
+  if (!isTodoIdentifier(planKey)) throw new TypeError('planKey must be a todo identifier');
+  const root = path.resolve(repoRoot, NOTE_ROOT_REF, planKey);
+  return { root, active: path.join(root, 'active.jsonl'), sealed: path.join(root, 'sealed') };
+}
+
+async function readOptionalBounded(ref, { missing = false } = {}) {
+  try {
+    const metadata = await stat(ref);
+    if (!metadata.isFile() || metadata.size > TODO_LIMITS.journalSegmentBytes) {
+      fail('NOTE_LOG_CORRUPT', 'note_segment_invalid', { ref });
+    }
+    return await readFile(ref);
+  } catch (error) {
+    if (error instanceof TodoNoteStoreError) throw error;
+    if (missing && error?.code === 'ENOENT') return null;
+    fail('NOTE_LOG_CORRUPT', 'note_segment_unreadable', { ref });
+  }
+}
+
+function parseCanonicalSegment(bytes, ref) {
+  if (bytes.length === 0 || bytes.at(-1) !== 0x0a) {
+    fail('NOTE_LOG_CORRUPT', 'note_segment_not_canonical', { ref });
+  }
+  const lines = bytes.toString('utf8').slice(0, -1).split('\n');
+  const events = [];
+  for (const line of lines) {
+    let event;
+    try { event = JSON.parse(line); } catch { fail('NOTE_LOG_CORRUPT', 'note_json_invalid', { ref }); }
+    if (!validateTodoNoteEvent(event) || canonicalLine(event).toString('utf8') !== `${line}\n`) {
+      fail('NOTE_LOG_CORRUPT', 'note_event_invalid', { ref });
+    }
+    events.push(event);
+  }
+  return events;
+}
+
+async function sealedFiles(ref) {
+  try {
+    const names = await readdir(ref);
+    if (names.length > MAX_SEGMENTS || names.some((name) => !SEALED_NAME.test(name))) {
+      fail('NOTE_LOG_CORRUPT', 'note_sealed_inventory_invalid', { ref });
+    }
+    return names.sort();
+  } catch (error) {
+    if (error instanceof TodoNoteStoreError) throw error;
+    if (error?.code === 'ENOENT') return [];
+    fail('NOTE_LOG_CORRUPT', 'note_sealed_inventory_unreadable', { ref });
+  }
+}
+
+function validateEventChain(events, { projectId, planKey }) {
+  for (let index = 0; index < events.length; index += 1) {
+    const event = events[index];
+    const previous = events[index - 1] ?? null;
+    if (event.project_id !== projectId || event.plan_key !== planKey
+      || event.sequence !== index + 1
+      || event.previous_digest !== (previous?.event_digest ?? null)) {
+      fail('NOTE_LOG_CORRUPT', 'note_digest_chain_invalid', {
+        plan_key: planKey, sequence: event.sequence,
+      });
+    }
+  }
+}
+
+/** planに属する独立note chainをbyte-levelで検証して読む。missingだけは空chainである。 */
+export async function readTodoNoteEvents(options = {}) {
+  const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
+  const { active, sealed } = notePaths(repoRoot, options.planKey);
+  const names = await sealedFiles(sealed);
+  const events = [];
+  let previousSegmentDigest = ZERO_DIGEST;
+  for (const name of names) {
+    const match = name.match(SEALED_NAME);
+    const bytes = await readOptionalBounded(path.join(sealed, name));
+    const segmentDigest = sha256(bytes);
+    const segmentEvents = parseCanonicalSegment(bytes, path.join(sealed, name));
+    if (Number(match[1]) !== segmentEvents[0]?.sequence
+      || Number(match[2]) !== segmentEvents.at(-1)?.sequence
+      || match[3] !== previousSegmentDigest || match[4] !== segmentDigest) {
+      fail('NOTE_LOG_CORRUPT', 'note_seal_invalid', { ref: path.join(sealed, name) });
+    }
+    events.push(...segmentEvents);
+    previousSegmentDigest = segmentDigest;
+  }
+  const activeBytes = await readOptionalBounded(active, { missing: true });
+  if (activeBytes !== null) events.push(...parseCanonicalSegment(activeBytes, active));
+  if (events.length > 0) {
+    validateEventChain(events, { projectId: events[0].project_id, planKey: options.planKey });
+  }
+  return {
+    events,
+    head_digest: events.at(-1)?.event_digest ?? null,
+    active_bytes: activeBytes ?? Buffer.alloc(0),
+    previous_segment_digest: previousSegmentDigest,
+  };
+}
+
+async function atomicWrite(ref, bytes) {
+  await mkdir(path.dirname(ref), { recursive: true });
+  const temporary = path.join(path.dirname(ref),
+    `.${path.basename(ref)}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`);
+  let handle;
+  try {
+    handle = await open(temporary, 'wx', 0o600);
+    await handle.writeFile(bytes);
+    await handle.sync();
+    await handle.close();
+    handle = null;
+    await rename(temporary, ref);
+    const directory = await open(path.dirname(ref), 'r');
+    try { await directory.sync(); } finally { await directory.close(); }
+  } finally {
+    if (handle) await handle.close();
+    await rm(temporary, { force: true });
+  }
+}
+
+async function withNoteLock(repoRoot, callback) {
+  const root = path.resolve(repoRoot, NOTE_ROOT_REF);
+  await mkdir(root, { recursive: true });
+  const lockRef = path.join(root, '.write.lock');
+  let handle;
+  try { handle = await open(lockRef, 'wx', 0o600); }
+  catch (error) {
+    if (error?.code === 'EEXIST') fail('NOTE_WRITE_CONFLICT', 'note_store_locked');
+    throw error;
+  }
+  try { return await callback(); }
+  finally { await handle.close(); await rm(lockRef, { force: true }); }
+}
+
+/** lifecycle artifactsへ触れず、独立note chainだけへ1 eventを追記する。 */
+export async function appendTodoNote(options = {}) {
+  const keys = [
+    'repoRoot', 'projectId', 'planKey', 'planVersion', 'taskId', 'actor',
+    'recordedAt', 'body', 'supersedes', 'eligibleSupersedes',
+  ];
+  if (!exactRecord(options, keys)
+    || !Array.isArray(options.eligibleSupersedes)
+    || !options.eligibleSupersedes.every(isTodoDigest)
+    || ![options.projectId, options.planKey, options.planVersion, options.taskId]
+    .every(isTodoIdentifier)) throw new TypeError('todo note append options invalid');
+  const repoRoot = path.resolve(options.repoRoot);
+  return withNoteLock(repoRoot, async () => {
+    const chain = await readTodoNoteEvents({ repoRoot, planKey: options.planKey });
+    if (options.supersedes !== null) {
+      const target = chain.events.find(({ event_digest: digest }) => digest === options.supersedes);
+      if (target === undefined || !options.eligibleSupersedes.includes(options.supersedes)) {
+        fail('NOTE_SUPERSEDES_INVALID', 'superseded_note_not_in_same_task', {
+          plan_key: options.planKey, task_id: options.taskId,
+        });
+      }
+    }
+    const previous = chain.events.at(-1) ?? null;
+    const event = {
+      schema: TODO_NOTE_EVENT_SCHEMA,
+      project_id: options.projectId,
+      plan_key: options.planKey,
+      task_id: options.taskId,
+      plan_version: options.planVersion,
+      sequence: (previous?.sequence ?? 0) + 1,
+      previous_digest: previous?.event_digest ?? null,
+      actor: options.actor,
+      recorded_at: options.recordedAt,
+      body: options.body,
+      supersedes: options.supersedes,
+      event_digest: '',
+    };
+    event.event_digest = todoSelfDigest(event, 'event_digest');
+    if (!validateTodoNoteEvent(event)) throw new TypeError('todo note event input invalid');
+
+    const paths = notePaths(repoRoot, options.planKey);
+    const eventBytes = canonicalLine(event);
+    if (chain.active_bytes.length > 0
+      && chain.active_bytes.length + eventBytes.length > TODO_LIMITS.journalSegmentBytes) {
+      const activeEvents = parseCanonicalSegment(chain.active_bytes, paths.active);
+      const segmentDigest = sha256(chain.active_bytes);
+      const name = `${String(activeEvents[0].sequence).padStart(12, '0')}`
+        + `-${String(activeEvents.at(-1).sequence).padStart(12, '0')}`
+        + `-${chain.previous_segment_digest}-${segmentDigest}.jsonl`;
+      await atomicWrite(path.join(paths.sealed, name), chain.active_bytes);
+      await atomicWrite(paths.active, eventBytes);
+    } else {
+      await atomicWrite(paths.active, Buffer.concat([chain.active_bytes, eventBytes]));
+    }
+    return event;
+  });
+}
+
+function noteProjectionEntry(event, supersededBy) {
+  return {
+    event_digest: event.event_digest,
+    origin_plan_version: event.plan_version,
+    origin_task_id: event.task_id,
+    actor: event.actor,
+    recorded_at: event.recorded_at,
+    body: event.body,
+    supersedes: event.supersedes,
+    superseded_by: supersededBy ?? null,
+    correction_state: supersededBy === undefined ? 'current' : 'superseded',
+  };
+}
+
+function migrationIndex(migrations) {
+  if (!Array.isArray(migrations)) throw new TypeError('todo note migrations must be an array');
+  const index = new Map();
+  for (const migration of migrations) {
+    if (!exactRecord(migration, ['from_plan_version', 'to_plan_version', 'task_migration'])
+      || !isTodoIdentifier(migration.from_plan_version)
+      || !isTodoIdentifier(migration.to_plan_version)
+      || migration.from_plan_version === migration.to_plan_version
+      || !Array.isArray(migration.task_migration)
+      || index.has(migration.from_plan_version)) {
+      fail('NOTE_PROJECTION_INVALID', 'note_migration_history_invalid');
+    }
+    const taskMap = new Map();
+    for (const entry of migration.task_migration) {
+      if (!exactRecord(entry, ['from_task_id', 'to_task_id'])
+        || !isTodoIdentifier(entry.from_task_id)
+        || !(entry.to_task_id === null || isTodoIdentifier(entry.to_task_id))
+        || taskMap.has(entry.from_task_id)) {
+        fail('NOTE_PROJECTION_INVALID', 'note_task_migration_invalid');
+      }
+      taskMap.set(entry.from_task_id, entry.to_task_id === 'removed' ? null : entry.to_task_id);
+    }
+    index.set(migration.from_plan_version, {
+      toPlanVersion: migration.to_plan_version, taskMap,
+    });
+  }
+  return index;
+}
+
+function resolveNoteTarget(event, { currentPlanVersion, currentTaskIds, migrations }) {
+  let version = event.plan_version;
+  let taskId = event.task_id;
+  const seen = new Set();
+  while (version !== currentPlanVersion) {
+    if (seen.has(version)) fail('NOTE_PROJECTION_INVALID', 'note_migration_cycle');
+    seen.add(version);
+    const step = migrations.get(version);
+    if (step === undefined) return { kind: 'archived' };
+    const nextTaskId = step.taskMap.get(taskId);
+    if (nextTaskId === undefined || nextTaskId === null) return { kind: 'archived' };
+    version = step.toPlanVersion;
+    taskId = nextTaskId;
+  }
+  return currentTaskIds.has(taskId) ? { kind: 'active', taskId } : { kind: 'archived' };
+}
+
+/**
+ * 既存task_migrationを合成し、現行taskへ渡すbounded contextとremoved taskのarchived束を作る。
+ * note listはこの全履歴を使えるが、通常詳細/startはcontextを自動同梱する。
+ */
+export function projectTodoNoteContext(options = {}) {
+  if (!exactRecord(options, [
+    'projectId', 'planKey', 'currentPlanVersion', 'currentTaskId',
+    'currentTaskIds', 'events', 'migrations',
+  ]) || ![options.projectId, options.planKey, options.currentPlanVersion, options.currentTaskId]
+    .every(isTodoIdentifier) || !Array.isArray(options.currentTaskIds)
+    || !options.currentTaskIds.every(isTodoIdentifier)
+    || !options.currentTaskIds.includes(options.currentTaskId)
+    || !Array.isArray(options.events) || !options.events.every(validateTodoNoteEvent)) {
+    throw new TypeError('todo note projection options invalid');
+  }
+  const currentTaskIds = new Set(options.currentTaskIds);
+  const migrations = migrationIndex(options.migrations);
+  const supersededBy = new Map();
+  for (const event of options.events) {
+    if (event.project_id !== options.projectId || event.plan_key !== options.planKey) {
+      fail('NOTE_LOG_CORRUPT', 'note_identity_mismatch');
+    }
+    if (event.supersedes !== null) supersededBy.set(event.supersedes, event.event_digest);
+  }
+
+  const current = [];
+  const archived = [];
+  const sequenceByDigest = new Map(options.events.map((event) => [event.event_digest, event.sequence]));
+  for (const event of options.events) {
+    const target = resolveNoteTarget(event, {
+      currentPlanVersion: options.currentPlanVersion, currentTaskIds, migrations,
+    });
+    const entry = noteProjectionEntry(event, supersededBy.get(event.event_digest));
+    if (target.kind === 'archived') archived.push(entry);
+    else if (target.taskId === options.currentTaskId) current.push(entry);
+  }
+  current.sort((left, right) => sequenceByDigest.get(right.event_digest)
+    - sequenceByDigest.get(left.event_digest));
+  archived.reverse();
+
+  const notes = [];
+  let usedBytes = 0;
+  for (const entry of current) {
+    const bytes = Buffer.byteLength(entry.body, 'utf8');
+    if (usedBytes + bytes > TODO_LIMITS.noteContextBytes) continue;
+    notes.push(entry);
+    usedBytes += bytes;
+  }
+  const context = {
+    schema: TODO_NOTE_CONTEXT_SCHEMA,
+    project_id: options.projectId,
+    plan_key: options.planKey,
+    task_id: options.currentTaskId,
+    notes,
+    note_head_digest: current[0]?.event_digest ?? null,
+    overflow_count: current.length - notes.length,
+    full_history_command: `lattice todo note list --plan ${options.planKey}`
+      + ` --task ${options.currentTaskId} --json`,
+    context_digest: '',
+  };
+  context.context_digest = todoSelfDigest(context, 'context_digest');
+  if (!validateTodoNoteContext(context)) {
+    fail('NOTE_PROJECTION_INVALID', 'note_context_invalid');
+  }
+  return { context, archived, history: current };
+}
+
+async function readCanonicalJson(ref, { missing = false } = {}) {
+  let bytes;
+  try {
+    const metadata = await stat(ref);
+    if (!metadata.isFile() || metadata.size > TODO_LIMITS.snapshotBytes) {
+      fail('NOTE_PROJECTION_INVALID', 'note_projection_artifact_invalid', { ref });
+    }
+    bytes = await readFile(ref);
+  } catch (error) {
+    if (error instanceof TodoNoteStoreError) throw error;
+    if (missing && error?.code === 'ENOENT') return null;
+    fail('NOTE_PROJECTION_INVALID', 'note_projection_artifact_unreadable', { ref });
+  }
+  let value;
+  try { value = JSON.parse(bytes.toString('utf8')); }
+  catch { fail('NOTE_PROJECTION_INVALID', 'note_projection_json_invalid', { ref }); }
+  if (!bytes.equals(canonicalLine(value))) {
+    fail('NOTE_PROJECTION_INVALID', 'note_projection_artifact_not_canonical', { ref });
+  }
+  return value;
+}
+
+async function readNoteMigrations(repoRoot, planKey, eventVersions) {
+  const base = path.resolve(repoRoot, '.lattice/todo/plans', planKey);
+  let entries;
+  try { entries = await readdir(base, { withFileTypes: true }); }
+  catch (error) {
+    if (error?.code === 'ENOENT' && eventVersions.size === 0) return [];
+    fail('NOTE_PROJECTION_INVALID', 'note_plan_history_unreadable', { plan_key: planKey });
+  }
+  const versions = new Set();
+  const migrations = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !isTodoIdentifier(entry.name)) {
+      fail('NOTE_PROJECTION_INVALID', 'note_plan_history_inventory_invalid', { plan_key: planKey });
+    }
+    const versionRoot = path.join(base, entry.name);
+    const plan = await readCanonicalJson(path.join(versionRoot, 'plan.json'));
+    if (!validateTodoPlan(plan) || plan.plan_key !== planKey || plan.plan_version !== entry.name) {
+      fail('NOTE_PROJECTION_INVALID', 'note_historical_plan_invalid', { plan_version: entry.name });
+    }
+    versions.add(entry.name);
+    const revision = await readCanonicalJson(path.join(versionRoot, 'revision.json'), { missing: true });
+    if (revision === null) continue;
+    if (!(validateTodoRevision(revision) || validatePhaseTodoRevision(revision))
+      || revision.plan_key !== planKey || revision.predecessor?.plan_version === undefined
+      || !Array.isArray(revision.task_migration)) {
+      fail('NOTE_PROJECTION_INVALID', 'note_historical_revision_invalid', { plan_version: entry.name });
+    }
+    migrations.push({
+      from_plan_version: revision.predecessor.plan_version,
+      to_plan_version: entry.name,
+      task_migration: revision.task_migration.map(({ from_task_id: fromTaskId, to_task_id: toTaskId }) => ({
+        from_task_id: fromTaskId, to_task_id: toTaskId,
+      })),
+    });
+  }
+  if ([...eventVersions].some((version) => !versions.has(version))) {
+    fail('NOTE_PROJECTION_INVALID', 'note_origin_plan_version_unknown');
+  }
+  return migrations;
+}
+
+/** active store memberと歴史revisionから、通常供給用contextを一回で読む。 */
+export async function readTodoNoteContext(options = {}) {
+  if (!exactRecord(options, ['repoRoot', 'store', 'planKey', 'taskId'])
+    || !isTodoIdentifier(options.planKey) || !isTodoIdentifier(options.taskId)
+    || options.store === null || typeof options.store !== 'object') {
+    throw new TypeError('todo note context read options invalid');
+  }
+  const repoRoot = path.resolve(options.repoRoot);
+  const member = options.store.members?.find(({ descriptor }) => (
+    descriptor.plan_key === options.planKey
+  ));
+  if (member === undefined) fail('NOTE_TASK_NOT_FOUND', 'note_plan_not_active', {
+    plan_key: options.planKey,
+  });
+  const task = member.plan.tasks.find(({ task_id: taskId }) => taskId === options.taskId);
+  if (task === undefined) fail('NOTE_TASK_NOT_FOUND', 'note_task_not_active', {
+    plan_key: options.planKey, task_id: options.taskId,
+  });
+  const chain = await readTodoNoteEvents({ repoRoot, planKey: options.planKey });
+  const migrations = await readNoteMigrations(repoRoot, options.planKey,
+    new Set(chain.events.map(({ plan_version: version }) => version)));
+  return projectTodoNoteContext({
+    projectId: member.plan.project_id,
+    planKey: options.planKey,
+    currentPlanVersion: member.plan.plan_version,
+    currentTaskId: task.task_id,
+    currentTaskIds: member.plan.tasks.map(({ task_id: taskId }) => taskId),
+    events: chain.events,
+    migrations,
+  });
+}
+
+/** Gantt用に1 planのchain/historyを一度だけ読み、全task contextへ投影する。 */
+export async function readTodoNoteContextsForPlan(options = {}) {
+  if (!exactRecord(options, ['repoRoot', 'store', 'planKey'])
+    || !isTodoIdentifier(options.planKey)
+    || options.store === null || typeof options.store !== 'object') {
+    throw new TypeError('todo note contexts read options invalid');
+  }
+  const repoRoot = path.resolve(options.repoRoot);
+  const member = options.store.members?.find(({ descriptor }) => (
+    descriptor.plan_key === options.planKey
+  ));
+  if (member === undefined) fail('NOTE_TASK_NOT_FOUND', 'note_plan_not_active', {
+    plan_key: options.planKey,
+  });
+  const chain = await readTodoNoteEvents({ repoRoot, planKey: options.planKey });
+  const migrations = await readNoteMigrations(repoRoot, options.planKey,
+    new Set(chain.events.map(({ plan_version: version }) => version)));
+  const currentTaskIds = member.plan.tasks.map(({ task_id: taskId }) => taskId);
+  const projected = member.plan.tasks.map((task) => projectTodoNoteContext({
+    projectId: member.plan.project_id,
+    planKey: options.planKey,
+    currentPlanVersion: member.plan.plan_version,
+    currentTaskId: task.task_id,
+    currentTaskIds,
+    events: chain.events,
+    migrations,
+  }));
+  return {
+    contexts: projected.map(({ context }) => context),
+    archived: projected[0]?.archived ?? [],
+    note_head_digest: chain.head_digest,
+  };
+}