hikoutei 0.10.10-dev → 0.10.13-dev

package/README.ja.md

@@ -12,7 +12,7 @@ Google Sheets を利用する MVP 向けの型付きリポジトリであり、
 Sheets へ非同期で投影されます。
 
 <a href="https://www.npmjs.com/package/hikoutei">npm</a> ·
-<a href="docs/quick-start.md">クイックスタート</a> ·
+<a href="website/guide/quick-start.md">クイックスタート</a> ·
 <a href="https://github.com/ManddarinShop/Hikoutei/issues">Issues</a>
 
 [![npm version](https://img.shields.io/npm/v/hikoutei?style=flat-square)](https://www.npmjs.com/package/hikoutei)
@@ -176,12 +176,12 @@ Hikoutei は、永続的なローカル outbox・冪等な配信・競合を考
 ため、一時的な API 障害でコミット済みのアプリケーション書き込みが失われる
 ことはありません。provider は資格情報・スプレッドシート ID・URL・ペイロードを
 ログに残さず、Google の割り当て枠に収まるようリクエスト開始間隔を調整します。
-詳細な状態機械と復旧ルールは[内部整合性モデル](docs/internal-consistency-model.md)を
+詳細な状態機械と復旧ルールは[内部整合性モデル](website/guide/internal-consistency.md)を
 参照してください。
 
 ライブの Google 呼び出しはオプトインであり、通常の検証経路はフェイク
 provider と SQLite フィクスチャです。詳細なセットアップとトラブルシューティン
-グは[クイックスタート](docs/quick-start.md)を参照してください。
+グは[クイックスタート](website/guide/quick-start.md)を参照してください。
 
 ## インストール
 
@@ -196,15 +196,15 @@ MikroORM は実装の詳細であり、Hikoutei の公開エンティティ API
 
 ## ドキュメント
 
-- [クイックスタート](docs/quick-start.md) — インストール、ORM ライフサイクル、
+- [クイックスタート](website/guide/quick-start.md) — インストール、ORM ライフサイクル、
   サービス側の同期設定
-- [アーキテクチャ](docs/architecture.md) — ローカルストアとシートビューの関係
-- [書き込みと同期フロー](docs/write-and-synchronization-flow.md) — 非同期配信と
+- [アーキテクチャ](website/guide/architecture.md) — ローカルストアとシートビューの関係
+- [書き込みと同期フロー](website/guide/sync-flow.md) — 非同期配信と
   復旧動作
-- [内部整合性モデル](docs/internal-consistency-model.md) — 永続的な outbox、
+- [内部整合性モデル](website/guide/internal-consistency.md) — 永続的な outbox、
   冪等な配信、競合を考慮した更新
-- [開発](docs/development.md) — ローカル開発とテストコマンド
-- [ベンチマークノート](docs/sync-bulk-write-benchmark.md) — 日付付きの測定と
+- [開発](website/guide/contributing.md) — ローカル開発とテストコマンド
+- [ベンチマークノート](website/guide/benchmarks.md) — 日付付きの測定と
   その限界
 
 ## 制限事項

package/README.ko.md

@@ -11,7 +11,7 @@ Google Sheets 기반 MVP를 위한 타입 안전 리포지토리이자 안전한
 사람이 검토하고 가볍게 협업할 수 있도록 Google Sheets에 비동기로 투영됩니다.
 
 <a href="https://www.npmjs.com/package/hikoutei">npm</a> ·
-<a href="docs/quick-start.md">빠른 시작</a> ·
+<a href="website/guide/quick-start.md">빠른 시작</a> ·
 <a href="https://github.com/ManddarinShop/Hikoutei/issues">이슈</a>
 
 [![npm version](https://img.shields.io/npm/v/hikoutei?style=flat-square)](https://www.npmjs.com/package/hikoutei)
@@ -169,11 +169,11 @@ Hikoutei는 내구성 있는 로컬 outbox, 멱등 전달, 충돌을 인지하
 사용하므로 일시적인 API 실패가 커밋된 애플리케이션 쓰기를 잃게 하지 않습니다.
 provider는 자격 증명, 스프레드시트 ID, URL, 페이로드를 로그에 남기지 않으며,
 Google 할당량 창 안에 머물도록 요청 시작 간격을 조절합니다. 상세 상태 머신과
-복구 규칙은 [내부 정합성 모델](docs/internal-consistency-model.md)을
+복구 규칙은 [내부 정합성 모델](website/guide/internal-consistency.md)을
 참고하세요.
 
 라이브 Google 호출은 opt-in이며, 일반적인 검증 경로는 fake provider와 SQLite
-fixture입니다. 자세한 설정과 문제 해결 단계는 [빠른 시작](docs/quick-start.md)을
+fixture입니다. 자세한 설정과 문제 해결 단계는 [빠른 시작](website/guide/quick-start.md)을
 참고하세요.
 
 ## 설치
@@ -190,14 +190,14 @@ MikroORM은 구현 세부 사항이며 Hikoutei의 공개 엔티티 API에는
 
 ## 문서
 
-- [빠른 시작](docs/quick-start.md) — 설치, ORM 생명주기, 서비스 측 동기화 설정
-- [아키텍처](docs/architecture.md) — 로컬 저장소와 Sheet 화면이 맞물리는 방식
-- [쓰기 및 동기화 흐름](docs/write-and-synchronization-flow.md) — 비동기 전달과
+- [빠른 시작](website/guide/quick-start.md) — 설치, ORM 생명주기, 서비스 측 동기화 설정
+- [아키텍처](website/guide/architecture.md) — 로컬 저장소와 Sheet 화면이 맞물리는 방식
+- [쓰기 및 동기화 흐름](website/guide/sync-flow.md) — 비동기 전달과
   복구 동작
-- [내부 정합성 모델](docs/internal-consistency-model.md) — 내구성 outbox,
+- [내부 정합성 모델](website/guide/internal-consistency.md) — 내구성 outbox,
   멱등 전달, 충돌을 인지하는 업데이트
-- [개발](docs/development.md) — 로컬 개발 및 테스트 명령어
-- [벤치마크 노트](docs/sync-bulk-write-benchmark.md) — 날짜가 기록된 측정과
+- [개발](website/guide/contributing.md) — 로컬 개발 및 테스트 명령어
+- [벤치마크 노트](website/guide/benchmarks.md) — 날짜가 기록된 측정과
   그 한계
 
 ## 한계

package/README.md

@@ -123,11 +123,14 @@ client directly.
 
 Google Sheets synchronization is a service-side concern. Applications do not
 import a provider client, pass Sheet routes to `createTypedSheets()`, or choose
-an operation for each write — the root API accepts only `dbName` and
-`entities`. The sync runtime uses one internal Google Sheets API provider with
-a service account — no Apps Script deployment. Sync auto-start is selected by
-`HIKOUTEI_SYNC_SPREADSHEET_URL` plus `GOOGLE_APPLICATION_CREDENTIALS`; there is
-no public `googleSheetsApi` bootstrap option to configure.
+an operation for each write — `CreateTypedSheetsOptions` fields (`dbName`,
+`entities`, `providerOptions`) are all optional. The sync runtime uses one
+internal Google Sheets API provider with a service account — no Apps Script
+deployment. Sync auto-start is selected by `HIKOUTEI_SYNC_SPREADSHEET_URL`
+plus `GOOGLE_APPLICATION_CREDENTIALS`. Optional `providerOptions` tunes the
+sync-path provider (telemetry/timeouts; inert when local-only), and
+`createTypedSheetsWithSync()` exposes the same options with a richer result
+for existing-sheet adoption.
 
 **Fastest path:** install the gcloud CLI, then run `npx hikoutei setup` from your
 project directory. On an interactive terminal it offers (press Enter) to
@@ -247,8 +250,8 @@ shared on the spreadsheet (the error tells you which email to share).
    `GOOGLE_APPLICATION_CREDENTIALS` and `HIKOUTEI_SYNC_SPREADSHEET_URL` set;
    `createTypedSheets()` detects them and starts the internal sync bootstrap —
    it creates and verifies headers on the registered tabs, then starts outbox
-   delivery and User_Input polling. There is no provider option to pass and no
-   internal bootstrap to start by hand.
+   delivery and User_Input polling. Pass `providerOptions` only when sync-path
+   tuning is needed; there is no internal bootstrap to start by hand.
 
 > **Legacy spreadsheet note.** Spreadsheets provisioned by the old Apps Script
 > provider with developer-metadata row anchors are not migrated: `User_Input`
@@ -273,15 +276,15 @@ verification path. The detailed setup and troubleshooting steps are in the
 
 ## Installation
 
-The project and npm package are both called `hikoutei`. The built-in SQLite
-provider currently requires MikroORM:
+The project and npm package are both called `hikoutei`. This repo uses pnpm
+(packageManager `pnpm@11.1.2`):
 
 ```sh
-npm install hikoutei @mikro-orm/core @mikro-orm/sql
+pnpm install --frozen-lockfile
 ```
 
-MikroORM is an implementation detail and does not appear in Hikoutei's public
-entity API.
+`@mikro-orm/core` and `@mikro-orm/sql` are optional peers (`optional: true`),
+lazy-loaded only when a runtime opens. `npm install` still works for consumers.
 
 ## Documentation
 

package/dist/auth/serviceAccountAuthPool.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Shared service-account credential-pool ownership (Batch A).
+ *
+ * This module owns the N-`GoogleAuth` pool every provider line paces and
+ * signs with: one auth per key file (one Google quota principal), the
+ * deterministic round-robin cursor, and the per-identity index binding that
+ * ties admission to transport (the admitted identity IS the signing
+ * identity). Providers build their API clients (`sheets({ version, auth })`
+ * stays provider-side) from the selected auths; the pacing pool
+ * (`CredentialPacingPool` in ikisaki) meets this pool at the existing
+ * admission→transport index binding, which is unchanged.
+ *
+ * Out-of-range selection fails CLOSED through the caller-supplied
+ * `onInvalidSelection` (same parameterization as the key loader's `fail`):
+ * signing with a different identity than the one admission paced against
+ * would silently defeat the per-identity quota contract.
+ */
+import type { GoogleAuth } from "google-auth-library";
+import { type ServiceAccountKeyLoadOptions } from "./serviceAccountKey.js";
+/**
+ * Advances (and returns) the next round-robin client index for a pool.
+ *
+ * A preferred (provider-admitted) index is returned WITHOUT advancing the
+ * cursor, so admission-bound calls never skew the fallback rotation. The
+ * cursor is a mutable carrier so callers keep the rotation across requests;
+ * `clientCount` must be ≥ 1.
+ */
+export declare function nextPooledClientIndex(cursor: {
+    next: number;
+}, clientCount: number, preferredIndex: number | undefined): number;
+/** Selection failure mapping (must throw, never return). */
+export interface ServiceAccountAuthPoolSelection {
+    readonly onInvalidSelection: (message: string) => never;
+}
+/** Key-file pool construction: scopes plus both failure mappings. */
+export interface ServiceAccountAuthPoolKeyFilesOptions extends ServiceAccountKeyLoadOptions, ServiceAccountAuthPoolSelection {
+    /** OAuth scopes the pooled auths request (provider-owned, e.g. Sheets/Drive). */
+    readonly scopes: readonly string[];
+}
+/**
+ * The N-`GoogleAuth` credential pool plus its rotation cursor.
+ *
+ * Generic over the auth value so providers wrap their own auth flavor
+ * (injected test auths, the ADC default) together with the file-backed
+ * `GoogleAuth` instances under ONE selection cursor.
+ */
+export declare class ServiceAccountAuthPool<TAuth = GoogleAuth> {
+    /** Every pooled credential; index-aligned with the provider's clients. */
+    readonly auths: readonly TAuth[];
+    private readonly selection;
+    /** Fallback rotation cursor for requests WITHOUT an admitted index. */
+    private readonly poolCursor;
+    constructor(
+    /** Every pooled credential; index-aligned with the provider's clients. */
+    auths: readonly TAuth[], selection: ServiceAccountAuthPoolSelection);
+    /**
+     * Builds the file-backed pool: each key file is read and turned into its
+     * own `GoogleAuth` at construction (fail fast on unreadable or malformed
+     * files). Error payloads carry the PATH only — never file contents,
+     * client emails, or key material.
+     */
+    static loadFromKeyFiles(keyFiles: readonly string[], options: ServiceAccountAuthPoolKeyFilesOptions): ServiceAccountAuthPool<GoogleAuth>;
+    /** Number of pooled credentials (quota principals). */
+    get size(): number;
+    /**
+     * Picks the pool index for one request: the admitted identity when the
+     * request carries one, otherwise the next round-robin entry (a 1-auth
+     * pool always selects index 0 — the historical single-auth path).
+     */
+    selectIndex(preferredIndex: number | undefined): number;
+}
+//# sourceMappingURL=serviceAccountAuthPool.d.ts.map

package/dist/auth/serviceAccountAuthPool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serviceAccountAuthPool.d.ts","sourceRoot":"","sources":["../../../../../../../src/auth/serviceAccountAuthPool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAIL,KAAK,4BAA4B,EAClC,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EACxB,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,GAAG,SAAS,GACjC,MAAM,CAOR;AAED,4DAA4D;AAC5D,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,kBAAkB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,KAAK,CAAC;CACzD;AAED,qEAAqE;AACrE,MAAM,WAAW,qCACf,SAAQ,4BAA4B,EAAE,+BAA+B;IACrE,iFAAiF;IACjF,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED;;;;;;GAMG;AACH,qBAAa,sBAAsB,CAAC,KAAK,GAAG,UAAU;IAKlD,0EAA0E;aAC1D,KAAK,EAAE,SAAS,KAAK,EAAE;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS;IAN5B,uEAAuE;IACvE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiC;;IAG1D,0EAA0E;IAC1D,KAAK,EAAE,SAAS,KAAK,EAAE,EACtB,SAAS,EAAE,+BAA+B;IAG7D;;;;;OAKG;WACW,gBAAgB,CAC5B,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,OAAO,EAAE,qCAAqC,GAC7C,sBAAsB,CAAC,UAAU,CAAC;IASrC,uDAAuD;IACvD,IAAW,IAAI,IAAI,MAAM,CAExB;IAED;;;;OAIG;IACI,WAAW,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM;CAe/D"}

package/dist/auth/serviceAccountAuthPool.js

@@ -0,0 +1,92 @@
+/**
+ * Shared service-account credential-pool ownership (Batch A).
+ *
+ * This module owns the N-`GoogleAuth` pool every provider line paces and
+ * signs with: one auth per key file (one Google quota principal), the
+ * deterministic round-robin cursor, and the per-identity index binding that
+ * ties admission to transport (the admitted identity IS the signing
+ * identity). Providers build their API clients (`sheets({ version, auth })`
+ * stays provider-side) from the selected auths; the pacing pool
+ * (`CredentialPacingPool` in ikisaki) meets this pool at the existing
+ * admission→transport index binding, which is unchanged.
+ *
+ * Out-of-range selection fails CLOSED through the caller-supplied
+ * `onInvalidSelection` (same parameterization as the key loader's `fail`):
+ * signing with a different identity than the one admission paced against
+ * would silently defeat the per-identity quota contract.
+ */
+import { createServiceAccountAuth, loadServiceAccountKeyFileSync, } from "./serviceAccountKey.js";
+/**
+ * Advances (and returns) the next round-robin client index for a pool.
+ *
+ * A preferred (provider-admitted) index is returned WITHOUT advancing the
+ * cursor, so admission-bound calls never skew the fallback rotation. The
+ * cursor is a mutable carrier so callers keep the rotation across requests;
+ * `clientCount` must be ≥ 1.
+ */
+export function nextPooledClientIndex(cursor, clientCount, preferredIndex) {
+    if (preferredIndex !== undefined) {
+        return preferredIndex;
+    }
+    const index = cursor.next % clientCount;
+    cursor.next = (index + 1) % clientCount;
+    return index;
+}
+/**
+ * The N-`GoogleAuth` credential pool plus its rotation cursor.
+ *
+ * Generic over the auth value so providers wrap their own auth flavor
+ * (injected test auths, the ADC default) together with the file-backed
+ * `GoogleAuth` instances under ONE selection cursor.
+ */
+export class ServiceAccountAuthPool {
+    auths;
+    selection;
+    /** Fallback rotation cursor for requests WITHOUT an admitted index. */
+    poolCursor = { next: 0 };
+    constructor(
+    /** Every pooled credential; index-aligned with the provider's clients. */
+    auths, selection) {
+        this.auths = auths;
+        this.selection = selection;
+    }
+    /**
+     * Builds the file-backed pool: each key file is read and turned into its
+     * own `GoogleAuth` at construction (fail fast on unreadable or malformed
+     * files). Error payloads carry the PATH only — never file contents,
+     * client emails, or key material.
+     */
+    static loadFromKeyFiles(keyFiles, options) {
+        const fail = (failure) => options.fail(failure);
+        const auths = keyFiles.map((keyFile) => {
+            const { credentials } = loadServiceAccountKeyFileSync(keyFile, { fail });
+            return createServiceAccountAuth(credentials, options.scopes);
+        });
+        return new ServiceAccountAuthPool(auths, options);
+    }
+    /** Number of pooled credentials (quota principals). */
+    get size() {
+        return this.auths.length;
+    }
+    /**
+     * Picks the pool index for one request: the admitted identity when the
+     * request carries one, otherwise the next round-robin entry (a 1-auth
+     * pool always selects index 0 — the historical single-auth path).
+     */
+    selectIndex(preferredIndex) {
+        if (preferredIndex !== undefined) {
+            if (this.auths[preferredIndex] === undefined) {
+                // Fail CLOSED before any wire contact: signing with a different
+                // identity than the one admission paced against would silently
+                // defeat the per-identity quota contract.
+                this.selection.onInvalidSelection("credentialIndex is outside the client pool");
+            }
+            return preferredIndex;
+        }
+        if (this.auths.length === 1) {
+            return 0;
+        }
+        return nextPooledClientIndex(this.poolCursor, this.auths.length, undefined);
+    }
+}
+//# sourceMappingURL=serviceAccountAuthPool.js.map

package/dist/auth/serviceAccountAuthPool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serviceAccountAuthPool.js","sourceRoot":"","sources":["../../../../../../../src/auth/serviceAccountAuthPool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EACL,wBAAwB,EACxB,6BAA6B,GAG9B,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAAwB,EACxB,WAAmB,EACnB,cAAkC;IAElC,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;QACjC,OAAO,cAAc,CAAC;IACxB,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,GAAG,WAAW,CAAC;IACxC,MAAM,CAAC,IAAI,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,WAAW,CAAC;IACxC,OAAO,KAAK,CAAC;AACf,CAAC;AAcD;;;;;;GAMG;AACH,MAAM,OAAO,sBAAsB;IAMf;IACC;IANnB,uEAAuE;IACtD,UAAU,GAAqB,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IAE5D;IACE,0EAA0E;IAC1D,KAAuB,EACtB,SAA0C;QAD3C,UAAK,GAAL,KAAK,CAAkB;QACtB,cAAS,GAAT,SAAS,CAAiC;IAC1D,CAAC;IAEJ;;;;;OAKG;IACI,MAAM,CAAC,gBAAgB,CAC5B,QAA2B,EAC3B,OAA8C;QAE9C,MAAM,IAAI,GAAG,CAAC,OAAiC,EAAS,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACjF,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;YACrC,MAAM,EAAE,WAAW,EAAE,GAAG,6BAA6B,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;YACzE,OAAO,wBAAwB,CAAC,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QAC/D,CAAC,CAAC,CAAC;QACH,OAAO,IAAI,sBAAsB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACpD,CAAC;IAED,uDAAuD;IACvD,IAAW,IAAI;QACb,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;IAC3B,CAAC;IAED;;;;OAIG;IACI,WAAW,CAAC,cAAkC;QACnD,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;YACjC,IAAI,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,KAAK,SAAS,EAAE,CAAC;gBAC7C,gEAAgE;gBAChE,+DAA+D;gBAC/D,0CAA0C;gBAC1C,IAAI,CAAC,SAAS,CAAC,kBAAkB,CAAC,4CAA4C,CAAC,CAAC;YAClF,CAAC;YACD,OAAO,cAAc,CAAC;QACxB,CAAC;QACD,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,OAAO,CAAC,CAAC;QACX,CAAC;QACD,OAAO,qBAAqB,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAC9E,CAAC;CACF"}

package/dist/auth/serviceAccountKey.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Shared service-account key-file loading + shape validation (Batch A).
+ *
+ * This is the ONE loader for Google service-account key files, reused by
+ * every provider line (Sheets today; Drive/Gmail next) and by the sync
+ * auto-start bridge. It reads, JSON-parses, and SHAPE-validates a key file
+ * so a misconfigured credential fails fast and locally — a malformed file
+ * must never build an auth client that only breaks on first signing.
+ *
+ * Neutral error contract: this leaf owns no provider vocabulary, so every
+ * failure is reported through the caller-supplied `fail` callback as a
+ * discriminated `ServiceAccountKeyFailure` (quotaGovernor `timingDefaults`
+ * precedent — behavior injected, dependency direction kept acyclic). The
+ * Sheets transport maps every kind to its transport error; the sync
+ * auto-start bridge maps them to the stable startup codes. Failure payloads
+ * carry the PATH (and field names) only — never file contents, client
+ * emails, or key material.
+ */
+import { GoogleAuth } from "google-auth-library";
+/** Required service-account key-file fields, checked by SHAPE (non-blank string) only at load. */
+export declare const SERVICE_ACCOUNT_KEY_FIELDS: readonly ["type", "client_email", "private_key", "project_id"];
+/** Structured key-file load failure (path-bearing only, never key material). */
+export type ServiceAccountKeyFailure = {
+    /** The file could not be read (`code` is the Node errno, e.g. `ENOENT`). */
+    readonly kind: "read-error";
+    readonly path: string;
+    readonly code: string | undefined;
+} | {
+    /** The file contents are not valid JSON. */
+    readonly kind: "invalid-json";
+    readonly path: string;
+} | {
+    /** The file parsed but is not a JSON object. */
+    readonly kind: "not-object";
+    readonly path: string;
+} | {
+    /** Required service-account fields are missing or blank (NAMES only, never values). */
+    readonly kind: "field-missing";
+    readonly path: string;
+    readonly fields: readonly string[];
+};
+/** Loader options: the caller's failure mapping (must throw, never return). */
+export interface ServiceAccountKeyLoadOptions {
+    readonly fail: (failure: ServiceAccountKeyFailure) => never;
+}
+/** One validated service-account key: raw credentials plus the client email. */
+export interface LoadedServiceAccountKey {
+    /** Parsed key JSON, passed straight into `GoogleAuth.credentials` (never logged). */
+    readonly credentials: Record<string, unknown>;
+    /** The `client_email` field (used for access-denied hints, never logged by this leaf). */
+    readonly clientEmail: string;
+}
+/**
+ * Validates parsed key JSON by SHAPE and promotes it to a loaded key.
+ *
+ * Shared by the sync/async file loaders so both paths enforce the identical
+ * contract: the payload must be a JSON object whose required
+ * service-account fields are non-blank strings. Without this, ANY JSON
+ * object builds a GoogleAuth client and the failure surfaces mid-run on
+ * first signing instead of at load.
+ */
+export declare function parseServiceAccountKeyJson(raw: string, path: string, options: ServiceAccountKeyLoadOptions): LoadedServiceAccountKey;
+/**
+ * Loads + validates one key file synchronously (transport construction path).
+ *
+ * Reads and shape-validates the file at construction so a misconfigured
+ * pool fails fast and locally. Failure messages carry the path only.
+ */
+export declare function loadServiceAccountKeyFileSync(keyFile: string, options: ServiceAccountKeyLoadOptions): LoadedServiceAccountKey;
+/**
+ * Loads + validates one key file asynchronously (startup-bridge path).
+ *
+ * Same contract as the sync loader; the bridge keeps its own env parsing
+ * and error-code mapping and delegates only file loading/validation here.
+ */
+export declare function loadServiceAccountKeyFile(keyFile: string, options: ServiceAccountKeyLoadOptions): Promise<LoadedServiceAccountKey>;
+/**
+ * Builds one pooled `GoogleAuth` from validated key credentials.
+ *
+ * The caller supplies the scopes (Sheets/Drive/Gmail each request their
+ * own); the cast keeps the google-auth-library version-shape mismatch
+ * inside this leaf, exactly like the former per-provider boundary casts.
+ */
+export declare function createServiceAccountAuth(credentials: Record<string, unknown>, scopes: readonly string[]): GoogleAuth;
+//# sourceMappingURL=serviceAccountKey.d.ts.map

package/dist/auth/serviceAccountKey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serviceAccountKey.d.ts","sourceRoot":"","sources":["../../../../../../../src/auth/serviceAccountKey.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAIjD,kGAAkG;AAClG,eAAO,MAAM,0BAA0B,gEAAiE,CAAC;AAEzG,gFAAgF;AAChF,MAAM,MAAM,wBAAwB,GAChC;IACE,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC,GACD;IACE,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,GACD;IACE,gDAAgD;IAChD,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,GACD;IACE,uFAAuF;IACvF,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC,CAAC;AAEN,+EAA+E;AAC/E,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,wBAAwB,KAAK,KAAK,CAAC;CAC7D;AAED,gFAAgF;AAChF,MAAM,WAAW,uBAAuB;IACtC,qFAAqF;IACrF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9C,0FAA0F;IAC1F,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,4BAA4B,GACpC,uBAAuB,CAkBzB;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,4BAA4B,GACpC,uBAAuB,CAQzB;AAED;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,uBAAuB,CAAC,CAQlC;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,MAAM,EAAE,SAAS,MAAM,EAAE,GACxB,UAAU,CAKZ"}

package/dist/auth/serviceAccountKey.js

@@ -0,0 +1,104 @@
+/**
+ * Shared service-account key-file loading + shape validation (Batch A).
+ *
+ * This is the ONE loader for Google service-account key files, reused by
+ * every provider line (Sheets today; Drive/Gmail next) and by the sync
+ * auto-start bridge. It reads, JSON-parses, and SHAPE-validates a key file
+ * so a misconfigured credential fails fast and locally — a malformed file
+ * must never build an auth client that only breaks on first signing.
+ *
+ * Neutral error contract: this leaf owns no provider vocabulary, so every
+ * failure is reported through the caller-supplied `fail` callback as a
+ * discriminated `ServiceAccountKeyFailure` (quotaGovernor `timingDefaults`
+ * precedent — behavior injected, dependency direction kept acyclic). The
+ * Sheets transport maps every kind to its transport error; the sync
+ * auto-start bridge maps them to the stable startup codes. Failure payloads
+ * carry the PATH (and field names) only — never file contents, client
+ * emails, or key material.
+ */
+import { GoogleAuth } from "google-auth-library";
+import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+/** Required service-account key-file fields, checked by SHAPE (non-blank string) only at load. */
+export const SERVICE_ACCOUNT_KEY_FIELDS = ["type", "client_email", "private_key", "project_id"];
+/**
+ * Validates parsed key JSON by SHAPE and promotes it to a loaded key.
+ *
+ * Shared by the sync/async file loaders so both paths enforce the identical
+ * contract: the payload must be a JSON object whose required
+ * service-account fields are non-blank strings. Without this, ANY JSON
+ * object builds a GoogleAuth client and the failure surfaces mid-run on
+ * first signing instead of at load.
+ */
+export function parseServiceAccountKeyJson(raw, path, options) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        options.fail({ kind: "invalid-json", path });
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        options.fail({ kind: "not-object", path });
+    }
+    const record = parsed;
+    const invalidFields = SERVICE_ACCOUNT_KEY_FIELDS.filter((field) => typeof record[field] !== "string" || record[field].trim() === "");
+    if (invalidFields.length > 0) {
+        options.fail({ kind: "field-missing", path, fields: invalidFields });
+    }
+    return { credentials: record, clientEmail: record.client_email };
+}
+/**
+ * Loads + validates one key file synchronously (transport construction path).
+ *
+ * Reads and shape-validates the file at construction so a misconfigured
+ * pool fails fast and locally. Failure messages carry the path only.
+ */
+export function loadServiceAccountKeyFileSync(keyFile, options) {
+    let raw;
+    try {
+        raw = readFileSync(keyFile, "utf8");
+    }
+    catch (error) {
+        options.fail({ kind: "read-error", path: keyFile, code: nodeErrorCode(error) });
+    }
+    return parseServiceAccountKeyJson(raw, keyFile, options);
+}
+/**
+ * Loads + validates one key file asynchronously (startup-bridge path).
+ *
+ * Same contract as the sync loader; the bridge keeps its own env parsing
+ * and error-code mapping and delegates only file loading/validation here.
+ */
+export async function loadServiceAccountKeyFile(keyFile, options) {
+    let raw;
+    try {
+        raw = await readFile(keyFile, "utf8");
+    }
+    catch (error) {
+        options.fail({ kind: "read-error", path: keyFile, code: nodeErrorCode(error) });
+    }
+    return parseServiceAccountKeyJson(raw, keyFile, options);
+}
+/**
+ * Builds one pooled `GoogleAuth` from validated key credentials.
+ *
+ * The caller supplies the scopes (Sheets/Drive/Gmail each request their
+ * own); the cast keeps the google-auth-library version-shape mismatch
+ * inside this leaf, exactly like the former per-provider boundary casts.
+ */
+export function createServiceAccountAuth(credentials, scopes) {
+    return new GoogleAuth({
+        scopes: [...scopes],
+        credentials,
+    });
+}
+/** Extracts the Node errno (`ENOENT`, ...) from a caught read failure. */
+function nodeErrorCode(error) {
+    if (error !== null && typeof error === "object") {
+        const code = error.code;
+        return typeof code === "string" ? code : undefined;
+    }
+    return undefined;
+}
+//# sourceMappingURL=serviceAccountKey.js.map

package/dist/auth/serviceAccountKey.js.map

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

package/dist/sheets/providers/google-sheets-api/transport/googleSheetsApiTransport.js

@@ -13,7 +13,7 @@ import { sheets } from "@googleapis/sheets";
 import { presentValue, absentValue, PRESENCE_KINDS } from "../../../../contracts/state/index.js";
 import { HIKOUTEI_LOG_LEVELS, logHikouteiInternalEvent, } from "../../../../contracts/shared/observability/internalLog.js";
 import { HIKOUTEI_LOG_COMPONENTS, HIKOUTEI_LOG_EVENTS, } from "../../../../contracts/shared/observability/logEvents.js";
-import { ServiceAccountAuthPool, } from "@hikoutei/google-auth/auth/serviceAccountAuthPool.js";
+import { ServiceAccountAuthPool, } from "../../../../auth/serviceAccountAuthPool.js";
 import { GOOGLE_SHEETS_API_SCOPES } from "../constants.js";
 import { GOOGLE_SHEETS_API_TRANSPORT_ERROR_CODES, GoogleSheetsApiTransportError, invalidProviderRequest, } from "../errors.js";
 import { parseRawErrorRecord, parseRawErrorText, parseRawHttpStatus, } from "@hikoutei/ikisaki";

package/dist/sync-engine/sync/service/syncAutoStart.js

@@ -21,7 +21,7 @@
  * the diagnostic sink (console by default), and thrown fail-closed: a startup
  * failure never leaves a half-open runtime behind.
  */
-import { loadServiceAccountKeyFile } from "@hikoutei/google-auth/auth/serviceAccountKey.js";
+import { loadServiceAccountKeyFile } from "../../../auth/serviceAccountKey.js";
 import { getEntityDescriptor, } from "../../api/entity.js";
 import { validateTypedSheetsOptions, } from "../../api/hikouteiCore.js";
 import { requireSyncEngineLocalRuntime } from "./compositionPorts.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hikoutei",
-  "version": "0.10.10-dev",
+  "version": "0.10.13-dev",
   "description": "Typed repository and safe write layer for Google Sheets-backed MVPs. SQLite-authoritative entity lifecycle with asynchronous Google Sheets projection.",
   "repository": {
     "type": "git",