hikoutei 0.2.0

package/dist/shared/state/types.d.ts

@@ -0,0 +1,23 @@
+import { APPLICABILITY_KINDS, LOOKUP_RESULT_KINDS, PRESENCE_KINDS } from "./constants.js";
+/** A value that is either present or explicitly absent. */
+export type Presence<T> = {
+    readonly kind: typeof PRESENCE_KINDS.PRESENT;
+    readonly value: T;
+} | {
+    readonly kind: typeof PRESENCE_KINDS.ABSENT;
+};
+/** A lookup that either found a value or explicitly found no value. */
+export type LookupResult<T> = {
+    readonly kind: typeof LOOKUP_RESULT_KINDS.FOUND;
+    readonly value: T;
+} | {
+    readonly kind: typeof LOOKUP_RESULT_KINDS.NOT_FOUND;
+};
+/** A value that applies to an operation or is not meaningful for it. */
+export type Applicability<T> = {
+    readonly kind: typeof APPLICABILITY_KINDS.APPLICABLE;
+    readonly value: T;
+} | {
+    readonly kind: typeof APPLICABILITY_KINDS.NOT_APPLICABLE;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/shared/state/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/shared/state/types.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,cAAc,EACf,MAAM,gBAAgB,CAAC;AAExB,2DAA2D;AAC3D,MAAM,MAAM,QAAQ,CAAC,CAAC,IAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,cAAc,CAAC,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACnE;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,cAAc,CAAC,MAAM,CAAA;CAAE,CAAC;AAEpD,uEAAuE;AACvE,MAAM,MAAM,YAAY,CAAC,CAAC,IACtB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,mBAAmB,CAAC,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACtE;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,mBAAmB,CAAC,SAAS,CAAA;CAAE,CAAC;AAE5D,wEAAwE;AACxE,MAAM,MAAM,aAAa,CAAC,CAAC,IACvB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,mBAAmB,CAAC,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAC3E;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,mBAAmB,CAAC,cAAc,CAAA;CAAE,CAAC"}

package/dist/shared/state/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/shared/state/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/shared/state/types.ts"],"names":[],"mappings":""}

package/dist/shared/validation.d.ts

@@ -0,0 +1,9 @@
+/** Checks whether an unknown value is a non-empty string. */
+export declare function isNonEmptyString(value: unknown): value is string;
+/** Checks whether an unknown value is a positive safe integer. */
+export declare function isPositiveSafeInteger(value: unknown): value is number;
+/** Checks whether an unknown value is a non-negative safe integer. */
+export declare function isNonNegativeSafeInteger(value: unknown): value is number;
+/** Checks whether a list contains at least one item. */
+export declare function isNonEmptyList<T>(values: readonly T[]): boolean;
+//# sourceMappingURL=validation.d.ts.map

package/dist/shared/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/shared/validation.ts"],"names":[],"mappings":"AASA,6DAA6D;AAC7D,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAKhE;AAED,kEAAkE;AAClE,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAMrE;AAED,sEAAsE;AACtE,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAMxE;AAED,wDAAwD;AACxD,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,GAAG,OAAO,CAE/D"}

package/dist/shared/validation.js

@@ -0,0 +1,25 @@
+import { EMPTY_ARRAY_LENGTH_ZERO, EMPTY_STRING_LENGTH_ZERO, NON_NEGATIVE_SAFE_INTEGER_MINIMUM, POSITIVE_SAFE_INTEGER_MINIMUM, } from "./constants.js";
+import { JAVASCRIPT_TYPE_NAMES } from "./encoding/constants.js";
+import { isJavaScriptType } from "./encoding/typeGuards.js";
+/** Checks whether an unknown value is a non-empty string. */
+export function isNonEmptyString(value) {
+    return (isJavaScriptType(value, JAVASCRIPT_TYPE_NAMES.STRING) &&
+        value.length !== EMPTY_STRING_LENGTH_ZERO);
+}
+/** Checks whether an unknown value is a positive safe integer. */
+export function isPositiveSafeInteger(value) {
+    return (isJavaScriptType(value, JAVASCRIPT_TYPE_NAMES.NUMBER) &&
+        Number.isSafeInteger(value) &&
+        value >= POSITIVE_SAFE_INTEGER_MINIMUM);
+}
+/** Checks whether an unknown value is a non-negative safe integer. */
+export function isNonNegativeSafeInteger(value) {
+    return (isJavaScriptType(value, JAVASCRIPT_TYPE_NAMES.NUMBER) &&
+        Number.isSafeInteger(value) &&
+        value >= NON_NEGATIVE_SAFE_INTEGER_MINIMUM);
+}
+/** Checks whether a list contains at least one item. */
+export function isNonEmptyList(values) {
+    return values.length !== EMPTY_ARRAY_LENGTH_ZERO;
+}
+//# sourceMappingURL=validation.js.map

package/dist/shared/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/shared/validation.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,wBAAwB,EACxB,iCAAiC,EACjC,6BAA6B,GAC9B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAE5D,6DAA6D;AAC7D,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,CACL,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,CAAC,MAAM,CAAC;QACrD,KAAK,CAAC,MAAM,KAAK,wBAAwB,CAC1C,CAAC;AACJ,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,OAAO,CACL,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,CAAC,MAAM,CAAC;QACrD,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC;QAC3B,KAAK,IAAI,6BAA6B,CACvC,CAAC;AACJ,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,wBAAwB,CAAC,KAAc;IACrD,OAAO,CACL,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,CAAC,MAAM,CAAC;QACrD,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC;QAC3B,KAAK,IAAI,iCAAiC,CAC3C,CAAC;AACJ,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,cAAc,CAAI,MAAoB;IACpD,OAAO,MAAM,CAAC,MAAM,KAAK,uBAAuB,CAAC;AACnD,CAAC"}

package/docs/architecture.md

@@ -0,0 +1,72 @@
+# Hikoutei Architecture
+
+Hikoutei separates the local canonical data model from the Google Sheets
+projection. The application server owns the entity lifecycle and SQLite state;
+Google Sheets is updated asynchronously through a thin Apps Script gateway.
+
+## System shape
+
+```text
+Application server
+  └─ Hikoutei EntityManager
+       └─ replaceable persistence adapter (currently MikroORM)
+            └─ SQLite canonical state + durable outbox
+                 └─ background effect worker
+                      └─ signed Apps Script operation gateway
+                           └─ Google Sheets projection
+```
+
+## Responsibilities
+
+### Application server
+
+The server exposes the application-facing entity API and decides when an
+entity is created, mutated, or removed. It does not treat a successful remote
+HTTP response as the source of truth.
+
+### EntityManager and persistence adapter
+
+The entity manager follows an entity lifecycle similar to MikroORM: load an
+entity, mutate it, and flush the unit of work. The persistence adapter keeps the
+public API independent from the current MikroORM implementation so another
+SQLite engine can be introduced later.
+
+### SQLite canonical state
+
+SQLite is the authoritative read and write store. A local transaction persists
+the entity state and the durable effect that must eventually be materialized in
+Sheets.
+
+### Durable outbox and effect worker
+
+The outbox records remote work until it is applied or classified as failed. The
+worker claims work with a lease, sends signed operation batches, recovers expired
+leases, and applies retry policy without blocking the application request.
+
+### Apps Script gateway
+
+The gateway validates a signed operation envelope and executes an allowlisted
+Sheet operation. It is intentionally not the owner of entity evaluation,
+canonical state, retry policy, or reconciliation decisions.
+
+### Google Sheets projection
+
+Sheets is the human-readable projection. It can lag behind SQLite, and external
+limits such as Apps Script execution time, Google Sheets quotas, network timeout,
+or response loss can affect convergence.
+
+## Consistency boundary
+
+A successful `flush()` means:
+
+- the local entity state was accepted by SQLite
+- the corresponding remote effect was durably queued
+
+It does not mean that the Google Sheet has already converged. The worker and
+reconciliation safety net complete the remote side asynchronously.
+
+## Design boundary
+
+Hikoutei is intended for a single SQLite writer process. It is not a distributed
+transaction coordinator or a replacement for a high-throughput relational
+database.

package/docs/code-guidelines.md

@@ -0,0 +1,256 @@
+# Code Guidelines
+
+## Project Identity
+
+This project is a TypeScript library for using Google Sheets as a lightweight, typed repository layer for MVP apps, internal tools, and low-traffic admin workflows.
+
+The project is not a full database replacement, not a Prisma/JPA clone, and not a general-purpose Google Sheets API wrapper. Existing libraries such as `google-spreadsheet` and `@googleapis/sheets` already cover low-level Sheets access.
+
+The core value is safety around common Google Sheets-as-data-store failure modes:
+
+- schema drift caused by manual sheet edits
+- stale writes and lost updates
+- invalid row parsing
+- duplicate or missing key columns
+- API quota pressure
+- future write serialization through Apps Script
+
+## Positioning
+
+Use this wording when describing the project:
+
+> Typed repository and safe write layer for Google Sheets-backed MVPs.
+
+Avoid these claims:
+
+- Google Sheets replacement for MySQL/Postgres
+- JPA for Google Sheets
+- Prisma for Google Sheets
+- transaction-safe database on top of Sheets
+
+The honest boundary matters. Google Sheets has no native database transaction model, limited quota, weak query capabilities, and manual edit risk. The library should make those constraints explicit instead of hiding them.
+
+## MVP Scope
+
+The first implementation should stay small and prove the core safety model.
+
+Required MVP capabilities:
+
+- schema definition API
+- adapter boundary for Sheets access
+- header/schema validation
+- required column detection
+- duplicate header detection
+- key column detection
+- row parsing
+- `text`, `number`, `boolean` basic column parsers
+- `findAll`
+- `findById`
+- `insert`
+- `update`
+- `_version` based optimistic locking
+- `SchemaDriftError`
+- `ConflictError`
+- `ParseError`
+
+MVP exclusions:
+
+- relations and joins
+- SQL-like query language
+- migration engine
+- lazy loading
+- multi-row atomic transactions
+- Apps Script automatic installation
+- Apps Script Web App gateway
+- caching
+- request collapse
+- retry/backoff
+- dashboard UI
+- browser support matrix
+
+## Architecture
+
+Keep domain rules separate from application orchestration, infrastructure
+storage, and Google API details.
+
+Recommended package boundaries:
+
+```txt
+src/
+  domain/                       # 정규화 값, 평가, 충돌, 상태 규칙
+  shared/                       # 도메인 간 공유 상수·인코딩·상태 계약
+  application/
+    orm/                        # 공개 ORM facade, mapping, flush 계획
+    sync/                       # worker, reconciliation, gateway orchestration
+  adapter/
+    persistence/
+      contracts/                # 저장소 공통 계약
+      providers/mikro-orm/      # 현재 MikroORM + SQLite 구현
+    sheets/
+      providers/apps-script-gateway/
+        protocol/               # 서명·직렬화·응답 검증
+        transport/              # HTTP operation client
+        operations/
+          read/                 # 테이블 읽기
+          write/                # fast append
+          observation/           # snapshot·anchor 관측
+          effect/               # update/delete effect
+  infrastructure/
+    storage/                    # SQLite canonical state와 outbox
+  index.ts
+```
+
+`domain/`과 `shared/`는 외부 SDK를 몰라야 한다. `application/`은 use case와
+동기화 흐름을 조율하고, `infrastructure/`는 SQLite 같은 외부 저장 기술을
+담당한다. `adapter/`는 persistence와 Sheets provider를 각각 계약 뒤에
+격리한다.
+
+The domain should depend on adapter interfaces, not directly on Google Sheets
+SDKs.
+
+The first tests should use an in-memory fake adapter. Real Google integration tests can come later and should be opt-in because they require credentials and quota.
+
+## Code Modification Rules
+
+Do not modify production source files under `src/**` unless the user explicitly asks for production implementation work.
+
+When the user asks for planning, review, explanation, test scaffolding, or configuration only:
+
+- do not edit `src/**`
+- do not create new production files under `src/**`
+- do not "fix" user-written production code opportunistically
+- explain suspected production code issues in the response instead
+- wait for explicit approval before changing production code
+
+Allowed without extra confirmation when requested:
+
+- documentation files
+- planning notes
+- test file scaffolding under `test/**`
+- TypeScript/package/test configuration files
+- `.gitignore`
+
+If a production source issue blocks the requested work, describe the blocker and ask before editing `src/**`.
+
+## Adapter Boundary
+
+Adapters are split by capability and provider. A provider is a concrete
+implementation such as MikroORM or Apps Script; a contract is the stable
+boundary that core, ORM, storage, or runtime code consumes.
+
+- `adapter/persistence/contracts/`: SQL and persistence contracts independent of
+  MikroORM, Prisma, or another future implementation
+- `adapter/persistence/providers/mikro-orm/`: the current MikroORM-backed
+  entity engine and SQLite storage bridge
+- `adapter/sheets/providers/apps-script-gateway/`: the current signed Apps Script
+  provider, separated into protocol, transport, and operation capabilities
+
+The adapter should expose sheet-level operations in terms the core needs, not Google-specific concepts.
+
+Suggested responsibilities:
+
+- read headers
+- read rows
+- append row
+- replace row by index or key
+- optionally re-read row before update
+
+Do not leak Google SDK response objects into core repository logic.
+
+## Schema Drift Policy
+
+Schema drift must not be silently ignored.
+
+The library should fail clearly when:
+
+- a required column is missing
+- the key column is missing
+- headers are duplicated
+- `_version` is required but missing
+- a row cannot be parsed into the declared type
+
+Unexpected extra columns may be allowed by default, but the behavior should be explicit and configurable later.
+
+## Stale Write Policy
+
+MVP optimistic locking should be based on a version column.
+
+Expected behavior:
+
+- read current row
+- keep its `_version`
+- before update, re-check the current `_version`
+- if the version changed, throw `ConflictError`
+- if unchanged, write the updated row with incremented `_version`
+
+This is not a true database transaction. Document it as stale-write protection, not full transactional safety.
+
+## Google Sheets API Constraints
+
+Design with quota and latency in mind.
+
+Current official Sheets API limits to consider:
+
+- 300 read requests per minute per project
+- 60 read requests per minute per user per project
+- 300 write requests per minute per project
+- 60 write requests per minute per user per project
+- 2MB recommended max request payload
+- 180 seconds max processing time per request
+- quota exceeded responses return 429
+
+This means the library should favor batch reads and avoid one API call per row where possible.
+
+## Future Extensions
+
+After the MVP is stable, possible extensions are:
+
+- read cache
+- in-flight read collapse
+- retry/backoff for 429 and transient 5xx
+- Google Sheet template generator
+- schema drift report
+- Apps Script installer CLI
+- Apps Script `LockService` write gateway
+- audit log sheet
+- `_createdAt` and `_updatedAt` system columns
+- GitHub Action for schema verification
+
+Add these only after the base repository model is tested and documented.
+
+## Testing Standard
+
+Tests should prove behavior through realistic sheet states, not through shallow mocks.
+
+Required test categories:
+
+- valid schema passes
+- missing required column fails
+- duplicate header fails
+- missing key column fails
+- invalid number/boolean parse fails
+- `findAll` returns typed rows
+- `findById` returns matching row
+- `findById` returns null/undefined for missing key, whichever API chooses
+- insert rejects duplicate key
+- update increments `_version`
+- update rejects stale version with `ConflictError`
+- extra column behavior is documented by test
+
+The fake adapter should be simple but should preserve enough behavior to expose row/header bugs.
+
+## Documentation Standard
+
+README should explain:
+
+- when this library is appropriate
+- when it is not appropriate
+- Google Sheets quota constraints
+- schema drift problem
+- stale write problem
+- quick start
+- API reference
+- limitations
+- roadmap
+
+Do not market the project as a general database replacement.

package/docs/development.md

@@ -0,0 +1,48 @@
+# Hikoutei Development
+
+## Local verification
+
+Install dependencies and run the normal checks:
+
+```sh
+npm ci
+npm test
+npm run typecheck
+npm run typecheck:test
+npm run build
+npm pack --dry-run
+```
+
+The default test suite uses fake gateways and SQLite/MikroORM fixtures. It does
+not require live Google credentials.
+
+## Google integration tests
+
+Live Google Sheets tests are opt-in. They require a deployed Apps Script
+gateway, credentials, a spreadsheet, and consume external quota. Keep secrets
+in an untracked environment file and never commit them.
+
+## Benchmarks
+
+Performance measurements should be recorded in
+[`sync-bulk-write-benchmark.md`](sync-bulk-write-benchmark.md). Separate:
+
+- one-time setup from steady-state work
+- raw Gateway writes from full worker drain
+- reconciliation from the normal append path
+- local SQLite/ORM time from HTTP and Apps Script time
+
+The benchmark history is not a universal Sheets performance guarantee. Network
+latency, Apps Script execution behavior, quotas, and spreadsheet state can
+change the result.
+
+## Package preview
+
+Before publishing, inspect the tarball contents:
+
+```sh
+npm pack --dry-run
+```
+
+The package should include the built `dist/` output, public documentation, and
+the deployable [`apps-script/gateway/Code.gs`](../apps-script/gateway/Code.gs).

package/docs/git-workflow.md

@@ -0,0 +1,224 @@
+# Git Workflow
+
+## Branch Model
+
+Use a simple branch model.
+
+```txt
+main      stable releases
+next      integration branch, optional
+feature/* feature work
+fix/*     bug fixes
+chore/*   maintenance
+```
+
+If the project is still early, `main` plus short-lived feature branches is enough.
+
+Do not commit directly to `main` once the first usable version is published.
+
+## Branch Naming
+
+Use English kebab-case branch names.
+
+Examples:
+
+```txt
+feature/core-schema
+feature/memory-adapter
+feature/version-locking
+feature/google-sheets-adapter
+feature/readme-quickstart
+fix/conflict-error-message
+chore/node-version-matrix
+```
+
+## Commit Messages
+
+Use Conventional Commits.
+
+Format:
+
+```txt
+<type>(<scope>): <summary>
+```
+
+Common types:
+
+```txt
+feat
+fix
+docs
+test
+refactor
+build
+ci
+chore
+```
+
+Examples:
+
+```txt
+feat(core): add schema definition API
+feat(core): add version-based stale write protection
+feat(adapter): add in-memory sheet adapter
+test(core): cover duplicate header detection
+docs(readme): clarify Google Sheets limitations
+ci(node): add Node version matrix
+```
+
+## PR Size
+
+Keep PRs reviewable.
+
+Target size:
+
+```txt
+300-1,000 changed lines
+```
+
+Split larger changes by responsibility.
+
+Good PR sequence:
+
+1. project scaffold
+2. core schema and column parsers
+3. memory adapter
+4. repository read methods
+5. insert/update methods
+6. optimistic locking
+7. README and examples
+8. Google Sheets adapter
+
+## First Milestone PR Plan
+
+Recommended first milestone:
+
+```txt
+PR 1: project scaffold
+PR 2: schema and parser core
+PR 3: memory adapter and read repository
+PR 4: insert/update with version conflict
+PR 5: README quickstart and limitations
+```
+
+Do not start with Google OAuth or Apps Script. Those belong after the core model is stable.
+
+## Release Policy
+
+Use semantic versioning.
+
+Before `1.0.0`, breaking changes are allowed but should be documented.
+
+Suggested early versions:
+
+```txt
+0.1.0 core schema + memory adapter
+0.2.0 repository CRUD + optimistic locking
+0.3.0 Google Sheets adapter
+0.4.0 README, examples, CI hardening
+```
+
+## Pull Request Template
+
+Each PR should include:
+
+```md
+## Summary
+
+## Why
+
+## Changes
+
+## Tests
+
+## Limitations
+```
+
+## Labels
+
+Use lowercase labels matching commit types where possible.
+
+```txt
+feat
+fix
+docs
+test
+refactor
+build
+ci
+chore
+```
+
+Additional useful labels:
+
+```txt
+core
+adapter
+docs
+release
+```
+
+## CI Expectations
+
+Minimum CI before first release:
+
+- install
+- typecheck
+- test
+- build
+
+Recommended Node matrix:
+
+```txt
+Node 18
+Node 20
+Node 22
+Node 24
+```
+
+Google integration tests should not run by default unless credentials are available.
+
+## Release Checklist
+
+Before publishing:
+
+- README quickstart works
+- package exports are correct
+- `npm pack` contents are checked
+- tests pass
+- typecheck passes
+- build output is verified
+- package name availability is checked
+- limitations are documented
+- no credentials or local files are included
+
+## Issue Strategy
+
+Initial issues should be small and implementation-oriented.
+
+Examples:
+
+```txt
+Add duplicate header detection
+Add missing key column error
+Add number parser
+Add memory adapter
+Add version conflict test
+Add README limitations section
+```
+
+Avoid opening vague issues such as:
+
+```txt
+Build ORM
+Add transactions
+Support everything
+```
+
+## Project Narrative
+
+The public project story should be:
+
+> Google Sheets is practical for early MVPs and internal tools, but manual edits introduce schema drift and stale writes. This library provides a typed repository layer that fails fast on schema drift and protects writes with version-based conflict detection.
+
+Do not claim full database semantics.