@asc-agent/runtime 0.1.0

package/dist/core/monitor/health-alerts.js

@@ -0,0 +1,88 @@
+// Coverage Health Escalation — 못 본 것을 못 봤다고 먼저 말한다 (C-12 §3).
+//
+// Coverage Health 값 자체는 B-31부터 있었다. 문제는 **사람이 `asc monitor status` 를 쳐야만
+// 보인다**는 것이었다. 감시가 상시로 도는데 감시의 고장은 수동 조회로만 알 수 있으면,
+// 가장 조용한 실패 모드가 남는다:
+//
+//   외부 소스가 죽었다 → 사건이 안 온다 → "변경 없음" 처럼 보인다
+//
+// **"변경 없음"과 "못 봄"을 합치지 않는다** (C-12 불변식 ⑫). 이 파일이 하는 일은 그 둘을
+// 가르는 판정 하나뿐이다.
+//
+// 판정은 하되 **승인 요청을 만들지 않는다** (불변식 ⑬). 결과는 사람이 볼 목록이며,
+// 기존 Presentation·Digest 경로로 나간다 — 새 채널도 새 상태도 만들지 않는다.
+//
+// 임계값은 Core 상수가 아니다 (불변식 ⑭). 호출자가 정해 넣는다.
+/**
+ * 지금 감시가 어디까지 성립하는가.
+ *
+ * **추측하지 않는다.** 사건이 안 오는 것이 조용한 것인지 끊긴 것인지 여기서 정하지 않고,
+ * "오래 안 왔다"는 사실만 든다 — 사람이 그 둘을 가른다.
+ */
+export function evaluateHealth(health, at, thresholds) {
+    const alerts = [];
+    const now = new Date(at).getTime();
+    const elapsed = (since) => {
+        if (!since)
+            return undefined;
+        const value = now - new Date(since).getTime();
+        return Number.isNaN(value) ? undefined : value;
+    };
+    if (!health.sourceHealthy) {
+        alerts.push({
+            kind: 'SOURCE_UNHEALTHY',
+            detail: health.detail ?? 'the external source could not be read — this is not "no changes", it is "not seen"',
+            ...(health.lastHotEventAt ? { lastAt: health.lastHotEventAt } : {}),
+        });
+    }
+    // 한 번도 안 돈 것과 오래 안 돈 것은 다르다. 전자는 설정 문제이고 후자는 운영 문제다.
+    if (!health.lastHotEventAt && !health.lastReconcileAt && !health.lastCensusAt) {
+        alerts.push({ kind: 'NEVER_RAN', detail: 'monitoring has never run — it was not started, or nothing triggered it' });
+        return alerts;
+    }
+    const hot = elapsed(health.lastHotEventAt);
+    if (hot === undefined || hot >= thresholds.hotPathMs) {
+        alerts.push({
+            kind: 'HOT_PATH_STALE',
+            detail: health.lastHotEventAt === undefined
+                ? '빠른 경로로 사건이 온 적이 없다 — 조용한 것인지 끊긴 것인지 모른다'
+                : `빠른 경로가 조용한 지 ${minutes(hot)}분 — 조용한 것인지 끊긴 것인지 모른다`,
+            ...(health.lastHotEventAt ? { lastAt: health.lastHotEventAt } : {}),
+        });
+    }
+    const reconcile = elapsed(health.lastReconcileAt);
+    if (reconcile === undefined || reconcile >= thresholds.reconcileMs) {
+        alerts.push({
+            kind: 'RECONCILE_STALE',
+            detail: health.lastReconcileAt === undefined
+                ? 'the reconcile path has never run — nothing has picked up what the fast path missed'
+                : `${minutes(reconcile)} min since the reconcile path last ran`,
+            ...(health.lastReconcileAt ? { lastAt: health.lastReconcileAt } : {}),
+        });
+    }
+    const census = elapsed(health.lastCensusAt);
+    if (census === undefined || census >= thresholds.censusMs) {
+        alerts.push({
+            kind: 'CENSUS_STALE',
+            detail: health.lastCensusAt === undefined
+                ? 'listing integrity has never been checked'
+                : `listing integrity last checked ${minutes(census)} min ago`,
+            ...(health.lastCensusAt ? { lastAt: health.lastCensusAt } : {}),
+        });
+    }
+    // 완주하지 못한 상태에서는 상실 판정 자체가 보류된다 — 그 사실을 사람이 알아야 한다.
+    if (!health.paginationComplete && (health.lastReconcileAt || health.lastCensusAt)) {
+        alerts.push({
+            kind: 'PAGINATION_INCOMPLETE',
+            detail: 'the last listing did not complete — disappearances are not judged in this state',
+        });
+    }
+    return alerts;
+}
+const minutes = (ms) => Math.floor(ms / 60_000);
+/** 사람이 읽는 블록. 조용한 실패를 조용하게 두지 않는 것이 목적이다. */
+export function healthAlertLines(alerts) {
+    if (alerts.length === 0)
+        return [];
+    return ['Monitoring warnings:', ...alerts.map((alert) => `  [${alert.kind}] ${alert.detail}`)];
+}

