@asc-agent/runtime 0.4.0 → 0.5.0

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}`;
+    }
+}

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

@@ -37,3 +37,25 @@ export declare function dueWorkspaces(views: readonly WorkspaceView[]): {
 }[];
 /** 사람이 읽는 기계 전체 화면. `cd` 없이 지금 무엇이 도는지 보여야 한다 (설계 §13.2). */
 export declare function renderWorkspaces(views: readonly WorkspaceView[]): string[];
+/** 회차 하나에서 workspace 하나가 어떻게 끝났는가. */
+export type PassResult = {
+    workspaceId: string;
+    code: number;
+};
+/**
+ * 기계 회차 전체의 결과 (P0-R2).
+ *
+ * 원칙 둘이 같이 선다: **한 workspace 의 실패가 다른 workspace 를 세우지 않는다** — 그래서
+ * 전부 돌린 뒤에 센다. 그리고 **기계 수준 결과는 실패를 삼키지 않는다** — 하나라도 0 이 아니면
+ * 회차도 0 이 아니다. 예전에는 무조건 0 을 돌려줘서 OS 기록(LastExitStatus)에는 두 workspace 가
+ * 실패한 회차가 정상으로 남았다. 실패를 지운 것이 아니라 볼 수 없게 만든 것이고, 그것이 더 나쁘다.
+ */
+export declare function summarizePass(ran: readonly PassResult[], skipped: readonly {
+    workspaceId: string;
+    health: WorkspaceHealth;
+}[]): {
+    code: 0 | 1;
+    outcome: 'ok' | 'partial' | 'failed';
+    failed: PassResult[];
+    line: string;
+};

package/dist/core/runtime/workspaces.js

@@ -62,3 +62,21 @@ export function renderWorkspaces(views) {
     }
     return lines;
 }
+/**
+ * 기계 회차 전체의 결과 (P0-R2).
+ *
+ * 원칙 둘이 같이 선다: **한 workspace 의 실패가 다른 workspace 를 세우지 않는다** — 그래서
+ * 전부 돌린 뒤에 센다. 그리고 **기계 수준 결과는 실패를 삼키지 않는다** — 하나라도 0 이 아니면
+ * 회차도 0 이 아니다. 예전에는 무조건 0 을 돌려줘서 OS 기록(LastExitStatus)에는 두 workspace 가
+ * 실패한 회차가 정상으로 남았다. 실패를 지운 것이 아니라 볼 수 없게 만든 것이고, 그것이 더 나쁘다.
+ */
+export function summarizePass(ran, skipped) {
+    const failed = ran.filter((result) => result.code !== 0);
+    const outcome = failed.length === 0 ? 'ok' : failed.length === ran.length ? 'failed' : 'partial';
+    const parts = [`${ran.length - failed.length} passed`];
+    if (failed.length > 0)
+        parts.push(`${failed.length} failed (${failed.map((r) => `${r.workspaceId}: ${r.code}`).join(', ')})`);
+    if (skipped.length > 0)
+        parts.push(`${skipped.length} skipped (${skipped.map((s) => s.health).join(', ')})`);
+    return { code: failed.length === 0 ? 0 : 1, outcome, failed, line: `Machine pass ${outcome} — ${parts.join(' · ')}` };
+}

package/dist/ports/coordination-surface.d.ts

@@ -0,0 +1,59 @@
+import type { RemoteIdentity } from '../core/runtime/coordination.ts';
+/**
+ * 밖으로 나가는 내용 **전부**.
+ *
+ * 상관 관계·근거 출처·라우팅·사적 메모는 여기 없다. 그것들은 호출자 쪽 내부 값이며
+ * 이 타입으로 들어올 자리가 없다 — 그것이 이 분리의 요점이다.
+ */
+export type PublicPayload = {
+    title: string;
+    body: string;
+    labels?: readonly string[];
+};
+/**
+ * 이미 있는 것을 찾기 위한 질의.
+ *
+ * **제목 유사도로 찾지 않는다.** 제목은 사람이 바꾸고, 비슷한 제목은 다른 것일 수 있다.
+ * 여기서 주는 것은 안정적인 관계 근거다 — 무엇에 대한 조율인지, 어떤 작업 항목에
+ * 걸려 있는지, 우리가 이미 아는 게시물이 있는지.
+ */
+export type SurfaceQuery = {
+    /** 이 조율이 어느 기대에 대한 것인가. adapter 는 이것을 자기 방식으로 심을 수 있다. */
+    correlation: string;
+    /** 관련된 작업 항목의 신원. adapter 어휘 그대로이며 Core 는 해석하지 않는다. */
+    workReference?: string;
+    /** 이미 아는 게시물. 있으면 그것부터 확인한다. */
+    known?: readonly Pick<RemoteIdentity, 'objectType' | 'objectId'>[];
+};
+/** 찾아진 후보 하나. */
+export type SurfaceCandidate = {
+    identity: RemoteIdentity;
+    title: string;
+    /**
+     * 왜 후보인가. **판정 근거를 값으로 든다** — 산문으로 적으면 호출자가 그것으로
+     * 판단할 수 없다.
+     */
+    matchedBy: 'known-identity' | 'correlation' | 'work-reference' | 'weak';
+    /** 닫힌 것인가. 닫힌 곳에 이어 붙일지는 호출자가 정한다. */
+    closed?: boolean;
+};
+/** 되읽기 결과. 없으면 `null` — "만들었다고 했는데 없다"는 별개의 사실이다. */
+export type SurfaceSnapshot = {
+    identity: RemoteIdentity;
+    title: string;
+    closed?: boolean;
+};
+/**
+ * 조율 표면 하나. adapter 가 구현한다.
+ *
+ * Core 는 이 인터페이스만 알고 provider 를 모른다 (C-09 §6).
+ */
+export interface CoordinationSurfacePort {
+    readonly id: string;
+    /** 이미 있는가. 없으면 빈 배열 — 못 찾은 것과 없는 것을 호출자가 구분하려면 throw 한다. */
+    find(query: SurfaceQuery): Promise<SurfaceCandidate[]>;
+    /** 만든다. 돌려주는 것은 주소가 아니라 **안정 신원**이다. */
+    create(payload: PublicPayload, query: SurfaceQuery): Promise<RemoteIdentity>;
+    /** 지금도 있는가. 만든 직후 이것으로 확인한다 — 만들었다는 주장만으로 끝내지 않는다. */
+    read(identity: Pick<RemoteIdentity, 'objectType' | 'objectId'>): Promise<SurfaceSnapshot | null>;
+}

package/dist/ports/coordination-surface.js

@@ -0,0 +1,16 @@
+// Coordination Surface — 밖에 무언가를 게시하고, 그것을 다시 찾고, 다시 읽는 통로.
+//
+// 기존 `ScmPort.execute` 로는 이 일을 할 수 없다. 그쪽은 성공을 문자열 하나로 돌려주고
+// (`resultRef`), 만들기 전에 이미 있는지 찾는 경로도, 만든 뒤 정말 있는지 되읽는 경로도
+// 없다. 실 프로젝트에서 그 구조가 같은 것을 두 번 만들게 했다:
+//
+//   생성 성공 → 돌아온 주소 모양이 예상과 다름 → 실패로 판정 → 다시 생성
+//
+// 대조할 값이 계약에 없으면 그 판정을 막을 방법이 없다. 그래서 이 Port 는 세 가지를
+// 요구한다 — **찾기 · 만들기 · 되읽기**. 그리고 성공의 정본은 주소가 아니라 그 시스템이
+// 준 안정적인 id 다.
+//
+// **공개될 것만 지나간다.** `PublicPayload` 밖의 값은 이 경계에 올 수 없다 — 내부 메모와
+// 공개 본문을 한 문자열에 담았다가 나중에 가르는 구조가 유출을 만들었고, 관례로 가르면
+// 언젠가 갈리지 않는다 (F4).
+export {};

package/dist/ports/resource-context.d.ts

@@ -6,6 +6,11 @@ export type ContextComment = {
     body: string;
     /** 아직 닫히지 않은 논의인가. provider가 알려주지 않으면 생략한다 — 추측하지 않는다. */
     unresolved?: boolean;
+    /**
+     * 사람이 쓴 것이 아니라 그 시스템이 남긴 자국인가 (커밋 언급·배정 변경 등).
+     * 사람의 답과 섞이면 "답이 왔다"가 자동으로 성립해 버린다.
+     */
+    system?: boolean;
 };
 export type ResourceSnapshot = {
     reference: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asc-agent/runtime",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "ASC (Agent Session Control) \u2014 local-first human-in-the-loop agent control plane: core, CLI, and adapters",
   "keywords": [
     "agent",