hikoutei 0.4.2 → 0.4.3

package/docs/ci.md

@@ -1,293 +0,0 @@
-# CI scenarios
-
-Hikoutei's CI runs two installed-consumer scenarios against the packed
-package. Each is built as an installed consumer: after `npm pack` it imports
-from the packed tarball rather than from `src/**` or the source-only test
-fake, and neither is allowed to import those.
-
-1. **Internal sync E2E** (`scripts/ci/run-api-scenario.mjs`) drives the
-   internal typed-sheets sync pipeline — projection registration, sheet
-   provisioning, the bounded effect worker, polling, and the MikroORM-backed
-   storage/CAS/hash machinery — and loads implementation modules directly from
-   the packed `dist/` tree.
-2. **Installed root API smoke** (`scripts/ci/run-root-api-scenario.mjs`)
-   imports ONLY the installed package root entrypoint `hikoutei` (no internal
-   package subpaths and no source imports) and exercises the public
-   entity-lifecycle contract an application is meant to use.
-
-The public contract is the high-level `hikoutei` root API: a SQLite-backed
-entity lifecycle. Sheet configuration, registration, and synchronization remain
-internal service concerns. The
-`hikoutei/orm` and `hikoutei/mikro-orm` package subpaths are intentionally not
-published; the root smoke performs those dynamic imports only as negative
-boundary assertions (they must be rejected with `ERR_PACKAGE_PATH_NOT_EXPORTED`)
-while the lifecycle itself imports only the root `hikoutei` entrypoint. This
-guards the boundary directly in an installed consumer in addition to the
-source-level tests.
-
-## Internal sync E2E
-
-The scenario is built as an installed consumer: after `npm pack` it imports the
-package entrypoints from the packed tarball rather than from `src/**` or the
-source-only test fake. It is not allowed to import those. Both backends execute
-the same lifecycle:
-
-1. create and register a mapped entity and its `System_State`/`User_Input`
-   projections;
-2. provision the Sheets tabs;
-3. insert, read, update, and delete one entity through the entity manager;
-4. run the bounded effect worker after each write;
-5. edit a User_Input value and verify that polling reports the changed row;
-6. restore the value, delete the entity, and verify the final projection state.
-
-## Installed root API smoke
-
-The root smoke imports only the installed `hikoutei` root entrypoint and drives
-the stable public lifecycle end to end against an in-memory SQLite authority
-(`dbName: ":memory:"`):
-
-1. define a scalar entity with `defineTypedSheetsEntity()`;
-2. open the runtime with `createTypedSheets()` and only `dbName` plus entity tokens;
-3. obtain a request-local manager with `em.fork()`;
-4. `create()` / `persist()` / `flush()` one entity and `findOne()`-verify it;
-5. mutate the loaded entity, `flush()`, and re-read it through a fresh fork to
-   confirm the mutation committed locally;
-6. `remove()` / `flush()` and verify the entity is gone through a fresh fork;
-7. close the runtime.
-
-It uses assertions and writes a JSON report plus a clear pass summary. It never
-contacts Google Sheets, never needs credentials, and never provisions remote
-tabs, so it runs as a packed consumer only in the normal CI, develop, and stable
-verify jobs and has no live counterpart. It is local-only — an in-memory SQLite
-authority with no backend concept — not a fake-backend scenario like the
-internal sync E2E. Its entity lifecycle imports only the
-root `hikoutei` package; the `hikoutei/orm` and `hikoutei/mikro-orm` dynamic
-imports it performs are negative boundary assertions that must be rejected,
-not part of the lifecycle.
-
-## Backends and triggers
-
-The normal CI, develop, and stable verification jobs run **both** installed-consumer
-scenarios — the internal sync E2E and the installed root API smoke. The
-internal E2E uses the **fake** backend (no Google Sheets contact, no
-credentials); the root API smoke is local-only, an in-memory SQLite authority
-(`:memory:`) with no backend concept. The workflows are:
-
-- `.github/workflows/ci.yml` runs on pull requests and pushes to `main` and
-  `develop`.
-- `.github/workflows/develop-version.yml` creates the next patch version and
-  `develop-vX.Y.Z` tag after a `develop` push.
-- `.github/workflows/develop-publish.yml` verifies and publishes that tag with
-  the `latest` dist-tag.
-- `.github/workflows/main-version.yml` creates the next minor version and
-  `vX.Y.Z` tag after a `main` push.
-- `.github/workflows/stable-publish.yml` verifies and publishes that tag with
-  the `latest` dist-tag too.
-
-Only the internal sync E2E has a live variant, in the separate
-`.github/workflows/live-integration.yml` workflow. It is opt-in via
-`workflow_dispatch` — a maintainer with write access dispatches it explicitly;
-it never runs automatically on pull requests or pushes — and exercises
-that single scenario against real Google Sheets with `--backend=live
---outbound=direct`. The installed root API smoke has no live
-counterpart: it is a local-only lifecycle smoke against an in-memory SQLite
-authority, so it never runs there.
-
-Because live is opt-in via `workflow_dispatch`, it is triggered manually by a
-maintainer with write access rather than automatically on pull requests, so
-there is no forked-PR secret-exposure path. The live path is
-service-account-only: the workflow materializes the service-account key in
-`$RUNNER_TEMP` and scopes the credential/spreadsheet environment to the live
-execution and cleanup steps only, not the whole job, so
-checkout/setup/install/build never see them. The live run uses a dedicated test
-spreadsheet shared with the service account and the following GitHub Actions
-secrets:
-
-- `GOOGLE_SERVICE_ACCOUNT_CREDENTIALS_JSON` (the service-account key JSON)
-- `GOOGLE_SHEETS_TEST_SPREADSHEET_ID`
-
-No gateway is deployed or invoked — the live path is service-account-only, so
-the workflow needs only those two secrets.
-
-## Cleanup
-
-Each live run generates unique tab names from the workflow run ID. The runner
-writes a manifest before provisioning, cleans those tabs in a `finally` path,
-and the workflow repeats cleanup with `if: always()` so a failed assertion does
-not leave the fixture behind. Cleanup uses the same service account
-(`deleteSheet` requests through the direct provider's transport) and removes
-the shared receipt tab too. Do not point the live secrets at a production
-spreadsheet; cleanup is intentionally scoped to the dedicated CI spreadsheet.
-
-## Kohkai dependency
-
-Hikoutei consumes the standalone `@hikoutei/kohkai` package from the
-`ManddarinShop/Kohkai` repository. The codec is not a Hikoutei workspace and
-its source is not included in the Hikoutei tarball:
-
-```json
-{
-  "dependencies": {
-    "@hikoutei/kohkai": "0.1.0"
-  }
-}
-```
-
-The root CI, develop publish, and stable publish workflows verify that the
-exact declared Kohkai version already exists on npm before installing or
-publishing Hikoutei. The first integration release therefore requires:
-
-1. publish `@hikoutei/kohkai@0.1.0` from the Kohkai repository using tag `v0.1.0`;
-2. merge the Hikoutei dependency integration;
-3. let the next develop release produce `0.3.2` from the current `0.3.1` baseline.
-
-Existing Hikoutei releases remain unchanged. The root
-`test/kohkai-compatibility.test.ts` pins the Hikoutei shared stable encoding to
-the Kohkai compatibility vectors and proves the local codec is byte-compatible
-with the generic `@hikoutei/kohkai` codec; the Apps Script codec mirror was
-removed with the gateway.
-
-## Develop publication
-
-A push to `develop` runs `.github/workflows/develop-version.yml`. It verifies
-the merged package, increments only the patch component, updates
-`package.json` and `package-lock.json`, commits the release version, and creates
-an annotated tag such as `develop-v0.3.1`. The generated commit is guarded from
-being processed as another release.
-
-The tag triggers `.github/workflows/develop-publish.yml`. It repeats the
-unit/type/build/package checks, the installed-package internal sync
-E2E, and the installed root API smoke before publishing the numeric package
-version with the npm `latest` dist-tag. The version has no `-beta` suffix, and
-a plain `npm install hikoutei` resolves this channel:
-
-```sh
-npm install hikoutei
-```
-
-The old `develop` dist-tag is no longer updated by this workflow; existing
-pinned `hikoutei@develop` installs keep the last develop-tagged version.
-
-The version calculation is isolated in `scripts/ci/release-version.mjs` and is
-covered by `test/release-version.test.ts`. For example:
-
-```text
-0.3.0 + patch → 0.3.1
-0.3.1 + patch → 0.3.2
-0.3.2 + patch → 0.3.3
-```The workflow requires a repository `RELEASE_TOKEN` secret with contents write
-permission. A token other than the default `GITHUB_TOKEN` is used because a
-push made by `GITHUB_TOKEN` does not trigger another workflow; the release tag
-must trigger `develop-publish.yml`. The publish job separately requires
-`NPM_TOKEN` plus npm provenance. The branch SHA is checked immediately before
-pushing, and the commit plus tag use one atomic Git push, so a concurrent
-develop merge fails without leaving a stale release tag. The version commit and
-npm publication are not atomic; a failed publish can be retried from the
-existing `develop-vX.Y.Z` tag after verifying that the version has not already
-been published.
-
-## Stable publication
-
-A push to `main` runs `.github/workflows/main-version.yml`. It verifies the
-merged package, increments the minor component, updates the package manifests,
-commits the release version, and creates an annotated tag such as `v0.4.0`:
-
-```text
-0.3.1 + minor → 0.4.0
-```
-
-The tag triggers `.github/workflows/stable-publish.yml`. That workflow only
-validates the numeric tag and matching package manifest versions, reruns the
-full checks and installed-consumer scenarios, and publishes to npm with the
-`latest` dist-tag. A `develop-v0.3.1` tag cannot trigger this numeric `vX.Y.Z`
-workflow.
-
-The main version workflow uses the same `RELEASE_TOKEN` requirement so its
-`vX.Y.Z` tag triggers `stable-publish.yml`. The stable publish job also
-requires the repository `NPM_TOKEN` secret and npm provenance before publishing
-`latest`. Stable package versions are
-immutable on npm, so reusing a published version fails instead of replacing
-it.
-
-Every release is also mirrored to GitHub Packages as the scoped package
-`@ManddarinShop/hikoutei` (`npm.pkg.github.com`), repacked from the
-verified tarball because the GitHub Packages npm registry only hosts
-scoped packages; the mirror uses the workflow `GITHUB_TOKEN` with
-`packages: write`.
-
-Both channels publish `latest`, so their versions must increase globally:
-
-```text
-develop merges → patch:   0.3.3 → 0.3.4 → 0.3.5   (latest)
-main merge (after merging develop) → minor: 0.3.5 → 0.4.0   (latest)
-merge main back into develop → 0.4.0
-next develop merges → patch: 0.4.0 → 0.4.1 → 0.4.2   (latest)
-next main merge → minor: 0.4.2 → 0.5.0   (latest)
-```
-
-Keep the channels aligned: after a stable main release, merge `main` back
-into `develop` so the next develop patch release starts from the new stable
-baseline. If a develop release is prepared before that back-merge, its
-publish fails loudly on the latest-dist-tag monotonicity check (the develop
-version trails the main minor); merge main back and re-run the publish from
-the existing `develop-vX.Y.Z` tag. Normal users install the rolling line
-with:
-
-```sh
-npm install hikoutei
-```
-
-## Artifacts
-
-The CI, develop, and stable jobs each emit a JSON report for **both**
-scenarios (internal sync E2E and installed root API smoke). The live
-job emits a JSON report only for the internal sync E2E, the single
-scenario it runs. Both runner scripts (`run-api-scenario.mjs` and
-`run-root-api-scenario.mjs`) default their `--summary` option to
-`GITHUB_STEP_SUMMARY`, so in GitHub Actions every CI/develop/stable invocation
-writes a step summary even though none passes `--summary` explicitly. The live
-internal E2E run is the only invocation that passes `--summary` explicitly
-(`--summary="$GITHUB_STEP_SUMMARY"`), which resolves to the same default but
-documents the intent. The develop and stable verify jobs upload their two
-installed-consumer scenario reports as a dedicated reports artifact
-(`if: always()`), separate from the package artifact (`if: success()`) that the
-publish job consumes. Setup time and steady-state time are reported separately
-for the internal E2E so spreadsheet creation and header provisioning do not
-distort the internal sync measurements.
-
-The develop and stable package artifacts are each a single directory that
-holds the npm tarball and its `sha256` checksum together under
-`$RUNNER_TEMP/hikoutei-{develop,stable}-package`. Their GitHub artifact names
-are `hikoutei-develop-package` and `hikoutei-stable-package`; the installed
-consumer report artifacts are `hikoutei-develop-fake-installed-consumer` and
-`hikoutei-stable-fake-installed-consumer`. The normal CI report artifact is
-`hikoutei-fake-installed-consumer`. The publish job downloads the corresponding
-package directory, asserts it contains exactly one `hikoutei-*.tgz` and the
-checksum file, verifies the checksum line names that exact tarball (not merely
-any file present in the directory), and only then runs `sha256sum --check`
-before publishing. Name/version validation, npm provenance, the
-`latest` dist-tag, and the stale branch SHA checks are enforced by
-the corresponding workflows.
-
-## Action versions
-
-Every workflow pins `actions/checkout`, `actions/setup-node`,
-`actions/upload-artifact`, and `actions/download-artifact` to the current
-Node 24-compatible major (`v5`) so the JavaScript actions run on the runner's
-Node 24 runtime:
-
-| Action | Major | Runtime |
-| --- | --- | --- |
-| `actions/checkout` | `v5` | Node 24 |
-| `actions/setup-node` | `v5` | Node 24 |
-| `actions/upload-artifact` | `v5` | Node 24 |
-| `actions/download-artifact` | `v5` | Node 24 |
-
-All four are on the same major, so there is no exception to record. The pin
-preserves behavior: artifacts are downloaded by name (not by artifact ID);
-`upload-artifact` still zips by default; `setup-node` `cache: npm` is set
-explicitly (the package has no `packageManager` field, so the auto-cache
-shortcut never applies); and the publish steps set `NODE_AUTH_TOKEN` in their
-own `env`, so npm provenance and the `id-token: write` permission are
-unchanged. This major is the action's own runtime version; the build and
-test job still uses `node-version: 22`.

package/docs/code-guidelines.md

@@ -1,248 +0,0 @@
-# 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
-- paced write serialization through the direct provider
-
-## 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
-- 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, Sheets 조정, telemetry
-  adapter/
-    persistence/
-      contracts/                # 저장소 공통 계약
-      providers/mikro-orm/      # 현재 MikroORM + SQLite 구현
-    sheets/
-      providers/google-sheets-api/
-        transport/              # paced REST transport client
-        model/                  # preflight·planner·observation·batch 모델
-  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 the Google Sheets REST provider; 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/google-sheets-api/`: the current direct Google
-  Sheets REST provider, separated into transport and model; the single sync
-  provider
-
-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
-- 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

@@ -1,74 +0,0 @@
-# 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 a fake Sheets provider and SQLite/MikroORM fixtures.
-It does not require live Google credentials.
-
-## Google integration tests
-
-Live Google Sheets tests are opt-in. The tracked live path is
-service-account-only: it requires a service-account key, a shared
-spreadsheet, and consumes external quota. Keep secrets in an untracked
-environment file and never commit them.
-
-The internal end-to-end scenario runs against the fake backend by default
-and against the live backend in full-direct mode:
-
-```sh
-node scripts/ci/run-api-scenario.mjs --backend fake
-node scripts/ci/run-api-scenario.mjs --backend live --outbound direct
-```
-
-The live backend is the service-account-only direct provider, used for
-provisioning, outbound effects, observation, `mutateRow`, and cleanup. It
-requires `GOOGLE_APPLICATION_CREDENTIALS` and
-`GOOGLE_SHEETS_TEST_SPREADSHEET_ID` — and nothing else. The report
-records only `sheetMatched: true` for the direct mode and never prints
-spreadsheet IDs.
-
-`--backend live` always runs the direct provider; the removed gateway mode no
-longer exists, so any `--outbound` value other than `direct` is rejected.
-
-## 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 transport writes from full worker drain
-- reconciliation from the normal append path
-- local SQLite/ORM time from HTTP and provider time
-
-The benchmark history is not a universal Sheets performance guarantee. Network
-latency, Sheets API behavior, quotas, and spreadsheet state can
-change the result. The full direct provider (`googleSheetsApi`) is not a
-performance claim either: the raw-transport benchmarks under `scripts/bench/`
-measure the unguarded API path (no receipts, no compare-and-set), while the
-provider adds fail-closed guarantees (receipts and compare-and-set), so its
-throughput is unverified until measured through the full worker.
-
-## Package preview
-
-Before publishing, inspect the tarball contents:
-
-```sh
-npm pack --dry-run
-```
-
-The package should include the built `dist/` output and the public
-documentation only — no Apps Script deployment. The sync provider calls the
-Google Sheets REST API (`spreadsheets.get` / `spreadsheets.batchUpdate`)
-through a service account, so the tarball contains no gateway sources or
-manifest; the service account needs only the Spreadsheets scope.