package/dist/core/monitor/investigation.d.ts

@@ -0,0 +1,82 @@
+import type { ChangeContextPort } from '../../ports/change-context.ts';
+import type { HistoryPort, ResourceContextPort } from '../../ports/resource-context.ts';
+import type { CanonicalSnapshot } from '../model/entities.ts';
+import { type OwnershipMap } from '../policy/ownership.ts';
+import type { Relevance } from './relevance.ts';
+export declare const STEPS: readonly ["resource", "delta", "responsibility", "work", "thread", "change", "work-context", "canonical", "relevance", "recommendation", "draft"];
+export type StepId = (typeof STEPS)[number];
+export type StepResult = {
+    id: StepId;
+    kind: 'DONE';
+    findings: string[];
+}
+/** 필요한 Port가 없거나 조회가 실패했다. **통과가 아니다.** */
+ | {
+    id: StepId;
+    kind: 'UNDECIDABLE';
+    detail: string;
+}
+/** 이 사건에는 해당하지 않는다 (변경이 없는 사건의 change 단계 등). */
+ | {
+    id: StepId;
+    kind: 'SKIPPED';
+    detail: string;
+};
+export type Investigation = {
+    steps: StepResult[];
+    /** 사람이 읽는 상황. 단계 산출을 이어 붙인 것이며 요약하지 않는다. */
+    situation: string[];
+    recommendation: string;
+    /** 확인하지 못한 것. 비어 있지 않으면 draft를 만들지 않는다. */
+    undecidable: string[];
+    draft?: string;
+    /** draft를 만들지 않은 이유. 만들었으면 없다. */
+    draftBlocked?: string;
+};
+export type InvestigationInput = {
+    reference: string;
+    /** Phase A가 이미 낸 판정. 여기서 다시 계산하지 않는다. */
+    relevance?: Relevance;
+    /** 지난 관측 — ② delta 단계의 기준. */
+    previous?: {
+        revisionMarker: string;
+        state?: string;
+    };
+    /** 이 사건에 걸린 결정 영역. 없으면 responsibility 단계는 owner 확인까지다. */
+    decisionDomains?: readonly string[];
+    ownership?: OwnershipMap;
+    owner?: string;
+    activeSessions?: readonly string[];
+    canonicalPaths?: readonly string[];
+    /** 조사 예산. inspect는 최근 것만, trace는 더 넓게 본다 (C-05 §3). */
+    commentLimit?: number;
+    /**
+     * 이 사건에 연결된 작업 항목 (⑦). 코드 쪽 reference와 **다른 Binding일 수 있다** —
+     * 코드가 한 곳, 작업 항목이 다른 곳인 것이 정상이다 (C-09 §3.1).
+     * 선언되지 않으면 그 단계는 해당 없음이다.
+     */
+    workReference?: string;
+    /** 경위를 어디까지 볼지. trace가 아니면 굳이 넓히지 않는다. */
+    historyLimit?: number;
+};
+export type InvestigationPorts = {
+    resource?: ResourceContextPort;
+    change?: ChangeContextPort;
+    /**
+     * 작업 항목 쪽 통로 (⑦). 코드 쪽과 **다른 adapter일 수 있다** — 같은 것을 쓰라고
+     * 강요하면 두 시스템을 동시에 붙일 수 없다.
+     */
+    work?: ResourceContextPort;
+    /** 경위 조회. 제공하지 못하는 adapter가 흔하므로 따로 받는다 (C-09 §2.1). */
+    history?: HistoryPort;
+    /** 정본 baseline 조회. 없으면 canonical 단계가 성립하지 않는다. */
+    baselines?: () => Promise<CanonicalSnapshot[]>;
+};
+/**
+ * 단계를 순서대로 밟는다. **각 단계는 자기가 필요한 Port만 요청한다** — 어떤 외부 시스템이
+ * 그것을 제공하는지는 Binding이 정한다 (C-09 §4).
+ *
+ * 이미 끝난 단계가 있으면 그 자리는 건너뛴다. 재시도가 조사를 처음부터 다시 하면 실패
+ * 지점이 비쌀수록 영영 넘지 못한다 (C-07 §6.3).
+ */
+export declare function investigate(input: InvestigationInput, ports: InvestigationPorts, done?: readonly StepResult[]): Promise<Investigation>;

