elanous 0.2.11 → 0.2.13

package/src/loops/package/verify.ts

@@ -0,0 +1,125 @@
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { debug } from '../../debug/log.js';
+import { loopAgentContractErrors } from '../contract/validate.js';
+
+const contractSchema = JSON.parse(readFileSync(resolve(import.meta.dir, '../contract/loop-agent.schema.json'), 'utf8')) as { $id: string };
+const allowedOverlayFields = new Set(['neighbors', 'cadence', 'grounding', 'budget']);
+type RecordValue = Record<string, unknown>;
+
+function record(value: unknown): value is RecordValue {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function schemaMajor(value: string): number | null {
+  const match = /^(?:https:\/\/elanous\.ai\/schemas\/loop-agent\/)?(\d+)\.\d+\.\d+$/.exec(value);
+  return match ? Number(match[1]) : null;
+}
+
+/** The package version is independent of the declared contract schema version. */
+export function contractMajor(manifest: RecordValue): { ok: boolean; error?: string } {
+  const declared = manifest.schema ?? manifest.$schema ?? contractSchema.$id;
+  const expected = schemaMajor(contractSchema.$id);
+  const actual = typeof declared === 'string' ? schemaMajor(declared) : null;
+  const other = manifest.schema !== undefined && manifest.$schema !== undefined ? manifest.$schema : undefined;
+  if (actual !== null && expected !== null && actual === expected &&
+      (other === undefined || typeof other === 'string' && schemaMajor(other) === expected)) return { ok: true };
+  return { ok: false, error: `contract major mismatch: declared ${String(declared)}${other === undefined ? '' : ` / ${String(other)}`}, expected ${contractSchema.$id}` };
+}
+
+/** Replace only allowlisted top-level fields; refused fields never enter the merged manifest. */
+export function mergeOverlay(manifest: RecordValue, overlay: unknown): { merged: RecordValue; refused: string[] } {
+  const merged = { ...manifest };
+  const refused: string[] = [];
+  if (!record(overlay)) return { merged, refused: ['overlay'] };
+  for (const [field, value] of Object.entries(overlay)) {
+    if (!allowedOverlayFields.has(field)) refused.push(field);
+    else merged[field] = value;
+  }
+  return { merged, refused };
+}
+
+function inside(root: string, path: string): boolean {
+  const part = relative(root, path);
+  return part !== '..' && !part.startsWith(`..${sep}`) && !isAbsolute(part);
+}
+
+function readReference(root: string, name: string, path: unknown, errors: string[]): void {
+  if (typeof path !== 'string' || !path || isAbsolute(path) || /^[a-zA-Z]:[\\/]/.test(path) || path.split(/[\\/]/).includes('..')) {
+    errors.push(`${name} path escape: ${String(path)}`);
+    return;
+  }
+  const candidate = resolve(root, path);
+  if (!inside(root, candidate)) {
+    errors.push(`${name} path escape: ${path}`);
+    return;
+  }
+  try {
+    const actual = realpathSync(candidate);
+    if (!inside(root, actual)) errors.push(`${name} path escape: ${path}`);
+    else if (!statSync(actual).isFile()) errors.push(`${name} file missing: ${path}`);
+  } catch {
+    errors.push(`${name} file missing: ${path}`);
+  }
+}
+
+export function readLoopPackage(dir: string): { manifest: RecordValue | null; overlay?: unknown; errors: string[] } {
+  const errors: string[] = [];
+  let manifest: RecordValue | null = null;
+  let overlay: unknown;
+  const root = realpathSync(dir);
+  if (!statSync(root).isDirectory()) throw new Error(`${dir} is not a directory`);
+  const readYaml = (name: string): unknown => {
+    const path = resolve(root, name);
+    const actual = realpathSync(path);
+    if (!inside(root, actual) || !statSync(actual).isFile()) throw new Error(`${name} path escape or not a file`);
+    return parseYaml(readFileSync(actual, 'utf8'));
+  };
+  try {
+    const parsed = readYaml('loop.yaml');
+    if (!record(parsed)) errors.push('loop.yaml must contain a manifest object');
+    else manifest = parsed;
+  } catch (error) { errors.push(`loop.yaml: ${error instanceof Error ? error.message : String(error)}`); }
+  try { overlay = readYaml('overlay.yaml'); }
+  catch (error) {
+    if (!(record(error) && error.code === 'ENOENT')) errors.push(`overlay.yaml: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (manifest) {
+    readReference(root, 'graph', manifest.graph, errors);
+    readReference(root, 'role', manifest.role, errors);
+  }
+  return { manifest, overlay, errors };
+}
+
+export function verifyLoopPackage(dir: string): {
+  ok: boolean; errors: string[]; refusedOverlayFields: string[]; merged: RecordValue | null;
+} {
+  let manifest: RecordValue | null = null;
+  let overlay: unknown;
+  const errors: string[] = [];
+  try {
+    const read = readLoopPackage(dir);
+    manifest = read.manifest;
+    overlay = read.overlay;
+    errors.push(...read.errors);
+  } catch (error) { errors.push(`package directory: ${error instanceof Error ? error.message : String(error)}`); }
+  let merged: RecordValue | null = null;
+  let refusedOverlayFields: string[] = [];
+  if (manifest) {
+    const major = contractMajor(manifest);
+    if (major.error) errors.push(major.error);
+    const result = overlay === undefined ? { merged: { ...manifest }, refused: [] } : mergeOverlay(manifest, overlay);
+    refusedOverlayFields = result.refused;
+    merged = result.merged;
+    if (refusedOverlayFields.length) errors.push(`overlay refused: ${refusedOverlayFields.join(', ')}`);
+    // Schema declaration is package metadata, not a field in the loop-agent contract.
+    const { schema: _schema, $schema: _dollarSchema, ...contractInput } = merged;
+    errors.push(...loopAgentContractErrors(contractInput));
+  }
+  const ok = errors.length === 0;
+  debug.log('loop.package', ok ? 'verified' : 'refused', {
+    id: manifest?.id, version: manifest?.version, errors: errors.length, refusedOverlayFields,
+  });
+  return { ok, errors, refusedOverlayFields, merged };
+}

package/src/loops/verdict.ts

@@ -0,0 +1,22 @@
+export type LoopCronVerdict = 'alive' | 'late' | 'failed' | 'off';
+
+/** Shared display inputs for a graph loop or a cron job. The caller supplies
+ * the cadence in milliseconds (or null when it is not known). */
+export interface LoopCronVerdictInput {
+  enabled: boolean;
+  lastRunAt: string | null;
+  lastStatus: string | null;
+  intervalMs: number | null;
+}
+
+/** Pure health classification; a failed last execution takes precedence over age.
+ * With no valid timestamp or positive cadence, lateness cannot be established. */
+export function loopCronVerdict(entry: LoopCronVerdictInput, nowMs: number): LoopCronVerdict {
+  if (!entry.enabled) return 'off';
+  if (entry.lastStatus === 'failed' || entry.lastStatus === 'error' || entry.lastStatus === 'failure') return 'failed';
+  const lastRunMs = entry.lastRunAt === null ? NaN : Date.parse(entry.lastRunAt);
+  if (Number.isFinite(nowMs) && Number.isFinite(lastRunMs) &&
+      entry.intervalMs !== null && Number.isFinite(entry.intervalMs) && entry.intervalMs > 0 &&
+      nowMs - lastRunMs > 2 * entry.intervalMs) return 'late';
+  return 'alive';
+}

package/src/maturity/feature-maturity.ts

@@ -57,11 +57,11 @@ export const FEATURE_MATURITY = {
     pty: 'beta', pr: 'beta', repo: 'beta', role: 'beta', machine: 'beta',
     where: 'stable', shadow: 'beta', llm: 'beta', storage: 'beta', leader: 'beta',
     pod: 'beta', browser: 'beta', questions: 'beta', usage: 'stable', live: 'beta',
-    research: 'beta', release: 'beta', seat: 'beta', coord: 'beta', context: 'beta', 'model-watch': 'beta', doctor: 'stable',
+    research: 'beta', release: 'beta', seat: 'beta', hq: 'beta', steward: 'beta', coord: 'beta', context: 'beta', 'model-watch': 'beta', doctor: 'stable',
     control: 'beta', resources: 'beta', hooks: 'beta', setup: 'stable', start: 'stable',
     grounding: 'beta', graph: 'beta', loop: 'stable', card: 'stable', 'launch-head': 'beta',
     a2a: 'beta', plugin: 'stable', make: 'beta', skills: 'beta', connect: 'beta', import: 'beta',
-    persona: 'beta', 'team-set': 'beta', market: 'beta', directive: 'stable', connector: 'beta', storyboard: 'beta',
+    persona: 'beta', team: 'beta', 'team-set': 'beta', market: 'beta', directive: 'stable', connector: 'beta', storyboard: 'beta',
     python: 'beta', 'self-update': 'stable', 'measure-fabric-arc-ab': 'beta', mcp: 'beta',
     relay: 'beta', 'telegram-test': 'beta', telegram: 'beta', 'discord-test': 'beta',
     sync: 'beta', status: 'beta', git: 'beta', gh: 'beta', repro: 'system',
@@ -71,7 +71,7 @@ export const FEATURE_MATURITY = {
     provider: 'stable', 'provider:set': 'beta', 'provider:restore': 'beta',
     'provider:rotate': 'beta', 'provider:use': 'beta', 'status-bar': 'beta',
     schedule: 'beta', intake: 'beta', logs: 'stable', ad: 'beta', docs: 'beta',
-    decisions: 'beta', directives: 'beta', fleet: 'beta', ops: 'stable', publish: 'beta',
+    decisions: 'beta', directives: 'beta', fleet: 'beta', ops: 'stable', outputs: 'beta', publish: 'beta',
     env: 'beta', 'agent-mission': 'beta', dev: 'beta', keys: 'beta', finance: 'beta',
     config: 'stable', tasks: 'stable', labels: 'beta', msg: 'beta', ask: 'stable',
     onboarding: 'beta', login: 'stable', session: 'beta', chat: 'stable', repl: 'stable',
@@ -89,6 +89,7 @@ export const FEATURE_MATURITY = {
     clear: 'stable',
     status: 'stable',
     now: 'beta', // CTX2 «지금 무엇이 돌고 있나» (#23379)
+    wish: 'beta',
     remaining: 'stable',
     setup: 'stable',
     quit: 'stable',
@@ -152,7 +153,7 @@ export const FEATURE_MATURITY = {
     ping: 'stable', provider: 'stable', sessions: 'stable', fork: 'stable', resume: 'stable',
     decisions: 'stable', work: 'stable', cancel: 'stable',
     skills: 'beta', skill: 'beta', digest: 'beta', intake: 'beta', ad: 'beta',
-    taste: 'beta', missions: 'beta', attach: 'beta', detach: 'beta', now: 'beta', project: 'beta',
+    taste: 'beta', missions: 'beta', attach: 'beta', detach: 'beta', now: 'beta', project: 'beta', wish: 'beta',
     brain: 'tool', cc: 'tool', cdx: 'tool', gem: 'tool', local: 'tool',
     harness: 'ops',
     // Existing commands outside the CXO four-grade menu list are owner-only.

package/src/memory.ts

@@ -63,6 +63,16 @@ export function writeFileDurable(path: string, data: string, fsync: (fd: number)
 
 export type MemoryType = 'user' | 'feedback' | 'project' | 'reference';
 
+/** Context-condense metadata travels with the existing curated memory file, not a parallel store. */
+export interface ContextMemoryCard {
+  project: string;
+  seat: string;
+  topic: string;
+  source: string;
+  updatedAt: string;
+  status: 'active' | 'retired';
+}
+
 export interface MemoryEntry {
   id: string;                 // uuid v4
   filename: string;           // "<uuid>-<slug>.md"
@@ -89,6 +99,7 @@ export interface MemoryEntry {
   pinned: boolean;
   /** Optional pinned-memory freshness window; absent memories retain their original injection text. */
   staleAfterMinutes?: number;
+  contextCard?: ContextMemoryCard;
 }
 
 // ── Paths ────────────────────────────────────────────────────────────
@@ -192,6 +203,7 @@ export interface SaveMemoryOpts {
   staleAfterMinutes?: number;
   /** Override the generated id (tests). */
   id?: string;
+  contextCard?: ContextMemoryCard;
 }
 
 export function saveMemory(opts: SaveMemoryOpts, root: string = memoryRoot()): MemoryEntry {
@@ -207,6 +219,7 @@ export function saveMemory(opts: SaveMemoryOpts, root: string = memoryRoot()): M
   let existingPriority: number | undefined;
   let existingPinned: boolean | undefined;
   let existingStaleAfterMinutes: number | undefined;
+  let existingContextCard: ContextMemoryCard | undefined;
   if (existsSync(path)) {
     try {
       const parsed = parseFrontmatter(readFileSync(path, 'utf-8'));
@@ -214,6 +227,7 @@ export function saveMemory(opts: SaveMemoryOpts, root: string = memoryRoot()): M
       if (parsed.fm.priority) existingPriority = parseInt(parsed.fm.priority, 10) || 0;
       if (parsed.fm.pinned) existingPinned = parsed.fm.pinned === 'true';
       existingStaleAfterMinutes = parseStaleAfterMinutes(parsed.fm['stale-after-minutes']);
+      existingContextCard = parseContextCard(parsed.fm['context-card']);
     } catch { /* keep new createdAt */ }
   }
   const priority = opts.priority ?? existingPriority ?? 0;
@@ -229,6 +243,8 @@ export function saveMemory(opts: SaveMemoryOpts, root: string = memoryRoot()): M
   if (priority > 0) frontmatter.priority = String(Math.floor(priority));
   if (pinned) frontmatter.pinned = 'true';
   if (staleAfterMinutes !== undefined) frontmatter['stale-after-minutes'] = String(staleAfterMinutes);
+  const contextCard = opts.contextCard ?? existingContextCard;
+  if (contextCard) frontmatter['context-card'] = JSON.stringify(contextCard);
   const raw = renderFrontmatter(frontmatter, opts.body);
   writeFileDurable(path, raw);
 
@@ -248,9 +264,23 @@ export function saveMemory(opts: SaveMemoryOpts, root: string = memoryRoot()): M
     priority,
     pinned,
     staleAfterMinutes,
+    ...(contextCard ? { contextCard } : {}),
   };
 }
 
+function parseContextCard(raw: string | undefined): ContextMemoryCard | undefined {
+  if (!raw) return undefined;
+  try {
+    const card: unknown = JSON.parse(raw);
+    if (card && typeof card === 'object' && !Array.isArray(card)) {
+      const c = card as Record<string, unknown>;
+      if (['project', 'seat', 'topic', 'source', 'updatedAt'].every(key => typeof c[key] === 'string')
+        && (c.status === 'active' || c.status === 'retired')) return c as unknown as ContextMemoryCard;
+    }
+  } catch { /* malformed metadata is not a context memory */ }
+  return undefined;
+}
+
 /** Parse one memory file. Returns null on read/parse error. */
 function parseMemoryFile(path: string): MemoryEntry | null {
   if (!existsSync(path)) return null;
@@ -261,6 +291,7 @@ function parseMemoryFile(path: string): MemoryEntry | null {
   const basename = path.split(/[\\/]/).pop() ?? '';
   const match = basename.match(/^([0-9a-f-]{36})-(.+)\.md$/i);
   const id = match ? match[1] : createHash('sha1').update(basename).digest('hex').slice(0, 36);
+  const contextCard = parseContextCard(fm['context-card']);
   return {
     id,
     filename: basename,
@@ -274,6 +305,7 @@ function parseMemoryFile(path: string): MemoryEntry | null {
     priority: fm.priority ? (parseInt(fm.priority, 10) || 0) : 0,
     pinned: fm.pinned === 'true',
     staleAfterMinutes: parseStaleAfterMinutes(fm['stale-after-minutes']),
+    ...(contextCard ? { contextCard } : {}),
   };
 }
 
@@ -364,6 +396,7 @@ export function searchMemories(
   const entries = listMemories({ type: opts.type }, root);
   const hits: SearchHit[] = [];
   for (const entry of entries) {
+    if (entry.contextCard?.status === 'retired') continue;
     // 정확-토큰 매칭(2026-07-19) — 이전 substring `includes(kw)` 는 "ref"가 "reference"·
     // "prefer" 안에까지 걸려 오차용(false-recall)을 냈다(openclaw tool-search.ts 이식:
     // tokenize→Set.has 전체토큰 동등). name/description 은 토큰집합 정확매칭, body 는
@@ -415,7 +448,7 @@ export function rebuildIndex(root: string = memoryRoot()): void {
   const byType: Record<MemoryType, MemoryEntry[]> = {
     user: [], feedback: [], project: [], reference: [],
   };
-  for (const e of entries) byType[e.type].push(e);
+  for (const e of entries) if (e.contextCard?.status !== 'retired') byType[e.type].push(e);
 
   const lines: string[] = [];
   lines.push('# elanous memory index');
@@ -515,7 +548,7 @@ export function buildMemoryInjection(
 
   // 📌 pinned 기억 — 키워드 무관 항상 주입(relevance gate bypass · Letta pinned block /
   //    claude-code MEMORY.md tier 동형). priority 높은 순. core/safety/ref-location 사실용.
-  const pinnedMems = listMemories({}, root).filter(m => m.pinned).sort((a, b) => b.priority - a.priority);
+  const pinnedMems = listMemories({}, root).filter(m => m.pinned && m.contextCard?.status !== 'retired').sort((a, b) => b.priority - a.priority);
   const pinnedParts: string[] = [];
   for (const e of pinnedMems) {
     const chunk = pinnedChunk(e);
@@ -678,7 +711,7 @@ export async function buildMemoryInjectionLLM(
   }
 
   // pinned 항상주입(키워드/판정 무관).
-  const pinnedMems = listMemories({}, root).filter((m) => m.pinned).sort((a, b) => b.priority - a.priority);
+  const pinnedMems = listMemories({}, root).filter((m) => m.pinned && m.contextCard?.status !== 'retired').sort((a, b) => b.priority - a.priority);
   const pinnedParts: string[] = [];
   for (const e of pinnedMems) {
     const chunk = pinnedChunk(e);
@@ -693,7 +726,7 @@ export async function buildMemoryInjectionLLM(
   let judged: MemoryEntry[] = [];
   if (!lowContext) {
     const candidates = listMemories({}, root)
-      .filter((m) => !m.pinned && !injected.includes(m.id))
+      .filter((m) => !m.pinned && m.contextCard?.status !== 'retired' && !injected.includes(m.id))
       .slice(0, opts.maxCandidates ?? 60);
     if (candidates.length > 0) {
       try {

package/src/nexus/api/card-followup-route.ts

@@ -0,0 +1,118 @@
+import { randomUUID } from 'node:crypto';
+import { chmodSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join, relative, sep } from 'node:path';
+import { defaultAttachmentBaseDir, resolveAttachmentPath } from '../../boot/attachment-store.js';
+import { detectCard, NotACardError, runCardFollowup } from '../../card-followup/core.js';
+import { debug } from '../../debug/log.js';
+import { effectiveInstanceRoot } from '../../instance/resolve.js';
+import { localOcrText } from '../../telegram-card-followup.js';
+import { jsonResponse } from './json-response.js';
+
+export const CARD_FOLLOWUP_PATH = '/v1/card-followup';
+
+type CardJob = { id: string; status: 'judging' | 'running' | 'done' | 'not-card' | 'failed'; updatedAt: number; replies?: [string, string, string]; error?: string };
+type CardDeps = {
+  rootDir?: string;
+  resolveAttachment?: typeof resolveAttachmentPath;
+  ocr?: typeof localOcrText;
+  detect?: typeof detectCard;
+  run?: typeof runCardFollowup;
+  now?: () => number;
+};
+
+function withinAttachmentStore(path: string): boolean {
+  try {
+    const relativePath = relative(realpathSync(defaultAttachmentBaseDir()), realpathSync(path));
+    return relativePath !== '' && relativePath !== '..' && !relativePath.startsWith(`..${sep}`) && !isAbsolute(relativePath);
+  } catch { return false; }
+}
+
+/** The in-memory set identifies only work launched by this daemon; disk is the pollable ledger. */
+export function createCardFollowupJobs({
+  rootDir = effectiveInstanceRoot(),
+  resolveAttachment = resolveAttachmentPath,
+  ocr = localOcrText,
+  detect = detectCard,
+  run = runCardFollowup,
+  now = Date.now,
+}: CardDeps = {}) {
+  const base = join(rootDir, 'graph-runs', 'card-followup');
+  const active = new Set<string>();
+  const unavailable = new Set<string>();
+  const file = (id: string) => join(base, `${id}.pwa.json`);
+  const save = (job: CardJob) => {
+    mkdirSync(base, { recursive: true, mode: 0o700 });
+    chmodSync(base, 0o700);
+    writeFileSync(file(job.id), JSON.stringify(job), { mode: 0o600 });
+    chmodSync(file(job.id), 0o600);
+  };
+
+  return {
+    async post(req: Request): Promise<Response> {
+      let body: unknown;
+      try { body = await req.json(); } catch { body = null; }
+      if (!body || typeof body !== 'object' || Array.isArray(body)) return jsonResponse({ error: 'bad_request' }, 400);
+      const { attachmentId, context } = body as Record<string, unknown>;
+      if (context !== undefined && typeof context !== 'string') return jsonResponse({ error: 'bad_request' }, 400);
+      const imagePath = typeof attachmentId === 'string' ? resolveAttachment(attachmentId) : null;
+      if (!imagePath || (resolveAttachment === resolveAttachmentPath && !withinAttachmentStore(imagePath))) {
+        return jsonResponse({ error: 'attachment-not-found' }, 400);
+      }
+
+      const id = randomUUID();
+      const update = (status: CardJob['status'], fields: Partial<Pick<CardJob, 'replies' | 'error'>> = {}) =>
+        save({ id, status, updatedAt: now(), ...fields });
+      update('judging');
+      active.add(id);
+      debug.log('card-followup.pwa', 'started', { id });
+      // Start OCR on the next event-loop turn so the acceptance response precedes the work.
+      setTimeout(() => {
+        void (async () => {
+          try {
+            const ocrText = await ocr(imagePath);
+            if (detect({ ocrText }).decision !== 'card') {
+              update('not-card');
+              debug.log('card-followup.pwa', 'not-card', { id });
+              return;
+            }
+            update('running');
+            const result = await run({ imagePath, ocrText, rootDir, runId: id, ...(context === undefined ? {} : { context }) });
+            update('done', { replies: result.replies });
+            debug.log('card-followup.pwa', 'done', { id });
+          } catch (cause) {
+            const notCard = cause instanceof NotACardError;
+            // OCR·그래프 예외 문구엔 명함 원문이 섞일 수 있다 — 원장·응답엔 고정 코드만 싣는다(리뷰 must-fix).
+            try {
+              update(notCard ? 'not-card' : 'failed', notCard ? {} : { error: 'card-followup-failed' });
+              debug.log('card-followup.pwa', notCard ? 'not-card' : 'failed', { id });
+            } catch {
+              unavailable.add(id);
+              debug.log('card-followup.pwa', 'failed', { id });
+            }
+          } finally {
+            active.delete(id);
+          }
+        })().catch(() => {
+          unavailable.add(id);
+          active.delete(id);
+        });
+      });
+      return jsonResponse({ id }, 202);
+    },
+    get(id: string): Response {
+      if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id)) return jsonResponse({ error: 'not-found' }, 404);
+      if (unavailable.has(id)) return jsonResponse({ id, status: 'failed', error: 'card-followup-failed' });
+      let job: CardJob;
+      try { job = JSON.parse(readFileSync(file(id), 'utf8')) as CardJob; }
+      catch { return jsonResponse({ error: 'not-found' }, 404); }
+      if (job.id !== id) return jsonResponse({ error: 'not-found' }, 404);
+      if ((job.status === 'judging' || job.status === 'running') && !active.has(id)) {
+        return jsonResponse({ id, status: 'failed', error: 'daemon-restarted' });
+      }
+      const { status, replies, error } = job;
+      return jsonResponse({ id, status, ...(replies ? { replies } : {}), ...(error ? { error } : {}) });
+    },
+  };
+}
+
+export type CardFollowupJobs = ReturnType<typeof createCardFollowupJobs>;

package/src/nexus/api/decisions-route.ts

@@ -0,0 +1,68 @@
+import { debug } from '../../debug/log.js';
+import { DecisionLedger, type DecisionEntry } from '../../decisions/decision-ledger.js';
+import { jsonResponse } from './json-response.js';
+
+export const DECISIONS_PATH = '/v1/decisions';
+
+export interface DecisionsRouteDeps {
+  authorize?: (request: Request) => boolean;
+  ledger?: Pick<DecisionLedger, 'list' | 'decide'>;
+}
+
+export async function handleDecisions(req: Request, deps: DecisionsRouteDeps = {}): Promise<Response> {
+  const pathname = new URL(req.url).pathname;
+  if (pathname !== DECISIONS_PATH && !/^\/v1\/decisions\/[^/]+\/decide$/.test(pathname)) return jsonResponse({ error: 'not-found' }, 404);
+  if (!deps.authorize?.(req)) {
+    debug.log('decisions.api', 'rejected', { reason: 'unauthorized' });
+    return jsonResponse({ error: 'unauthorized' }, 401);
+  }
+  const ledger = deps.ledger ?? new DecisionLedger();
+  if (pathname === DECISIONS_PATH) {
+    if (req.method !== 'GET') return jsonResponse({ error: 'method-not-allowed' }, 405);
+    if (new URL(req.url).searchParams.get('status') !== 'open') {
+      debug.log('decisions.api', 'rejected', { reason: 'invalid-status' });
+      return jsonResponse({ error: 'bad_request' }, 400);
+    }
+    const decisions = ledger.list({ status: 'open' }).map(entry => ({
+      id: entry.id,
+      title: entry.title,
+      situation: entry.scqa.s.slice(0, 200),
+      options: entry.options.map(option => ({ id: option.key, label: option.label })),
+      recommendation: entry.recommendation,
+      raisedAt: entry.raisedAt,
+      dueAt: entry.dueAt,
+    }));
+    debug.log('decisions.api', 'listed', { count: decisions.length });
+    return jsonResponse({ decisions });
+  }
+  if (req.method !== 'POST') return jsonResponse({ error: 'method-not-allowed' }, 405);
+  let id: string;
+  try { id = decodeURIComponent(pathname.slice(DECISIONS_PATH.length + 1, -'/decide'.length)); }
+  catch {
+    debug.log('decisions.api', 'rejected', { reason: 'invalid-id' });
+    return jsonResponse({ error: 'not-found' }, 404);
+  }
+  let body: unknown;
+  try { body = await req.json(); } catch { body = null; }
+  if (!body || typeof body !== 'object' || Array.isArray(body)
+    || !('choice' in body) || typeof body.choice !== 'string' || !body.choice
+    || ('note' in body && body.note !== undefined && typeof body.note !== 'string')) {
+    debug.log('decisions.api', 'rejected', { id, reason: 'invalid-body' });
+    return jsonResponse({ error: 'bad_request' }, 400);
+  }
+  const { choice, note } = body as { choice: string; note?: string };
+  try {
+    const entry: DecisionEntry = ledger.decide(id, choice, { kind: 'human' }, note);
+    debug.log('decisions.api', 'decided', { id });
+    return jsonResponse(entry);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : '';
+    const status = message.startsWith('decision not found:') ? 404
+      : message.startsWith('decision already closed:') ? 409
+      : message.startsWith('option not found:') || message.startsWith('note ') ? 400 : 0;
+    if (!status) throw error;
+    const reason = status === 404 ? 'not-found' : status === 409 ? 'already-decided' : 'bad_request';
+    debug.log('decisions.api', 'rejected', { id, reason });
+    return jsonResponse({ error: reason }, status);
+  }
+}