hikoutei 0.3.2 → 0.3.4

package/dist/infrastructure/storage/sync/shared/spreadsheetAuthority.js

@@ -0,0 +1,92 @@
+/** Durable per-spreadsheet authority records used to fence remote mutations. */
+import { STORAGE_ERROR_CODES, StorageError } from "../../errors.js";
+import { isFencingValidWithSql } from "./writerLease.js";
+const READ_PHYSICAL_AUTHORITY_SQL = `
+  SELECT physical.spreadsheet_id, authority.owner_id, authority.authority_epoch,
+         authority.authority_token, authority.updated_at
+  FROM physical_sheet_registry AS physical
+  LEFT JOIN spreadsheet_authority AS authority
+    ON authority.spreadsheet_id = physical.spreadsheet_id
+  WHERE physical.physical_sheet_id = ?
+`;
+const INSERT_AUTHORITY_SQL = `
+  INSERT INTO spreadsheet_authority (
+    spreadsheet_id, owner_id, authority_epoch, authority_token, updated_at
+  ) VALUES (?, ?, ?, ?, ?)
+`;
+const UPDATE_AUTHORITY_SQL = `
+  UPDATE spreadsheet_authority
+  SET owner_id = ?, authority_epoch = ?, authority_token = ?, updated_at = ?
+  WHERE spreadsheet_id = ?
+    AND authority_epoch <= ?
+`;
+/** Ensures the current writer fence owns one registered spreadsheet authority. */
+export async function ensureSpreadsheetAuthorityWithSql(sql, options) {
+    if (options.ownerId.length === 0 || options.physicalSheetId.length === 0) {
+        throw new StorageError(STORAGE_ERROR_CODES.INVALID_WRITER_LEASE_OPTIONS, "spreadsheet authority owner and physical sheet ID are required");
+    }
+    if (!(await isFencingValidWithSql(sql, options)))
+        return { kind: "fenced_out" };
+    const row = await sql.get(READ_PHYSICAL_AUTHORITY_SQL, [options.physicalSheetId]);
+    if (row === undefined || row.spreadsheet_id.length === 0) {
+        throw new StorageError(STORAGE_ERROR_CODES.SYNC_REGISTRY_TARGET_UNAVAILABLE, "physical sheet is not registered for spreadsheet authority");
+    }
+    if (row.authority_epoch !== undefined && row.authority_epoch !== null && (row.authority_epoch > options.writerEpoch ||
+        row.authority_epoch === options.writerEpoch && (row.authority_token !== options.fencingToken || row.owner_id !== options.ownerId))) {
+        return { kind: "fenced_out" };
+    }
+    const authority = {
+        spreadsheetId: row.spreadsheet_id,
+        ownerId: options.ownerId,
+        authorityEpoch: options.writerEpoch,
+        authorityToken: options.fencingToken,
+        updatedAt: options.now,
+    };
+    if (row.authority_epoch === undefined || row.authority_epoch === null) {
+        const inserted = await sql.run(INSERT_AUTHORITY_SQL, [
+            authority.spreadsheetId,
+            authority.ownerId,
+            authority.authorityEpoch,
+            authority.authorityToken,
+            authority.updatedAt,
+        ]);
+        if (inserted.changes !== 1)
+            return { kind: "fenced_out" };
+        return { kind: "claimed", authority };
+    }
+    const updated = await sql.run(UPDATE_AUTHORITY_SQL, [
+        authority.ownerId,
+        authority.authorityEpoch,
+        authority.authorityToken,
+        authority.updatedAt,
+        authority.spreadsheetId,
+        authority.authorityEpoch,
+    ]);
+    return updated.changes === 1
+        ? { kind: "claimed", authority }
+        : { kind: "fenced_out" };
+}
+/** Ensures a spreadsheet authority through an adapter-owned transaction. */
+export async function ensureSpreadsheetAuthorityWithAdapter(storage, options) {
+    return storage.transaction(({ sql }) => ensureSpreadsheetAuthorityWithSql(sql, options));
+}
+/** Reads the durable authority attached to one registered physical sheet. */
+export async function readSpreadsheetAuthorityWithSql(sql, physicalSheetId) {
+    const row = await sql.get(READ_PHYSICAL_AUTHORITY_SQL, [physicalSheetId]);
+    if (row === undefined || row.authority_epoch === undefined || row.authority_epoch === null ||
+        row.authority_token === undefined || row.authority_token === null) {
+        return undefined;
+    }
+    return {
+        spreadsheetId: row.spreadsheet_id,
+        ownerId: row.owner_id ?? "",
+        authorityEpoch: row.authority_epoch,
+        authorityToken: row.authority_token,
+        updatedAt: row.updated_at ?? 0,
+    };
+}
+/** Reads one durable spreadsheet authority through a fresh adapter context. */
+export async function readSpreadsheetAuthorityWithAdapter(storage, physicalSheetId) {
+    return storage.read(({ sql }) => readSpreadsheetAuthorityWithSql(sql, physicalSheetId));
+}
+//# sourceMappingURL=spreadsheetAuthority.js.map