package/dist/core/monitor/investigation.js

@@ -0,0 +1,232 @@
+// Typed Investigation — "AI가 알아서 확인"을 단계 계약으로 바꾼다 (C-07 §6).
+//
+// 조사를 자유 서술로 두면 무엇을 봤고 무엇을 못 봤는지가 남지 않는다. 그러면 못 본 것이
+// 조용히 "문제 없음"이 되고, 사람은 확인되지 않은 것을 확인된 것으로 읽는다.
+//
+// 단계마다 두 가지가 분명해야 한다:
+//   무엇을 필요로 하는가  — 그 단계가 요청하는 Port. provider 이름으로 갈라지지 않는다
+//   못 했으면 왜 못 했는가 — 판정 불성립은 통과가 아니다. 다른 단계 결과로 대신하지 않는다
+import { isWithinScopes } from "../policy/scope.js";
+import { lookupAuthority } from "../policy/ownership.js";
+export const STEPS = [
+    'resource', // ① 사건 자체 재확인 — 요약을 믿지 않는다
+    'delta', // ② 직전 관측 대비 무엇이 달라졌나
+    'responsibility', // ③ 누가 끌고 가고 누가 결정하는가
+    'work', // ④ 지금 돌고 있는 것과의 관계
+    'thread', // ⑤ 논의
+    'change', // ⑥ 변경 경로·요약
+    'work-context', // ⑦ 작업 항목의 상태·연결 (다른 Binding일 수 있다)
+    'canonical', // ⑧ 정본 대조
+    'relevance', // ⑨ 관련성과 영향
+    'recommendation', // ⑩ 무엇을 하면 되는가
+    'draft', // ⑪ 초안 (조건을 만족할 때만)
+];
+const missingPort = (id, what) => ({
+    id,
+    kind: 'UNDECIDABLE',
+    detail: `${what} 를 제공하는 binding이 없다 — 이 단계는 확인하지 못했다`,
+});
+/**
+ * 단계를 순서대로 밟는다. **각 단계는 자기가 필요한 Port만 요청한다** — 어떤 외부 시스템이
+ * 그것을 제공하는지는 Binding이 정한다 (C-09 §4).
+ *
+ * 이미 끝난 단계가 있으면 그 자리는 건너뛴다. 재시도가 조사를 처음부터 다시 하면 실패
+ * 지점이 비쌀수록 영영 넘지 못한다 (C-07 §6.3).
+ */
+export async function investigate(input, ports, done = []) {
+    const steps = [...done];
+    const already = new Set(done.map((s) => s.id));
+    const put = (result) => {
+        if (!already.has(result.id))
+            steps.push(result);
+    };
+    // ① 사건 자체 — 알림 요약을 그대로 믿지 않는다.
+    const resource = ports.resource ? await ports.resource.getResource(input.reference).catch(() => null) : null;
+    if (!ports.resource)
+        put(missingPort('resource', '리소스 조회'));
+    else if (!resource || resource.missing) {
+        put({ id: 'resource', kind: 'UNDECIDABLE', detail: '리소스를 읽지 못했다 (사라졌거나 접근 불가)' });
+    }
+    else {
+        put({
+            id: 'resource',
+            kind: 'DONE',
+            findings: [
+                `${resource.title} — ${resource.state}`,
+                ...(resource.assignees?.length ? [`배정: ${resource.assignees.join(', ')}`] : []),
+                ...(resource.labels?.length ? [`라벨: ${resource.labels.join(', ')}`] : []),
+            ],
+        });
+    }
+    // ② Delta — 현재 모습만 보면 무엇이 새로운지 알 수 없다.
+    if (!input.previous) {
+        put({ id: 'delta', kind: 'SKIPPED', detail: '지난 관측이 없다 — 처음 보는 사건이다' });
+    }
+    else if (!resource) {
+        put(missingPort('delta', '리소스 조회'));
+    }
+    else {
+        const changes = [];
+        if (input.previous.revisionMarker !== resource.revisionMarker)
+            changes.push('실질 변화 있음');
+        if (input.previous.state && input.previous.state !== resource.state) {
+            changes.push(`상태 ${input.previous.state} → ${resource.state}`);
+        }
+        put({ id: 'delta', kind: 'DONE', findings: changes.length > 0 ? changes : ['지난 관측과 같다'] });
+    }
+    // ③ Responsibility — B-23~B-25를 실제로 쓴다 (C-04).
+    const responsibility = [];
+    if (input.owner)
+        responsibility.push(`Owner: ${input.owner}`);
+    for (const domain of input.decisionDomains ?? []) {
+        const found = lookupAuthority(input.ownership, domain);
+        responsibility.push(found.kind === 'RESOLVED'
+            ? `${domain} → ${found.role}`
+            : found.kind === 'AMBIGUOUS'
+                ? `${domain} → 갈림 (${found.candidates.join(', ')})`
+                : `${domain} → 결정권자 미선언`);
+    }
+    put(responsibility.length > 0
+        ? { id: 'responsibility', kind: 'DONE', findings: responsibility }
+        : { id: 'responsibility', kind: 'SKIPPED', detail: 'owner·결정 영역이 선언되지 않았다' });
+    // ④ 지금 돌고 있는 것과의 관계.
+    put(input.activeSessions?.length
+        ? { id: 'work', kind: 'DONE', findings: [`활성 세션: ${input.activeSessions.join(', ')}`] }
+        : { id: 'work', kind: 'SKIPPED', detail: '지금 돌고 있는 세션이 없다' });
+    // ⑤ Thread — 전부 읽지 않는다. 판단에 필요한 만큼만 (C-05 §3).
+    if (!ports.resource)
+        put(missingPort('thread', '스레드 조회'));
+    else {
+        const comments = await ports.resource
+            .getComments(input.reference, { limit: input.commentLimit ?? 5 })
+            .catch(() => null);
+        put(comments === null
+            ? { id: 'thread', kind: 'UNDECIDABLE', detail: '논의를 읽지 못했다' }
+            : {
+                id: 'thread',
+                kind: 'DONE',
+                findings: comments.slice(0, 3).map((c) => `${c.author}: ${c.body.slice(0, 80)}`),
+            });
+    }
+    // ⑥ Change — 실제 변경 내용으로 본다. reviewer 지정 여부가 아니다.
+    const change = ports.change ? await ports.change.getChange(input.reference).catch(() => null) : null;
+    if (!ports.change)
+        put(missingPort('change', '변경 조회'));
+    else if (!change || change.missing) {
+        put({ id: 'change', kind: 'SKIPPED', detail: '변경이 딸린 사건이 아니거나 읽지 못했다' });
+    }
+    else {
+        put({
+            id: 'change',
+            kind: 'DONE',
+            findings: [
+                `변경 경로 ${change.changedPaths.length}건${change.truncated ? ' (일부만 받았다)' : ''}`,
+                ...change.changedPaths.slice(0, 5),
+                ...(change.reviewState ? [`검토: ${change.reviewState}`] : []),
+            ],
+        });
+    }
+    // ⑦ Work Context — 작업 항목의 상태·연결. 코드 쪽과 다른 Binding일 수 있다.
+    if (!input.workReference) {
+        put({ id: 'work-context', kind: 'SKIPPED', detail: '연결된 작업 항목이 선언되지 않았다' });
+    }
+    else if (!ports.work) {
+        put(missingPort('work-context', '작업 항목 조회'));
+    }
+    else {
+        const item = await ports.work.getResource(input.workReference).catch(() => null);
+        if (!item || item.missing) {
+            put({ id: 'work-context', kind: 'UNDECIDABLE', detail: '작업 항목을 읽지 못했다' });
+        }
+        else {
+            // 경위는 있으면 더한다. 없다고 이 단계 전체가 무너지지는 않는다 —
+            // 이력을 모르는 도구가 흔하고, 그것과 "못 읽었다"는 다르다.
+            const history = ports.history
+                ? await ports.history.getHistory(input.workReference, input.historyLimit ?? 3).catch(() => [])
+                : [];
+            put({
+                id: 'work-context',
+                kind: 'DONE',
+                findings: [
+                    `${item.title} — ${item.state}`,
+                    ...(item.assignees?.length ? [`담당: ${item.assignees.join(', ')}`] : []),
+                    ...(item.related?.length ? [`연결: ${item.related.join(', ')}`] : []),
+                    ...history.map((event) => `${event.at} ${event.actor} ${event.kind}`),
+                ],
+            });
+        }
+    }
+    // ⑧ Canonical — 계약이 고정한 것과 이번 변경을 견준다.
+    let canonicalConflict = false;
+    if (!ports.baselines)
+        put(missingPort('canonical', '정본 조회'));
+    else {
+        const snapshots = await ports.baselines().catch(() => null);
+        if (!snapshots)
+            put({ id: 'canonical', kind: 'UNDECIDABLE', detail: '정본을 읽지 못했다' });
+        else {
+            const touched = (change?.changedPaths ?? []).filter((path) => input.canonicalPaths?.length && isWithinScopes(path, input.canonicalPaths));
+            canonicalConflict = touched.length > 0;
+            put({
+                id: 'canonical',
+                kind: 'DONE',
+                findings: [
+                    `정본 ${snapshots.length}갈래 기준`,
+                    ...(canonicalConflict ? [`contract drift 후보 — 정본 영역 변경: ${touched.join(', ')}`] : []),
+                ],
+            });
+        }
+    }
+    // ⑨ Relevance — Phase A 판정을 근거와 함께 옮긴다. 여기서 다시 계산하지 않는다.
+    put(input.relevance
+        ? {
+            id: 'relevance',
+            kind: 'DONE',
+            findings: input.relevance.evidence.map((e) => `${e.supports ? '+' : '-'} ${e.detail}`),
+        }
+        : { id: 'relevance', kind: 'SKIPPED', detail: '관련성 판정을 받지 못했다' });
+    const undecidable = steps
+        .filter((s) => s.kind === 'UNDECIDABLE')
+        .map((s) => `${s.id}: ${s.detail}`);
+    // ⑩ Recommendation — 못 본 것이 있으면 그것부터 말한다.
+    const recommendation = undecidable.length > 0
+        ? '확인하지 못한 것이 있다. 아래를 먼저 채우고 다시 본다.'
+        : canonicalConflict
+            ? '정본 영역이 바뀌었다. 계약 영향을 확인한 뒤 대응한다.'
+            : input.relevance?.actual === 'HIGH'
+                ? '관련이 확인됐다. 대응 여부를 정한다.'
+                : '지금은 행동이 필요해 보이지 않는다.';
+    put({ id: 'recommendation', kind: 'DONE', findings: [recommendation] });
+    // ⑪ Draft — 조건을 만족할 때만 (C-07 §7).
+    const blocked = draftBlocker(input, undecidable, canonicalConflict);
+    put(blocked
+        ? { id: 'draft', kind: 'SKIPPED', detail: blocked }
+        : { id: 'draft', kind: 'DONE', findings: ['초안 작성 조건을 만족한다'] });
+    return {
+        steps,
+        situation: steps.flatMap((s) => (s.kind === 'DONE' ? s.findings : [`${s.id}: 확인 못 함 — ${s.detail}`])),
+        recommendation,
+        undecidable,
+        ...(blocked ? { draftBlocked: blocked } : {}),
+    };
+}
+/**
+ * 초안을 만들면 안 되는 이유. 단정적인 초안은 그 자체로 판단을 실어 나르고, 사람은 초안을
+ * 검토하는 대신 승인하게 된다 (C-07 §7).
+ */
+function draftBlocker(input, undecidable, canonicalConflict) {
+    if (undecidable.length > 0)
+        return `확인하지 못한 단계가 있다 (${undecidable.length}건)`;
+    if (canonicalConflict)
+        return '정본과 충돌 가능성이 있다 — 사람이 먼저 정한다';
+    if (!input.relevance)
+        return '관련성 판정이 없다';
+    if (input.relevance.actual !== 'HIGH')
+        return '관련 근거가 약하다';
+    for (const domain of input.decisionDomains ?? []) {
+        const found = lookupAuthority(input.ownership, domain);
+        if (found.kind !== 'RESOLVED')
+            return `'${domain}' 의 결정권자가 정해지지 않았다`;
+    }
+    return undefined;
+}

