@asc-agent/runtime 0.3.2 → 0.5.0

package/dist/core/runtime/background.d.ts

@@ -0,0 +1,104 @@
+import type { ScopedStore } from '../../ports/state-store.ts';
+import type { TickKind } from './orchestrator.ts';
+/** 이 lease가 사는 열쇠. Monitor의 scan-lease와 다른 층이다 — 저쪽은 한 회차, 이쪽은 루프. */
+export declare const RUNTIME_LEASE_KEY = "runtime-lease";
+/** 마지막 회차 시각이 사는 열쇠. Orchestrator가 쓰고 status가 읽는다. */
+export declare const LAST_RUN_KEY = "last-run";
+/**
+ * lease가 죽은 것으로 보이기까지의 최소 시간.
+ *
+ * **주기보다 길어야 한다.** 10분마다 도는 루프에 5분 만료를 걸면 회차 사이에 자기 lease가
+ * 죽은 것으로 보이고, 두 번째 프로세스가 조용히 끼어든다. 그래서 회수 기준은 주기의
+ * 3배이며, 이 값은 그 아래로 내려가지 않게 막는 바닥이다.
+ */
+export declare const MIN_STALE_MS: number;
+/** 주기에서 회수 기준을 정한다. 상수를 Core에 박지 않는다 (C-12 불변식 ③). */
+export declare const staleAfter: (intervalMs: number) => number;
+export type LeaseRecord = {
+    /** 누가 잡고 있는가. 사람이 읽고 죽일 수 있어야 한다. */
+    owner: string;
+    pid: number;
+    /** 마지막으로 살아 있다고 말한 시각. 회차마다 갱신된다. */
+    at: string;
+    /** 언제부터 돌고 있는가. `at`과 달리 갱신되지 않는다. */
+    startedAt: string;
+};
+export type LeaseState = 
+/** 아무도 안 잡고 있다. */
+{
+    kind: 'FREE';
+}
+/** 살아 있는 주인이 있다. */
+ | {
+    kind: 'HELD';
+    record: LeaseRecord;
+}
+/** 기록은 있는데 오래됐다 — 비정상 종료로 남은 것으로 본다. */
+ | {
+    kind: 'STALE';
+    record: LeaseRecord;
+    silentFor: number;
+};
+/**
+ * 루프 하나만 돌게 하는 lease.
+ *
+ * **이중 기동은 오류가 아니다** (C-12 불변식 ⑥). 늦게 온 쪽은 조용히 물러나고, 이미
+ * 도는 쪽이 계속한다. 비정상 종료로 남은 lease는 시간이 지나면 회수된다 — 한 번 죽었다고
+ * 영영 못 켜지면 그것이 더 나쁜 고장이다.
+ */
+export declare class RuntimeLease {
+    #private;
+    constructor(deps: {
+        scope: ScopedStore;
+        owner: string;
+        pid?: number;
+        staleMs?: number;
+        now?: () => string;
+    });
+    /** 지금 누가 잡고 있는가. 읽기만 한다 — status가 이것을 그린다. */
+    read(): Promise<LeaseState>;
+    /**
+     * 잡는다. 이미 살아 있는 주인이 있으면 `false` — 조용히 물러나는 것이 계약이다.
+     *
+     * Monitor scan-lease와 같은 모양이다: `setIfAbsent` 로 원자적으로 걸고, 오래된 것만
+     * 지우고 다시 건다. 확인과 쓰기 사이의 틈은 Adapter가 막는다.
+     */
+    acquire(): Promise<boolean>;
+    /**
+     * 살아 있다고 말한다. 회차마다 부른다 — 이것이 없으면 주기가 만료보다 긴 순간
+     * 자기 lease가 죽은 것으로 보인다.
+     *
+     * **남의 lease를 갱신하지 않는다.** 주인이 바뀌어 있으면 `false` 를 돌려주고, 호출자는
+     * 그것을 "내가 밀려났다"로 읽는다.
+     */
+    renew(): Promise<boolean>;
+    /** 내 것일 때만 놓는다. 남이 이미 잡았으면 건드리지 않는다. */
+    release(): Promise<void>;
+}
+export type BackgroundStatus = {
+    lease: LeaseState;
+    /** 갈래별 마지막 실행 시각. 없는 갈래는 한 번도 돌지 않았다. */
+    lastRun: Partial<Record<TickKind, string>>;
+    /** 회수 기준. 사람이 "얼마나 조용하면 죽은 것인가"를 알아야 판단할 수 있다. */
+    staleMs: number;
+};
+/** 상태를 모은다. **읽기만 한다** — 보는 것이 상태를 바꾸면 아무도 못 본다. */
+export declare function readBackground(scope: ScopedStore, staleMs: number, now?: () => string): Promise<BackgroundStatus>;
+/**
+ * 사람이 읽는 줄.
+ *
+ * **"안 돌고 있다"와 "돌았는데 변화가 없다"를 합치지 않는다** (C-12 불변식 ⑫과 같은 태도).
+ * 그래서 lease 상태와 마지막 회차 시각을 각각 말한다 — 둘 중 하나만 보면 오해한다.
+ */
+export declare function renderBackground(status: BackgroundStatus): string[];
+/**
+ * 파일 하나짜리 ScopedStore (설계 §5.1).
+ *
+ * **서비스 lease 와 workspace lease 는 다른 소유 영역이다.** 저쪽은 "이 workspace 의
+ * 이번 회차를 누가 잡았는가"이고, 이쪽은 "이 기계의 runtime 을 지금 누가 도는가"다.
+ * 둘을 합치면 workspace 가 늘 때마다 기계 수준 직렬화가 무너진다.
+ *
+ * workspace 상태 저장소를 기계 뿌리에 열지 않는 이유: 그러면 ~/.asc 에 workspace 용
+ * 파일들이 생기고, 그것은 그 자리에 없어야 할 것들이다.
+ */
+export declare function fileScope(path: string): ScopedStore;