package/dist/infrastructure/storage/sync/shared/spreadsheetAuthority.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spreadsheetAuthority.js","sourceRoot":"","sources":["../../../../../src/infrastructure/storage/sync/shared/spreadsheetAuthority.ts"],"names":[],"mappings":"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"}

package/dist/infrastructure/storage/sync/shared/writerLease.js

@@ -169,7 +169,9 @@ function makeLease(role, writerId, writerEpoch, leaseUntil) {
         role,
         writerId,
         writerEpoch,
-        fencingToken: `fence-${writerEpoch}`,
+        // Include the owner identity as well as the monotonically increasing epoch;
+        // equal epochs from different roles must never share a remote authority token.
+        fencingToken: `fence-${writerEpoch}:${writerId}`,
         leaseUntil,
     };
 }

package/dist/infrastructure/storage/sync/shared/writerLease.js.map

@@ -1 +1 @@
-{"version":3,"file":"writerLease.js","sourceRoot":"","sources":["../../../../../src/infrastructure/storage/sync/shared/writerLease.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"writerLease.js","sourceRoot":"","sources":["../../../../../src/infrastructure/storage/sync/shared/writerLease.ts"],"names":[],"mappings":"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"}

package/docs/advanced-sheets-gateway-concurrency-problem.md

@@ -0,0 +1,434 @@
+# Hikoutei Advanced Sheets Gateway 동시성/정합성 문제 해결 요청서
+
+> 이 문서만 읽고도 현재 문제의 원인을 분석하고, 락 제거 여부와 대체 정합성 모델을 설계할 수 있도록 작성한 독립 문서다.
+
+## 1. 해결해야 할 문제
+
+Hikoutei는 SQLite를 애플리케이션의 authority로 사용하고, Google Sheets를 비동기 projection 및 human input surface로 사용한다. SQLite의 flush는 entity table, canonical sync state, durable Sheet effect outbox를 하나의 SQLite transaction으로 커밋한다. Google Sheets 원격 반영은 flush 이후 worker가 비동기로 수행한다.
+
+현재 Apps Script Gateway write path에 Advanced Sheets `Sheets.Spreadsheets.batchUpdate`를 도입했다. 그러나 Locust 부하에서 Gateway latency와 오류가 급증한다.
+
+핵심 질문은 다음이다.
+
+> `batchUpdate`를 사용해도 Apps Script 전역 Script Lock과 원격 read/validate/write 구조 때문에 병목이 남는다. 전역 락을 제거하고 SQLite authority, effect receipt, CAS/fencing, durable outbox를 이용한 다른 정합성 모델로 바꾸는 것이 안전한가? 안전하다면 정확한 설계와 단계별 변경안을 제시하라.
+
+단순히 락을 제거하는 패치를 제안하지 말고, 동시 append, response loss, retry, stale CAS, duplicate identity, multi-worker fencing을 모두 고려해야 한다.
+
+---
+
+## 2. 반드시 보존해야 하는 불변조건
+
+1. **SQLite authority**
+   - 애플리케이션은 정상 entity data를 Sheets에서 읽지 않는다.
+   - Sheets는 비동기 projection이며 User_Input을 제외하면 사람이 직접 수정하는 source of truth가 아니다.
+
+2. **Durable outbox**
+   - 효과는 flush 시 SQLite outbox에 저장된다.
+   - 메모리에 효과를 30초 이상 모아두지 않는다.
+   - process crash 이후에도 pending/retry/recovery가 가능해야 한다.
+
+3. **Effect idempotency**
+   - effect ID와 payload hash가 receipt에 기록된다.
+   - 같은 effect ID를 같은 payload로 재시도하면 `already_applied`/`applied`로 안전하게 회복해야 한다.
+   - 같은 effect ID를 다른 payload로 재사용하면 fail-closed 해야 한다.
+   - effect ID를 확인했다고 해서 row postcondition이 검증된 것으로 간주하면 안 된다.
+
+4. **CAS와 fencing**
+   - guarded update/delete는 expected visible revision/hash와 target evidence를 사용한다.
+   - 오래된 worker나 lease를 잃은 worker가 원격 row를 덮어쓰면 안 된다.
+   - SQLite writer lease와 effect lease의 fencing semantics를 보존해야 한다.
+
+5. **Duplicate identity fail-closed**
+   - business identity, `Conflict_ID`, physical anchor가 중복되면 자동 삭제하지 않는다.
+   - 중복 row는 진단/quarantine 대상으로 남겨야 한다.
+
+6. **Public boundary 유지**
+   - `src/index.ts`와 public EntityManager API를 변경하지 않는다.
+   - Apps Script `Code.gs` dispatcher/business logic은 현재 단계에서 변경하지 않는다.
+   - SQLite authority, outbox, receipt, recovery semantics를 약화하지 않는다.
+
+---
+
+## 3. 현재 시스템 구조
+
+### 3.1 Node/Application side
+
+- Entity flush가 SQLite entity table과 canonical state를 저장한다.
+- 같은 transaction에서 Sheet effect outbox를 만든다.
+- `SyncEffectWorker`가 SQLite에서 effect를 claim하고 route별로 전송한다.
+- worker는 adaptive batch controller를 사용한다.
+  - coalescing window: 기본 500ms
+  - 내부 effect batch 범위: 5~20
+  - initial batch: 10
+  - gateway의 공식 제한이 아니라 내부 방어 상한이다.
+- effect lease 기본값은 120초, writer lease 기본값은 180초다.
+- worker와 polling supervisor가 별도 경로로 Gateway에 요청한다.
+- load harness의 `POST /__test/user-input`은 테스트용으로 `User_Input` row를 직접 수정하는 별도 control operation을 보낸다. 이것은 production effect가 아니다.
+
+### 3.2 Apps Script Gateway
+
+`apps-script/gateway/Code.gs`는 다음만 수행한다.
+
+1. signed POST 검증
+2. HMAC/body hash/time/sheet allowlist 검증
+3. `applyOperations`의 serialized function source를 실행
+4. 응답 JSON envelope 생성
+5. 마지막에 `SpreadsheetApp.flush()` 호출
+
+Data-plane의 `Code.gs` 자체는 일반 effect마다 Script Lock을 잡지 않는다. 다만 eval로 실행되는 operation source들이 `LockService.getScriptLock()`을 사용한다.
+
+### 3.3 Operation source별 락
+
+#### `batchAppendOperation.ts`
+
+`LockService.getScriptLock()`을 잡은 뒤 다음 전체를 수행한다.
+
+- target sheet와 header 확인
+- receipt sheet 확인/생성
+- 모든 receipt 읽기
+- effect ID/payload hash 확인
+- target sheet의 identity 중복 확인
+- `lastRow` 계산
+- Advanced Sheets `batchUpdate` 실행
+  - row reservation
+  - row cell write
+  - developer metadata anchor 생성
+  - receipt row 삽입/기록
+- receipt/visible evidence 검증
+- lock release
+
+즉, lock critical section 안에 원격 read, 전체 receipt scan, identity scan, write가 모두 들어 있다.
+
+#### `effectOperationScript.ts`
+
+일반 update/delete/effect materialization도 `LockService.getScriptLock()`을 약 20초 timeout으로 잡고, effect별 precondition/read/write/receipt 처리를 수행한다.
+
+#### `observationOperation.ts`
+
+anchor assignment가 포함된 full observation은 Script Lock을 사용한다. 이 경로는 다음을 할 수 있다.
+
+- registered range read
+- Developer Metadata anchor 검색
+- 누락 anchor 생성
+- values/formulas/display values/merged range 읽기
+- snapshot hash 생성
+- duplicate anchor 진단
+
+반면 `READ_SNAPSHOT_OPERATION_SOURCE`는 anchor mutation이 없는 read-only snapshot path로 만들기 위해 lock prologue/epilogue를 제거한 별도 source다.
+
+---
+
+## 4. 왜 `batchUpdate`만으로 문제가 해결되지 않는가
+
+Advanced Sheets `batchUpdate`는 **하나의 API 요청 안의 request 배열을 원자적으로 처리**할 수 있다. 그러나 다음까지 보장하지 않는다.
+
+- 서로 다른 두 HTTP 요청 사이의 serializable isolation
+- read 후 write 사이의 compare-and-set
+- effect ID/receipt의 unique constraint
+- developer metadata anchor의 create-if-absent
+- `lastRow` 계산의 동시성 안전성
+- User_Input row에 대한 conditional update
+
+예를 들어 두 요청 A/B가 동시에 다음을 수행하면 된다.
+
+```text
+A: receipt에 e1 없음
+B: receipt에 e1 없음
+A: identity u1 없음
+B: identity u1 없음
+A: lastRow = 100
+B: lastRow = 100
+A: row 101에 u1 append
+B: row 101 또는 shifted row에 u1 append
+```
+
+각 요청의 `batchUpdate`는 내부적으로 원자적일 수 있어도, A와 B 사이의 unique identity 보장은 없다. 락을 완전히 제거하면 다음 문제가 가능하다.
+
+- 같은 effect의 duplicate row
+- 같은 business identity의 duplicate row
+- 같은 anchor의 duplicate metadata
+- receipt와 data row의 서로 다른 상태
+- stale `User_Input` candidate overwrite
+- response loss 이후 재시도 시 duplicate materialization
+
+따라서 “`batchUpdate`이므로 전역 락을 그냥 삭제해도 된다”는 가정은 성립하지 않는다.
+
+---
+
+## 5. 관측된 실제 증상
+
+### 5.1 이전 누적 상태 run
+
+이전 run은 stale SQLite/Sheet state와 duplicate/failure effect가 섞여 있었다.
+
+- 2,648 requests
+- HTTP failure 12.61%
+- Gateway p50 4.34초
+- Gateway p95 34.25초
+- 최대 60.01초
+
+이 run은 신규 구현의 공정한 성능 비교로 사용하면 안 된다.
+
+### 5.2 Fresh run
+
+- 날짜: 2026-08-03
+- branch: `perf/adaptive-sync-performance`
+- fresh SQLite 및 fresh `System_State`, `User_Input`, `Sync_Conflicts` tabs
+- Locust: 10 users, spawn rate 2/s, 60초
+- command:
+
+```sh
+locust -f .local/locustfile.py \
+  --host http://127.0.0.1:8787 \
+  --headless \
+  --users 10 \
+  --spawn-rate 2 \
+  --run-time 60s \
+  --csv .local/locust-20260803-231300-clean2 \
+  --html .local/locust-20260803-231300-clean2.html \
+  --only-summary
+```
+
+Locust 결과:
+
+| Endpoint | Requests | Failures | p50 | p95 | Max |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| `GET /users/:id` | 134 | 0 | 2ms | 4ms | 6ms |
+| `POST /users` | 81 | 0 | 5ms | 6ms | 19ms |
+| `PATCH /users/:id` | 76 | 0 | 5ms | 8ms | 22ms |
+| `POST /__test/user-input` | 38 | 8 | 2.2s | 31.0s | 31.9s |
+| **Total** | **339** | **8 (2.36%)** | **4ms** | **2.3s** | **31.9s** |
+
+서버-side Gateway snapshot은 workload 종료 후 background worker/polling을 포함해 다음과 같았다.
+
+- Gateway requests: 100
+- Gateway failures: 34
+- Gateway p50: 3.71초
+- Gateway p95: 33.47초
+- Gateway max: 60.00초
+- outbox: `pending 306`, `processing 8`, `applied 2`, `superseded 2`
+
+주요 오류:
+
+- `Code.gs response was not valid JSON`
+- `Code.gs operation request timed out`
+- 이전 run에는 `Could not acquire the sync observation gateway lock`도 관측됨
+
+Fresh server startup 중에도 Gateway가 간헐적으로 HTTP 404/non-JSON을 반환했다. idle 상태에서 단일 signed no-op probe를 순차 실행하면 성공하기도 했으므로, 단순한 함수 문법 오류보다 원격 실행 queue/lock/transport/deployment 상태를 분리해 조사해야 한다.
+
+### 5.3 해석
+
+이 run은 다음을 보여준다.
+
+- local SQLite/entity flush 경로는 낮은 latency로 동작한다.
+- entity create/read/update HTTP API는 실패하지 않았다.
+- Gateway boundary는 10-user 정도의 mixed workload에서도 tail latency와 non-JSON/timeout을 보였다.
+- `User_Input` test control path가 stage-1 bulk append benchmark와 섞여 결과를 오염시켰다.
+- outbox가 workload보다 빠르게 drain되지 않았으므로 성공적인 성능 benchmark가 아니다.
+
+따라서 현재 결과만으로 `batchUpdate` 자체의 throughput이나 correctness를 판정할 수 없다. 하지만 Gateway의 concurrency/transport 병목은 실제로 존재한다.
+
+---
+
+## 6. 해결책을 설계할 때 반드시 분리할 문제
+
+### A. Transport/deployment 문제
+
+다음은 Script Lock 제거와 별개일 수 있다.
+
+- HTTP 404
+- redirect 뒤 non-JSON response
+- Apps Script execution timeout
+- deployed Code.gs 버전/manifest/Advanced Sheets service 불일치
+- Gateway quota 또는 transient execution failure
+
+먼저 no-op signed operation, provisioning operation, single append operation을 각각 독립적으로 측정해야 한다.
+
+### B. Script Lock 경합
+
+다음은 현재 전역 Script Lock으로 직접 악화될 수 있다.
+
+- effect operation이 receipt/identity 전체 scan 중인 동안 observation이 대기
+- full metadata observation이 anchor/hash를 계산하는 동안 append가 대기
+- 20초 `tryLock` timeout과 60초 HTTP timeout이 겹침
+- polling, outbound worker, test control operation이 동일 spreadsheet/script에 동시에 접근
+
+### C. 락 제거 시 생기는 정합성 문제
+
+락을 삭제하면 해결되는 latency와 새로 생기는 correctness failure를 구분해야 한다.
+
+- lock-free append에서 duplicate identity를 어떻게 막을 것인가?
+- receipt의 create-if-absent를 어떻게 보장할 것인가?
+- `lastRow`/row reservation race를 어떻게 처리할 것인가?
+- stale CAS를 어떻게 원격에서 거절할 것인가?
+- response loss 후 같은 effect의 duplicate row를 어떻게 방지할 것인가?
+- 여러 Node process가 동시에 같은 spreadsheet를 dispatch할 때 어떻게 fencing할 것인가?
+
+---
+
+## 7. 우선 검토할 대체 설계
+
+아래 설계를 비교하고, 더 나은 설계가 있다면 이유를 제시하라.
+
+### 설계안 1: SQLite durable single remote writer
+
+- spreadsheet/route별 remote dispatch ownership을 SQLite writer lease로 결정한다.
+- lease holder만 해당 spreadsheet의 mutation Gateway call을 보낸다.
+- 효과를 메모리에 오래 모으지 않고, SQLite outbox에서 bounded batch만 읽어 보낸다.
+- process가 죽어도 outbox가 남으므로 재시작 후 recovery한다.
+- 같은 process의 worker/polling/test control이 Gateway로 직접 병렬 mutation을 보내지 않게 한다.
+- remote lock을 제거하거나 최소화하고, serialization을 SQLite authority 쪽으로 옮긴다.
+
+검토할 것:
+
+- polling read는 mutation writer와 병렬화해도 되는가?
+- full observation의 anchor mutation은 어느 lane에 넣어야 하는가?
+- 여러 Node process의 writer lease fencing이 충분한가?
+- lease 만료 중 remote call이 끝나는 경우 response-loss/postcondition 처리는 어떻게 하는가?
+
+### 설계안 2: operation class별 락
+
+- 순수 values/read snapshot: lock-free
+- append-only `System_State`/`Sync_Conflicts`: 별도 mutation lane 또는 짧은 route별 serialization
+- CAS update/delete/User_Input: 당분간 serialization 유지
+- full metadata/anchor assignment: 낮은 빈도의 별도 safety lane
+
+Apps Script `LockService`에는 일반적인 arbitrary route key lock이 없으므로, “route별 lock”을 제안할 경우 실제 구현 방식(SQLite lease, PropertiesService, sheet lease row 등)의 원자성과 crash recovery를 설명해야 한다.
+
+### 설계안 3: append-only command/effect ledger
+
+Sheet에 직접 unique row를 materialize하기보다 effect command/receipt를 append-only로 기록하고, 단일 materializer가 projection row를 만든다.
+
+장점:
+
+- append-only write가 row update보다 단순하다.
+- replay와 audit가 쉽다.
+
+단점:
+
+- ledger 자체의 duplicate effect ID 방지 문제가 남는다.
+- materializer가 결국 단일 writer가 되어야 한다.
+- 기존 Sheet 사용자-facing layout과의 migration 비용이 크다.
+
+### 설계안 4: optimistic concurrency/version column
+
+각 row에 revision/version을 두고 expected version을 같이 전송한다.
+
+단, Google Sheets Advanced API의 `batchUpdate`가 서버-side conditional compare-and-set을 제공하는지 확인해야 한다. 단순히 version을 읽은 뒤 update하는 것은 CAS가 아니다. 실제로 조건부 update를 보장하지 못한다면 User_Input guarded path의 정합성 대체안으로 인정하지 않는다.
+
+---
+
+## 8. 권장 단계
+
+1. **Gateway 단독 안정성 확인**
+   - signed no-op 10회
+   - provisioning/read 10회
+   - 단일 append 1회
+   - status, redirect, body classification, execution duration 기록
+
+2. **단일 effect correctness 확인**
+   - `System_State` append
+   - receipt 확인
+   - 같은 effect replay
+   - payload hash mismatch
+   - response loss simulation
+   - duplicate identity simulation
+
+3. **stage-1 benchmark 분리**
+   - Locust에서 `User_Input` control traffic 제외
+   - `System_State`와 `Sync_Conflicts` outbound path만 측정
+   - batch 1/5/10/20 sweep
+   - workload window와 background drain window를 분리
+
+4. **concurrency correctness 확인**
+   - 같은 effect ID 동시 2회
+   - 서로 다른 effect의 동시 append
+   - 같은 business identity 동시 append
+   - full observation과 append 동시 실행
+   - worker lease expiry 중 원격 response 도착
+
+5. **User_Input 별도 검증**
+   - guarded update/delete의 stale candidate 거부
+   - remote candidate 재관찰/quarantine
+   - CAS path를 lock-free로 바꿀 수 있는지 별도 판단
+
+6. **최종 Locust**
+   - fresh SQLite/tabs
+   - 한 writer/한 Gateway deployment
+   - Gateway p50/p95/max
+   - non-JSON/timeout 비율
+   - lock wait
+   - pending/processing/applied/failed/superseded/blocked_candidate
+   - outbox drain rate와 effect creation rate 비교
+
+---
+
+## 9. 금지해야 할 단순 해결책
+
+다음 제안은 충분한 정합성 증명 없이는 채택하지 않는다.
+
+- `LockService`를 모두 삭제하고 retry만 추가
+- `batchUpdate`이므로 cross-request CAS도 된다고 가정
+- duplicate identity를 자동 삭제
+- receipt에 effect ID만 있으면 성공으로 판정
+- timeout을 늘려 lock contention을 숨김
+- pending effect를 메모리에 모아 Gateway latency를 숨김
+- User_Input 실패를 전체 benchmark에서 제외하고 성공으로 보고
+- 404/non-JSON을 단순 retry로만 처리
+- public API나 `Code.gs` dispatcher를 변경해 내부 병목을 숨김
+
+---
+
+## 10. 답변을 작성할 GPT에게 요구하는 결과
+
+다음 형식으로 답하라.
+
+1. **Root cause 분리**
+   - Script Lock contention
+   - Apps Script/HTTP transport/deployment instability
+   - read/validate/write race
+   - worker scheduling contention
+   을 각각 어느 증거가 지지하는지 설명하라.
+
+2. **추천 consistency model**
+   - 어떤 경로에서 lock을 제거하는가?
+   - 무엇이 SQLite에서 serialize되는가?
+   - 어떤 경로는 왜 lock/CAS가 여전히 필요한가?
+   - response loss와 duplicate identity를 어떻게 처리하는가?
+
+3. **상태 전이와 fencing**
+   - outbox status
+   - writer lease
+   - effect lease
+   - remote receipt
+   - postcondition
+   사이의 정확한 전이를 제시하라.
+
+4. **구체적인 코드 변경 위치**
+   - 변경할 파일
+   - 변경하지 않을 파일
+   - operation source의 critical section
+   - worker dispatch/scheduler
+   - 필요한 schema/telemetry
+   를 명시하라.
+
+5. **실패 주입 테스트**
+   - timeout
+   - HTTP 404/non-JSON
+   - response loss
+   - lock contention
+   - concurrent append
+   - stale CAS
+   - duplicate identity
+   를 재현하고 기대 결과를 정의하라.
+
+6. **성능 측정 계획**
+   - stage-1과 stage-2를 분리하라.
+   - setup/no-setup/steady-state/drain을 분리하라.
+   - 성공률뿐 아니라 outbox convergence와 correctness를 포함하라.
+
+7. **채택 기준과 rollback 기준**
+   - 어떤 수치와 invariant를 만족해야 lock-free 또는 reduced-lock 설계를 채택하는가?
+   - 어떤 오류가 발생하면 기존 안전 경로로 rollback하는가?
+
+핵심은 **락을 무조건 제거하는 것**이 아니라, Apps Script의 긴 전역 critical section을 줄이면서도 SQLite authority, durable outbox, effect receipt, CAS/fencing, duplicate fail-closed를 유지하는 것이다.

package/docs/architecture.md

@@ -95,9 +95,11 @@ projection registry/state
 Sheet effect outbox
 ```
 
-The service-side configuration supplies projection routes, spreadsheet identity,
-and user-owned fields. Those values are not entity metadata or public ORM
-options.
+The service-side configuration supplies the required `System_State`,
+`User_Input`, and `Sync_Conflicts` routes, spreadsheet identity, and user-owned
+fields. Those values are not entity metadata or public ORM options. Every
+internal sync runtime fails closed if any of the three physical routes or its
+fixed headers are missing or drifted.
 
 ## Google Sheets projection
 
@@ -109,11 +111,27 @@ The application does not call Sheet operations. A successful public `flush()`
 means that the local SQLite transaction committed. It does not mean that a
 remote Sheet write has completed.
 
+The MVP gateway is a single file, `apps-script/gateway/Code.gs`, copied into a
+spreadsheet-bound Apps Script project and deployed as a Web App. The deployer
+pastes the `/exec` URL into `TYPED_SHEETS_GATEWAY_URL` and runs
+`setupSyncGateway()` from the editor, which stores the bound spreadsheet ID and
+a generated shared secret in Script Properties. This default path requires no
+`appsscript.json` manifest, no Apps Script Advanced Sheets Service, no Google
+Cloud Sheets API activation, and no service account. Sheet consistency does
+not rely on cross-request Sheet transactions; it comes from the Apps Script
+script lock, the hidden effect-receipt tab, effect-id/payload-hash dedupe, the
+SQLite durable outbox, fencing, and postcondition recovery.
+
 `System_State` is materialized from canonical SQLite state. `User_Input` is
 observed by the internal polling loop, evaluated with ownership and field-level
-compare-and-set rules, and then committed back to SQLite. Stale, conflicting,
-and malformed input is recorded in SQLite rather than silently overwriting the
-entity table.
+compare-and-set rules, and then committed back to SQLite. `Sync_Conflicts` is a
+system-owned audit projection of field-level conflict evidence and resolution
+outcomes; it is created even when empty and resolved rows remain visible for
+audit. A detected conflict is resolved with the fenced `acknowledge_system`
+policy: revision, candidate-hash, and epoch CAS clear the active candidate and
+queue the canonical User_Input rewrite. A newer remote edit that fails that CAS
+starts a new conflict instead of being overwritten. Stale, conflicting, and
+malformed input is therefore never silently written over the entity table.
 
 ## Transaction and lifecycle boundary
 
@@ -124,26 +142,50 @@ em.persist(entity) / em.remove(entity)
 SQLite transaction (internal sync service mode)
   ├─ entity table
   ├─ canonical state and conflict evidence
+  ├─ automatic system-wins resolution receipt/state
   └─ durable Sheet effect outbox
           │
           ▼
 internal outbound effect supervisor
-  ├─ claim leases and send signed operations
-  ├─ retry recoverable failures
+  ├─ claim leases and send bounded signed operation batches
+  ├─ persist delivery uncertainty and due postcondition probes in SQLite
+  ├─ fence remote routes with the current spreadsheet authority epoch/token
   └─ reconcile remote drift
           │
           ▼
 Apps Script gateway ──▶ Google Sheets
 
 internal User_Input polling
-  ├─ read registered projections
+  ├─ adaptive values-only preflight over registered projections
+  ├─ escalate changed/ambiguous/schema tables to full metadata
+  ├─ periodic safety full scan for formula/merged/error fidelity
   ├─ evaluate ownership/revisions/CAS
+  ├─ persist conflict evidence and automatic system-wins resolution in SQLite
   └─ persist accepted observations and entity mutations in SQLite
 ```
 
+Inbound polling defaults to an adaptive values-only preflight that reads the
+cheap value surface and only escalates a table to the metadata-preserving
+snapshot read when it changed, is ambiguous (unknown or duplicate business key,
+a missing expected entity, or a type-invalid cell), or when the periodic safety
+full scan falls due. The safety scan (default one minute, configurable) keeps
+formula, merged, and error cell fidelity because the values-only read drops that
+metadata; the scan's overdue lag is recorded for diagnostics. Outbound effects
+are split into bounded sub-batches per physical route so one gateway call returns
+a complete result set, and a pass that only requeued uncertain work backs off with
+a bounded delay instead of retrying a struggling remote in a tight loop.
+
 The service bootstrap starts provisioning, outbound delivery, and inbound polling
-as one internal runtime. Shutdown stops polling first, waits for remote calls,
-stops the outbound supervisor, and only then closes SQLite.
+as one internal runtime. Outbound dispatch keeps the SQLite outbox as its only
+durable buffer, coalesces only a short in-process burst, and adapts each route's
+Gateway batch between five and twenty effects from latency and response-loss
+signals. The effect lease is longer than the configured Gateway timeout so a
+slow but valid request is recovered only after its remote result is checked.
+Ambiguous delivery is stored as `delivery_uncertain` with `uncertain_since`,
+`next_probe_at`, and `dispatch_id`; only a due probe may return it to processing.
+A terminal structured remote failure does not enter the ambiguous probe path.
+Shutdown stops polling first, waits for remote calls, stops the outbound
+supervisor, and only then closes SQLite.
 
 ## Design limits