projectkeeper 0.0.0-stage → 1.0.0

package/src/process/index.ts

@@ -0,0 +1,243 @@
+/**
+ * The process engine (Spec v3.0 §2.12 工作的过程与断点, §1.18 送回, §2.13 rows 1–5 — what the program computes): each
+ * piece of work's process as the ledger shows it, its four things, a plan's execution shape, the breakpoints lit and
+ * put out, and the send-backs moved on by themselves. The program half of the owner's process view (CKC-24; CKC-27
+ * AC-6, AC-11); the round's model steps confirm or refute what rests on judgement and suggest the other send-backs.
+ *
+ * What the rest of the app wires in:
+ * - `processRunner(ledgerService)` — the round's program step `process` (keeper/organize/clerk.ts `ProcessRunner`);
+ * - `processEngines(ledgerService)` — `KEngines.process` for the process view (server/k-views.ts): a work item's steps
+ *   and four things, a plan's shape, and the work item a fix or check is a step of (`stepOf`);
+ * - `processBlock(store)` — the synthesis' block: breakpoints lit by kind and object, the candidates as leads, open send-backs;
+ * - `computeBreakpoints` — the candidates recomputed when the main agent enters a stage that reads them (D99, `pk_stage`);
+ * - `spotCheckTargets(store, round)` — what the spot-check checks: every looked candidate and the weighted sample (D99);
+ *   and (CS) every standing reason for leaving an item unplaced no spot-check has checked, and the program's unreviewed placements;
+ * - `unlightUnchecked(store)` — at start: breakpoints lit without the independent check become candidates again (D99).
+ */
+import type { Ledger } from '../ledger/index.ts';
+import type { LedgerService } from '../ledger/adapters.ts';
+import type { ProcessRunner } from '../keeper/organize/clerk.ts';
+import type { KEngines } from '../server/k-views.ts';
+import type { Project } from '../model/types.ts';
+import type { FourThingsView, PlanShapeView, ProcessStepView } from '../model/views-k.ts';
+import type { ProjectStore } from '../store/project-store.ts';
+import { analyze, type Analysis } from './analysis.ts';
+import type { Breakpoint } from '../model/k-types.ts';
+import { BREAKPOINT_KINDS, computeFindings, isCandidate, reconcile, type ReconcileResult } from './breakpoints.ts';
+import { generationPlanText } from './generations.ts';
+import { planShapeOf } from './plan.ts';
+import { advance, type SendBackResult } from './sendbacks.ts';
+import { clip } from './text.ts';
+import { stepOfThread } from './units.ts';
+import { fourThingsOf } from './work.ts';
+
+export { analyze } from './analysis.ts';
+export type { Analysis } from './analysis.ts';
+export { isCandidate, spotCheckTargets, spotCheckBlock, unlightUnchecked, type SpotCheckTargets } from './breakpoint-candidates.ts';
+
+// ───────────────────────── one work item, one plan ─────────────────────────
+
+/** A work item's steps and four things (§2.12). Null when the store has no such work item. */
+export function work(store: ProjectStore, project: Project, ledger: Ledger, workId: string): { readonly steps: readonly ProcessStepView[]; readonly four: FourThingsView } | null {
+  return workOf(analyze(store, project, ledger), workId);
+}
+
+function workOf(a: Analysis, workId: string): { readonly steps: readonly ProcessStepView[]; readonly four: FourThingsView } | null {
+  const p = a.process(workId);
+  if (!p) return null;
+  return { steps: p.steps, four: fourThingsOf(a.store, p, a.expecting(p.thread, 'Independent check') !== null) };
+}
+
+/** A plan's execution shape (§6.3, CKC-24 AC-2). Null when the store has no such `Plan` item. */
+export function plan(store: ProjectStore, project: Project, ledger: Ledger, planId: string): PlanShapeView | null {
+  return planShapeOf(analyze(store, project, ledger), planId);
+}
+
+/**
+ * The work item a work item is a step of — a fix or a check of it, however many fixes and checks lie between (AD,
+ * AF, AK and AO → AB) — so List and Graph fold it under that work; null for a piece of work of its own.
+ */
+export function stepOf(store: ProjectStore, project: Project, ledger: Ledger, workId: string): string | null {
+  return stepOfThread(analyze(store, project, ledger).index, workId);
+}
+
+// ───────────────────────── the round's program step ─────────────────────────
+
+/** The job of this round's `process` step, so what it writes is counted as the round's (clerk.ts `closeRound`). */
+function processJobOf(store: ProjectStore, roundId: string | null): string | null {
+  if (!roundId) return null;
+  return store.jobs.filter((j) => j.step?.roundId === roundId && j.step.kind === 'process').sort((a, b) => b.queuedAt.localeCompare(a.queuedAt))[0]?.id ?? null;
+}
+
+/**
+ * Recompute the candidates, keep what the spot-check lit and still holds, put out what no longer holds (§2.12, D99). The
+ * writes count under `jobId` when given (the main agent entering a stage), else under the round's process step.
+ */
+export function computeBreakpoints(store: ProjectStore, project: Project, ledger: Ledger, roundId: string | null, jobId?: string | null): ReconcileResult {
+  const a = analyze(store, project, ledger);
+  return reconcile(store, project.id, computeFindings(a), roundId, jobId === undefined ? processJobOf(store, roundId) : jobId);
+}
+
+/** Record the send-backs the project's failed checks and reviews started, and move every send-back on (§1.18). */
+export function advanceSendBacks(store: ProjectStore, project: Project, ledger: Ledger, roundId: string | null): SendBackResult {
+  return advance(analyze(store, project, ledger), roundId, processJobOf(store, roundId));
+}
+
+export interface ProcessRun {
+  readonly works: number;
+  readonly steps: number;
+  readonly sendBacks: SendBackResult;
+  readonly breakpoints: ReconcileResult;
+  readonly ms: number;
+  readonly note: string;
+}
+
+/**
+ * The whole step once, on one analysis: the breakpoints first, then the send-backs — a send-back that came from a
+ * breakpoint closes on the evidence that put the breakpoint out in the same round.
+ */
+export function runProcess(store: ProjectStore, project: Project, ledger: Ledger, roundId: string | null): ProcessRun {
+  const started = Date.now();
+  const jobId = processJobOf(store, roundId);
+  const a = analyze(store, project, ledger);
+  const breakpoints = reconcile(store, project.id, computeFindings(a), roundId, jobId);
+  const sendBacks = advance(a, roundId, jobId);
+  const threads = store.threads.all();
+  const steps = threads.reduce((n, t) => n + (a.process(t.id)?.steps.length ?? 0), 0);
+  const ms = Date.now() - started;
+  const kinds = BREAKPOINT_KINDS.filter((k) => breakpoints.litByKind[k]).map((k) => `${k} ${breakpoints.litByKind[k]}`).join(', ');
+  const leads = BREAKPOINT_KINDS.filter((k) => breakpoints.candidatesByKind[k]).map((k) => `${k} ${breakpoints.candidatesByKind[k]}`).join(', ');
+  const note = [
+    `${threads.length} work item${threads.length === 1 ? '' : 's'}, ${steps} step${steps === 1 ? '' : 's'} from the ledger`,
+    `breakpoints lit ${breakpoints.lit}${kinds ? ` (${kinds})` : ''}, candidates ${breakpoints.candidates}${leads ? ` (${leads})` : ''}, ${breakpoints.putOut} put out, ${breakpoints.keptOut} kept out`,
+    `send-backs: ${sendBacks.created} recorded from failed checks and reviews, ${sendBacks.returned} returned, ${sendBacks.closed} closed, ${sendBacks.open} open`,
+    `${(ms / 1000).toFixed(1)} s`,
+  ].join(' · ');
+  return { works: threads.length, steps, sendBacks, breakpoints, ms, note };
+}
+
+/** The round's program step (clerk.ts `ProcessRunner`): recompute each round, after the trunk and before the synthesis. */
+export function processRunner(ledgerService: LedgerService): ProcessRunner {
+  return {
+    run: async (store, project, roundId) => {
+      const ledger = ledgerService.ledger(project.id);
+      if (!ledger) return { note: 'The project has no ledger yet: no process, breakpoint or send-back was computed.' };
+      return { note: runProcess(store, project, ledger, roundId).note };
+    },
+  };
+}
+
+// ───────────────────────── the process view's engines ─────────────────────────
+
+/**
+ * What the store looks like to the engine: when any of what the processes read changed, the analysis is recomputed. The
+ * view asks for every work item in one request; one analysis serves them all.
+ */
+function storeMark(store: ProjectStore): string {
+  const part = (xs: readonly { readonly id: string; readonly updatedAt?: string }[]) => `${xs.length}:${xs.reduce((m, x) => ((x.updatedAt ?? '') > m ? x.updatedAt ?? '' : m), '')}`;
+  return [
+    part(store.threads.all()), part(store.reference.all()), part(store.relations.all()), part(store.rules.all()), part(store.generations.all()),
+    part(store.layers.all()),   // CZ: which documents list work decides what was carried on (carried-on.ts)
+    part(store.breakpoints.all()), part(store.sendbacks.all()), part(store.numbers.all().map((n) => ({ id: n.id, updatedAt: n.at }))),
+    part(store.links.all().map((l) => ({ id: `${l.id}${l.confirmed ? '+' : l.check?.passed ? '~' : ''}`, updatedAt: l.at }))), String(store.sources.size), String(store.patches.size),
+  ].join('|');
+}
+
+function ledgerMark(ledger: Ledger): string {
+  const r = ledger.db.prepare('SELECT max(id) id, max(ended_at) at FROM rebuilds').get() as { id: number | null; at: string | null } | undefined;
+  return `${r?.id ?? 0}:${r?.at ?? ''}`;
+}
+
+/** `KEngines.process` (server/k-views.ts): a work item's steps and four things, a plan's execution shape, what a work item
+ *  is a step of, and an earlier generation's plan document as it stood (§2.12, D82). */
+export function processEngines(ledgerService: LedgerService): NonNullable<KEngines['process']> {
+  const cache = new Map<string, { ledger: Ledger; store: ProjectStore; mark: string; analysis: Analysis }>();
+  const analysisOf = (store: ProjectStore, project: Project): Analysis | null => {
+    const ledger = ledgerService.ledger(project.id);
+    if (!ledger) return null;
+    const mark = `${ledgerMark(ledger)}#${storeMark(store)}`;
+    const hit = cache.get(project.id);
+    if (hit && hit.ledger === ledger && hit.store === store && hit.mark === mark) return hit.analysis;
+    const analysis = analyze(store, project, ledger);
+    cache.set(project.id, { ledger, store, mark, analysis });
+    return analysis;
+  };
+  return {
+    work: (store, project, workId) => {
+      try { const a = analysisOf(store, project); return a ? workOf(a, workId) : null; } catch { return null; }
+    },
+    plan: (store, project, planId) => {
+      try { const a = analysisOf(store, project); return a ? planShapeOf(a, planId) : null; } catch { return null; }
+    },
+    stepOf: (store, project, workId) => {
+      try { const a = analysisOf(store, project); return a ? stepOfThread(a.index, workId) : null; } catch { return null; }
+    },
+    generationPlan: (store, project, generationId, index, fromLine) => {
+      const ledger = ledgerService.ledger(project.id);
+      const g = store.generations.get(generationId);
+      if (!ledger || !g) return null;
+      try { return generationPlanText(ledger, store, g, index, fromLine ?? 1); } catch { return null; }
+    },
+  };
+}
+
+// ───────────────────────── the synthesis' block ─────────────────────────
+
+/**
+ * What the main agent and the synthesis are given of the program's process (§3.3, §2.12): the breakpoints lit — found
+ * missing after a lane looked and the spot-check confirmed (D99) — by kind and object, with their ids and evidence, the
+ * lines themselves; then, apart from them, the candidates, leads for reading and not findings; and the send-backs still
+ * open. The synthesis tags the six things and writes the notes and send-backs from the lit ones only.
+ */
+export function processBlock(store: ProjectStore, opts: { readonly candidates?: 'list' | 'count'; readonly answered?: number } = {}): string {
+  const name = (id: string) => {
+    const t = store.threads.get(id);
+    const r = t ? undefined : store.reference.get(id);
+    return t ? `${t.ids[0] ? `${t.ids[0]} ` : ''}${t.title}` : r ? `${r.category} ${r.name}` : id;
+  };
+  const evidence = (b: Breakpoint, lines: string[]) => {
+    for (const e of b.evidence.slice(0, 5)) lines.push(`  · ${e.kind} ${e.kind === 'file' ? e.label : e.id}${e.line ? `: “${clip(e.line, 160)}”` : ` (${clip(e.label, 100)})`}`);
+    if (b.evidence.length > 5) lines.push(`  · … ${b.evidence.length - 5} more`);
+  };
+  const lit = store.breakpoints.filter((b) => b.lit && !b.ownerResponse);
+  const leads = store.breakpoints.filter(isCandidate);
+  const lines: string[] = [`=== Process and breakpoints (computed by the program this round; ids to cite, lines as the material wrote them)`];
+  lines.push(`Breakpoints lit (${lit.length}) — a lane looked and the spot-check confirmed:`);
+  for (const kind of BREAKPOINT_KINDS) {
+    const of = lit.filter((b) => b.kind === kind).sort((x, y) => x.since.at.localeCompare(y.since.at));
+    if (of.length === 0) continue;
+    lines.push(`${kind} (${of.length})${of[0]!.sixThing ? ` — six thing ${of[0]!.sixThing}` : ''}:`);
+    for (const b of of) {
+      lines.push(`- ${b.id} on ${name(b.targetId)} (${b.targetId}) · ${b.basis}${b.basis === 'Inferred' ? ' (refute with pk_confirm if it does not hold)' : ''}${b.checked ? ` · checked ${b.checked.at.slice(0, 10)}` : b.confirmedInRoundId ? ' · confirmed' : ''}${b.sendBackId ? ` · send-back ${b.sendBackId}` : ''} · since ${b.since.at.slice(0, 10)}`);
+      lines.push(`  ${b.why}`);
+      evidence(b, lines);
+    }
+  }
+  // D103: the synthesis job gets the candidates' state as counts — a candidate is a clue it writes about as an open
+  // question, not a finding it judges one by one; the list comes on request (pk_round_state { list: "candidates" }).
+  if (opts.candidates === 'count') {
+    const looked = leads.filter((b) => b.looked).length;
+    const byKind = BREAKPOINT_KINDS.flatMap((kind) => { const n = leads.filter((b) => b.kind === kind).length; return n ? [`${kind} ${n}`] : []; });
+    lines.push(`Breakpoint candidates (${leads.length}) — leads, not findings; only the spot-check, which runs after you, lights one, and never in a First usable round: ${leads.length ? byKind.join(', ') : 'none'}. ${looked} of them a lane looked for and did not find (the spot-check checks those); ${leads.length - looked} nobody looked for yet${opts.answered !== undefined ? `; ${opts.answered} more were answered by this round's writes` : ''}. pk_round_state({ list: "candidates" }) lists those with no result; pk_read_assets kind breakpoint reads any.`);
+  }
+  if (opts.candidates !== 'count') lines.push(`Breakpoint candidates (${leads.length}) — leads, not findings: the program computed them from the ledger's ids and the links made so far, and what is written elsewhere it may have missed. Before anything is written as missing, a lane reads where the step would be written (execution arrangements, summaries, receipts, QC reports, the ledger, the code): found, it links it (pk_link_process); not found, it records where it looked (pk_record_looked). Only the spot-check lights one, and never in a First usable round:`);
+  for (const kind of opts.candidates === 'count' ? [] : BREAKPOINT_KINDS) {
+    const of = leads.filter((b) => b.kind === kind).sort((x, y) => x.since.at.localeCompare(y.since.at));
+    if (of.length === 0) continue;
+    lines.push(`${kind} (${of.length}):`);
+    for (const b of of) {
+      lines.push(`- ${b.id} on ${name(b.targetId)} (${b.targetId}) · ${b.basis}${b.looked ? ` · looked in ${clip(b.looked.where.join('; '), 200)}` : ' · not looked for yet'}`);
+      lines.push(`  ${b.why}`);
+      evidence(b, lines);
+    }
+  }
+  const open = store.sendbacks.filter((s) => s.stage !== 'Closed' && !s.ownerResponse).sort((x, y) => x.occurred.at.localeCompare(y.occurred.at));
+  lines.push(`Send-backs open (${open.length}):`);
+  for (const s of open) {
+    lines.push(`- ${s.id} · ${s.stage} · to ${s.to} · on ${name(s.targetId)} (${s.targetId}) · from ${s.from.kind} ${s.from.id}`);
+    lines.push(`  ${clip(s.what, 200)}${s.returned ? ` — returned by ${clip(s.returned.by.label, 100)}` : ''}`);
+  }
+  if (!lit.length && !leads.length && !open.length) lines.push('Nothing is lit, no candidate waits and no send-back is open.');
+  return lines.join('\n');
+}
+

package/src/process/integration.ts

@@ -0,0 +1,128 @@
+/**
+ * How each commit reached the trunk (Spec v3.0 §1.16 row 1; §2.12 `Merged`): the merges that brought it in, innermost
+ * first, and the branch each one names.
+ *
+ * A branch is often merged into an integration branch that is then merged into the trunk (ContextKeeper's k-clerk-tools
+ * → k-clerk → main). The ledger's `introducedBy` gives only the last of these, the trunk's merge, for everything under
+ * it; the merge a piece of work was integrated by is the innermost one — of the merges that brought a commit in, the one
+ * that brought in the fewest commits. A merge of the trunk into a branch (`Merge main into b-scope`, `Merge main (AQ)
+ * into k-clerk`) only keeps that branch up to date and integrates nothing: it is left out.
+ *
+ * The walk stays inside what each trunk merge brought in: a merge nested under it can only bring in commits of that set,
+ * so the cost follows the size of the branches, not of the whole history.
+ *
+ * Everything here is a fact of the ledger's commit graph; nothing is judged.
+ */
+import type { CommitFact, Facts } from './facts.ts';
+
+export interface Integration {
+  /** The merge commit. */
+  readonly merge: CommitFact;
+  /** The branch it merged, as its subject names it (`Merge branch 'k-longout'`, `Merge k-ayfix-a (…)`), else the branch whose tip is its second parent. */
+  readonly source: string | null;
+  /** The branch it merged into, when its subject says (`… into k-clerk`). */
+  readonly target: string | null;
+  /** Every commit it brought into its first parent's line (merges among them), by full hash. */
+  readonly brought: ReadonlySet<string>;
+}
+
+export interface Integrations {
+  /** The integrating merges, oldest first; the merges that only bring the trunk into a branch are not among them. */
+  readonly merges: readonly Integration[];
+  /** The innermost integrating merge of each commit one brought in. */
+  readonly innermost: ReadonlyMap<string, Integration>;
+  /** The integrating merges that brought a commit in, innermost first (the trunk's own merge last). */
+  chainOf(hash: string): readonly Integration[];
+  /** The trunk's own merge (on its first-parent line) that brought a commit in, or the commit itself when it is on that line. */
+  trunkMergeOf(hash: string): CommitFact | null;
+}
+
+/** The branch names a merge's subject gives: `Merge branch 'x' into y`, `Merge pull request #n from u/x`, `Merge x into y: …`, `Merge x (…)`. */
+export function mergeSubjectBranches(subject: string): { source: string | null; target: string | null } {
+  const s = subject.trim();
+  const quoted = /^Merge (?:remote-tracking )?branch(?:es)? '([^']+)'(?:\s+(?:of\s+\S+\s+)?into\s+'?([^'\s:(]+)'?)?/i.exec(s);
+  if (quoted) return { source: quoted[1]!, target: quoted[2] ?? null };
+  const pull = /^Merge pull request #\d+ from [^/\s]+\/(\S+)/i.exec(s);
+  if (pull) return { source: pull[1]!, target: null };
+  // `Merge k-clerk into k-ledger: …`, `Merge k-ayfix-a (…)`, `Merge k-clerk: …`, `Merge main (AQ) into k-clerk`.
+  const plain = /^Merge\s+([A-Za-z0-9][\w./-]*)(?=\s*(?:[:：(]|\binto\b|$))(?:\s*\([^)]*\))?(?:\s+into\s+([\w./-]+))?/i.exec(s);
+  if (plain && !/^(?:branch|branches|pull|remote-tracking)$/i.test(plain[1]!)) return { source: plain[1]!, target: plain[2] ?? null };
+  return { source: null, target: null };
+}
+
+const plainBranch = (name: string): string => name.replace(/^(?:refs\/)?(?:heads\/|remotes\/[^/]+\/|origin\/|upstream\/)/, '');
+
+/** Whether a branch name is the trunk of its repository (a merge of it into a branch only keeps that branch up to date). */
+function isTrunkName(name: string, trunk: string | null): boolean {
+  const n = plainBranch(name).toLowerCase();
+  return n === (trunk ?? '').toLowerCase() || n === 'main' || n === 'master' || n === 'trunk' || n === 'head';
+}
+
+export function integrationsOf(facts: Facts): Integrations {
+  const trunkName = new Map(facts.ledger.repos().map((r) => [r.id, r.trunk]));
+  const tipNames = new Map<string, string[]>();
+  for (const b of facts.branches) {
+    const name = b.namespace === 'remotes' ? b.name.replace(/^[^/]+\//, '') : b.name;
+    if (name === 'HEAD') continue;
+    tipNames.set(b.tip, [...new Set([...(tipNames.get(b.tip) ?? []), name])]);
+  }
+  // What each merge of the trunk's first-parent line brought in.
+  const members = new Map<string, Set<string>>();
+  for (const [h, by] of facts.introducedBy) {
+    if (h === by) continue;
+    const s = members.get(by) ?? new Set<string>();
+    s.add(h);
+    members.set(by, s);
+  }
+  /** Every commit reachable from `from` without leaving `inside`. */
+  const walk = (from: readonly string[], inside: ReadonlySet<string>, stop: ReadonlySet<string> | null): Set<string> => {
+    const seen = new Set<string>();
+    const stack = from.filter((h) => inside.has(h));
+    while (stack.length) {
+      const h = stack.pop()!;
+      if (seen.has(h) || stop?.has(h)) continue;
+      seen.add(h);
+      for (const p of facts.commits.get(h)?.parents ?? []) if (inside.has(p)) stack.push(p);
+    }
+    return seen;
+  };
+  const merges: Integration[] = [];
+  const describe = (c: CommitFact, brought: Set<string>): void => {
+    if (brought.size === 0) return;
+    const named = mergeSubjectBranches(c.subject);
+    const byTip = c.parents.slice(1).flatMap((p) => tipNames.get(p) ?? []).filter((n) => !isTrunkName(n, trunkName.get(c.repo) ?? null));
+    const source = named.source ?? byTip[0] ?? null;
+    if (source && isTrunkName(source, trunkName.get(c.repo) ?? null)) return;
+    merges.push({ merge: c, source: source ? plainBranch(source) : null, target: named.target ? plainBranch(named.target) : null, brought });
+  };
+  for (const [by, set] of members) {
+    const top = facts.commits.get(by);
+    if (!top || !top.merge) continue;
+    describe(top, set);
+    for (const h of set) {
+      const c = facts.commits.get(h)!;
+      if (!c.merge || c.parents.length < 2) continue;
+      const base = walk([c.parents[0]!], set, null);
+      describe(c, walk(c.parents.slice(1), set, base));
+    }
+  }
+  merges.sort((a, b) => a.merge.ms - b.merge.ms || a.merge.hash.localeCompare(b.merge.hash));
+  const chains = new Map<string, Integration[]>();
+  for (const m of merges) for (const h of m.brought) chains.set(h, [...(chains.get(h) ?? []), m]);
+  const innermost = new Map<string, Integration>();
+  for (const [h, list] of chains) {
+    list.sort((a, b) => a.brought.size - b.brought.size || a.merge.ms - b.merge.ms);
+    innermost.set(h, list[0]!);
+  }
+  return {
+    merges,
+    innermost,
+    chainOf: (hash) => chains.get(hash) ?? [],
+    trunkMergeOf(hash: string): CommitFact | null {
+      const c = facts.commits.get(hash);
+      if (!c || !c.onTrunk) return null;
+      const by = facts.introducedBy.get(hash);
+      return by ? facts.commits.get(by) ?? null : null;
+    },
+  };
+}

package/src/process/placement.ts

@@ -0,0 +1,107 @@
+/**
+ * Where a piece of work stands in a plan (Spec v3.0 §2.12 `Planned`, §6.3 execution shape): which `Plan` reference item
+ * it belongs to — by the relations the round recorded (`serves`, `implements`, `carries out`) — which batch of that
+ * plan it is, by its own arrangement's words (`批次 2`, `batch 6 of 7`, `批次 5b`), and the version of the plan document
+ * the plan's section first appears in.
+ */
+import type { ReferenceItem, WorkThread } from '../model/types.ts';
+import type { ProjectStore } from '../store/project-store.ts';
+import type { Occurred } from '../model/k-types.ts';
+import { pathKey } from '../util/paths.ts';
+import type { DocVersionFact, Facts } from './facts.ts';
+import type { Unit } from './units.ts';
+
+export interface BatchLabel {
+  /** The plan's batch number as the arrangement writes it (`5`). */
+  readonly batch: string;
+  /** A half or part of the batch (`a`, `b`, `前半`), when the work is one of several. */
+  readonly part: string | null;
+  /** The line it was read from. */
+  readonly line: string;
+}
+
+/** `批次 2`, `批次 5a`, `第 3 批`, `batch 6 of 7`, `Batch 5b`, `批次 5 前半`. */
+const BATCH = /批次\s*(\d{1,3})\s*([a-z]|[前后上下]半)?|第\s*(\d{1,3})\s*批\s*([a-z])?|\bbatch(?:es)?\s*(\d{1,3})\s*([a-z])?\b(?:\s*of\s*\d{1,3})?/i;
+
+export function batchOf(unit: Unit): BatchLabel | null {
+  const latest = unit.prompts[unit.prompts.length - 1];
+  const candidates = [unit.title ?? '', unit.fields.milestone ?? '', unit.fields.batch ?? '', ...(latest?.data.batches ?? []).slice(0, 3)];
+  for (const text of candidates) {
+    const m = BATCH.exec(text);
+    if (!m) continue;
+    const batch = m[1] ?? m[3] ?? m[5];
+    if (!batch) continue;
+    const part = m[2] ?? m[4] ?? m[6] ?? null;
+    return { batch, part: part ? part.toLowerCase() : null, line: text };
+  }
+  return null;
+}
+
+/** The `Plan` reference items a work item belongs to, by the round's relations. */
+export function plansOf(store: ProjectStore, thread: WorkThread): ReferenceItem[] {
+  const ids = new Set<string>();
+  for (const s of thread.serves) ids.add(s.referenceId);
+  for (const r of store.relations.all()) if (r.from === thread.id && (r.type === 'serves' || r.type === 'implements' || r.type === 'carries out' || r.type === 'refines')) ids.add(r.to);
+  return [...ids].flatMap((id) => { const r = store.reference.get(id); return r && r.category === 'Plan' ? [r] : []; });
+}
+
+/** The work items a plan names, by the round's relations (the thread side and the graph side). */
+export function workOfPlan(store: ProjectStore, planId: string): WorkThread[] {
+  const out = new Map<string, WorkThread>();
+  for (const t of store.threads.all()) if (t.serves.some((s) => s.referenceId === planId)) out.set(t.id, t);
+  for (const r of store.relations.all()) {
+    if (r.to !== planId || !(r.type === 'serves' || r.type === 'implements' || r.type === 'carries out' || r.type === 'refines')) continue;
+    const t = store.threads.get(r.from);
+    if (t) out.set(t.id, t);
+  }
+  return [...out.values()];
+}
+
+export interface PlanDocument {
+  readonly repo: string;
+  readonly path: string;
+  /** The heading path of the plan's section in the document ("Title › 11. 实施顺序"), or null for the whole document. */
+  readonly section: string | null;
+  readonly headingPath: readonly string[];
+  /** The version the section first appears in. */
+  readonly first: DocVersionFact | null;
+  /** The version the checkout has. */
+  readonly current: DocVersionFact | null;
+}
+
+/** The document (and section) a plan item was read from, located in the ledger's document history. */
+export function planDocument(store: ProjectStore, facts: Facts, plan: ReferenceItem): PlanDocument | null {
+  const repos = facts.ledger.repos();
+  for (const sid of plan.sourceIds) {
+    const s = store.sources.get(sid);
+    if (!s) continue;
+    const a = s.anchor;
+    let repo: string | null = null;
+    let rel: string | null = null;
+    let headingPath: readonly string[] = [];
+    if (a.kind === 'file') {
+      const at = facts.relPathOf(a.path);
+      if (!at) continue;
+      repo = at.repo;
+      rel = at.path;
+      headingPath = a.headingPath;
+    } else if (a.kind === 'revision') {
+      const r = repos.find((x) => pathKey(x.path) === pathKey(a.repo)) ?? repos.find((x) => facts.relPathOf(a.repo)?.repo === x.id);
+      if (!r) continue;
+      repo = r.id;
+      rel = a.path;
+    } else continue;
+    const versions = (facts.docsByPath.get(rel) ?? []).filter((d) => d.repo === repo);
+    if (versions.length === 0) continue;
+    const section = headingPath.length ? headingPath.join(' › ') : null;
+    const first = section ? versions.find((d) => d.added.includes(section) || d.changed.includes(section)) ?? versions[0]! : versions[0]!;
+    const current = [...versions].reverse().find((d) => d.current) ?? null;
+    return { repo, path: rel, section, headingPath, first, current };
+  }
+  return null;
+}
+
+/** When a plan document version happened: the ledger's own time for it. */
+export function versionOccurred(facts: Facts, v: DocVersionFact): Occurred {
+  return facts.entry(v.id)?.occurred ?? { at: new Date(v.ms).toISOString(), basis: 'Commit', anchor: v.id };
+}