package/dist/core/runtime/background.js

@@ -0,0 +1,225 @@
+// Background Runtime — 대화가 닫혀 있어도 도는 자리 (C-12 §0·§1.1).
+//
+// Orchestrator는 "언제 무엇을 부를지"를 이미 안다. 없던 것은 그 회차를 **누가 계속
+// 돌리는가**와, 돌고 있는지를 **사람이 어떻게 보는가**였다:
+//
+//   asc runtime start   터미널을 잡고 있어야 했다 — 창을 닫으면 감시가 죽는다
+//   asc runtime tick    한 회차만 돈다. 부를 사람이 없으면 아무 일도 안 일어난다
+//   asc runtime status  어느 빌드를 쓰는지만 답했다 (C-14 §4) — 감시가 사는지는 몰랐다
+//
+// 여기는 그 셋을 잇는 **상태**만 다룬다. 판정도, 감시도, 승인도 하지 않는다
+// (C-12 불변식 ②). scheduler 제품도 모른다 (불변식 ④) — cron이 tick을 부르든, 떨어져
+// 나간 프로세스가 스스로 돌든 같은 lease를 지난다.
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+/** 이 lease가 사는 열쇠. Monitor의 scan-lease와 다른 층이다 — 저쪽은 한 회차, 이쪽은 루프. */
+export const RUNTIME_LEASE_KEY = 'runtime-lease';
+/** 마지막 회차 시각이 사는 열쇠. Orchestrator가 쓰고 status가 읽는다. */
+export const LAST_RUN_KEY = 'last-run';
+/**
+ * lease가 죽은 것으로 보이기까지의 최소 시간.
+ *
+ * **주기보다 길어야 한다.** 10분마다 도는 루프에 5분 만료를 걸면 회차 사이에 자기 lease가
+ * 죽은 것으로 보이고, 두 번째 프로세스가 조용히 끼어든다. 그래서 회수 기준은 주기의
+ * 3배이며, 이 값은 그 아래로 내려가지 않게 막는 바닥이다.
+ */
+export const MIN_STALE_MS = 5 * 60_000;
+/** 주기에서 회수 기준을 정한다. 상수를 Core에 박지 않는다 (C-12 불변식 ③). */
+export const staleAfter = (intervalMs) => Math.max(MIN_STALE_MS, intervalMs * 3);
+/**
+ * 루프 하나만 돌게 하는 lease.
+ *
+ * **이중 기동은 오류가 아니다** (C-12 불변식 ⑥). 늦게 온 쪽은 조용히 물러나고, 이미
+ * 도는 쪽이 계속한다. 비정상 종료로 남은 lease는 시간이 지나면 회수된다 — 한 번 죽었다고
+ * 영영 못 켜지면 그것이 더 나쁜 고장이다.
+ */
+export class RuntimeLease {
+    #scope;
+    #owner;
+    #pid;
+    #staleMs;
+    #now;
+    #startedAt;
+    constructor(deps) {
+        this.#scope = deps.scope;
+        this.#owner = deps.owner;
+        this.#pid = deps.pid ?? process.pid;
+        this.#staleMs = deps.staleMs ?? MIN_STALE_MS;
+        this.#now = deps.now ?? (() => new Date().toISOString());
+    }
+    /** 지금 누가 잡고 있는가. 읽기만 한다 — status가 이것을 그린다. */
+    async read() {
+        const raw = await this.#scope.get(RUNTIME_LEASE_KEY);
+        if (!raw)
+            return { kind: 'FREE' };
+        let record;
+        try {
+            record = JSON.parse(raw);
+        }
+        catch {
+            // 읽을 수 없는 lease는 죽은 것으로 본다. 다만 무엇이 있었는지는 남긴다.
+            return { kind: 'STALE', record: { owner: '(unreadable)', pid: 0, at: '', startedAt: '' }, silentFor: Infinity };
+        }
+        const silentFor = new Date(this.#now()).getTime() - new Date(record.at).getTime();
+        // 시계가 뒤로 갔거나 기록이 깨졌으면 살아 있는 쪽으로 읽는다 — 남의 lease를 뺏는
+        // 것보다 한 회차 쉬는 편이 싸다.
+        if (Number.isNaN(silentFor))
+            return { kind: 'HELD', record };
+        return silentFor >= this.#staleMs ? { kind: 'STALE', record, silentFor } : { kind: 'HELD', record };
+    }
+    /**
+     * 잡는다. 이미 살아 있는 주인이 있으면 `false` — 조용히 물러나는 것이 계약이다.
+     *
+     * Monitor scan-lease와 같은 모양이다: `setIfAbsent` 로 원자적으로 걸고, 오래된 것만
+     * 지우고 다시 건다. 확인과 쓰기 사이의 틈은 Adapter가 막는다.
+     */
+    async acquire() {
+        const at = this.#now();
+        this.#startedAt = at;
+        const mine = JSON.stringify({ owner: this.#owner, pid: this.#pid, at, startedAt: at });
+        if (await this.#scope.setIfAbsent(RUNTIME_LEASE_KEY, mine))
+            return true;
+        const state = await this.read();
+        if (state.kind === 'HELD')
+            return false;
+        await this.#scope.delete(RUNTIME_LEASE_KEY);
+        return this.#scope.setIfAbsent(RUNTIME_LEASE_KEY, mine);
+    }
+    /**
+     * 살아 있다고 말한다. 회차마다 부른다 — 이것이 없으면 주기가 만료보다 긴 순간
+     * 자기 lease가 죽은 것으로 보인다.
+     *
+     * **남의 lease를 갱신하지 않는다.** 주인이 바뀌어 있으면 `false` 를 돌려주고, 호출자는
+     * 그것을 "내가 밀려났다"로 읽는다.
+     */
+    async renew() {
+        const raw = await this.#scope.get(RUNTIME_LEASE_KEY);
+        if (raw) {
+            try {
+                const held = JSON.parse(raw);
+                if (held.owner !== this.#owner)
+                    return false;
+                this.#startedAt ??= held.startedAt;
+            }
+            catch {
+                // 못 읽는 lease 위에 내 것을 덮어쓴다 — 아래에서 다시 쓴다
+            }
+        }
+        const at = this.#now();
+        this.#startedAt ??= at;
+        await this.#scope.set(RUNTIME_LEASE_KEY, JSON.stringify({ owner: this.#owner, pid: this.#pid, at, startedAt: this.#startedAt }));
+        return true;
+    }
+    /** 내 것일 때만 놓는다. 남이 이미 잡았으면 건드리지 않는다. */
+    async release() {
+        const raw = await this.#scope.get(RUNTIME_LEASE_KEY);
+        if (!raw)
+            return;
+        try {
+            if (JSON.parse(raw).owner !== this.#owner)
+                return;
+        }
+        catch {
+            // 못 읽는 것은 내가 남긴 것으로 보고 치운다
+        }
+        await this.#scope.delete(RUNTIME_LEASE_KEY);
+    }
+}
+/** 상태를 모은다. **읽기만 한다** — 보는 것이 상태를 바꾸면 아무도 못 본다. */
+export async function readBackground(scope, staleMs, now = () => new Date().toISOString()) {
+    const lease = await new RuntimeLease({ scope, owner: '(reader)', staleMs, now }).read();
+    const raw = await scope.get(LAST_RUN_KEY);
+    let lastRun = {};
+    if (raw) {
+        try {
+            lastRun = JSON.parse(raw);
+        }
+        catch {
+            // 깨진 기록은 없는 것으로 본다 — 아래 렌더가 "한 번도 돌지 않았다"로 말한다
+        }
+    }
+    return { lease, lastRun, staleMs };
+}
+const ORDER = ['delta', 'reconcile', 'census', 'digest'];
+/**
+ * 사람이 읽는 줄.
+ *
+ * **"안 돌고 있다"와 "돌았는데 변화가 없다"를 합치지 않는다** (C-12 불변식 ⑫과 같은 태도).
+ * 그래서 lease 상태와 마지막 회차 시각을 각각 말한다 — 둘 중 하나만 보면 오해한다.
+ */
+export function renderBackground(status) {
+    const lines = [];
+    switch (status.lease.kind) {
+        case 'FREE':
+            lines.push('Background runtime: not running — `asc runtime start --detach` keeps it observing');
+            break;
+        case 'HELD':
+            lines.push(`Background runtime: running (pid ${status.lease.record.pid}, since ${status.lease.record.startedAt}, last heartbeat ${status.lease.record.at})`);
+            break;
+        case 'STALE':
+            lines.push(`Background runtime: not running — a lease from pid ${status.lease.record.pid} has been silent for ` +
+                `${Math.round(status.lease.silentFor / 60_000)} min and will be reclaimed on the next start`);
+            break;
+    }
+    const ran = ORDER.filter((kind) => status.lastRun[kind]);
+    if (ran.length === 0) {
+        // 설정만 하고 켜지 않은 상태다. 조용한 것과 구분해서 말한다.
+        lines.push('  no pass has run yet');
+        return lines;
+    }
+    for (const kind of ORDER) {
+        lines.push(`  ${kind}: ${status.lastRun[kind] ?? 'never run'}`);
+    }
+    return lines;
+}
+/**
+ * 파일 하나짜리 ScopedStore (설계 §5.1).
+ *
+ * **서비스 lease 와 workspace lease 는 다른 소유 영역이다.** 저쪽은 "이 workspace 의
+ * 이번 회차를 누가 잡았는가"이고, 이쪽은 "이 기계의 runtime 을 지금 누가 도는가"다.
+ * 둘을 합치면 workspace 가 늘 때마다 기계 수준 직렬화가 무너진다.
+ *
+ * workspace 상태 저장소를 기계 뿌리에 열지 않는 이유: 그러면 ~/.asc 에 workspace 용
+ * 파일들이 생기고, 그것은 그 자리에 없어야 할 것들이다.
+ */
+export function fileScope(path) {
+    const read = async () => {
+        try {
+            return JSON.parse(await readFile(path, 'utf8'));
+        }
+        catch {
+            // 없거나 깨진 파일은 빈 것으로 본다 — lease 는 시간으로 회수되므로 안전하다
+            return {};
+        }
+    };
+    // tmp+rename. 반쯤 쓰인 lease 를 다른 프로세스가 읽으면 판정이 흔들린다 (C-11 불변식 ⑨).
+    const write = async (data) => {
+        await mkdir(dirname(path), { recursive: true });
+        const tmp = `${path}.tmp-${process.pid}`;
+        await writeFile(tmp, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+        await rename(tmp, path);
+    };
+    return {
+        async get(key) {
+            return (await read())[key] ?? null;
+        },
+        async set(key, value) {
+            await write({ ...(await read()), [key]: value });
+        },
+        async delete(key) {
+            const data = await read();
+            delete data[key];
+            await write(data);
+        },
+        async keys(prefix) {
+            return Object.keys(await read()).filter((key) => (prefix ? key.startsWith(prefix) : true));
+        },
+        async setIfAbsent(key, value) {
+            const data = await read();
+            if (key in data)
+                return false;
+            await write({ ...data, [key]: value });
+            return true;
+        },
+    };
+}

package/dist/core/runtime/coordination.d.ts

@@ -0,0 +1,312 @@
+import { z } from 'zod';
+import type { ScopedStore } from '../../ports/state-store.ts';
+/**
+ * 외부 시스템이 준 **안정적인** 신원 (F3).
+ *
+ * 사람이 보는 링크는 여기 있어도 되지만 그것이 정본은 아니다. 링크의 모양이 예상과
+ * 다르다는 이유로 생성이 실패했다고 읽고 하나 더 만든 사고가 실제로 있었다 — 그때
+ * 대조할 수 있는 다른 값이 계약에 없었다.
+ */
+export declare const RemoteIdentity: z.ZodObject<{
+    /** 어느 adapter 가 이 사실을 만들었는가. provider 이름이 아니라 adapter id 다. */
+    adapter: z.ZodString;
+    /** 그 adapter 의 어휘로 된 객체 종류. Core 는 이 문자열로 분기하지 않는다. */
+    objectType: z.ZodString;
+    /** 그 시스템 안에서 이 객체를 다시 찾을 수 있는 값. **성공의 정본이다.** */
+    objectId: z.ZodString;
+    /** 어느 자원 아래인가 (저장소·프로젝트 등). adapter 어휘 그대로. */
+    resource: z.ZodOptional<z.ZodString>;
+    /**
+     * 사람이 열어 보는 주소. **판정에 쓰지 않는다** — 모양이 바뀌어도 같은 객체다.
+     */
+    locator: z.ZodOptional<z.ZodString>;
+    /** 이 시점의 판본. 있으면 응답 중복을 가리는 데 쓴다. */
+    revisionMarker: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    adapter: string;
+    objectType: string;
+    objectId: string;
+    resource?: string | undefined;
+    revisionMarker?: string | undefined;
+    locator?: string | undefined;
+}, {
+    adapter: string;
+    objectType: string;
+    objectId: string;
+    resource?: string | undefined;
+    revisionMarker?: string | undefined;
+    locator?: string | undefined;
+}>;
+export type RemoteIdentity = z.infer<typeof RemoteIdentity>;
+/**
+ * 기대가 실제로 밖에 게시됐다는 증거.
+ *
+ * **이 레코드를 만드는 것이 게시가 아니다.** 게시는 adapter 가 하고, 여기 남는 것은
+ * 그것이 일어났다는 관측이다 — 그 구분이 사라지면 "적어 뒀으니 됐다"가 다시 성립한다.
+ */
+export declare const CommunicationEvidence: z.ZodObject<{
+    evidenceId: z.ZodString;
+    /** 어느 기대에 대한 것인가. 지금은 Bounded Query 가 기대의 정본이다 (C-04). */
+    queryId: z.ZodString;
+    /** 어느 binding 을 통해 나갔는가 (C-09). 역할 이름이며 provider 이름이 아니다. */
+    bindingRole: z.ZodOptional<z.ZodString>;
+    identity: z.ZodObject<{
+        /** 어느 adapter 가 이 사실을 만들었는가. provider 이름이 아니라 adapter id 다. */
+        adapter: z.ZodString;
+        /** 그 adapter 의 어휘로 된 객체 종류. Core 는 이 문자열로 분기하지 않는다. */
+        objectType: z.ZodString;
+        /** 그 시스템 안에서 이 객체를 다시 찾을 수 있는 값. **성공의 정본이다.** */
+        objectId: z.ZodString;
+        /** 어느 자원 아래인가 (저장소·프로젝트 등). adapter 어휘 그대로. */
+        resource: z.ZodOptional<z.ZodString>;
+        /**
+         * 사람이 열어 보는 주소. **판정에 쓰지 않는다** — 모양이 바뀌어도 같은 객체다.
+         */
+        locator: z.ZodOptional<z.ZodString>;
+        /** 이 시점의 판본. 있으면 응답 중복을 가리는 데 쓴다. */
+        revisionMarker: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        adapter: string;
+        objectType: string;
+        objectId: string;
+        resource?: string | undefined;
+        revisionMarker?: string | undefined;
+        locator?: string | undefined;
+    }, {
+        adapter: string;
+        objectType: string;
+        objectId: string;
+        resource?: string | undefined;
+        revisionMarker?: string | undefined;
+        locator?: string | undefined;
+    }>;
+    /** 누구에게 닿아야 하는가. 프로젝트 정책이 정하고 여기서는 그대로 보관한다. */
+    audience: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    publishedAt: z.ZodString;
+    /** 이 사실을 우리가 언제 봤는가. 게시 시각과 다를 수 있다. */
+    observedAt: z.ZodString;
+    /** 선언인가 관측인가 (C-10 의 같은 필드와 같은 뜻). */
+    evidenceSource: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    observedAt: string;
+    identity: {
+        adapter: string;
+        objectType: string;
+        objectId: string;
+        resource?: string | undefined;
+        revisionMarker?: string | undefined;
+        locator?: string | undefined;
+    };
+    evidenceSource: string;
+    evidenceId: string;
+    queryId: string;
+    audience: string[];
+    publishedAt: string;
+    bindingRole?: string | undefined;
+}, {
+    observedAt: string;
+    identity: {
+        adapter: string;
+        objectType: string;
+        objectId: string;
+        resource?: string | undefined;
+        revisionMarker?: string | undefined;
+        locator?: string | undefined;
+    };
+    evidenceSource: string;
+    evidenceId: string;
+    queryId: string;
+    publishedAt: string;
+    bindingRole?: string | undefined;
+    audience?: string[] | undefined;
+}>;
+export type CommunicationEvidence = z.infer<typeof CommunicationEvidence>;
+/**
+ * 그 게시물에 외부 응답이 도착했다는 증거.
+ *
+ * **답의 의미를 판정하지 않는다.** 이것은 `QueryAnswer` 가 아니고, 자동으로 그것이
+ * 되지도 않는다 — 누가 무엇을 결정할 수 있는지는 C-04 의 권한 판정이고, 사람 승인은
+ * C-13 이다. 여기 있는 것은 "왔다"까지다.
+ */
+export declare const ResponseEvidence: z.ZodObject<{
+    evidenceId: z.ZodString;
+    /** 어느 게시물에 대한 응답인가. */
+    communicationId: z.ZodString;
+    identity: z.ZodObject<{
+        /** 어느 adapter 가 이 사실을 만들었는가. provider 이름이 아니라 adapter id 다. */
+        adapter: z.ZodString;
+        /** 그 adapter 의 어휘로 된 객체 종류. Core 는 이 문자열로 분기하지 않는다. */
+        objectType: z.ZodString;
+        /** 그 시스템 안에서 이 객체를 다시 찾을 수 있는 값. **성공의 정본이다.** */
+        objectId: z.ZodString;
+        /** 어느 자원 아래인가 (저장소·프로젝트 등). adapter 어휘 그대로. */
+        resource: z.ZodOptional<z.ZodString>;
+        /**
+         * 사람이 열어 보는 주소. **판정에 쓰지 않는다** — 모양이 바뀌어도 같은 객체다.
+         */
+        locator: z.ZodOptional<z.ZodString>;
+        /** 이 시점의 판본. 있으면 응답 중복을 가리는 데 쓴다. */
+        revisionMarker: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        adapter: string;
+        objectType: string;
+        objectId: string;
+        resource?: string | undefined;
+        revisionMarker?: string | undefined;
+        locator?: string | undefined;
+    }, {
+        adapter: string;
+        objectType: string;
+        objectId: string;
+        resource?: string | undefined;
+        revisionMarker?: string | undefined;
+        locator?: string | undefined;
+    }>;
+    /** 그 시스템이 말하는 응답자. 우리 역할 이름으로 번역하지 않는다. */
+    responder: z.ZodOptional<z.ZodString>;
+    receivedAt: z.ZodString;
+    observedAt: z.ZodString;
+    evidenceSource: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    observedAt: string;
+    identity: {
+        adapter: string;
+        objectType: string;
+        objectId: string;
+        resource?: string | undefined;
+        revisionMarker?: string | undefined;
+        locator?: string | undefined;
+    };
+    evidenceSource: string;
+    evidenceId: string;
+    communicationId: string;
+    receivedAt: string;
+    responder?: string | undefined;
+}, {
+    observedAt: string;
+    identity: {
+        adapter: string;
+        objectType: string;
+        objectId: string;
+        resource?: string | undefined;
+        revisionMarker?: string | undefined;
+        locator?: string | undefined;
+    };
+    evidenceSource: string;
+    evidenceId: string;
+    communicationId: string;
+    receivedAt: string;
+    responder?: string | undefined;
+}>;
+export type ResponseEvidence = z.infer<typeof ResponseEvidence>;
+/**
+ * 파생 상태. **저장하지 않는다** — 위 증거들에서 매번 계산한다.
+ */
+export type CoordinationState = 
+/** 기대는 있는데 밖에 나간 적이 없다. */
+'UNPUBLISHED'
+/** 나갔고, 답을 기다린다. */
+ | 'WAITING_EXTERNAL'
+/** 답이 왔다. 그 답이 무엇을 뜻하는지는 여기서 정하지 않는다. */
+ | 'RESPONSE_RECEIVED'
+/** 나갔고, 애초에 답을 기대하지 않는다. */
+ | 'PUBLISHED';
+export type CoordinationView = {
+    queryId: string;
+    state: CoordinationState;
+    /** 이 기대가 답을 기다리는가. 기대 쪽 사실이며 증거가 아니다. */
+    expectsResponse: boolean;
+    communications: CommunicationEvidence[];
+    responses: ResponseEvidence[];
+};
+/**
+ * 기대 하나의 지금 상태를 계산한다.
+ *
+ * 순서가 곧 규칙이다: 응답이 있으면 왔다, 없으면 기다리는지 아닌지, 게시가 없으면
+ * 아직 나가지 않았다. **없는 것을 있는 것으로 올리는 방향은 없다.**
+ */
+export declare function deriveCoordination(input: {
+    queryId: string;
+    expectsResponse: boolean;
+    communications: readonly CommunicationEvidence[];
+    responses: readonly ResponseEvidence[];
+}): CoordinationView;
+export type AppendOutcome<T> = {
+    ok: true;
+    evidence: T;
+}
+/** 같은 id 가 이미 있다. 덮지 않는다 — 증거는 한 번만 쓰인다 (C-10 과 같은 이유). */
+ | {
+    ok: false;
+    reason: 'ALREADY_EXISTS';
+    detail: string;
+}
+/** 가리키는 게시물이 없다. 없는 것에 응답을 붙이지 않는다. */
+ | {
+    ok: false;
+    reason: 'COMMUNICATION_NOT_FOUND';
+    detail: string;
+};
+/**
+ * 조율 증거 원장. append-only 이며 `setIfAbsent` 위에 선다.
+ *
+ * 잃는 것이 표시값이 아니라 **누가 무엇을 밖에 내보냈고 누가 답했는가**이기 때문에,
+ * 나중 쓰기가 앞선 것을 덮지 않는다.
+ */
+/** 밖에서 본 글 하나. adapter 어휘를 그대로 받되 Core 는 세 가지만 본다. */
+export type ObservedRemark = {
+    id: string;
+    author: string;
+    at: string;
+    /** 사람이 쓴 것이 아니라 그 시스템이 남긴 자국인가. */
+    system?: boolean;
+};
+/**
+ * 게시물에 붙은 글 중 **응답으로 셀 것**을 고른다.
+ *
+ * 두 가지를 뺀다: 그 시스템이 스스로 남긴 자국(커밋 언급·배정 변경)과, 우리가 쓴 글.
+ * 둘 다 세면 아무도 답하지 않은 스레드가 답이 온 것으로 보인다 — 이 구조가 막으려는
+ * 바로 그 착각이다.
+ *
+ * **답의 의미는 판정하지 않는다.** 여기서 나오는 것은 "왔다"까지이고, 그것이 결정인지
+ * 승인인지는 C-04·C-13 의 몫이다.
+ */
+export declare function responsesFrom(communication: CommunicationEvidence, remarks: readonly ObservedRemark[], mine: ReadonlySet<string>): Omit<ResponseEvidence, 'observedAt'>[];
+export declare class CoordinationLedger {
+    #private;
+    constructor(scope: ScopedStore, now?: () => string);
+    publishRecorded(input: Omit<CommunicationEvidence, 'observedAt'> & {
+        observedAt?: string;
+    }): Promise<AppendOutcome<CommunicationEvidence>>;
+    responseRecorded(input: Omit<ResponseEvidence, 'observedAt'> & {
+        observedAt?: string;
+    }): Promise<AppendOutcome<ResponseEvidence>>;
+    communications(): Promise<CommunicationEvidence[]>;
+    responses(): Promise<ResponseEvidence[]>;
+    /**
+     * 이미 이 게시물이 있는가 — **원격 신원으로** 찾는다 (F3).
+     *
+     * 같은 것을 두 번 만들지 않기 위한 조회다. 제목이나 링크가 아니라 adapter 가 준
+     * 안정 id 로 본다.
+     */
+    findByIdentity(identity: Pick<RemoteIdentity, 'adapter' | 'objectType' | 'objectId'>): Promise<CommunicationEvidence | null>;
+    /** 기대 하나에 달린 증거 전부. */
+    forQuery(queryId: string): Promise<{
+        communications: CommunicationEvidence[];
+        responses: ResponseEvidence[];
+    }>;
+}
+/**
+ * 기대 목록과 증거를 합쳐 지금 상태를 낸다.
+ *
+ * 기대는 이 모듈이 만들지 않는다 — Bounded Query 가 정본이고, 여기서는 그것을 받아
+ * 증거와 맞춘다. 기대가 없으면 조율도 없다.
+ */
+export declare function viewCoordination(ledger: CoordinationLedger, expectations: readonly {
+    id: string;
+    expectsResponse: boolean;
+}[]): Promise<CoordinationView[]>;
+/**
+ * 사람이 읽는 줄. **없는 것을 0 으로 그리지 않는다** — 기대가 없으면 그렇게 말한다.
+ */
+export declare function coordinationLines(views: readonly CoordinationView[]): string[];