elanous 0.2.0 → 0.2.5

package/src/intake-plane/intake-to-tasks.ts

@@ -0,0 +1,303 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { debug } from '../debug/log.js';
+import type { TaskPriority } from '../task-orchestrator/types.js';
+import { TASK_DEFAULTS } from '../task-orchestrator/types.js';
+import { intakeLedgerDir, listIntakeItems, type IntakeItem } from './items.js';
+import { intakeOutboxDir } from './route.js';
+
+export interface IntakeTaskRequest {
+  title: string;
+  description: string;
+  priority: Exclude<TaskPriority, 'urgent'>;
+  type?: IntakeTaskType;
+  acceptance?: { criteria: string[] };
+  external: { provider: 'intake'; ref: string; url?: string };
+}
+
+export interface IntakeTaskInterpretation {
+  title: string;
+  description: string;
+  priority: Exclude<TaskPriority, 'urgent'>;
+}
+
+export type IntakeTaskType = 'implement' | 'research' | 'document' | 'operate';
+
+export interface IntakeInputTask extends IntakeTaskInterpretation {
+  type: IntakeTaskType;
+  acceptanceCriteria: string[];
+}
+
+export interface IntakeInputInterpretation {
+  tasks: IntakeInputTask[];
+  questions: string[];
+}
+
+export function interpretIntakeInput(response: string): IntakeInputInterpretation | null {
+  const text = response.trim();
+  const fenced = text.match(/^```(?:json)?\s*\n([\s\S]*?)\n```$/);
+  if (text.startsWith('```') && !fenced) return null;
+  let raw: unknown;
+  try { raw = JSON.parse(fenced ? fenced[1] : text); }
+  catch { return null; }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const value = raw as Record<string, unknown>;
+  if (!Array.isArray(value.tasks) || !Array.isArray(value.questions)) return null;
+
+  const questions = value.questions.filter((question): question is string => typeof question === 'string' && question.trim().length > 0)
+    .map((question) => question.trim());
+  const tasks: IntakeInputTask[] = [];
+  for (const candidate of value.tasks) {
+    if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) continue;
+    const task = candidate as Record<string, unknown>;
+    if (task.type !== 'implement' && task.type !== 'research' && task.type !== 'document' && task.type !== 'operate') continue;
+    if (typeof task.title !== 'string' || !task.title.trim() || task.title.trim().length > TASK_DEFAULTS.titleMaxLen) continue;
+    if (typeof task.description !== 'string' || task.description.length > TASK_DEFAULTS.descriptionMaxLen) continue;
+    if (task.priority !== 'low' && task.priority !== 'medium' && task.priority !== 'high') continue;
+    if (!Array.isArray(task.acceptanceCriteria) || !task.acceptanceCriteria.some((criterion) => typeof criterion === 'string' && criterion.trim())) {
+      questions.push(task.title.trim());
+      continue;
+    }
+    if (tasks.length < 3) tasks.push({
+      type: task.type,
+      title: task.title.trim(),
+      description: task.description,
+      priority: task.priority,
+      acceptanceCriteria: task.acceptanceCriteria.filter((criterion): criterion is string => typeof criterion === 'string' && criterion.trim().length > 0)
+        .map((criterion) => criterion.trim()),
+    });
+  }
+  return { tasks, questions };
+}
+
+export type IntakeTaskInput =
+  | { kind: 'goal-line'; id: string; fact: string; current: string; url?: string }
+  | { kind: 'idea-note'; id: string; content: string; url?: string };
+
+export interface IntakeToTasksDeps {
+  llm: (input: IntakeTaskInput) => Promise<string>;
+  post: (request: IntakeTaskRequest) => Promise<{ taskId: string; deduplicated?: boolean }>;
+  list?: typeof listIntakeItems;
+  readNote?: (path: string) => string;
+}
+
+export interface IntakeToTasksResult {
+  processed: number;
+  created: number;
+  skipped: number;
+  failed: number;
+  items: Array<{ id: string; status: 'created' | 'deduplicated' | 'dry-run' | 'skipped' | 'failed'; taskId?: string; types?: IntakeTaskType[]; reason?: string }>;
+}
+
+export function interpretIntakeItem(response: string): IntakeTaskInterpretation | null {
+  const text = response.trim();
+  const fenced = text.match(/^```(?:json)?\s*\n([\s\S]*?)\n```$/);
+  if (text.startsWith('```') && !fenced) return null;
+  let raw: unknown;
+  try { raw = JSON.parse(fenced ? fenced[1] : text); }
+  catch { return null; }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const value = raw as Record<string, unknown>;
+  if (typeof value.title !== 'string') return null;
+  const title = value.title.trim();
+  if (!title || title.length > TASK_DEFAULTS.titleMaxLen) return null;
+  if (typeof value.description !== 'string' || value.description.length > TASK_DEFAULTS.descriptionMaxLen) return null;
+  if (value.priority !== 'low' && value.priority !== 'medium' && value.priority !== 'high') return null;
+  return { title, description: value.description, priority: value.priority };
+}
+
+export function toIntakeTaskRequest(item: IntakeItem, interpretation: IntakeTaskInterpretation): IntakeTaskRequest {
+  return {
+    ...interpretation,
+    external: { provider: 'intake', ref: item.id, ...(item.url ? { url: item.url } : {}) },
+  };
+}
+
+function goalLineId(file: string, index: number): string {
+  return `goal:${createHash('sha256').update(`${file}:${index}`).digest('hex').slice(0, 16)}`;
+}
+
+function consumedFile(root: string): string { return join(intakeLedgerDir(root), 'to-tasks.jsonl'); }
+
+interface SavedTaskPlan {
+  inputId: string;
+  tasks: IntakeInputTask[];
+  completed: Array<{ taskId: string; deduplicated: boolean } | null>;
+}
+
+function planFile(root: string, id: string): string {
+  return join(intakeLedgerDir(root), 'to-tasks-plans', `${createHash('sha256').update(id).digest('hex')}.json`);
+}
+
+function loadTaskPlan(root: string, id: string): SavedTaskPlan | null {
+  const path = planFile(root, id);
+  if (!existsSync(path)) return null;
+  const raw: unknown = JSON.parse(readFileSync(path, 'utf8'));
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('invalid saved task plan');
+  const value = raw as Record<string, unknown>;
+  if (value.inputId !== id || !Array.isArray(value.completed) || !Array.isArray(value.tasks)
+    || value.tasks.length < 1 || value.tasks.length > 3 || value.completed.length !== value.tasks.length) {
+    throw new Error('invalid saved task plan');
+  }
+  const parsed = interpretIntakeInput(JSON.stringify({ tasks: value.tasks, questions: [] }));
+  if (!parsed || parsed.tasks.length !== value.tasks.length
+    || value.completed.some((entry) => entry !== null && (!entry || typeof entry !== 'object' || Array.isArray(entry)
+      || typeof entry.taskId !== 'string' || !entry.taskId || typeof entry.deduplicated !== 'boolean'))) {
+    throw new Error('invalid saved task plan');
+  }
+  return { inputId: id, tasks: parsed.tasks, completed: value.completed as SavedTaskPlan['completed'] };
+}
+
+function saveTaskPlan(root: string, plan: SavedTaskPlan): void {
+  const path = planFile(root, plan.inputId);
+  mkdirSync(join(intakeLedgerDir(root), 'to-tasks-plans'), { recursive: true });
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  writeFileSync(temporary, JSON.stringify(plan));
+  renameSync(temporary, path);
+}
+
+function consumedInputs(root: string): Set<string> {
+  const file = consumedFile(root);
+  if (!existsSync(file)) return new Set();
+  const ids = new Set<string>();
+  for (const line of readFileSync(file, 'utf8').split('\n')) {
+    try {
+      const row: unknown = JSON.parse(line);
+      if (row && typeof row === 'object' && 'id' in row && typeof row.id === 'string') ids.add(row.id);
+    } catch { /* ignore incomplete ledger lines */ }
+  }
+  return ids;
+}
+
+function goalLines(root: string): IntakeTaskInput[] {
+  const dir = join(intakeOutboxDir(root), 'goals');
+  if (!existsSync(dir)) return [];
+  const rows: IntakeTaskInput[] = [];
+  for (const file of readdirSync(dir).filter((name) => /^\d{4}-\d{2}-\d{2}\.jsonl$/.test(name)).sort()) {
+    readFileSync(join(dir, file), 'utf8').split('\n').forEach((line, index) => {
+      try {
+        const value: unknown = JSON.parse(line);
+        if (!value || typeof value !== 'object' || Array.isArray(value)) return;
+        const row = value as Record<string, unknown>;
+        if (typeof row.fact !== 'string' || !row.fact.trim()) return;
+        rows.push({ kind: 'goal-line', id: goalLineId(file, index), fact: row.fact, current: typeof row.current === 'string' ? row.current : '',
+          ...(typeof row.url === 'string' ? { url: row.url } : {}) });
+      } catch { /* ignore malformed outbox lines */ }
+    });
+  }
+  return rows;
+}
+
+function noteRoutingHistory(root: string): { eligible: Set<string>; legacyPosted: Set<string> } {
+  const file = join(intakeLedgerDir(root), 'items.jsonl');
+  if (!existsSync(file)) return { eligible: new Set(), legacyPosted: new Set() };
+  const previous = new Map<string, string>();
+  const eligible = new Set<string>();
+  const legacyPosted = new Set<string>();
+  for (const line of readFileSync(file, 'utf8').split('\n')) {
+    try {
+      const row: unknown = JSON.parse(line);
+      if (!row || typeof row !== 'object' || Array.isArray(row)) continue;
+      const item = row as Record<string, unknown>;
+      if (typeof item.id !== 'string' || typeof item.status !== 'string') continue;
+      const prior = previous.get(item.id);
+      if (item.status === 'routed' && prior !== 'routed') {
+        // Old to-tasks changed queued → routed after POST under item.id. Route uses absorbed → routed.
+        if (prior === 'queued') legacyPosted.add(item.id);
+        if ((prior === 'absorbed' || prior === 'checked') && !legacyPosted.has(item.id)) eligible.add(item.id);
+        else eligible.delete(item.id);
+      }
+      previous.set(item.id, item.status);
+    } catch { /* ignore incomplete ledger lines */ }
+  }
+  for (const id of legacyPosted) eligible.delete(id);
+  return { eligible, legacyPosted };
+}
+
+function ideaNotes(root: string, deps: IntakeToTasksDeps): Array<{ input: IntakeTaskInput; path: string }> {
+  const { eligible: routedNotes, legacyPosted } = noteRoutingHistory(root);
+  return (deps.list ?? listIntakeItems)(root)
+    .filter((item) => !legacyPosted.has(item.id) && (item.status === 'absorbed' || (item.status === 'routed' && routedNotes.has(item.id))) && item.privacy === 'public'
+      && item.outputs.some((output) => output.kind === 'note' && isAbsolute(output.ref))
+      && !item.outputs.some((output) => output.kind === 'goal'))
+    .sort((a, b) => a.observedAt.localeCompare(b.observedAt) || a.id.localeCompare(b.id))
+    .map((item) => ({ input: { kind: 'idea-note' as const, id: `note:${item.id}`, content: '',
+      ...(item.url ? { url: item.url } : {}) },
+      path: [...item.outputs].reverse().find((output) => output.kind === 'note' && isAbsolute(output.ref))!.ref }));
+}
+
+export async function runIntakeToTasks(
+  instanceRoot: string,
+  opts: { limit?: number; dryRun?: boolean },
+  deps: IntakeToTasksDeps,
+): Promise<IntakeToTasksResult> {
+  const limit = opts.limit ?? 5;
+  if (!Number.isSafeInteger(limit) || limit < 0) throw new RangeError('limit must be a non-negative integer');
+  if (limit === 0) return { processed: 0, created: 0, skipped: 0, failed: 0, items: [] };
+  const consumed = consumedInputs(instanceRoot);
+  const selected: Array<{ input: IntakeTaskInput; path?: string }> = [...goalLines(instanceRoot).map((input) => ({ input })), ...ideaNotes(instanceRoot, deps)]
+    .filter(({ input }) => !consumed.has(input.id)).slice(0, limit);
+  const result: IntakeToTasksResult = { processed: selected.length, created: 0, skipped: 0, failed: 0, items: [] };
+  for (const { input, path } of selected) {
+    try {
+      let plan = loadTaskPlan(instanceRoot, input.id);
+      if (!plan) {
+        let safeInput = input;
+        if (input.kind === 'idea-note') {
+          try {
+            const content = (deps.readNote ?? ((notePath: string) => readFileSync(notePath, 'utf8')))(path!);
+            if (!content.trim()) throw new Error('empty note');
+            safeInput = { ...input, content: content.slice(0, 12_000) };
+          } catch {
+            result.skipped++;
+            result.items.push({ id: input.id, status: 'skipped', reason: 'note-read-failed' });
+            continue;
+          }
+        }
+        const interpreted = interpretIntakeInput(await deps.llm(safeInput));
+        if (!interpreted || (!interpreted.tasks.length && !interpreted.questions.length)) {
+          result.skipped++;
+          result.items.push({ id: input.id, status: 'skipped', reason: 'invalid-llm-response' });
+          continue;
+        }
+        if (interpreted.tasks.length === 0) {
+          result.skipped++;
+          result.items.push({ id: input.id, status: 'skipped', reason: 'needs-clarification' });
+          continue;
+        }
+        plan = { inputId: input.id, tasks: interpreted.tasks, completed: interpreted.tasks.map(() => null) };
+        if (!opts.dryRun) saveTaskPlan(instanceRoot, plan);
+      }
+      if (opts.dryRun) {
+        result.items.push({ id: input.id, status: 'dry-run', types: plan.tasks.map((task) => task.type) });
+        continue;
+      }
+      for (const [index, task] of plan.tasks.entries()) {
+        if (plan.completed[index]) continue;
+        const request: IntakeTaskRequest = {
+          title: task.title, description: task.description, priority: task.priority,
+          type: task.type, acceptance: { criteria: task.acceptanceCriteria },
+          external: { provider: 'intake', ref: `${input.id}:${index}`, ...(input.url ? { url: input.url } : {}) },
+        };
+        const response = await deps.post(request);
+        if (!response.taskId) throw new Error('Nexus returned no taskId');
+        plan.completed[index] = { taskId: response.taskId, deduplicated: !!response.deduplicated };
+        saveTaskPlan(instanceRoot, plan);
+        if (!response.deduplicated) result.created++;
+      }
+      const allDeduplicated = plan.completed.every((entry) => entry?.deduplicated);
+      const lastTaskId = plan.completed.at(-1)?.taskId;
+      if (!lastTaskId) throw new Error('incomplete saved task plan');
+      mkdirSync(intakeLedgerDir(instanceRoot), { recursive: true });
+      appendFileSync(consumedFile(instanceRoot), JSON.stringify({ id: input.id, taskId: lastTaskId }) + '\n');
+      result.items.push({ id: input.id, status: allDeduplicated ? 'deduplicated' : 'created', taskId: lastTaskId,
+        types: plan.tasks.map((task) => task.type) });
+    } catch {
+      result.failed++;
+      result.items.push({ id: input.id, status: 'failed', reason: 'intake-to-tasks request failed' });
+      debug.log('intake.to-tasks', 'failed', { id: input.id });
+    }
+  }
+  return result;
+}

