@asc-agent/runtime 0.1.0

package/dist/adapters/mattermost/presentation.d.ts

@@ -0,0 +1,43 @@
+import type { DecisionSummary } from '../../core/view/decision-view.ts';
+import type { DeliveryOutcome, DigestBatch, PresentationCapability, PresentationPort } from '../../ports/presentation.ts';
+export type MattermostPost = {
+    channel_id: string;
+    message: string;
+    root_id?: string;
+};
+export type MattermostTransport = {
+    /** 게시 한 번. 성공하면 provider의 post id를 돌려준다. */
+    post(payload: MattermostPost): Promise<{
+        ok: true;
+        id: string;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+};
+export type MattermostPresentationDeps = {
+    transport: MattermostTransport;
+    channelId: string;
+    /** 이 채널의 이름. 사람이 읽는 표시에만 쓰고 판정에는 쓰지 않는다. */
+    id?: string;
+};
+export declare class MattermostPresentation implements PresentationPort {
+    #private;
+    readonly id: string;
+    readonly capabilities: ReadonlySet<PresentationCapability>;
+    constructor(deps: MattermostPresentationDeps);
+    presentDigest(batch: DigestBatch): Promise<DeliveryOutcome>;
+    /**
+     * 지금 끊어야 하는 한 건.
+     *
+     * 요약만 받는다 — 전체 view를 실어 나르면 전달 한 번에 조사 한 번이 딸려 붙는다
+     * (Port 주석). 더 필요하면 사람이 `requestId` 로 ASC에서 읽는다.
+     */
+    presentUrgent(item: DecisionSummary): Promise<DeliveryOutcome>;
+}
+/**
+ * 묶음 한 덩어리를 메시지로. **결정 버튼을 만들지 않는다** — 여기에 버튼이 생기는 순간
+ * 메신저가 결정 경로가 되고, 그건 다른 계약이다.
+ */
+export declare function renderBatch(batch: DigestBatch): string;
+export declare function renderUrgent(item: DecisionSummary): string;

package/dist/adapters/mattermost/presentation.js

@@ -0,0 +1,88 @@
+// Mattermost Presentation — 묶음과 급한 것을 메신저로 건넨다 (C-08 §1, B-13).
+//
+// **PresentationPort를 바꾸지 않는다.** 채널 하나가 늘었다고 계약이 흔들리면 그건 계약이
+// 아니라 첫 구현의 형태였다는 뜻이다. 여기서 하는 일은 그 계약을 이 provider의 어휘로
+// 옮기는 것뿐이다.
+//
+// 이 adapter가 지키는 세 가지:
+//
+//   ① 결정 표면이 없다 — 묶어서 보여주는 데까지다. approve/dismiss는 기존 결정 경로로만
+//      간다 (C-08 §4). 메신저에서 버튼을 눌러 승인하는 것은 별도 계약(ApprovalChannel)이며
+//      그 자리는 아직 열지 않는다.
+//   ② 전달 실패가 canonical state를 흔들지 않는다 (C-08 §1.3). 못 보냈으면 못 보냈다고
+//      돌려주고, 그 사실로 요청 상태를 바꾸지 않는다.
+//   ③ 자격을 남기지 않는다. 토큰은 환경에서만 오고 어디에도 적히지 않는다.
+/** 이 provider가 실제로 하는 것만 적는다. 결정 수신은 없다. */
+const CAPABILITIES = new Set(['presentation.digest', 'presentation.priority']);
+const PRIORITY_LABEL = { P0: '🔴 지금', P1: '🟡 오늘', P2: '⚪ 이번 주' };
+export class MattermostPresentation {
+    id;
+    capabilities = CAPABILITIES;
+    #transport;
+    #channelId;
+    constructor(deps) {
+        this.id = deps.id ?? 'mattermost';
+        this.#transport = deps.transport;
+        this.#channelId = deps.channelId;
+    }
+    async presentDigest(batch) {
+        return this.#send(renderBatch(batch));
+    }
+    /**
+     * 지금 끊어야 하는 한 건.
+     *
+     * 요약만 받는다 — 전체 view를 실어 나르면 전달 한 번에 조사 한 번이 딸려 붙는다
+     * (Port 주석). 더 필요하면 사람이 `requestId` 로 ASC에서 읽는다.
+     */
+    async presentUrgent(item) {
+        return this.#send(renderUrgent(item));
+    }
+    async #send(message) {
+        let result;
+        try {
+            result = await this.#transport.post({ channel_id: this.#channelId, message });
+        }
+        catch (error) {
+            // 전달 실패는 전달 실패일 뿐이다 — 요청 상태를 바꾸지 않는다 (C-08 §1.3)
+            return { ok: false, error: error instanceof Error ? error.message : String(error) };
+        }
+        return result.ok ? { ok: true, externalRef: result.id } : { ok: false, error: result.error };
+    }
+}
+/**
+ * 묶음 한 덩어리를 메시지로. **결정 버튼을 만들지 않는다** — 여기에 버튼이 생기는 순간
+ * 메신저가 결정 경로가 되고, 그건 다른 계약이다.
+ */
+export function renderBatch(batch) {
+    const lines = [`**ASC** · ${batch.at}`];
+    for (const group of batch.groups) {
+        lines.push(`${PRIORITY_LABEL[group.priority] ?? group.priority} ${group.items.length}건`);
+        for (const item of group.items) {
+            lines.push(`- \`${item.requestId}\` ${item.reference} — ${item.title}`);
+            // 묶은 뒤 값이 변한 것은 새 상태를 만들지 않고 freshness로 말한다 (C-08 §3.3)
+            if (item.freshness !== 'CURRENT')
+                lines.push(`  _(${item.freshness})_`);
+        }
+    }
+    if (batch.suppressed?.shadow)
+        lines.push(`⚪ 숨김 ${batch.suppressed.shadow} — 관련 근거 없음(계속 본다)`);
+    if (batch.suppressed?.alreadyDecided)
+        lines.push(`⚪ 이미 결정됨 ${batch.suppressed.alreadyDecided}`);
+    if (batch.recovered)
+        lines.push(`↺ 회수 경로에서 발견 ${batch.recovered}`);
+    if (batch.groups.length === 0)
+        lines.push('건넬 것이 없다.');
+    // 결정은 ASC에서 한다. 그 사실을 매번 같이 보낸다 — 채널이 결정 표면이 아님을 사람이 알게.
+    lines.push('');
+    lines.push('_결정은 `asc inbox decide` 로 한다 — 이 메시지는 알림이지 승인 창구가 아니다._');
+    return lines.join('\n');
+}
+export function renderUrgent(item) {
+    return [
+        `🔴 **지금 판단이 필요하다** · \`${item.requestId}\``,
+        `${item.reference} — ${item.title}`,
+        `감지 ${item.detectedAt}${item.freshness === 'CURRENT' ? '' : ` · ${item.freshness}`}`,
+        '',
+        '_결정은 `asc inbox decide` 로 한다._',
+    ].join('\n');
+}