package/dist/core/monitor/observation.d.ts

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+import type { ScopedStore } from '../../ports/state-store.ts';
+import type { Disposition, Relevance } from './relevance.ts';
+/**
+ * 이번에 본 모습. 셋 중 하나라도 달라지면 실질 변화다 (C-07 §4.3).
+ *
+ * evidence를 넣는 이유: 같은 스레드라도 근거가 달라졌으면 새 사건이다. 변경 경로가 내
+ * 영역까지 넓어진 것을 "같은 스레드"라고 묶으면 그게 정확히 놓치는 경우다.
+ */
+export type Fingerprint = {
+    revisionMarker: string;
+    evidence: readonly string[];
+};
+export declare const Observation: z.ZodObject<{
+    reference: z.ZodString;
+    revisionMarker: z.ZodString;
+    evidence: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** 지난번 처분. SHADOW면 숨긴 것이고 INBOX면 올린 것이다. */
+    disposition: z.ZodEnum<["INBOX", "SHADOW"]>;
+    /** 왜 그렇게 처분했는지. 나중에 사람이 "왜 안 보였나"를 물을 때 답이 된다. */
+    reason: z.ZodOptional<z.ZodString>;
+    firstSeenAt: z.ZodString;
+    lastSeenAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    reference: string;
+    disposition: "INBOX" | "SHADOW";
+    evidence: string[];
+    revisionMarker: string;
+    firstSeenAt: string;
+    lastSeenAt: string;
+    reason?: string | undefined;
+}, {
+    reference: string;
+    disposition: "INBOX" | "SHADOW";
+    revisionMarker: string;
+    firstSeenAt: string;
+    lastSeenAt: string;
+    evidence?: string[] | undefined;
+    reason?: string | undefined;
+}>;
+export type Observation = z.infer<typeof Observation>;
+export type SurfaceDecision = {
+    surface: true;
+    reason: 'NEW' | 'MATERIAL_CHANGE' | 'PROMOTED';
+}
+/**
+ * 올리지 않는다. 두 이유를 나누는 까닭: `SHADOWED`는 관련 근거가 없어서이고
+ * `NO_MATERIAL_CHANGE`는 관련은 있는데 지난번과 같아서다. 사람이 "왜 안 보였나"를
+ * 물을 때 답이 다르다.
+ */
+ | {
+    surface: false;
+    reason: 'SHADOWED' | 'NO_MATERIAL_CHANGE';
+    previous?: Observation;
+};
+/** 근거를 비교 가능한 문자열로. 순서가 흔들려 오탐하지 않게 정렬한다. */
+export declare const fingerprintOf: (relevance: Relevance, revisionMarker: string) => Fingerprint;
+export declare class ObservationLedger {
+    #private;
+    constructor(scope: ScopedStore, now?: () => string);
+    /**
+     * 이번 관측을 올릴 것인가.
+     *
+     * 처음 보는 것은 올린다. 지난번에 Shadow로 내렸던 것이 이번에 INBOX 판정이면 **승격**이다 —
+     * 그게 Shadow를 버리지 않고 두는 이유다.
+     */
+    decide(reference: string, fingerprint: Fingerprint, disposition: Disposition): Promise<SurfaceDecision>;
+    /** 이번 관측을 기록한다. 처음 본 시각은 보존한다 — 언제부터 지켜봤는지가 사라지면 안 된다. */
+    record(reference: string, fingerprint: Fingerprint, disposition: Disposition, reason?: string): Promise<Observation>;
+    get(reference: string): Promise<Observation | null>;
+    list(): Promise<Observation[]>;
+    /**
+     * 지금 숨겨 두고 보는 것들. **숨김이지 폐기가 아니다** — 사람이 물으면 그대로 보여준다
+     * (C-07 §5.4).
+     */
+    shadowed(): Promise<Observation[]>;
+}
+/** 사람이 읽는 줄. 왜 숨겼는지를 함께 적는다 — 이유 없는 숨김은 폐기와 구분되지 않는다. */
+export declare function shadowLines(records: readonly Observation[]): string[];

