@asc-agent/runtime 0.3.2 → 0.5.0

package/dist/core/runtime/coordination.js

@@ -0,0 +1,247 @@
+// Coordination Evidence — 물었다는 사실과, 전달됐다는 사실과, 답이 왔다는 사실을 나눈다.
+//
+// 반복된 실패는 이것이었다:
+//
+//   dependency 가 있다
+//   ≠ 상대에게 전달됐다
+//   ≠ 상대가 응답했다
+//
+// 세 사실이 한 레코드로 뭉개지면 "Task 도 있고 무언가 오갔으니 됐다"가 성립한다.
+// 그래서 뭉개지지 않게 **따로 적는다.**
+//
+// 새 subsystem 을 만들지 않는다. 기대는 이미 Bounded Query 가 지고 있고(C-04), 여기서
+// 더하는 것은 C-10 과 같은 모양의 append-only 원장 둘뿐이다:
+//
+//   ExecutionEvidence   누가 이 세션을 실제로 집었는가        (C-10, 이미 있음)
+//   CommunicationEvidence  그 기대가 실제로 밖에 게시됐는가   (여기)
+//   ResponseEvidence       그 게시물에 실제로 답이 왔는가      (여기)
+//
+// 상태를 저장하지 않는다. `UNPUBLISHED`·`WAITING_EXTERNAL`·`RESPONSE_RECEIVED` 는
+// 전부 위 셋에서 **파생**한다 — 저장하면 그것이 곧 두 번째 정본이 되고, 증거와 어긋나는
+// 순간 어느 쪽이 맞는지 정할 방법이 없어진다.
+//
+// **provider 이름을 모른다.** 아는 것은 adapter id 와 그 adapter 가 준 opaque identity 다
+// (C-09 §6 과 같은 선). 어느 외부 시스템의 이름도 이 파일에 나오지 않으며, 그것은
+// core/** 전체에 걸린 기존 규칙이기도 하다.
+import { z } from 'zod';
+import { QUERY_ID } from "../model/ids.js";
+/**
+ * 외부 시스템이 준 **안정적인** 신원 (F3).
+ *
+ * 사람이 보는 링크는 여기 있어도 되지만 그것이 정본은 아니다. 링크의 모양이 예상과
+ * 다르다는 이유로 생성이 실패했다고 읽고 하나 더 만든 사고가 실제로 있었다 — 그때
+ * 대조할 수 있는 다른 값이 계약에 없었다.
+ */
+export const RemoteIdentity = z.object({
+    /** 어느 adapter 가 이 사실을 만들었는가. provider 이름이 아니라 adapter id 다. */
+    adapter: z.string().min(1),
+    /** 그 adapter 의 어휘로 된 객체 종류. Core 는 이 문자열로 분기하지 않는다. */
+    objectType: z.string().min(1),
+    /** 그 시스템 안에서 이 객체를 다시 찾을 수 있는 값. **성공의 정본이다.** */
+    objectId: z.string().min(1),
+    /** 어느 자원 아래인가 (저장소·프로젝트 등). adapter 어휘 그대로. */
+    resource: z.string().min(1).optional(),
+    /**
+     * 사람이 열어 보는 주소. **판정에 쓰지 않는다** — 모양이 바뀌어도 같은 객체다.
+     */
+    locator: z.string().min(1).optional(),
+    /** 이 시점의 판본. 있으면 응답 중복을 가리는 데 쓴다. */
+    revisionMarker: z.string().min(1).optional(),
+});
+/**
+ * 기대가 실제로 밖에 게시됐다는 증거.
+ *
+ * **이 레코드를 만드는 것이 게시가 아니다.** 게시는 adapter 가 하고, 여기 남는 것은
+ * 그것이 일어났다는 관측이다 — 그 구분이 사라지면 "적어 뒀으니 됐다"가 다시 성립한다.
+ */
+export const CommunicationEvidence = z.object({
+    evidenceId: z.string().min(1),
+    /** 어느 기대에 대한 것인가. 지금은 Bounded Query 가 기대의 정본이다 (C-04). */
+    queryId: z.string().regex(QUERY_ID),
+    /** 어느 binding 을 통해 나갔는가 (C-09). 역할 이름이며 provider 이름이 아니다. */
+    bindingRole: z.string().min(1).optional(),
+    identity: RemoteIdentity,
+    /** 누구에게 닿아야 하는가. 프로젝트 정책이 정하고 여기서는 그대로 보관한다. */
+    audience: z.array(z.string()).default([]),
+    publishedAt: z.string().min(1),
+    /** 이 사실을 우리가 언제 봤는가. 게시 시각과 다를 수 있다. */
+    observedAt: z.string().min(1),
+    /** 선언인가 관측인가 (C-10 의 같은 필드와 같은 뜻). */
+    evidenceSource: z.string().min(1),
+});
+/**
+ * 그 게시물에 외부 응답이 도착했다는 증거.
+ *
+ * **답의 의미를 판정하지 않는다.** 이것은 `QueryAnswer` 가 아니고, 자동으로 그것이
+ * 되지도 않는다 — 누가 무엇을 결정할 수 있는지는 C-04 의 권한 판정이고, 사람 승인은
+ * C-13 이다. 여기 있는 것은 "왔다"까지다.
+ */
+export const ResponseEvidence = z.object({
+    evidenceId: z.string().min(1),
+    /** 어느 게시물에 대한 응답인가. */
+    communicationId: z.string().min(1),
+    identity: RemoteIdentity,
+    /** 그 시스템이 말하는 응답자. 우리 역할 이름으로 번역하지 않는다. */
+    responder: z.string().min(1).optional(),
+    receivedAt: z.string().min(1),
+    observedAt: z.string().min(1),
+    evidenceSource: z.string().min(1),
+});
+/**
+ * 기대 하나의 지금 상태를 계산한다.
+ *
+ * 순서가 곧 규칙이다: 응답이 있으면 왔다, 없으면 기다리는지 아닌지, 게시가 없으면
+ * 아직 나가지 않았다. **없는 것을 있는 것으로 올리는 방향은 없다.**
+ */
+export function deriveCoordination(input) {
+    const communications = [...input.communications].sort((a, b) => a.evidenceId.localeCompare(b.evidenceId));
+    const responses = [...input.responses].sort((a, b) => a.evidenceId.localeCompare(b.evidenceId));
+    const state = communications.length === 0
+        ? 'UNPUBLISHED'
+        : responses.length > 0
+            ? 'RESPONSE_RECEIVED'
+            : input.expectsResponse
+                ? 'WAITING_EXTERNAL'
+                : 'PUBLISHED';
+    return { queryId: input.queryId, state, expectsResponse: input.expectsResponse, communications, responses };
+}
+const communicationKey = (id) => `coord:pub:${id}`;
+const responseKey = (id) => `coord:res:${id}`;
+/**
+ * 게시물에 붙은 글 중 **응답으로 셀 것**을 고른다.
+ *
+ * 두 가지를 뺀다: 그 시스템이 스스로 남긴 자국(커밋 언급·배정 변경)과, 우리가 쓴 글.
+ * 둘 다 세면 아무도 답하지 않은 스레드가 답이 온 것으로 보인다 — 이 구조가 막으려는
+ * 바로 그 착각이다.
+ *
+ * **답의 의미는 판정하지 않는다.** 여기서 나오는 것은 "왔다"까지이고, 그것이 결정인지
+ * 승인인지는 C-04·C-13 의 몫이다.
+ */
+export function responsesFrom(communication, remarks, mine) {
+    return remarks
+        .filter((remark) => !remark.system && !mine.has(remark.author))
+        .map((remark) => ({
+        // 같은 글을 다시 봐도 같은 id 다 — append-only 원장이 두 번째를 거절한다.
+        evidenceId: `${communication.evidenceId}:${remark.id}`,
+        communicationId: communication.evidenceId,
+        identity: { ...communication.identity, revisionMarker: remark.at },
+        responder: remark.author,
+        receivedAt: remark.at,
+        evidenceSource: 'surface-remark',
+    }));
+}
+export class CoordinationLedger {
+    #scope;
+    #now;
+    constructor(scope, now = () => new Date().toISOString()) {
+        this.#scope = scope;
+        this.#now = now;
+    }
+    async publishRecorded(input) {
+        const evidence = CommunicationEvidence.parse({ ...input, observedAt: input.observedAt ?? this.#now() });
+        const written = await this.#scope.setIfAbsent(communicationKey(evidence.evidenceId), JSON.stringify(evidence));
+        return written
+            ? { ok: true, evidence }
+            : { ok: false, reason: 'ALREADY_EXISTS', detail: `${evidence.evidenceId} 는 이미 있다` };
+    }
+    async responseRecorded(input) {
+        const target = await this.#scope.get(communicationKey(input.communicationId));
+        if (!target) {
+            return {
+                ok: false,
+                reason: 'COMMUNICATION_NOT_FOUND',
+                detail: `${input.communicationId} 를 찾지 못했다 — 게시된 적 없는 것에 응답을 붙이지 않는다`,
+            };
+        }
+        const evidence = ResponseEvidence.parse({ ...input, observedAt: input.observedAt ?? this.#now() });
+        const written = await this.#scope.setIfAbsent(responseKey(evidence.evidenceId), JSON.stringify(evidence));
+        return written
+            ? { ok: true, evidence }
+            : { ok: false, reason: 'ALREADY_EXISTS', detail: `${evidence.evidenceId} 는 이미 있다` };
+    }
+    async communications() {
+        const out = [];
+        for (const key of await this.#scope.keys('coord:pub:')) {
+            const raw = await this.#scope.get(key);
+            if (raw)
+                out.push(CommunicationEvidence.parse(JSON.parse(raw)));
+        }
+        return out.sort((a, b) => a.evidenceId.localeCompare(b.evidenceId));
+    }
+    async responses() {
+        const out = [];
+        for (const key of await this.#scope.keys('coord:res:')) {
+            const raw = await this.#scope.get(key);
+            if (raw)
+                out.push(ResponseEvidence.parse(JSON.parse(raw)));
+        }
+        return out.sort((a, b) => a.evidenceId.localeCompare(b.evidenceId));
+    }
+    /**
+     * 이미 이 게시물이 있는가 — **원격 신원으로** 찾는다 (F3).
+     *
+     * 같은 것을 두 번 만들지 않기 위한 조회다. 제목이나 링크가 아니라 adapter 가 준
+     * 안정 id 로 본다.
+     */
+    async findByIdentity(identity) {
+        for (const evidence of await this.communications()) {
+            const seen = evidence.identity;
+            if (seen.adapter === identity.adapter && seen.objectType === identity.objectType && seen.objectId === identity.objectId) {
+                return evidence;
+            }
+        }
+        return null;
+    }
+    /** 기대 하나에 달린 증거 전부. */
+    async forQuery(queryId) {
+        const communications = (await this.communications()).filter((evidence) => evidence.queryId === queryId);
+        const ids = new Set(communications.map((evidence) => evidence.evidenceId));
+        const responses = (await this.responses()).filter((evidence) => ids.has(evidence.communicationId));
+        return { communications, responses };
+    }
+}
+/**
+ * 기대 목록과 증거를 합쳐 지금 상태를 낸다.
+ *
+ * 기대는 이 모듈이 만들지 않는다 — Bounded Query 가 정본이고, 여기서는 그것을 받아
+ * 증거와 맞춘다. 기대가 없으면 조율도 없다.
+ */
+export async function viewCoordination(ledger, expectations) {
+    const views = [];
+    for (const expectation of expectations) {
+        const { communications, responses } = await ledger.forQuery(expectation.id);
+        views.push(deriveCoordination({
+            queryId: expectation.id,
+            expectsResponse: expectation.expectsResponse,
+            communications,
+            responses,
+        }));
+    }
+    return views.sort((a, b) => a.queryId.localeCompare(b.queryId));
+}
+/**
+ * 사람이 읽는 줄. **없는 것을 0 으로 그리지 않는다** — 기대가 없으면 그렇게 말한다.
+ */
+export function coordinationLines(views) {
+    if (views.length === 0)
+        return ['No external expectation is recorded here.'];
+    const lines = [];
+    const counts = {
+        UNPUBLISHED: 0,
+        WAITING_EXTERNAL: 0,
+        RESPONSE_RECEIVED: 0,
+        PUBLISHED: 0,
+    };
+    for (const view of views)
+        counts[view.state] += 1;
+    lines.push(`Coordination: ${views.length} expectation${views.length === 1 ? '' : 's'} — ` +
+        `unpublished ${counts.UNPUBLISHED} · waiting ${counts.WAITING_EXTERNAL} · ` +
+        `answered ${counts.RESPONSE_RECEIVED} · published ${counts.PUBLISHED}`);
+    for (const view of views) {
+        const where = view.communications[0]?.identity;
+        // 링크는 사람이 열어 보는 값이다. 없으면 안정 신원을 보인다 — 판정의 정본은 그쪽이다.
+        const at = where ? ` @ ${where.locator ?? `${where.adapter}:${where.objectType}:${where.objectId}`}` : '';
+        lines.push(`  ${view.queryId} ${view.state}${at}`);
+    }
+    return lines;
+}

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

@@ -2,6 +2,7 @@ import type { StateStore } from '../../ports/state-store.ts';
 import type { HealthAlert } from '../monitor/health-alerts.ts';
 import type { EscalationRecord } from './escalation.ts';
 import type { DecisionSummary } from '../view/decision-view.ts';
+import type { CoordinationView } from './coordination.ts';
 export type FrontState = {
     /** 지금 돌고 있는 것. */
     active: {
@@ -57,6 +58,13 @@ export type FrontState = {
         workspaceId: string;
         locator: string;
     };
+    /**
+     * 밖에 물어 둔 것들의 지금 상태.
+     *
+     * **저장된 값이 아니다** — 기대와 증거에서 파생해 받은 것을 그대로 보인다. 이것이
+     * 화면에 없으면 "안에서 할 일이 없다"가 "끝났다"로 읽힌다.
+     */
+    coordination?: readonly CoordinationView[];
 };
 export type RestoreInput = {
     store: StateStore;
@@ -68,6 +76,8 @@ export type RestoreInput = {
         workspaceId: string;
         locator: string;
     };
+    /** 파생된 조율 상태. 없으면 이 축을 그리지 않는다 — 모르는 것을 "없음"으로 그리지 않는다. */
+    coordination?: readonly CoordinationView[];
     /**
      * 세션별 소유권 조회. **구조로만 받는다** — Core가 Host adapter를 알면 안 된다.
      * 없으면 이 축은 그리지 않는다(모르는 것을 "없음"으로 그리지 않는다).
@@ -85,6 +95,54 @@ export type RestoreInput = {
  * 새로 계산하지 않는다. 여기서 파생을 만들면 그 파생이 곧 두 번째 정본이 된다.
  */
 export declare function restoreFront(input: RestoreInput): Promise<FrontState>;
+/**
+ * 새 Front Session이 열렸을 때의 판정 (C-12 §4).
+ *
+ * **Host를 모른다.** Claude Code든 다른 무엇이든 "여기서 세션이 열렸다"는 사실 하나를
+ * 받고, 붙을 수 있는지와 무엇이 걸려 있는지를 답한다. Host adapter는 이 답을 자기
+ * 호스트의 형식으로 옮기기만 한다 — Core에 `if (host === 'claude')` 가 생기면 그 순간
+ * 두 번째 호스트는 Core를 고쳐야 들어온다.
+ *
+ * 세 갈래를 **구분한다**:
+ *
+ *   NOT_ASC       이 경로는 ASC 소관이 아니다. 조용히 지나간다 — 남의 도구를 방해하지
+ *                 않는다 (C-11 불변식 ⑪).
+ *   UNAVAILABLE   붙어야 하는데 못 붙었다. **빈 화면을 주지 않고 왜인지 말한다**
+ *                 (C-12 불변식 ⑰).
+ *   BOUND         붙었다. 지금 무엇이 걸려 있는지가 함께 온다.
+ */
+export type FrontOpening = {
+    kind: 'NOT_ASC';
+} | {
+    kind: 'UNAVAILABLE';
+    detail: string;
+} | {
+    kind: 'BOUND';
+    state: FrontState;
+};
+/**
+ * 세션이 열렸다 — 붙을 수 있는가.
+ *
+ * **읽기만 한다.** 세션을 만들지 않는다: 실제 작업 요청이 없는데 Session Contract를
+ * 만들어 내는 것은 없던 사실을 제조하는 일이다 (AGENTS.md "Do not create a session to
+ * demonstrate that setup worked" 와 같은 선).
+ */
+export declare function openFront(input: {
+    /** 이 경로가 어느 workspace인가. `null` 이면 ASC 소관이 아니다. */
+    workspace: {
+        workspaceId: string;
+        locator: string;
+    } | null;
+    /** 상태를 읽는다. 던지면 UNAVAILABLE 로 접힌다 — 못 읽은 것을 "없음"으로 그리지 않는다. */
+    restore: () => Promise<FrontState>;
+}): Promise<FrontOpening>;
+/**
+ * Host가 사람에게 보여 줄 줄. **Host별 포장은 여기 없다** — 문자열 목록까지가 Core다.
+ *
+ * `NOT_ASC` 는 빈 목록이다. 할 말이 없는 것과 "아무 일도 없다"는 다르고, 전자는
+ * 아무것도 띄우지 않는 것이 맞다.
+ */
+export declare function frontOpeningLines(opening: FrontOpening): string[];
 /**
  * 사람이 읽는 복원 화면.
  *

package/dist/core/runtime/front.js

@@ -61,8 +61,43 @@ export async function restoreFront(input) {
             runnable: [...record.stillRunnableNodes],
         })),
         ...(input.workspace ? { workspace: input.workspace } : {}),
+        ...(input.coordination ? { coordination: input.coordination } : {}),
     };
 }
+/**
+ * 세션이 열렸다 — 붙을 수 있는가.
+ *
+ * **읽기만 한다.** 세션을 만들지 않는다: 실제 작업 요청이 없는데 Session Contract를
+ * 만들어 내는 것은 없던 사실을 제조하는 일이다 (AGENTS.md "Do not create a session to
+ * demonstrate that setup worked" 와 같은 선).
+ */
+export async function openFront(input) {
+    if (!input.workspace)
+        return { kind: 'NOT_ASC' };
+    try {
+        return { kind: 'BOUND', state: await input.restore() };
+    }
+    catch (error) {
+        return { kind: 'UNAVAILABLE', detail: error instanceof Error ? error.message : String(error) };
+    }
+}
+/**
+ * Host가 사람에게 보여 줄 줄. **Host별 포장은 여기 없다** — 문자열 목록까지가 Core다.
+ *
+ * `NOT_ASC` 는 빈 목록이다. 할 말이 없는 것과 "아무 일도 없다"는 다르고, 전자는
+ * 아무것도 띄우지 않는 것이 맞다.
+ */
+export function frontOpeningLines(opening) {
+    switch (opening.kind) {
+        case 'NOT_ASC':
+            return [];
+        case 'UNAVAILABLE':
+            // 조용히 빈 화면을 주지 않는다 (C-12 불변식 ⑰)
+            return [`ASC is attached here but its state could not be read — ${opening.detail}`];
+        case 'BOUND':
+            return renderFront(opening.state);
+    }
+}
 /**
  * 사람이 읽는 복원 화면.
  *
@@ -129,12 +164,26 @@ export function renderFront(state) {
             lines.push(`  … and ${state.awaitingController.length - 5} more`);
         }
     }
+    // 밖에 걸린 것을 안에서 할 일과 나눠 든다. 나가지 않은 기대는 **아무도 기다리지
+    // 않는다** — 그것이 가장 조용한 실패다.
+    const outward = (state.coordination ?? []).filter((view) => view.state !== 'PUBLISHED');
+    if (outward.length > 0) {
+        const unpublished = outward.filter((view) => view.state === 'UNPUBLISHED');
+        const waiting = outward.filter((view) => view.state === 'WAITING_EXTERNAL');
+        const answered = outward.filter((view) => view.state === 'RESPONSE_RECEIVED');
+        lines.push(`Asked outside (${outward.length}): not sent ${unpublished.length} · waiting ${waiting.length} · answered ${answered.length}`);
+        // 안 나간 것을 먼저 든다 — 기다리는 것보다 나쁜 상태다
+        for (const view of [...unpublished, ...answered, ...waiting]) {
+            lines.push(`  ${view.queryId} ${view.state}`);
+        }
+    }
     if (state.pendingDecisions.length === 0 &&
         state.active.length === 0 &&
         state.escalations.length === 0 &&
         state.unclaimed.length === 0 &&
         state.awaitingCollect.length === 0 &&
-        state.awaitingController.length === 0) {
+        state.awaitingController.length === 0 &&
+        outward.length === 0) {
         // 비어 있는 것과 못 보는 것을 구분한다 (C-12 불변식 ⑫과 같은 태도)
         lines.push(state.health.length > 0
             ? 'Nothing is pending — but read the monitoring state above first.'

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

@@ -0,0 +1,107 @@
+import type { CoordinationSurfacePort, PublicPayload, SurfaceCandidate } from '../../ports/coordination-surface.ts';
+import type { CoordinationLedger, CommunicationEvidence, RemoteIdentity } from './coordination.ts';
+/**
+ * 게시 의도. **내부와 공개를 처음부터 다른 필드로 든다** (F4).
+ *
+ * 한 문자열에 담았다가 나중에 가르는 경로는 여기 없다. `internal` 은 이 타입 밖으로
+ * 나가지 않으며, Port 가 받는 것은 `publicPayload` 뿐이다.
+ */
+export type PublishIntent = {
+    /** 어느 기대에 대한 게시인가. */
+    queryId: string;
+    /** 밖으로 나가는 내용 전부. */
+    publicPayload: PublicPayload;
+    /** 상관 관계·근거 출처·라우팅·사적 메모. **경계를 넘지 않는다.** */
+    internal?: Record<string, unknown>;
+    /** 누구에게 닿아야 하는가. 프로젝트 정책이 정한다. */
+    audience?: readonly string[];
+    /** 이미 아는 게시물. 있으면 찾기의 첫 근거가 된다. */
+    known?: readonly Pick<RemoteIdentity, 'objectType' | 'objectId'>[];
+    /** 관련 작업 항목. adapter 어휘 그대로. */
+    workReference?: string;
+};
+export type PublishDecision = {
+    verdict: 'ATTACH_EXISTING';
+    candidate: SurfaceCandidate;
+    why: string;
+} | {
+    verdict: 'CREATE_NEW';
+    why: string;
+} | {
+    verdict: 'AMBIGUOUS';
+    candidates: SurfaceCandidate[];
+    why: string;
+};
+/**
+ * 찾은 것들을 보고 무엇을 할지 정한다. **밖을 치지 않는다** — 판정만 한다.
+ *
+ * 강한 근거(이미 아는 신원 · 우리가 심은 상관 관계)가 정확히 하나면 그것에 붙는다.
+ * 강한 근거가 여럿이면 고르지 않는다. 약한 근거뿐이면 그것으로 붙지 않고, 그렇다고
+ * 새로 만들지도 않는다 — 같은 것이 이미 있을 수 있기 때문이다.
+ */
+export declare function decidePublish(candidates: readonly SurfaceCandidate[]): PublishDecision;
+export type PublishOutcome = 
+/** 새로 만들었고, 되읽어 확인했다. */
+{
+    ok: true;
+    action: 'CREATED';
+    identity: RemoteIdentity;
+    evidence: Omit<CommunicationEvidence, 'evidenceId' | 'observedAt'>;
+}
+/** 이미 있던 것에 붙였다. 아무것도 만들지 않았다. */
+ | {
+    ok: true;
+    action: 'ATTACHED';
+    identity: RemoteIdentity;
+    evidence: Omit<CommunicationEvidence, 'evidenceId' | 'observedAt'>;
+}
+/** 사람이 정해야 한다. **만들지 않았다.** */
+ | {
+    ok: false;
+    reason: 'AMBIGUOUS';
+    candidates: SurfaceCandidate[];
+    detail: string;
+}
+/** 찾지 못했다 — 없는 것과 다르다. 이 상태에서 만들지 않는다. */
+ | {
+    ok: false;
+    reason: 'DISCOVERY_FAILED';
+    detail: string;
+}
+/** 만들었다는데 되읽히지 않는다. 다시 만들지 않는다. */
+ | {
+    ok: false;
+    reason: 'NOT_VERIFIED';
+    identity: RemoteIdentity;
+    detail: string;
+} | {
+    ok: false;
+    reason: 'CREATE_FAILED';
+    detail: string;
+};
+export type PublishDeps = {
+    surface: CoordinationSurfacePort;
+    /** 이 binding 이 어떤 역할로 쓰이는가 (C-09). provider 이름이 아니다. */
+    bindingRole?: string;
+    now?: () => string;
+};
+/**
+ * 한 번 게시한다.
+ *
+ * **되읽기가 성공의 정본이다.** 만들기가 예외 없이 끝났다는 것만으로 끝내지 않는다 —
+ * 그 반대(만들어졌는데 응답을 잃음)가 실제로 일어났고, 그때 다시 만들면 중복이 된다.
+ * 되읽히지 않으면 실패로 적되 **다시 만들지 않는다**: 다음 회차가 찾기부터 다시 한다.
+ */
+export declare function publishOnce(intent: PublishIntent, deps: PublishDeps): Promise<PublishOutcome>;
+/**
+ * 게시 사실을 원장에 남긴다.
+ *
+ * `evidenceId` 를 **신원에서 만든다** — 같은 게시물을 다시 봐도 같은 id 가 나오고,
+ * 원장은 append-only 이므로 두 번째 기록은 조용히 거절된다 (F3). 무작위 id 를 쓰면
+ * 재시도할 때마다 같은 게시가 새 사실로 쌓인다.
+ */
+export declare function recordPublication(ledger: CoordinationLedger, outcome: Extract<PublishOutcome, {
+    ok: true;
+}>): Promise<Awaited<ReturnType<CoordinationLedger['publishRecorded']>>>;
+/** 사람이 읽는 한 줄. 무엇을 했는지·무엇이 남았는지가 여기 있어야 한다. */
+export declare function publishLine(outcome: PublishOutcome): string;

package/dist/core/runtime/publish.js

@@ -0,0 +1,153 @@
+// Publish — 밖에 하나를 만들되, 두 번 만들지 않는다.
+//
+// 실 프로젝트에서 이런 일이 있었다:
+//
+//   생성 요청 → 원격에 실제로 생성됨 → 돌아온 주소 모양이 예상과 다름
+//   → 실패로 판정 → 다시 생성 → 같은 것이 둘
+//
+// 원인은 재시도가 아니라 **성공의 정본이 주소였다**는 것이다. 주소는 사람이 여는 값이고
+// 시스템마다 모양이 다르며 바뀌기도 한다. 그것으로 존재를 판정하면 존재하지 않는 실패가
+// 만들어진다.
+//
+// 그래서 순서를 고정한다:
+//
+//   찾는다 → 정한다 → (필요하면) 만든다 → 되읽는다 → 증거를 남긴다
+//
+// 그리고 세 판정 중 하나로만 끝난다:
+//
+//   ATTACH_EXISTING   이미 있다. 만들지 않는다
+//   CREATE_NEW        없다. 만든다
+//   AMBIGUOUS         모르겠다. **만들지 않는다**
+//
+// 모호할 때 만드는 것이 중복을 만든다. 제목이 비슷하다는 것은 근거가 아니다 — 안정적인
+// 관계 근거가 없으면 모르는 것이 맞고, 그 판단은 사람이 한다.
+/**
+ * 찾은 것들을 보고 무엇을 할지 정한다. **밖을 치지 않는다** — 판정만 한다.
+ *
+ * 강한 근거(이미 아는 신원 · 우리가 심은 상관 관계)가 정확히 하나면 그것에 붙는다.
+ * 강한 근거가 여럿이면 고르지 않는다. 약한 근거뿐이면 그것으로 붙지 않고, 그렇다고
+ * 새로 만들지도 않는다 — 같은 것이 이미 있을 수 있기 때문이다.
+ */
+export function decidePublish(candidates) {
+    const strong = candidates.filter((candidate) => candidate.matchedBy === 'known-identity' || candidate.matchedBy === 'correlation');
+    if (strong.length === 1) {
+        return {
+            verdict: 'ATTACH_EXISTING',
+            candidate: strong[0],
+            why: `이미 있다 (${strong[0].matchedBy})`,
+        };
+    }
+    if (strong.length > 1) {
+        return {
+            verdict: 'AMBIGUOUS',
+            candidates: strong,
+            why: `강한 근거를 가진 후보가 ${strong.length}개다 — 고르지 않는다`,
+        };
+    }
+    const weak = candidates.filter((candidate) => candidate.matchedBy === 'work-reference' || candidate.matchedBy === 'weak');
+    if (weak.length > 0) {
+        // 제목이나 작업 항목이 겹친다는 것은 같은 조율이라는 뜻이 아니다. 붙이지도, 만들지도
+        // 않는다 — 여기서 만들면 중복이 나고, 붙이면 남의 스레드에 끼어든다.
+        return {
+            verdict: 'AMBIGUOUS',
+            candidates: weak,
+            why: `약한 근거만 있다 (${weak.map((candidate) => candidate.matchedBy).join(', ')}) — 사람이 정한다`,
+        };
+    }
+    return { verdict: 'CREATE_NEW', why: '후보 없음' };
+}
+/**
+ * 한 번 게시한다.
+ *
+ * **되읽기가 성공의 정본이다.** 만들기가 예외 없이 끝났다는 것만으로 끝내지 않는다 —
+ * 그 반대(만들어졌는데 응답을 잃음)가 실제로 일어났고, 그때 다시 만들면 중복이 된다.
+ * 되읽히지 않으면 실패로 적되 **다시 만들지 않는다**: 다음 회차가 찾기부터 다시 한다.
+ */
+export async function publishOnce(intent, deps) {
+    const now = deps.now ?? (() => new Date().toISOString());
+    const query = {
+        correlation: intent.queryId,
+        ...(intent.workReference ? { workReference: intent.workReference } : {}),
+        ...(intent.known ? { known: intent.known } : {}),
+    };
+    let candidates;
+    try {
+        candidates = await deps.surface.find(query);
+    }
+    catch (error) {
+        // 못 찾은 것을 "없다"로 읽으면 그 자리에서 중복이 난다.
+        return { ok: false, reason: 'DISCOVERY_FAILED', detail: String(error) };
+    }
+    const decision = decidePublish(candidates);
+    if (decision.verdict === 'AMBIGUOUS') {
+        return { ok: false, reason: 'AMBIGUOUS', candidates: decision.candidates, detail: decision.why };
+    }
+    const evidenceFor = (identity, source) => ({
+        queryId: intent.queryId,
+        ...(deps.bindingRole ? { bindingRole: deps.bindingRole } : {}),
+        identity,
+        audience: [...(intent.audience ?? [])],
+        publishedAt: now(),
+        evidenceSource: source,
+    });
+    if (decision.verdict === 'ATTACH_EXISTING') {
+        return {
+            ok: true,
+            action: 'ATTACHED',
+            identity: decision.candidate.identity,
+            evidence: evidenceFor(decision.candidate.identity, 'surface-discovered'),
+        };
+    }
+    let created;
+    try {
+        // **공개될 것만 넘어간다.** `intent.internal` 은 이 호출에 닿지 않는다 (F4).
+        created = await deps.surface.create(intent.publicPayload, query);
+    }
+    catch (error) {
+        return { ok: false, reason: 'CREATE_FAILED', detail: String(error) };
+    }
+    const snapshot = await deps.surface.read(created).catch(() => null);
+    if (!snapshot) {
+        return {
+            ok: false,
+            reason: 'NOT_VERIFIED',
+            identity: created,
+            detail: '만들었다고 했는데 되읽히지 않는다 — 다시 만들지 않는다. 다음 회차가 찾기부터 다시 한다.',
+        };
+    }
+    return {
+        ok: true,
+        action: 'CREATED',
+        identity: snapshot.identity,
+        evidence: evidenceFor(snapshot.identity, 'surface-read-back'),
+    };
+}
+/**
+ * 게시 사실을 원장에 남긴다.
+ *
+ * `evidenceId` 를 **신원에서 만든다** — 같은 게시물을 다시 봐도 같은 id 가 나오고,
+ * 원장은 append-only 이므로 두 번째 기록은 조용히 거절된다 (F3). 무작위 id 를 쓰면
+ * 재시도할 때마다 같은 게시가 새 사실로 쌓인다.
+ */
+export async function recordPublication(ledger, outcome) {
+    const { identity } = outcome;
+    const evidenceId = `${outcome.evidence.queryId}:${identity.adapter}:${identity.objectType}:${identity.objectId}`;
+    return ledger.publishRecorded({ ...outcome.evidence, evidenceId });
+}
+/** 사람이 읽는 한 줄. 무엇을 했는지·무엇이 남았는지가 여기 있어야 한다. */
+export function publishLine(outcome) {
+    if (outcome.ok) {
+        const at = outcome.identity.locator ?? `${outcome.identity.objectType}:${outcome.identity.objectId}`;
+        return outcome.action === 'CREATED' ? `published — ${at}` : `already there, attached — ${at}`;
+    }
+    switch (outcome.reason) {
+        case 'AMBIGUOUS':
+            return `not published — ${outcome.detail}. ${outcome.candidates.length} candidate(s); a person picks one.`;
+        case 'DISCOVERY_FAILED':
+            return `not published — could not look for an existing one (${outcome.detail}). Nothing was created.`;
+        case 'NOT_VERIFIED':
+            return `created but not verified — ${outcome.detail}`;
+        case 'CREATE_FAILED':
+            return `not published — ${outcome.detail}`;
+    }
+}