@asc-agent/runtime 0.1.0

package/dist/core/monitor/coverage.js

@@ -0,0 +1,129 @@
+// Coverage Ledger — 빠른 경로가 놓친 것을 찾기 위해 "지난번엔 이랬다"를 남긴다 (C-07 §1).
+//
+// Delta(빠른 경로)는 놓치면 그대로 놓친다. webhook이 유실되고, 지정이 빠지고, 닫힌 뒤에
+// 달린 댓글은 알림이 오지 않는다. 그래서 주기적으로 목록을 다시 세어 본다.
+//
+// **event 스트림을 재생하지 않는다** (C-07 §1.4). 매 회차 같은 객체를 새 key로 올리면
+// 회차마다 새 패킷이 된다. reference 하나의 상태를 지난번과 비교해 **달라진 것만** 올린다.
+//
+// Observation Ledger(observation.ts)와 나누는 이유: 저쪽은 "이 사건을 사람에게 올릴까"이고
+// 이쪽은 "이 리소스가 지난번과 달라졌나"다. 하나는 판단이고 하나는 관측 사실이다.
+import { z } from 'zod';
+export const CoverageRecord = z.object({
+    reference: z.string().min(1),
+    state: z.string(),
+    revisionMarker: z.string(),
+    updatedAt: z.string(),
+    /** 마지막으로 목록에서 본 시각. missing 판정의 기준이 된다. */
+    seenAt: z.string().min(1),
+});
+/**
+ * 지금까지 어디까지 확인했는가 (C-07 §8.2). **100% 보장을 대신하는 값이 아니라, 무엇을
+ * 확인했고 무엇을 모르는지 사람이 볼 수 있게 하는 값이다.**
+ */
+export const CoverageHealth = z.object({
+    lastHotEventAt: z.string().optional(),
+    lastReconcileAt: z.string().optional(),
+    lastCensusAt: z.string().optional(),
+    /** 이 시각까지의 변경은 회수했다고 보는 기준선. */
+    coverageWatermark: z.string().optional(),
+    /**
+     * 마지막 열거가 목록을 빠짐없이 훑었는가. **모르면 false다** — 이 값이 false인 열거로
+     * missing을 판정하면 없는 상실을 만들어낸다.
+     */
+    paginationComplete: z.boolean().default(false),
+    sourceHealthy: z.boolean().default(true),
+    /** 마지막 실패 이유. 상태만 주면 고칠 수가 없다. */
+    detail: z.string().optional(),
+});
+const recordKey = (reference) => `cov:${reference}`;
+const HEALTH_KEY = 'coverage-health';
+export class CoverageLedger {
+    #scope;
+    #now;
+    constructor(scope, now = () => new Date().toISOString()) {
+        this.#scope = scope;
+        this.#now = now;
+    }
+    async get(reference) {
+        const raw = await this.#scope.get(recordKey(reference));
+        return raw ? CoverageRecord.parse(JSON.parse(raw)) : null;
+    }
+    async list() {
+        const out = [];
+        for (const key of await this.#scope.keys('cov:')) {
+            const raw = await this.#scope.get(key);
+            if (raw)
+                out.push(CoverageRecord.parse(JSON.parse(raw)));
+        }
+        return out.sort((a, b) => a.reference.localeCompare(b.reference));
+    }
+    /** 이번에 본 모습을 남긴다. 빠른 경로도 이걸 갱신해야 회수 경로가 같은 것을 또 올리지 않는다. */
+    async record(item) {
+        const at = this.#now();
+        await this.#scope.set(recordKey(item.reference), JSON.stringify(CoverageRecord.parse({
+            reference: item.reference,
+            state: item.state ?? '',
+            revisionMarker: item.revisionMarker,
+            updatedAt: item.updatedAt ?? at,
+            seenAt: at,
+        })));
+    }
+    /** 이번 목록과 지난 기록을 견준다. 달라진 것만 돌려준다. */
+    async diff(items) {
+        const out = [];
+        for (const item of items) {
+            const previous = await this.get(item.reference);
+            if (!previous) {
+                out.push({ kind: 'NEW', item });
+                continue;
+            }
+            // marker가 실질 변화의 정본이다. state는 보조 — 빠른 경로가 남긴 기록에는 상태가
+            // 없을 수 있고(알림에는 목록 상태가 안 실린다), 그것을 "달라졌다"로 읽으면 같은
+            // 변화로 패킷이 둘 생긴다.
+            const stateChanged = previous.state !== '' && previous.state !== item.state;
+            if (previous.revisionMarker !== item.revisionMarker || stateChanged) {
+                out.push({ kind: 'CHANGED', item, previous });
+            }
+        }
+        return out;
+    }
+    /**
+     * 알던 것 중 이번 목록에 없는 것.
+     *
+     * **빠짐없이 훑은 열거에서만 판정한다.** 페이지를 다 돌지 못한 목록으로 비교하면
+     * 멀쩡한 리소스가 사라졌다고 나온다.
+     */
+    async missing(seen, paginationComplete) {
+        if (!paginationComplete)
+            return [];
+        return (await this.list())
+            .filter((record) => !seen.has(record.reference))
+            .map((previous) => ({ kind: 'RESOURCE_MISSING', reference: previous.reference, previous }));
+    }
+    async health() {
+        const raw = await this.#scope.get(HEALTH_KEY);
+        return raw ? CoverageHealth.parse(JSON.parse(raw)) : CoverageHealth.parse({});
+    }
+    async updateHealth(patch) {
+        const merged = CoverageHealth.parse({ ...(await this.health()), ...patch });
+        await this.#scope.set(HEALTH_KEY, JSON.stringify(merged));
+        return merged;
+    }
+}
+/**
+ * 사람이 읽는 상태. **"100% 감지 보장"이라고 쓰지 않는다** (C-07 §8.1) — provider 장애·자격
+ * 문제·전달 실패·가시성 변화 중 어느 것도 ASC가 통제하지 못한다.
+ */
+export function renderHealth(sourceId, health) {
+    const or = (value) => value ?? '(없음)';
+    return [
+        `${sourceId}`,
+        `  빠른 경로 마지막 사건: ${or(health.lastHotEventAt)}`,
+        `  마지막 대조(reconcile): ${or(health.lastReconcileAt)}`,
+        `  마지막 전수(census):    ${or(health.lastCensusAt)}`,
+        `  확인 기준선:            ${or(health.coverageWatermark)}`,
+        `  목록 완주:              ${health.paginationComplete ? '예' : '아니오 (이 상태로는 상실을 판정하지 않는다)'}`,
+        `  연결 상태:              ${health.sourceHealthy ? '정상' : `이상 — ${or(health.detail)}`}`,
+    ];
+}

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