package/dist/core/monitor/observation.js

@@ -0,0 +1,110 @@
+// Observation Ledger — reference 하나를 계속 지켜본 기록 (C-07 §4·§5).
+//
+// 두 가지를 같은 자리에서 푼다. 둘 다 "이 reference를 지난번에 어떻게 봤나"가 있어야
+// 성립하기 때문이다:
+//
+//   Material Change  같은 스레드에서 실질 변화 없이 다시 부를 때 패킷을 만들지 않는다
+//   Shadow Watch     지금은 내 일이 아니라고 본 것을 버리지 않고 계속 본다
+//
+// 왜 Request 상태가 아닌가: 상태를 하나 더 만들면 승인 lifecycle 전체가 영향을 받는다
+// (OM §11.2 열거는 동결이다). 그리고 이건 요청에 대한 사실이 아니라 **외부 리소스에 대한
+// 우리 관측**이다 — 요청이 만들어지기 전에도, 만들어지지 않아도 존재한다.
+//
+// 저장은 adapter-scope다 (C-07 §0.2, Closure Ledger·Bounded Query 선례).
+//
+// 여기는 closure.ts와 달리 읽고-고쳐-쓴다. 기록이 갱신돼야 하는 물건이라 setIfAbsent로는
+// 표현되지 않기 때문이다. 안전한 이유는 Monitor Run이 프로젝트 단위 lease로 직렬화되어
+// 같은 scope를 두 Run이 동시에 만지지 않기 때문이다 (engine.ts scan lease).
+import { z } from 'zod';
+export const Observation = z.object({
+    reference: z.string().min(1),
+    revisionMarker: z.string(),
+    evidence: z.array(z.string()).default([]),
+    /** 지난번 처분. SHADOW면 숨긴 것이고 INBOX면 올린 것이다. */
+    disposition: z.enum(['INBOX', 'SHADOW']),
+    /** 왜 그렇게 처분했는지. 나중에 사람이 "왜 안 보였나"를 물을 때 답이 된다. */
+    reason: z.string().optional(),
+    firstSeenAt: z.string().min(1),
+    lastSeenAt: z.string().min(1),
+});
+const key = (reference) => `obs:${reference}`;
+/** 근거를 비교 가능한 문자열로. 순서가 흔들려 오탐하지 않게 정렬한다. */
+export const fingerprintOf = (relevance, revisionMarker) => ({
+    revisionMarker,
+    evidence: relevance.evidence
+        .filter((e) => e.supports)
+        .map((e) => `${e.kind}:${e.detail}`)
+        .sort(),
+});
+export class ObservationLedger {
+    #scope;
+    #now;
+    constructor(scope, now = () => new Date().toISOString()) {
+        this.#scope = scope;
+        this.#now = now;
+    }
+    /**
+     * 이번 관측을 올릴 것인가.
+     *
+     * 처음 보는 것은 올린다. 지난번에 Shadow로 내렸던 것이 이번에 INBOX 판정이면 **승격**이다 —
+     * 그게 Shadow를 버리지 않고 두는 이유다.
+     */
+    async decide(reference, fingerprint, disposition) {
+        const previous = await this.get(reference);
+        if (!previous) {
+            return disposition === 'INBOX'
+                ? { surface: true, reason: 'NEW' }
+                : { surface: false, reason: 'SHADOWED' };
+        }
+        if (previous.disposition === 'SHADOW' && disposition === 'INBOX') {
+            return { surface: true, reason: 'PROMOTED' };
+        }
+        if (disposition === 'SHADOW')
+            return { surface: false, reason: 'SHADOWED', previous };
+        const changed = previous.revisionMarker !== fingerprint.revisionMarker ||
+            previous.evidence.join(' ') !== fingerprint.evidence.join(' ');
+        return changed
+            ? { surface: true, reason: 'MATERIAL_CHANGE' }
+            : { surface: false, reason: 'NO_MATERIAL_CHANGE', previous };
+    }
+    /** 이번 관측을 기록한다. 처음 본 시각은 보존한다 — 언제부터 지켜봤는지가 사라지면 안 된다. */
+    async record(reference, fingerprint, disposition, reason) {
+        const previous = await this.get(reference);
+        const at = this.#now();
+        const observation = Observation.parse({
+            reference,
+            revisionMarker: fingerprint.revisionMarker,
+            evidence: [...fingerprint.evidence],
+            disposition,
+            ...(reason ? { reason } : {}),
+            firstSeenAt: previous?.firstSeenAt ?? at,
+            lastSeenAt: at,
+        });
+        await this.#scope.set(key(reference), JSON.stringify(observation));
+        return observation;
+    }
+    async get(reference) {
+        const raw = await this.#scope.get(key(reference));
+        return raw ? Observation.parse(JSON.parse(raw)) : null;
+    }
+    async list() {
+        const out = [];
+        for (const stored of await this.#scope.keys('obs:')) {
+            const raw = await this.#scope.get(stored);
+            if (raw)
+                out.push(Observation.parse(JSON.parse(raw)));
+        }
+        return out.sort((a, b) => a.reference.localeCompare(b.reference));
+    }
+    /**
+     * 지금 숨겨 두고 보는 것들. **숨김이지 폐기가 아니다** — 사람이 물으면 그대로 보여준다
+     * (C-07 §5.4).
+     */
+    async shadowed() {
+        return (await this.list()).filter((o) => o.disposition === 'SHADOW');
+    }
+}
+/** 사람이 읽는 줄. 왜 숨겼는지를 함께 적는다 — 이유 없는 숨김은 폐기와 구분되지 않는다. */
+export function shadowLines(records) {
+    return records.map((o) => `${o.reference} — ${o.reason ?? '관련 근거 없음'} (처음 ${o.firstSeenAt} · 마지막 ${o.lastSeenAt})`);
+}