package/src/intake-plane/items.ts

@@ -0,0 +1,247 @@
+// 정기 외부 흡수 원장 — 입력원마다 모양이 다른 것을 `IntakeItem` 한 모양 · 원장 하나로 모은다.
+// 설계 = 내부 문서 `RFC-regular-external-intake-and-normalization-pipeline-2026-09-26` §3 (① 모양 맞추기 · ② 중복 없애기).
+import { createHash } from 'node:crypto';
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { debug } from '../debug/log.js';
+
+export const INTAKE_SOURCES = ['x', 'youtube', 'github', 'telegram-saved', 'telegram-bot', 'memo', 'pwa'] as const;
+export type IntakeSource = typeof INTAKE_SOURCES[number];
+export type IntakeKind = 'video' | 'repo' | 'post' | 'article' | 'note';
+export type IntakePrivacy = 'public' | 'user-private';
+export const INTAKE_STATUSES = ['new', 'queued', 'absorbed', 'checked', 'routed', 'discarded', 'deferred'] as const;
+export type IntakeStatus = typeof INTAKE_STATUSES[number];
+
+export interface IntakeItem {
+  id: string;
+  source: IntakeSource;
+  /** 같은 항목이 다른 입력원에서도 왔으면 여기 모인다 — «두 입력원에서 동시에 뜬 것»이 신호다. */
+  sources: IntakeSource[];
+  url?: string;
+  kind: IntakeKind;
+  title?: string;
+  text?: string;
+  observedAt: string;
+  lastSeenAt: string;
+  /** `<입력원>.<신호>` → 마지막으로 본 값 */
+  signals: Record<string, number>;
+  axis?: string;
+  judgement?: { axis: string; axisConf: number; promo: number; learn: number };
+  privacy: IntakePrivacy;
+  status: IntakeStatus;
+  outputs: { kind: 'note' | 'goal' | 'manual' | 'release' | 'grounding'; ref: string }[];
+}
+
+/** 수집기가 내는 한 줄 — 모양 맞추기 전. */
+export interface RawIntakeItem {
+  url?: string;
+  title?: string;
+  text?: string;
+  kind?: IntakeKind;
+  observedAt?: string;
+  signals?: Record<string, number>;
+  axis?: string;
+  judgement?: IntakeItem['judgement'];
+}
+
+const TRACKING_PARAMS = /^(utm_[a-z]+|fbclid|gclid|igshid|si|feature|ref_src|ref_url|s|mc_cid|mc_eid)$/i;
+
+/** 정규 URL — 같은 대상이 다른 모양으로 와도 같은 id 가 되게. 해석 못 하면 undefined. */
+export function canonicalUrl(raw: string): string | undefined {
+  let u: URL;
+  try { u = new URL(raw.trim()); } catch { return undefined; }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') return undefined;
+  const host = u.hostname.toLowerCase().replace(/^(www|m|mobile)\./, '');
+  const path = u.pathname.replace(/\/+$/, '');
+  // YouTube — youtu.be · shorts · live · embed · watch 를 watch?v= 로
+  const yt = host === 'youtu.be' ? path.slice(1)
+    : /(^|\.)youtube\.com$/.test(host)
+      ? (u.searchParams.get('v') ?? path.match(/^\/(?:shorts|live|embed|v)\/([^/]+)/)?.[1])
+      : undefined;
+  if (yt && /^[A-Za-z0-9_-]{11}$/.test(yt)) return `https://www.youtube.com/watch?v=${yt}`;
+  // X — 사용자 이름은 바뀔 수 있으니 status id 로
+  if (host === 'x.com' || host === 'twitter.com') {
+    const id = path.match(/\/status(?:es)?\/(\d+)/)?.[1];
+    if (id) return `https://x.com/i/status/${id}`;
+  }
+  // GitHub — 저장소 단위(owner/repo)로 · 대소문자 무시
+  if (host === 'github.com') {
+    const m = path.match(/^\/([^/]+)\/([^/]+)/);
+    if (m && !['orgs', 'topics', 'search', 'settings', 'marketplace', 'features'].includes(m[1].toLowerCase())) {
+      return `https://github.com/${m[1].toLowerCase()}/${m[2].toLowerCase().replace(/\.git$/, '')}`;
+    }
+  }
+  const params = [...u.searchParams.entries()].filter(([k]) => !TRACKING_PARAMS.test(k)).sort(([a], [b]) => a.localeCompare(b));
+  const q = params.length ? `?${new URLSearchParams(params).toString()}` : '';
+  return `https://${host}${path}${q}`;
+}
+
+export function intakeItemId(source: IntakeSource, raw: Pick<RawIntakeItem, 'url' | 'text'>): string {
+  const url = raw.url ? canonicalUrl(raw.url) : undefined;
+  const basis = url ?? `${source}:${(raw.text ?? '').trim().slice(0, 200)}`;
+  return createHash('sha256').update(basis).digest('hex').slice(0, 16);
+}
+
+function kindFor(source: IntakeSource, url: string | undefined): IntakeKind {
+  if (url?.startsWith('https://www.youtube.com/')) return 'video';
+  if (url?.startsWith('https://github.com/')) return 'repo';
+  if (url?.startsWith('https://x.com/')) return 'post';
+  if (!url) return 'note';
+  return source === 'x' ? 'post' : 'article';
+}
+
+/** 개인 메모 입력원은 user-private — 원문을 바깥 LLM 에 보내지 않는다(RFC §3.4). PWA 칸에 사람이 쓴 글도 같다(RFC-pwa-intake-front-door). */
+export function privacyFor(source: IntakeSource): IntakePrivacy {
+  return source === 'telegram-saved' || source === 'memo' || source === 'pwa' ? 'user-private' : 'public';
+}
+
+/** ① 모양 맞추기 — 수집기 한 줄 → IntakeItem. 비어 있으면(URL·본문 둘 다 없음) null. */
+export function shapeIntakeItem(source: IntakeSource, raw: RawIntakeItem, now: string): IntakeItem | null {
+  const url = raw.url ? canonicalUrl(raw.url) : undefined;
+  const text = raw.text?.trim() || undefined;
+  if (!url && !text) return null;
+  const observedAt = raw.observedAt ?? now;
+  const signals: Record<string, number> = {};
+  for (const [k, v] of Object.entries(raw.signals ?? {})) if (Number.isFinite(v)) signals[`${source}.${k}`] = v;
+  return {
+    id: intakeItemId(source, { url, text }),
+    source,
+    sources: [source],
+    ...(url ? { url } : {}),
+    kind: raw.kind ?? kindFor(source, url),
+    ...(raw.title?.trim() ? { title: raw.title.trim().slice(0, 300) } : {}),
+    ...(text ? { text: text.slice(0, 2000) } : {}),
+    observedAt,
+    lastSeenAt: observedAt,
+    signals,
+    ...(raw.axis ? { axis: raw.axis } : {}),
+    ...(raw.judgement ? { judgement: raw.judgement } : {}),
+    privacy: privacyFor(source),
+    status: 'new',
+    outputs: [],
+  };
+}
+
+export function intakeLedgerDir(instanceRoot: string): string { return join(instanceRoot, 'intake'); }
+function ledgerFile(instanceRoot: string): string { return join(intakeLedgerDir(instanceRoot), 'items.jsonl'); }
+
+/** 원장 = 덧붙이기만 하는 줄 목록 · 같은 id 는 마지막 줄이 이긴다. 깨진 줄은 건너뛰고 센다. */
+export function loadIntakeLedger(instanceRoot: string): { items: Map<string, IntakeItem>; badLines: number } {
+  const items = new Map<string, IntakeItem>();
+  let badLines = 0;
+  const file = ledgerFile(instanceRoot);
+  if (!existsSync(file)) return { items, badLines };
+  for (const line of readFileSync(file, 'utf8').split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const item = JSON.parse(line) as IntakeItem;
+      if (item && typeof item.id === 'string') items.set(item.id, item); else badLines++;
+    } catch { badLines++; }
+  }
+  return { items, badLines };
+}
+
+function appendItems(instanceRoot: string, items: IntakeItem[]): void {
+  if (!items.length) return;
+  mkdirSync(intakeLedgerDir(instanceRoot), { recursive: true });
+  appendFileSync(ledgerFile(instanceRoot), items.map((i) => JSON.stringify(i)).join('\n') + '\n');
+}
+
+export interface IngestResult { shaped: number; added: number; merged: number; seen: number; skipped: number; badLines: number }
+
+const SETTLED: ReadonlySet<IntakeStatus> = new Set(['absorbed', 'discarded', 'routed', 'checked']);
+
+/**
+ * ② 중복 없애기 — 같은 id 는 새 항목을 만들지 않고 신호·입력원을 합친다.
+ * 이미 흡수·버림·갈래가 끝난 것은 «seen» 으로 세고 상태를 되돌리지 않는다(다시 올리지 않는다).
+ */
+export function ingestIntakeItems(instanceRoot: string, source: IntakeSource, raws: RawIntakeItem[], now = new Date().toISOString(),
+  log: (event: string, data: Record<string, unknown>) => void = (e, d) => { debug.log('intake.normalize', e, d); }): IngestResult {
+  const { items: existing, badLines } = loadIntakeLedger(instanceRoot);
+  const result: IngestResult = { shaped: 0, added: 0, merged: 0, seen: 0, skipped: 0, badLines };
+  const writes = new Map<string, IntakeItem>();
+  for (const raw of raws) {
+    const shaped = shapeIntakeItem(source, raw, now);
+    if (!shaped) { result.skipped++; continue; }
+    result.shaped++;
+    const prev = writes.get(shaped.id) ?? existing.get(shaped.id);
+    if (!prev) { writes.set(shaped.id, shaped); result.added++; continue; }
+    const merged: IntakeItem = {
+      ...prev,
+      sources: [...new Set([...prev.sources, source])],
+      lastSeenAt: now,
+      signals: { ...prev.signals, ...shaped.signals },
+      title: prev.title ?? shaped.title,
+      text: prev.text ?? shaped.text,
+      axis: shaped.axis ?? prev.axis,
+      judgement: shaped.judgement ?? prev.judgement,
+      // 한 번이라도 개인 입력원에서 왔으면 개인으로 남긴다(공개로 풀지 않는다).
+      privacy: prev.privacy === 'user-private' || shaped.privacy === 'user-private' ? 'user-private' : 'public',
+    };
+    writes.set(shaped.id, merged);
+    if (SETTLED.has(prev.status)) result.seen++; else result.merged++;
+  }
+  appendItems(instanceRoot, [...writes.values()]);
+  log('ingested', { source, ...result });
+  return result;
+}
+
+/** 상태·산출 갱신 — 흡수 뒤 `absorbed` · 노트 경로 등. 없는 id 면 false. */
+export function markIntakeItem(instanceRoot: string, id: string, patch: { status?: IntakeStatus; output?: IntakeItem['outputs'][number] },
+  now = new Date().toISOString()): boolean {
+  const { items } = loadIntakeLedger(instanceRoot);
+  const prev = items.get(id);
+  if (!prev) return false;
+  const next: IntakeItem = {
+    ...prev,
+    ...(patch.status ? { status: patch.status } : {}),
+    outputs: patch.output ? [...prev.outputs, patch.output] : prev.outputs,
+    lastSeenAt: now,
+  };
+  appendItems(instanceRoot, [next]);
+  debug.log('intake.normalize', 'item-marked', { id, status: next.status, output: patch.output?.kind });
+  return true;
+}
+
+export function listIntakeItems(instanceRoot: string, filter: { status?: IntakeStatus; source?: IntakeSource } = {}): IntakeItem[] {
+  return [...loadIntakeLedger(instanceRoot).items.values()]
+    .filter((i) => (!filter.status || i.status === filter.status) && (!filter.source || i.sources.includes(filter.source)))
+    .sort((a, b) => b.lastSeenAt.localeCompare(a.lastSeenAt));
+}
+
+/** 수집기 산출(JSONL · 한 줄 = RawIntakeItem) 읽기. 깨진 줄은 세고 건너뛴다. */
+export function parseRawIntakeJsonl(text: string): { raws: RawIntakeItem[]; bad: number } {
+  const raws: RawIntakeItem[] = [];
+  let bad = 0;
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    try { const o = JSON.parse(line); if (o && typeof o === 'object') raws.push(o as RawIntakeItem); else bad++; } catch { bad++; }
+  }
+  return { raws, bad };
+}
+
+/**
+ * 자동 흡수 대기열 — 텔레그램 저장 링크는 별도 레인(기본 30), 일반 몫은 하루 상한(기본 10). RFC §4 O1.
+ * 레인이 먼저. 각 몫 안에서는 사용자가 직접 남긴 것(메모 포함) → 여러 입력원 → 점수(`*.score`) → 최근에 본 것.
+ * 고른 항목은 `queued` 로 옮겨 다음 판에 다시 고르지 않는다(흡수 뒤 `absorbed`, 실패는 `deferred`).
+ */
+const STALE_QUEUED_MS = 24 * 3600_000;
+
+export function pickAbsorbQueue(instanceRoot: string, opts: { max: number; laneMax?: number; kind?: IntakeKind; dryRun?: boolean }, now = new Date().toISOString()): IntakeItem[] {
+  const userLeft = (i: IntakeItem) => i.sources.some((s) => s === 'telegram-saved' || s === 'memo');
+  const score = (i: IntakeItem) => Math.max(0, ...Object.entries(i.signals).filter(([k]) => k.endsWith('.score')).map(([, v]) => v));
+  const eligible = [...loadIntakeLedger(instanceRoot).items.values()]
+    // queued 로 옮긴 뒤 흡수·표시가 없이 하루가 지난 것(흡수 도중 죽은 판)은 다시 고른다.
+    .filter((i) => (i.status === 'new' || (i.status === 'queued' && Date.parse(now) - Date.parse(i.lastSeenAt) > STALE_QUEUED_MS))
+      && !!i.url && (!opts.kind || i.kind === opts.kind))
+    .sort((a, b) => Number(userLeft(b)) - Number(userLeft(a)) || b.sources.length - a.sources.length || score(b) - score(a) || b.lastSeenAt.localeCompare(a.lastSeenAt));
+  const laneMax = opts.laneMax ?? 30;
+  const lane = eligible.filter((i) => i.sources.includes('telegram-saved')).slice(0, Math.max(0, laneMax));
+  const regular = eligible.filter((i) => !i.sources.includes('telegram-saved')).slice(0, Math.max(0, opts.max));
+  const picked = [...lane, ...regular];
+  if (!opts.dryRun && picked.length) {
+    appendItems(instanceRoot, picked.map((i) => ({ ...i, status: 'queued' as const, lastSeenAt: now })));
+  }
+  debug.log('intake.normalize', 'absorb-queue', { picked: picked.length, max: opts.max, lane: lane.length, laneMax, kind: opts.kind, dryRun: !!opts.dryRun });
+  return picked.map((i) => (opts.dryRun ? i : { ...i, status: 'queued' as const }));
+}