@@ -0,0 +1,134 @@
+import { type Priority } from '../model/entities.ts';
+import type { EventSource, RawEvent } from '../../ports/event-source.ts';
+import type { InventoryPort } from '../../ports/inventory.ts';
+import type { OwnershipMap } from '../policy/ownership.ts';
+import type { ScmPort } from '../../ports/scm.ts';
+import type { StateStore } from '../../ports/state-store.ts';
+import { type MonitorConfig, type SignalContext } from './signals.ts';
+import { type RelevanceContext } from './relevance.ts';
+import { type ObservationLedger } from './observation.ts';
+import { type SweepKind } from './coverage.ts';
+import { type InvestigationPorts } from './investigation.ts';
+/** 회수 경로 한 회차. scan과 나누는 이유는 답하는 질문이 다르기 때문이다. */
+export type SweepOutcome = {
+    skipped?: boolean;
+    kind: SweepKind;
+    /** 목록에서 본 리소스 수. */
+    seen: number;
+    /** 지난번과 달라 올린 것. */
+    changed: number;
+    packets: string[];
+    /** 알던 것 중 이번 목록에 없던 것. 원인은 판정하지 않는다 (C-07 §1.5). */
+    missing: string[];
+    /** 목록을 빠짐없이 훑었는가. 아니면 상실 판정을 하지 않았다는 뜻이다. */
+    complete: boolean;
+    /** 조회 자체가 실패했다면 그 이유. */
+    detail?: string;
+};
+export type ScanOutcome = {
+    /** 다른 Run이 돌고 있어 이번엔 건너뛰었다. polling이므로 다음 회차가 잡는다. */
+    skipped?: boolean;
+    detected: number;
+    duplicates: number;
+    logged: number;
+    packets: string[];
+    retries: string[];
+    cursor: string | null;
+};
+export type MonitorDeps = {
+    store: StateStore;
+    source: EventSource;
+    config: MonitorConfig;
+    /** Phase B의 맥락 조사에 쓴다. 없으면 정본 대조 없이 얕은 보고서만 만든다. */
+    scm?: ScmPort;
+    /** 이 요청을 결정할 수 있는 사람. Profile/Override가 채운다 (OM §11.6). */
+    authorizedApprover: string;
+    /** canonical source 목록. 보고서의 기준선이 된다 (OM §8). */
+    canonicalSources?: readonly string[];
+    /**
+     * 이 사건에 대해 지금 관찰된 사실을 모아 준다 (C-07 §2·§3). 없으면 신호만으로 판정하며,
+     * 그러면 "나를 불렀는가"까지밖에 알 수 없다.
+     *
+     * 콜백 하나로 받는 이유: 이벤트마다 외부 조회가 필요할 수 있어 여러 번 왕복하면
+     * 회차 비용이 그만큼 늘어난다.
+     */
+    observe?: (event: RawEvent) => Promise<EventObservation> | EventObservation;
+    /** 같은 reference를 지난번에 어떻게 봤는지 (C-07 §4·§5). 없으면 억제도 Shadow도 없다. */
+    observations?: ObservationLedger;
+    /**
+     * 목록을 다시 세어 놓친 것을 찾는 통로 (C-07 §1.2·§1.3). 없으면 reconcile·census가
+     * 성립하지 않는다 — 빠른 경로만으로는 완전성을 말할 수 없다.
+     */
+    inventory?: InventoryPort;
+    /**
+     * 조사 단계가 요청하는 통로들 (C-07 §6.2). 없는 것은 그 단계가 판정 불성립으로 남는다 —
+     * 다른 단계 결과로 대신하지 않는다.
+     */
+    investigation?: Pick<InvestigationPorts, 'resource' | 'change' | 'work' | 'history'>;
+    /** 조사에 넘길 프로젝트 사실. Core는 Profile을 모르므로 Surface가 꺼내 준다. */
+    investigationContext?: (event: RawEvent) => {
+        ownership?: OwnershipMap;
+        owner?: string;
+        decisionDomains?: readonly string[];
+        canonicalPaths?: readonly string[];
+        /** 이 사건에 연결된 작업 항목. 코드 쪽과 다른 Binding일 수 있다 (C-07 §6.1 ⑦). */
+        workReference?: string;
+    };
+    /** 이 Run의 이름. lease에 남아 누가 잡고 있는지 보인다. */
+    runId?: string;
+    /**
+     * cursor가 없을 때 어디서부터 볼지. 주지 않으면 처음부터 — 붙인 지 오래된 저장소에서는
+     * 그 자체가 잡음이 된다 (OM §18).
+     */
+    startFrom?: string;
+    now?: () => string;
+};
+/** 이번 사건에 대해 밖에서 알아 온 것. 없는 항목은 그 판정을 하지 않는다. */
+export type EventObservation = {
+    signal?: SignalContext;
+    relevance?: RelevanceContext;
+    /**
+     * 실질 변화 마커 (C-07 §4.2). adapter가 만든다. 없으면 억제 판정이 서지 않으므로
+     * 같은 스레드의 반복 호출이 매번 새 패킷이 된다.
+     */
+    revisionMarker?: string;
+};
+export declare class MonitorEngine {
+    #private;
+    constructor(deps: MonitorDeps);
+    /**
+     * 한 회차. 겹쳐 돌면 같은 이벤트로 요청이 두 개 생기므로 하나만 돈다 (OM §7.2·§10.1).
+     *
+     * 같은 객체 안에서만 막으면 소용이 없다 — CLI를 두 번 띄우면 프로세스가 둘이고, 둘 다
+     * 자기 안에서는 첫 Run이다. 그래서 잠금을 `.asc/` 안에 둔다: 프로젝트 하나에 Run 하나.
+     *
+     * 대기시키지 않고 건너뛰는 이유는, 밀린 Run이 쌓이는 것보다 다음 회차가 다시 보는 편이
+     * 싸기 때문이다 — 이벤트는 사라지지 않고 cursor에 남아 있다.
+     */
+    scan(): Promise<ScanOutcome>;
+    /**
+     * 빠른 경로가 놓친 것을 회수한다 (C-07 §1.2). 알림 재생이 아니라 **목록 재조회**다.
+     *
+     * `updatedSince` 기준선 이후만 본다 — 전수는 census의 몫이고, 매번 전부 훑으면
+     * 30분마다 도는 물건이 될 수 없다.
+     */
+    reconcile(): Promise<SweepOutcome>;
+    /**
+     * 우리가 아는 세계와 provider의 실제 세계가 일치하는지 본다 (C-07 §1.3).
+     * 기준선 없이 전부 훑고, 알던 것 중 이번에 없는 것도 찾는다.
+     */
+    census(): Promise<SweepOutcome>;
+    /** 지금까지 어디까지 확인했는가. 판정하지 않고 보여주기만 한다. */
+    health(): Promise<{
+        paginationComplete: boolean;
+        sourceHealthy: boolean;
+        detail?: string | undefined;
+        lastHotEventAt?: string | undefined;
+        lastReconcileAt?: string | undefined;
+        lastCensusAt?: string | undefined;
+        coverageWatermark?: string | undefined;
+    }>;
+}
+export type PacketDepth = 'full' | 'compact' | 'brief';
+/** OM §10.3 — 대응형·작업형은 전부, 정보형은 우선순위에 따라 접는다. */
+export declare function packetDepth(type: string, priority: Priority): PacketDepth;