package/dist/core/monitor/relevance.d.ts

@@ -0,0 +1,47 @@
+import type { OwnershipMap } from '../policy/ownership.ts';
+import type { GenericSignal } from './signals.ts';
+export type RelevanceLevel = 'HIGH' | 'LOW';
+/** 근거의 갈래. 우선순위 순서이며, 마지막(semantic)은 보조다 (C-07 §3.2). */
+export type EvidenceKind = 'ownership' | 'work' | 'contract' | 'participation' | 'semantic' | 'targeting';
+export type RelevanceEvidence = {
+    kind: EvidenceKind;
+    /** 사람이 읽는 한 줄. 왜 그렇게 봤는지가 여기 남는다. */
+    detail: string;
+    /** 관련성을 올리는 근거인가, 내리는 근거인가. 반대 근거도 적는다. */
+    supports: boolean;
+};
+export type Disposition = 'INBOX' | 'SHADOW';
+export type Relevance = {
+    explicit: RelevanceLevel;
+    actual: RelevanceLevel;
+    evidence: RelevanceEvidence[];
+    disposition: Disposition;
+};
+export type RelevanceContext = {
+    /** Profile이 선언한 책임 지도 (C-04 §6). */
+    ownership?: OwnershipMap;
+    /** 이 사람이 맡은 역할들. 비어 있으면 ownership 근거는 성립하지 않는다. */
+    myRoles?: readonly string[];
+    /** 이번 변경이 건드린 실제 경로. 모르면 생략한다 — 빈 배열과 다르다. */
+    changedPaths?: readonly string[];
+    /** 지금 돌고 있는 세션들의 쓰기 범위. */
+    activeBoundaries?: readonly {
+        sessionId: string;
+        paths: readonly string[];
+    }[];
+    /** 정본이 사는 경로. contract 근거의 기준이다. */
+    canonicalPaths?: readonly string[];
+    /** 내가 전에 이 스레드에 참여했는가. */
+    participated?: boolean;
+    /** 제목·본문이 내 영역과 연관된다고 볼 근거(보조). Surface가 판단해 넘긴다. */
+    semanticHint?: string;
+};
+/**
+ * 두 축을 판정한다.
+ *
+ * **숫자를 내지 않는다** (C-07 §3.3). 0.82 같은 값은 사람이 검증할 수 없고, 틀렸을 때 어디가
+ * 틀렸는지도 말해주지 않는다. 대신 근거 문장을 남겨 사람이 뒤집을 수 있게 한다.
+ */
+export declare function evaluateRelevance(signals: readonly GenericSignal[], context?: RelevanceContext): Relevance;
+/** 사람이 읽는 근거 블록. 근거 없이 결론만 보여주지 않는다. */
+export declare function renderRelevance(relevance: Relevance): string[];