@autodevjapan/godd-mcp-alpha 2.14.1 → 2.15.1

package/docs/adapter-contracts.md

@@ -0,0 +1,112 @@
+# Adapter contracts
+
+For adapter implementers only. These subpaths expose **no** production processing route — they validate and forward an envelope, nothing more.
+
+This file ships inside the npm tarball, so after `npm install` you can read it at
+`node_modules/@autodevjapan/godd-mcp-alpha/docs/adapter-contracts.md`.
+
+Everything user-facing (tool list, CLI reference, troubleshooting) lives on the
+[documentation site](https://www.getgodd.dev/en/docs).
+
+---
+
+## Media interval adapter contract
+
+```ts
+import {
+  forwardMediaIntervalTransformation,
+  loadMediaIntervalCalibrationSnapshot,
+  validateMediaIntervalAdapterContract,
+} from "@autodevjapan/godd-mcp-alpha/media-interval-adapter-contract";
+
+const contract = validateMediaIntervalAdapterContract(adapterPayload);
+const transformation = forwardMediaIntervalTransformation(contract);
+const calibration = loadMediaIntervalCalibrationSnapshot();
+if (calibration.status === "INCONCLUSIVE") {
+  throw new Error("Media interval calibration could not be verified");
+}
+```
+
+### English
+
+Node validates and forwards the envelope only. Interval arithmetic, canonical union coverage, coverage decisions, and source-buffer application remain Rust-owned and must not be duplicated in the adapter payload. An unsupported schema, unknown nested field, insufficient sample count, invalid metadata, or digest mismatch returns `INCONCLUSIVE` with no numeric fallback — stop instead of inventing a default tolerance.
+
+### 日本語
+
+Node は envelope の検証と転送のみを行います。区間算術、canonical union coverage、coverage判定、source bufferへの適用はRustだけが所有し、アダプター payload 側で再実装してはいけません。未対応スキーマ・未知のネストフィールド・サンプル数不足・不正なメタデータ・digest 不一致は `INCONCLUSIVE` を返し、数値のフォールバックは行いません。既定の許容値を捏造せず、処理を停止してください。
+
+### Русский
+
+Node только проверяет и передаёт envelope. Расчёт интервалов, canonical union coverage, решение по coverage и применение к source buffer остаются исключительно в Rust и не должны дублироваться в payload адаптера. Неподдерживаемая схема, неизвестное вложенное поле, недостаточное число выборок, некорректные метаданные или несовпадение digest возвращают `INCONCLUSIVE` без числового запасного значения — остановитесь, а не придумывайте допуск по умолчанию.
+
+---
+
+## Audio length adapter contract
+
+```ts
+import { validateAudioLengthAdapterContract } from "@autodevjapan/godd-mcp-alpha/audio-length-adapter-contract";
+
+const contract = validateAudioLengthAdapterContract(adapterPayload);
+// contract.length_arithmetic_owner === "rust"
+```
+
+`validateAudioLengthAdapterContract` accepts one object with exactly these five
+keys and nothing else: `schema_version` (must be `1`),
+`length_arithmetic_owner` (must be `"rust"`), `waveform_input`, `mel_input`,
+and `audio_output`. Any extra or missing key throws.
+
+| Envelope | Required keys | Fixed values |
+|---|---|---|
+| `waveform_input` | `kind`, `shape`, `channel_sample_lengths`, `dtype` | `kind: "waveform"`, `dtype: "f32"`, `shape` = 2 positive safe integers |
+| `mel_input` | `kind`, `shape`, `layout`, `dtype` | `kind: "mel"`, `dtype: "f32"`, `layout` ∈ {`"BinsFirst"`, `"FramesFirst"`}, `shape` = 3 positive safe integers |
+| `audio_output` | `kind`, `container`, `encoding`, `sample_rate`, `channels`, `samples_per_channel` | `kind: "audio"`, `container: "wav"`, `encoding: "pcm_s16le"`, the three numbers positive safe integers |
+
+Two rules are the point of the contract:
+
+- **Length arithmetic stays in Rust.** The keys `padding_samples`,
+  `processing_samples`, `expected_feature_frames`, and `trimmed_samples` are
+  rejected anywhere in the three envelopes. If your adapter has computed them,
+  it has already duplicated the owning implementation — send the shapes, not
+  the results.
+- **`channel_sample_lengths` must be internally consistent.** It must have
+  exactly `shape[0]` entries and every entry must equal `shape[1]`. A ragged
+  waveform is rejected rather than truncated to the shortest channel.
+
+## Compile cache adapter contract
+
+```ts
+import {
+  policyForCompileCacheReceipt,
+  projectCompileCacheRegisterRequest,
+  validateCompileCacheReceipt,
+} from "@autodevjapan/godd-mcp-alpha/compile-cache-adapter-contract";
+
+const request = projectCompileCacheRegisterRequest(projectInput);
+const receipt = validateCompileCacheReceipt(rawReceipt);
+const { action, disposition } = policyForCompileCacheReceipt(rawReceipt);
+```
+
+This subpath carries **no source body**. `canonical_source`, `source`,
+`source_body`, `source_text`, `compiled_javascript`, `compiled_module`,
+`host_path`, and `deck_title` are structurally impossible on the boundary
+types — the guarantee is a compile-time assertion, so a change that reintroduces
+one of them fails `pnpm typecheck` rather than leaking at runtime. Pass the
+canonical source to `projectCompileCacheRegisterRequest`, which hashes it into
+`canonical_source_digest` and returns a request that no longer contains it.
+
+Every receipt maps to exactly one caller action via
+`COMPILE_CACHE_OUTCOME_POLICY`. Do not branch on the outcome string yourself —
+read `action` and `disposition`:
+
+| Disposition | Outcomes | What the caller does |
+|---|---|---|
+| `CONTINUE` | `CACHE_HIT`, `CACHE_MISS_COMPILED`, `SINGLE_FLIGHT_JOINED`, `TOO_LARGE_FOR_CACHE`, `BUDGET_EVICTED_LRU`, `SUPERSEDED_BY_NEW_SOURCE`, `DECK_TOMBSTONED`, `STALE_GENERATION_REJECTED`, `PREVIEW_LEASE_EXPIRED`, `AGE_EXPIRED`, `IDLE_EXPIRED`, `RESERVATION_EXPIRED`, `COMPILE_FAILED_ROLLED_BACK` | proceeds — the cache simply did not help |
+| `RETRY` | `BUDGET_UNRECLAIMABLE` | retries **at most once** (`max_retries: 1`), then `REJECT` |
+| `REJECT` | `BUDGET_OVERFLOW`, `RECONCILE_CLOCK_REGRESSION` | stops; these mean arithmetic overflow or a clock that went backwards |
+
+Reconciliation ownership is fixed, not negotiated:
+`COMPILE_CACHE_RECONCILE_OWNER` declares `nextjs-server` as the owner, a
+`monotonic-milliseconds` clock, and a timer-and-after-lifecycle-event trigger.
+`deriveCompileCacheReconcilePolicy({ age_ms, idle_ms, reservation_ttl_ms })`
+returns that owner plus `interval_ms` = the minimum of the three budgets, so the
+sweep can never run less often than the shortest deadline it must enforce.

package/native-assets.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
-  "releaseTag": "godd-native-v0.2.25",
-  "expectedVersion": "godd-native 0.2.25",
-  "sourceCommit": "0e3d92fadc039b73404ee62d1e151699d95a6273",
+  "releaseTag": "godd-native-v0.2.27",
+  "expectedVersion": "godd-native 0.2.27",
+  "sourceCommit": "313e1c76395d0fcbdd071c695f1d405aa71d67c3",
   "capabilities": [
     "cobol-evidence",
     "codec-capability",
@@ -13,7 +13,7 @@
     "plan-audit",
     "research"
   ],
-  "baselineBytes": 36857772,
+  "baselineBytes": 36863916,
   "maximumAssetBytes": 50000000,
   "maximumTarballBytes": 25000000,
   "maximumUnpackedBytes": 55000000,
@@ -21,22 +21,22 @@
     "darwin-x64": {
       "artifact": "godd-native-x86_64-apple-darwin",
       "bytes": 8704856,
-      "sha256": "387b1eeceff77b77712db3528ba451aee1db1145f6ad7d41c636bec14585c2b3"
+      "sha256": "450bfd9030682b2755d17e45efa2f2a6808a990cf246036cb9a9e703383eb4c7"
     },
     "darwin-arm64": {
       "artifact": "godd-native-aarch64-apple-darwin",
       "bytes": 7905536,
-      "sha256": "b38d1c6037ca5ae209c6532b8f7c489d5bd51987c0935ac0fd0e1d2feec71d20"
+      "sha256": "43bacbb81e170e3a821a8aadb7aba33cea0b7871f5a3232bb7e598f347f90c80"
     },
     "linux-x64": {
       "artifact": "godd-native-x86_64-unknown-linux-musl",
       "bytes": 9651280,
-      "sha256": "2e215e4bd78d0cf5d54fb235f59711467b3896acfde776277ab23cda41e4523c"
+      "sha256": "6a2f7c8a7b3cace0b3b41f7f73f5bbae05fd42e9d52a5bcd19f338d7302022df"
     },
     "win32-x64": {
       "artifact": "godd-native-x86_64-pc-windows-msvc.exe",
-      "bytes": 10595840,
-      "sha256": "d265c18a2c627bdf88bed1480c070ffb4c286030e979a82c5884cc76b6d32a91"
+      "bytes": 10601984,
+      "sha256": "5b945c654547e8652ed42e410f9be8ba54e20c0d078838fa3342fdfd1918697a"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autodevjapan/godd-mcp-alpha",
-  "version": "2.14.1",
+  "version": "2.15.1",
   "type": "module",
   "description": "Governed AI development workflows that turn natural-language intent into specifications, tested code, reviews, documentation, and shippable pull requests.",
   "license": "UNLICENSED",
@@ -18,6 +18,11 @@
       "require": "./dist/media-interval-adapter-contract.cjs",
       "default": "./dist/media-interval-adapter-contract.cjs"
     },
+    "./compile-cache-adapter-contract": {
+      "types": "./dist/compile-cache-adapter-contract.d.ts",
+      "require": "./dist/compile-cache-adapter-contract.cjs",
+      "default": "./dist/compile-cache-adapter-contract.cjs"
+    },
     "./*": "./*"
   },
   "bin": {
@@ -34,6 +39,8 @@
     "dist/audio-length-adapter-contract.d.ts",
     "dist/media-interval-adapter-contract.cjs",
     "dist/media-interval-adapter-contract.d.ts",
+    "dist/compile-cache-adapter-contract.cjs",
+    "dist/compile-cache-adapter-contract.d.ts",
     "scripts/postinstall.js",
     "scripts/atomic-binary-install.js",
     "scripts/postinstall-godd-native.js",
@@ -41,6 +48,7 @@
     "scripts/godd-tk-assets.js",
     "scripts/postinstall-godd-tk.js",
     "scripts/write-sha256.js",
+    "docs/adapter-contracts.md",
     "README.md"
   ],
   "engines": {
@@ -58,14 +66,15 @@
     "godd"
   ],
   "scripts": {
-    "build": "pnpm generate:native-catalog && node esbuild.config.js && tsc --ignoreConfig src/audio-length-adapter-contract.ts src/media-interval-adapter-contract.ts --declaration --emitDeclarationOnly --declarationMap false --outDir dist --module ES2022 --target ES2022 --moduleResolution bundler --resolveJsonModule --types node --skipLibCheck",
-    "build:release": "pnpm generate:native-catalog && GODD_BUILD_MODE=release node esbuild.config.js && tsc --ignoreConfig src/audio-length-adapter-contract.ts src/media-interval-adapter-contract.ts --declaration --emitDeclarationOnly --declarationMap false --outDir dist --module ES2022 --target ES2022 --moduleResolution bundler --resolveJsonModule --types node --skipLibCheck",
+    "build": "pnpm generate:native-catalog && node esbuild.config.js && tsc --ignoreConfig src/audio-length-adapter-contract.ts src/media-interval-adapter-contract.ts src/compile-cache-adapter-contract.ts --declaration --emitDeclarationOnly --declarationMap false --outDir dist --module ES2022 --target ES2022 --moduleResolution bundler --resolveJsonModule --types node --skipLibCheck",
+    "build:release": "pnpm generate:native-catalog && GODD_BUILD_MODE=release node esbuild.config.js && tsc --ignoreConfig src/audio-length-adapter-contract.ts src/media-interval-adapter-contract.ts src/compile-cache-adapter-contract.ts --declaration --emitDeclarationOnly --declarationMap false --outDir dist --module ES2022 --target ES2022 --moduleResolution bundler --resolveJsonModule --types node --skipLibCheck",
     "generate:native-catalog": "tsx scripts/generate-native-catalog.ts",
     "catalog:generate": "tsx scripts/generate-command-catalog.ts",
     "catalog:check": "tsx scripts/generate-command-catalog.ts --check",
     "catalog:check:full": "tsx scripts/generate-command-catalog.ts --check --require-site",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
+    "test:docs-contract": "node scripts/docs-contract-tests.mjs",
     "test:realtime-parity": "node scripts/realtime-admission-parity.mjs",
     "quality-gate:realtime-docker": "docker buildx build --load --no-cache-filter gate --file docker/realtime-admission-parity.Dockerfile --tag godd-realtime-admission-gate:local ..",
     "test:watch": "vitest",
@@ -84,7 +93,7 @@
     "esbuild": "0.28.1",
     "tsx": "4.23.1",
     "typescript": "7.0.2",
-    "vite": "8.1.5",
+    "vite": "8.2.0",
     "vitest": "4.1.10"
   },
   "pnpm": {
@@ -94,9 +103,9 @@
     "overrides": {
       "esbuild": "0.28.1",
       "rollup": ">=4.59.0",
-      "hono": ">=4.12.32",
+      "hono": ">=4.12.34",
       "@hono/node-server": ">=2.0.5",
-      "fast-uri": ">=3.1.4",
+      "fast-uri": ">=4.1.2",
       "express-rate-limit": ">=8.6.0",
       "ip-address": ">=10.1.1",
       "qs": ">=6.15.3",

package/scripts/native-assets.js

@@ -173,9 +173,12 @@ export const EXPECTED_NATIVE_ASSET_FILES = Object.freeze(
 // 気づけない）。到達前に検知するため、警告用の閾値と ratchet 上限を定義する。
 export const NATIVE_ASSET_HEADROOM_WARNING_BYTES = 2_000_000;
 
-// `godd-native-v0.2.25` の exact baseline を、意味のある追加増加を止める
+// `godd-native-v0.2.27` の exact baseline を、意味のある追加増加を止める
 // non-cumulative ratchet として固定する。absolute ceiling は別途50MBで維持する。
-export const NATIVE_ASSET_BASELINE_CEILING_BYTES = 36_857_772;
+// v0.2.25 (36,857,772) からの +18,432 bytes は registry anchor (#1493) と
+// compile cache (#1463) の実装分。昇格ごとに実測値へ再固定するため、
+// 小さな増加が誰にも気づかれずに累積することはない。
+export const NATIVE_ASSET_BASELINE_CEILING_BYTES = 36_863_916;
 
 /**
  * 現在の昇格済みreleaseを上限とし、1 byteでも追加増加すれば拒否するratchet。