package/dist/adapters/memory/mocks.d.ts

@@ -0,0 +1,87 @@
+import type { CanonicalSnapshot } from '../../core/model/entities.ts';
+import type { DecisionSummary, DecisionView } from '../../core/view/decision-view.ts';
+import type { ApprovalCapability, ApprovalChannel, IdentityBinding, PresentationOutcome } from '../../ports/approval.ts';
+import type { Cursor, EventBatch, EventSource, RawEvent } from '../../ports/event-source.ts';
+import type { InventoryItem, InventoryPage, InventoryPort, InventoryQuery } from '../../ports/inventory.ts';
+import type { DeliveryOutcome, DigestBatch, PresentationCapability, PresentationPort } from '../../ports/presentation.ts';
+import type { BaselineQuery, ExternalAction, ExternalActionResult, ScmPort, ThreadSnapshot } from '../../ports/scm.ts';
+import type { ScopedStore } from '../../ports/state-store.ts';
+/**
+ * 채널 구현 참조. presentation 매핑은 Core entity가 아니라 이 Adapter가 받은
+ * ScopedStore에 둔다 — PresentationRecord 소유 결정(ports/approval.ts)의 실물이다.
+ */
+export declare class MemoryChannel implements ApprovalChannel {
+    #private;
+    readonly id: string;
+    readonly capabilities: ReadonlySet<ApprovalCapability>;
+    /** 테스트 관찰용 — 어떤 view가 몇 번 표시·갱신됐는지. */
+    readonly presented: DecisionView[];
+    readonly updated: DecisionView[];
+    constructor(id: string, store: ScopedStore, capabilities?: readonly ApprovalCapability[]);
+    /** 채널이 죽었거나 메시지 수정을 지원하지 않는 상황을 흉내 낸다. */
+    breakUpdates(): void;
+    present(view: DecisionView): Promise<PresentationOutcome>;
+    update(view: DecisionView): Promise<PresentationOutcome>;
+}
+/** 로컬 결정도 무조건 신뢰하지 않는다 — 매핑된 identity만 승인자로 인정한다 (OM §11.6). */
+export declare class MapIdentityBinding implements IdentityBinding {
+    #private;
+    constructor(entries: Record<string, string>);
+    verify({ channel, actor, authorizedApprover }: {
+        channel: string;
+        actor: string;
+        authorizedApprover: string;
+    }): Promise<boolean>;
+}
+export declare class FakeScm implements ScmPort {
+    #private;
+    readonly id = "fake-scm";
+    readonly executed: ExternalAction[];
+    setThread(reference: string, lastEventId: string): void;
+    setBaseline(sourceId: string, baseline: string): void;
+    failNextExecute(error: string): void;
+    getThread(reference: string): Promise<ThreadSnapshot>;
+    getBaselines(queries: readonly BaselineQuery[]): Promise<CanonicalSnapshot[]>;
+    execute(action: ExternalAction): Promise<ExternalActionResult>;
+}
+/** 미리 넣어둔 배치를 순서대로 돌려준다. push형 Adapter의 내부 버퍼 drain과 같은 모양. */
+export declare class FixtureEventSource implements EventSource {
+    #private;
+    readonly id = "fixture";
+    constructor(batches: RawEvent[][]);
+    drain(cursor: Cursor): Promise<EventBatch>;
+}
+/**
+ * 목록을 통째로 들고 있는 Inventory. 페이지 나눔과 "완주하지 못함"을 흉내 낼 수 있어야
+ * Coverage 판정(C-07 §1.5)을 실제로 검사할 수 있다.
+ */
+export declare class FixtureInventory implements InventoryPort {
+    #private;
+    readonly id = "fixture";
+    /** 회차마다 다른 목록을 주려면 여기를 바꿔 끼운다. */
+    items: InventoryItem[];
+    /** true면 어떤 페이지도 complete를 말하지 않는다 — 목록을 다 못 본 상황. */
+    incomplete: boolean;
+    /** 설정하면 enumerate가 실패한다. */
+    failWith: string | null;
+    constructor(items?: InventoryItem[], options?: {
+        pageSize?: number;
+        incomplete?: boolean;
+    });
+    enumerate(query: InventoryQuery, cursor?: string): Promise<InventoryPage>;
+}
+/**
+ * 교체 검증용 전달 채널. 능력을 골라 끼울 수 있어야 "일부만 제공하는 채널"(C-08 §1.2)이
+ * 실제로 degrade되는지 볼 수 있다.
+ */
+export declare class FixturePresentation implements PresentationPort {
+    readonly id: string;
+    readonly capabilities: ReadonlySet<PresentationCapability>;
+    digests: DigestBatch[];
+    urgent: DecisionSummary[];
+    /** 설정하면 전달이 실패한다 — best-effort 계약을 확인하기 위해서다. */
+    failWith: string | null;
+    constructor(id?: string, capabilities?: PresentationCapability[]);
+    presentDigest(batch: DigestBatch): Promise<DeliveryOutcome>;
+    presentUrgent(item: DecisionSummary): Promise<DeliveryOutcome>;
+}