package/src/intake-plane/link-ledger.ts

@@ -0,0 +1,27 @@
+import { debug } from '../debug/log.js';
+import { ingestIntakeItems, intakeItemId, markIntakeItem, type IntakeSource } from './items.js';
+
+/** Record a URL route only after its note has been saved. Ledger failure must not block the reply. */
+export function recordRoutedLinkAbsorbed(
+  root: string,
+  input: { source: IntakeSource; url: string; notePath: string; title?: string },
+  now = new Date().toISOString(),
+): string | null {
+  try {
+    const { source, url, notePath, title } = input;
+    const id = intakeItemId(source, { url });
+    ingestIntakeItems(root, source, [{ url, title }], now);
+    if (!markIntakeItem(root, id, { status: 'absorbed', output: { kind: 'note', ref: notePath } }, now)) {
+      throw new Error('item-not-found');
+    }
+    debug.log('intake.link-ledger', 'recorded', { source, id });
+    return id;
+  } catch (error) {
+    // FS errors may embed the private note path. Only emit the error class/code.
+    const reason = error && typeof error === 'object' && 'code' in error && typeof error.code === 'string'
+      ? error.code
+      : error instanceof Error ? error.name : 'unknown';
+    debug.log('intake.link-ledger', 'record-failed', { reason });
+    return null;
+  }
+}