package/dist/adapters/memory/mocks.js

@@ -0,0 +1,163 @@
+// 나머지 4개 Port(Approval Channel / SCM / Event Source / Renderer)의 in-memory 구현.
+// Port 계약이 실제로 구현 가능한지, 그리고 Core가 특정 플랫폼을 몰라도 되는지 확인하는
+// 참조 구현이다. 실 Adapter는 B-04·B-08·B-13에서 별도로 만든다.
+/**
+ * 채널 구현 참조. presentation 매핑은 Core entity가 아니라 이 Adapter가 받은
+ * ScopedStore에 둔다 — PresentationRecord 소유 결정(ports/approval.ts)의 실물이다.
+ */
+export class MemoryChannel {
+    id;
+    capabilities;
+    /** 테스트 관찰용 — 어떤 view가 몇 번 표시·갱신됐는지. */
+    presented = [];
+    updated = [];
+    #store;
+    #failUpdates = false;
+    constructor(id, store, capabilities = ['interactive_actions']) {
+        this.id = id;
+        this.#store = store;
+        this.capabilities = new Set(capabilities);
+    }
+    /** 채널이 죽었거나 메시지 수정을 지원하지 않는 상황을 흉내 낸다. */
+    breakUpdates() {
+        this.#failUpdates = true;
+    }
+    async present(view) {
+        this.presented.push(view);
+        const externalRef = `${this.id}:msg:${view.requestId}`;
+        await this.#store.set(`presentation:${view.requestId}`, JSON.stringify({
+            requestId: view.requestId,
+            channel: this.id,
+            externalMessageRef: externalRef,
+            renderedAt: view.stored.detectedAt,
+        }));
+        return { ok: true, externalRef };
+    }
+    async update(view) {
+        if (this.#failUpdates)
+            return { ok: false, error: 'channel unreachable' };
+        const record = await this.#store.get(`presentation:${view.requestId}`);
+        if (!record)
+            return { ok: false, error: 'no presentation to update' };
+        this.updated.push(view);
+        return { ok: true, externalRef: JSON.parse(record).externalMessageRef };
+    }
+}
+/** 로컬 결정도 무조건 신뢰하지 않는다 — 매핑된 identity만 승인자로 인정한다 (OM §11.6). */
+export class MapIdentityBinding {
+    #map; // `${channel}:${actor}` → controller identity
+    constructor(entries) {
+        this.#map = new Map(Object.entries(entries));
+    }
+    async verify({ channel, actor, authorizedApprover }) {
+        return this.#map.get(`${channel}:${actor}`) === authorizedApprover;
+    }
+}
+export class FakeScm {
+    id = 'fake-scm';
+    executed = [];
+    #threads = new Map();
+    #baselines = new Map();
+    #failNext = null;
+    setThread(reference, lastEventId) {
+        this.#threads.set(reference, { reference, lastEventId });
+    }
+    setBaseline(sourceId, baseline) {
+        this.#baselines.set(sourceId, baseline);
+    }
+    failNextExecute(error) {
+        this.#failNext = error;
+    }
+    async getThread(reference) {
+        return this.#threads.get(reference) ?? { reference, lastEventId: '', missing: true };
+    }
+    async getBaselines(queries) {
+        return queries.map((q) => ({ sourceId: q.sourceId, baseline: this.#baselines.get(q.sourceId) ?? 'unknown' }));
+    }
+    async execute(action) {
+        if (this.#failNext) {
+            const error = this.#failNext;
+            this.#failNext = null;
+            return { ok: false, error };
+        }
+        this.executed.push(action);
+        return { ok: true, resultRef: `${this.id}://${action.target}/${this.executed.length}` };
+    }
+}
+/** 미리 넣어둔 배치를 순서대로 돌려준다. push형 Adapter의 내부 버퍼 drain과 같은 모양. */
+export class FixtureEventSource {
+    id = 'fixture';
+    #batches;
+    constructor(batches) {
+        this.#batches = batches.map((b) => [...b]);
+    }
+    async drain(cursor) {
+        const index = cursor ? Number(cursor) : 0;
+        const events = this.#batches[index] ?? [];
+        const hasMore = index + 1 < this.#batches.length;
+        return { events, cursor: String(index + 1), hasMore };
+    }
+}
+/**
+ * 목록을 통째로 들고 있는 Inventory. 페이지 나눔과 "완주하지 못함"을 흉내 낼 수 있어야
+ * Coverage 판정(C-07 §1.5)을 실제로 검사할 수 있다.
+ */
+export class FixtureInventory {
+    id = 'fixture';
+    /** 회차마다 다른 목록을 주려면 여기를 바꿔 끼운다. */
+    items;
+    #pageSize;
+    /** true면 어떤 페이지도 complete를 말하지 않는다 — 목록을 다 못 본 상황. */
+    incomplete;
+    /** 설정하면 enumerate가 실패한다. */
+    failWith = null;
+    constructor(items = [], options = {}) {
+        this.items = items;
+        this.#pageSize = options.pageSize ?? 100;
+        this.incomplete = options.incomplete ?? false;
+    }
+    async enumerate(query, cursor) {
+        if (this.failWith)
+            throw new Error(this.failWith);
+        // 경계는 포함해서 준다. 겹쳐 읽는 편이 놓치는 것보다 싸다 (OM §10.5).
+        const filtered = query.updatedSince
+            ? this.items.filter((item) => item.updatedAt >= query.updatedSince)
+            : this.items;
+        const page = cursor ? Number(cursor) : 0;
+        const slice = filtered.slice(page * this.#pageSize, (page + 1) * this.#pageSize);
+        const more = (page + 1) * this.#pageSize < filtered.length;
+        return {
+            items: slice,
+            ...(more ? { next: String(page + 1) } : {}),
+            complete: !more && !this.incomplete,
+        };
+    }
+}
+/**
+ * 교체 검증용 전달 채널. 능력을 골라 끼울 수 있어야 "일부만 제공하는 채널"(C-08 §1.2)이
+ * 실제로 degrade되는지 볼 수 있다.
+ */
+export class FixturePresentation {
+    id;
+    capabilities;
+    digests = [];
+    urgent = [];
+    /** 설정하면 전달이 실패한다 — best-effort 계약을 확인하기 위해서다. */
+    failWith = null;
+    constructor(id = 'fixture-channel', capabilities = ['presentation.digest']) {
+        this.id = id;
+        this.capabilities = new Set(capabilities);
+    }
+    async presentDigest(batch) {
+        if (this.failWith)
+            return { ok: false, error: this.failWith };
+        this.digests.push(batch);
+        return { ok: true, externalRef: `${this.id}://digest/${this.digests.length}` };
+    }
+    async presentUrgent(item) {
+        if (this.failWith)
+            return { ok: false, error: this.failWith };
+        this.urgent.push(item);
+        return { ok: true, externalRef: `${this.id}://urgent/${item.requestId}` };
+    }
+}

package/dist/adapters/memory/runtime-binding.d.ts

@@ -0,0 +1,23 @@
+import type { ScopedStore } from '../../ports/state-store.ts';
+import { RuntimeBinding, type ClaimOutcome, type RuntimeBindings } from '../../core/operator/runtime-binding.ts';
+/** 내려놓음·승계의 흔적. 현재 view가 아니라 이력이다. */
+export type BindingLogEntry = {
+    logicalSessionId: string;
+    physicalSessionId: string;
+    provider: string;
+    workerId?: string;
+    kind: 'RELEASED' | 'SUPERSEDED';
+    claimedAt: string;
+    endedAt: string;
+};
+export declare class ScopedRuntimeBindings implements RuntimeBindings {
+    #private;
+    constructor(scope: ScopedStore, now?: () => string);
+    claim(binding: Omit<RuntimeBinding, 'updatedAt'>, at: string): Promise<ClaimOutcome>;
+    observe(logicalSessionId: string, physicalSessionId: string, patch: Partial<Pick<RuntimeBinding, 'workerId' | 'runtimeKind' | 'lastObservedState' | 'capabilitySnapshot'>>, at: string): Promise<ClaimOutcome>;
+    release(logicalSessionId: string, physicalSessionId: string): Promise<boolean>;
+    rebind(binding: Omit<RuntimeBinding, 'updatedAt'>, at: string): Promise<RuntimeBinding>;
+    /** 이 세션을 거쳐 간 소유권 이력. 현재 owner는 여기 없다 — get()이 답한다. */
+    history(logicalSessionId: string): Promise<BindingLogEntry[]>;
+    get(logicalSessionId: string): Promise<RuntimeBinding | null>;
+}

package/dist/adapters/memory/runtime-binding.js

@@ -0,0 +1,118 @@
+// RuntimeBindings의 ScopedStore 구현 — B-14의 fake host 검증용이자 참조 구현.
+//
+// memory 디렉터리에 있지만 특정 저장소에 매이지 않는다: ScopedStore를 받아 그 위에서
+// 동작하므로, Host Adapter가 자기 scope를 넘겨 그대로 재사용한다 —
+// 소유권 로직을 provider마다 다시 쓰는 순간 원자성 보장이 갈라진다.
+import { RuntimeBinding, } from "../../core/operator/runtime-binding.js";
+const keyOf = (logicalSessionId) => `runtime-binding:${logicalSessionId}`;
+/**
+ * 내려놓은 소유권의 묘비 (C-10 §1.3 불변식 ④).
+ *
+ * 현재 소유권은 사라져도 "그때 그 Physical Run이 이 세션을 잡고 있었다"는 사실은 남아야
+ * 한다. 지금까지는 release가 파일을 지워서 회수 뒤에는 몇 개의 실행이 거쳐 갔는지조차
+ * 복원할 수 없었다.
+ *
+ * **접두어가 `runtime-binding`이면 안 된다.** Host Adapter의 guard hook은 이 scope에서
+ * `runtime-binding` 으로 시작하는 파일을 훑어 관리 대상 세션을 찾는다. 묘비가 그 앞에
+ * 걸리면 이미 내려놓은 세션이 계속 관리 대상으로 읽혀 죽은 소유권으로 차단 판정이 선다.
+ */
+const logKey = (logicalSessionId, seq) => `binding-log:${logicalSessionId}:${seq}`;
+const logPrefix = (logicalSessionId) => `binding-log:${logicalSessionId}:`;
+export class ScopedRuntimeBindings {
+    #scope;
+    #now;
+    constructor(scope, now = () => new Date().toISOString()) {
+        this.#scope = scope;
+        this.#now = now;
+    }
+    async claim(binding, at) {
+        const parsed = RuntimeBinding.parse({ ...binding, updatedAt: at });
+        // setIfAbsent가 원자성을 진다 — 확인과 쓰기 사이에 다른 Physical Session이 끼지 못한다.
+        if (await this.#scope.setIfAbsent(keyOf(parsed.logicalSessionId), JSON.stringify(parsed))) {
+            return { ok: true, binding: parsed };
+        }
+        const current = await this.get(parsed.logicalSessionId);
+        if (!current) {
+            // 그 사이 owner가 내려놨다 — 한 번 더 집어 본다. 또 지면 진 것이다.
+            if (await this.#scope.setIfAbsent(keyOf(parsed.logicalSessionId), JSON.stringify(parsed))) {
+                return { ok: true, binding: parsed };
+            }
+            return { ok: false, reason: 'RUNTIME_CONFLICT', current: (await this.get(parsed.logicalSessionId)) };
+        }
+        // 같은 Physical Session의 재-claim은 충돌이 아니라 이어 잡기다 (respawn 아님)
+        if (current.physicalSessionId === parsed.physicalSessionId) {
+            const refreshed = { ...current, updatedAt: at };
+            await this.#scope.set(keyOf(parsed.logicalSessionId), JSON.stringify(refreshed));
+            return { ok: true, binding: refreshed };
+        }
+        return { ok: false, reason: 'RUNTIME_CONFLICT', current };
+    }
+    async observe(logicalSessionId, physicalSessionId, patch, at) {
+        const current = await this.get(logicalSessionId);
+        if (!current || current.physicalSessionId !== physicalSessionId) {
+            // owner가 아니면 관찰도 못 쓴다 — 남의 binding을 덮는 경로를 만들지 않는다
+            return current
+                ? { ok: false, reason: 'RUNTIME_CONFLICT', current }
+                : { ok: false, reason: 'RUNTIME_CONFLICT', current: RuntimeBinding.parse({
+                        logicalSessionId, provider: 'unknown', physicalSessionId: '(none)', updatedAt: at,
+                    }) };
+        }
+        const next = RuntimeBinding.parse({ ...current, ...patch, updatedAt: at });
+        await this.#scope.set(keyOf(logicalSessionId), JSON.stringify(next));
+        return { ok: true, binding: next };
+    }
+    async release(logicalSessionId, physicalSessionId) {
+        const current = await this.get(logicalSessionId);
+        if (!current || current.physicalSessionId !== physicalSessionId)
+            return false;
+        // 지우기 전에 남긴다. 순서가 반대면 그 사이에 죽었을 때 흔적 없이 사라진다.
+        await this.#log(current, 'RELEASED');
+        await this.#scope.delete(keyOf(logicalSessionId));
+        return true;
+    }
+    async rebind(binding, at) {
+        const previous = await this.get(binding.logicalSessionId);
+        // 승계는 덮어쓰기지만, 덮이는 쪽도 있었던 일이다.
+        if (previous && previous.physicalSessionId !== binding.physicalSessionId) {
+            await this.#log(previous, 'SUPERSEDED');
+        }
+        const next = RuntimeBinding.parse({ ...binding, updatedAt: at });
+        await this.#scope.set(keyOf(next.logicalSessionId), JSON.stringify(next));
+        return next;
+    }
+    /** 이 세션을 거쳐 간 소유권 이력. 현재 owner는 여기 없다 — get()이 답한다. */
+    async history(logicalSessionId) {
+        const keys = await this.#scope.keys(logPrefix(logicalSessionId));
+        const out = [];
+        for (const key of keys.sort()) {
+            const raw = await this.#scope.get(key);
+            if (raw)
+                out.push(JSON.parse(raw));
+        }
+        return out;
+    }
+    /**
+     * 묘비를 append한다. 순번은 setIfAbsent가 성공할 때까지 올린다 — 같은 세션의 두
+     * 내려놓음이 겹쳐도 하나가 조용히 사라지지 않는다.
+     */
+    async #log(binding, kind) {
+        const entry = {
+            logicalSessionId: binding.logicalSessionId,
+            physicalSessionId: binding.physicalSessionId,
+            provider: binding.provider,
+            ...(binding.workerId ? { workerId: binding.workerId } : {}),
+            kind,
+            claimedAt: binding.updatedAt,
+            endedAt: this.#now(),
+        };
+        const existing = await this.#scope.keys(logPrefix(binding.logicalSessionId));
+        let seq = existing.reduce((max, key) => Math.max(max, Number(key.slice(key.lastIndexOf(':') + 1)) || 0), 0) + 1;
+        while (!(await this.#scope.setIfAbsent(logKey(binding.logicalSessionId, seq), JSON.stringify(entry)))) {
+            seq += 1;
+        }
+    }
+    async get(logicalSessionId) {
+        const raw = await this.#scope.get(keyOf(logicalSessionId));
+        return raw ? RuntimeBinding.parse(JSON.parse(raw)) : null;
+    }
+}

package/dist/adapters/memory/state-store.d.ts

@@ -0,0 +1,17 @@
+import type { ControlState } from '../../core/model/entities.ts';
+import { type CasResult, type CreateResult, type EntityKind, type EntityMap, type HistoryEntry, type ListFilter, type ScopedStore, type StateStore } from '../../ports/state-store.ts';
+export declare class MemoryStateStore implements StateStore {
+    #private;
+    get<K extends EntityKind>(kind: K, id: string): Promise<EntityMap[K] | null>;
+    list<K extends EntityKind>(kind: K, filter?: ListFilter<K>): Promise<EntityMap[K][]>;
+    create<K extends EntityKind>(kind: K, entity: EntityMap[K]): Promise<CreateResult<EntityMap[K]>>;
+    compareAndSet<K extends EntityKind>(kind: K, id: string, expectedVersion: number, next: EntityMap[K]): Promise<CasResult<EntityMap[K]>>;
+    archive<K extends EntityKind>(kind: K, id: string): Promise<boolean>;
+    /** 테스트에서 옮겨진 것을 확인할 때 쓴다. 옮겼을 뿐 잃지 않았음을 보이기 위함이다. */
+    archived<K extends EntityKind>(kind: K, id: string): EntityMap[K] | null;
+    getControlState(): Promise<ControlState>;
+    setControlState(expectedVersion: number, next: ControlState): Promise<CasResult<ControlState>>;
+    appendHistory(entry: HistoryEntry): Promise<void>;
+    readHistory(limit?: number): Promise<HistoryEntry[]>;
+    scope(adapterId: string): ScopedStore;
+}

package/dist/adapters/memory/state-store.js

@@ -0,0 +1,125 @@
+// In-memory State Store — Port 계약의 참조 구현이자 테스트 기본값.
+// 실제 운용 저장소는 Markdown Adapter(B-04)이고, 이 구현은 Core 로직을 파일 시스템 없이
+// 검증하기 위해 존재한다. 두 Adapter가 같은 CAS semantics를 보이는지가 계약의 핵심이다.
+import { ENTITY_KEY, } from "../../ports/state-store.js";
+const clone = (value) => structuredClone(value);
+const keyOf = (kind, entity) => String(entity[ENTITY_KEY[kind]]);
+export class MemoryStateStore {
+    #tables = new Map();
+    #archived = new Map();
+    #scopes = new Map();
+    #history = [];
+    #control = { version: 0, activeSessions: [], writeBoundaryOccupancy: [], awaitingController: [], controllerAttention: [] };
+    #table(kind) {
+        let table = this.#tables.get(kind);
+        if (!table) {
+            table = new Map();
+            this.#tables.set(kind, table);
+        }
+        return table;
+    }
+    async get(kind, id) {
+        const found = this.#table(kind).get(id);
+        return found ? clone(found) : null;
+    }
+    async list(kind, filter = {}) {
+        const where = filter.where;
+        let rows = [...this.#table(kind).values()];
+        if (where) {
+            rows = rows.filter((row) => Object.entries(where).every(([field, value]) => row[field] === value));
+        }
+        return rows.slice(0, filter.limit ?? rows.length).map(clone);
+    }
+    async create(kind, entity) {
+        const table = this.#table(kind);
+        const id = keyOf(kind, entity);
+        const existing = table.get(id);
+        if (existing)
+            return { ok: false, reason: 'ALREADY_EXISTS', current: clone(existing) };
+        table.set(id, clone(entity));
+        return { ok: true, entity: clone(entity) };
+    }
+    async compareAndSet(kind, id, expectedVersion, next) {
+        // 버전을 올리지 않은 갱신은 계약 위반이지 경쟁 실패가 아니다 — 호출자 버그이므로 던진다.
+        if (next.version !== expectedVersion + 1) {
+            throw new Error(`CAS contract: next.version must be ${expectedVersion + 1}, got ${next.version}`);
+        }
+        const table = this.#table(kind);
+        const current = table.get(id);
+        if (!current)
+            return { ok: false, reason: 'NOT_FOUND' };
+        if (current.version !== expectedVersion) {
+            return { ok: false, reason: 'VERSION_CONFLICT', current: clone(current) };
+        }
+        table.set(id, clone(next));
+        return { ok: true, entity: clone(next) };
+    }
+    async archive(kind, id) {
+        const table = this.#table(kind);
+        const entity = table.get(id);
+        if (!entity)
+            return false;
+        let bucket = this.#archived.get(kind);
+        if (!bucket) {
+            bucket = new Map();
+            this.#archived.set(kind, bucket);
+        }
+        bucket.set(id, entity);
+        table.delete(id);
+        return true;
+    }
+    /** 테스트에서 옮겨진 것을 확인할 때 쓴다. 옮겼을 뿐 잃지 않았음을 보이기 위함이다. */
+    archived(kind, id) {
+        const found = this.#archived.get(kind)?.get(id);
+        return found ? clone(found) : null;
+    }
+    async getControlState() {
+        return clone(this.#control);
+    }
+    async setControlState(expectedVersion, next) {
+        if (next.version !== expectedVersion + 1) {
+            throw new Error(`CAS contract: next.version must be ${expectedVersion + 1}, got ${next.version}`);
+        }
+        if (this.#control.version !== expectedVersion) {
+            return { ok: false, reason: 'VERSION_CONFLICT', current: clone(this.#control) };
+        }
+        this.#control = clone(next);
+        return { ok: true, entity: clone(next) };
+    }
+    async appendHistory(entry) {
+        this.#history.push(clone(entry));
+    }
+    async readHistory(limit) {
+        const rows = this.#history.map(clone);
+        return limit ? rows.slice(-limit) : rows;
+    }
+    scope(adapterId) {
+        let bucket = this.#scopes.get(adapterId);
+        if (!bucket) {
+            bucket = new Map();
+            this.#scopes.set(adapterId, bucket);
+        }
+        const store = bucket;
+        return {
+            async get(key) {
+                return store.get(key) ?? null;
+            },
+            async set(key, value) {
+                store.set(key, value);
+            },
+            async setIfAbsent(key, value) {
+                // 단일 스레드라 확인과 쓰기 사이에 다른 코드가 끼어들지 않는다
+                if (store.has(key))
+                    return false;
+                store.set(key, value);
+                return true;
+            },
+            async delete(key) {
+                store.delete(key);
+            },
+            async keys(prefix = '') {
+                return [...store.keys()].filter((k) => k.startsWith(prefix));
+            },
+        };
+    }
+}