@aiquants/enrichment-core 0.3.0 → 0.3.1

package/README.md

@@ -22,7 +22,7 @@ Transport- and DB-agnostic storage metadata AI enrichment core: canonical types,
 | `SearchResponseSchema` | `HybridSearchResponse` | `hits` (`SearchHitSchema`: `metadata_id` / `chunk_index` / `text` / `score`)、`graph_hits` (`GraphSearchHitSchema`)、`tiers` (層の名前ごとの真偽値)、`metadata` |
 | `SearchMetadataSchema` | `SearchMetadata` | `circuit_breaker_status` と `quality_tier` は文字列 (検索サービスは走らせたモード、層を飛ばしたときは `DEGRADED` を報告)、`latency_ms`、`total_hits`、`fallback_applied`、`degraded_reason` (飛ばした層の理由、無ければ `null`) |
 
-- `EnrichmentClient` が持つのは `search` だけである。送信先は `<baseUrl>/ai/search/hybrid` であり、`baseUrl` はエンリッチメントのルーターが載る API ルート (quants-api ではホストと API 接頭辞、例 `https://api.example.com/api/v1`)。
+- `EnrichmentClient` が持つのは `search` だけである。送信先は `<baseUrl>/ai/search/hybrid` であり、`baseUrl` はエンリッチメントのルーターが載る API ルート (エンリッチメントのルーターを載せる API サーバーのホストと API 接頭辞、例 `https://api.example.com/api/v1`)。
 - ルートは `Authorization: Bearer <apiKey>` の利用者を認可し、テナントを `X-Tenant-Id` から取る。クライアントは `X-Tenant-Id` に本文の `tenant_id` を入れる (両者が食い違えばルートが 403 で拒む)。`apiKey` には利用者のアクセストークンを渡す (無ければルートが拒む)。
 - 2xx 以外の応答と通信失敗は `EnrichmentClientError` (`statusCode`・`responseBody`・JSON なら `parsedBody`、通信失敗は `statusCode` 0)、JSON でない 2xx は `EnrichmentClientError`、スキーマに反する要求・応答 (空本文を含む) は `ZodError` を投げる。
 - 縮退理由の語彙 (`search.ts`) は閉じた集合であり、発生源ごとに `LOCAL_DEGRADATION_REASONS` (web が遠隔層を呼ばなかった理由) / `REMOTE_DEGRADATION_REASONS` (検索サービスが層を飛ばした理由) / `DISPATCH_DEGRADATION_REASONS` (遠隔の呼び出しと管理者の無効化) と、遮断器の `circuit_breaker_open:<service>` に分かれる (4 つは重ならない)。
@@ -44,7 +44,7 @@ Transport- and DB-agnostic storage metadata AI enrichment core: canonical types,
 | `FlowStep.gatePolicy` (`FlowGatePolicy`) | 1 つの流れに限り、その段の全ての門の意味を上書きする。宣言できるのは `{ whenClosed: "fail", failureStatus }` だけ。門を持たない段に書くと `orderedSteps` が throw する |
 | `flowStepGates(flowStep)` | 流れの中で段が持つ門 (上書きを適用した結果、宣言順)。ワーカーが評価し、コンソールが描くのはこの値であり、`PIPELINE_STEPS[key].gates` を直に読まない |
 
-- 子の読み取りの段 (`ocr_children`) は門を宣言しない。子の文字層 (テキスト・メール・Office・PDF) は `ENABLE_OCR` に関係なく読まなければならず、段ごと飛ばすと添付のテキストが本文から消えるためである。認識の要る子だけが quants-api の中で `ENABLE_OCR` に従い、閉じていればワーカーはその子の行を `gate_closed:ENABLE_OCR` で `SKIPPED` と記録する (段のキーに OCR の名が残るのは、共有 DB の段の記録と集計がこのキーで引かれるためであり、運用者に見せる名前は「子アセットの読み取り」)。
+- 子の読み取りの段 (`ocr_children`) は門を宣言しない。子の文字層 (テキスト・メール・Office・PDF) は `ENABLE_OCR` に関係なく読まなければならず、段ごと飛ばすと添付のテキストが本文から消えるためである。認識の要る子だけが API サーバー の中で `ENABLE_OCR` に従い、閉じていればワーカーはその子の行を `gate_closed:ENABLE_OCR` で `SKIPPED` と記録する (段のキーに OCR の名が残るのは、共有 DB の段の記録と集計がこのキーで引かれるためであり、運用者に見せる名前は「子アセットの読み取り」)。
 - 出荷する上書きは 2 つだけ: 画像の流れの `ocr_document` とメディアの流れの `analyze_media`。どちらも流れの唯一の本文の出所であり、フラグ (`ENABLE_OCR` / `ENABLE_MEDIA_ANALYSIS`) が閉じていれば、その門で実行を `FAILED_EXTRACT` として止める。文字層を持つ流れ (pdf / email / office / google_native) の `ocr_document` は宣言どおり飛ばす。
 - 実行側の契約 (`orderedSteps` の docstring): ワーカーは `orderedSteps(flow)` の順に段を走らせ、各段の前に `flowStepGates(step)` を評価する。最初に閉じていた門が決める — `skip` は段を `gate_closed:<flag>` で `SKIPPED` と記録して次へ進み、`fail` は段を `FAILED` と記録してその門の `failureStatus` で実行を終える。段は全ての門が開いているときだけ走る。
 - どの流れも、門で飛ばされうる段だけに本文を頼らない (本文を作りうる段 `extract_text` / `ocr_document` / `analyze_media` のうち少なくとも 1 つは、閉じれば実行を止めるか門を持たない)。テストが出荷する全ての流れでこれを検査する。
@@ -92,7 +92,7 @@ Transport- and DB-agnostic storage metadata AI enrichment core: canonical types,
 
 ## Integrity audit contract / 整合性監査の契約
 
-監査は quants-api の中で走り、`td_integrity_audit_run` / `td_integrity_audit_quantity` / `td_integrity_audit_finding` へ記録する。ホストはその行を読み、次の形でコンソールへ渡す。記録の語彙 (下の表の `IntegrityStoreSchema` から `IntegrityRepairSkipReasonSchema` までの 12 の列挙と `IntegrityFindingItemClassSchema`) と区分の方針 (`INTEGRITY_CLASS_POLICY`) は各表の CHECK 制約の写しであり、実行の行の制約が持つ削除印の保持日数の範囲は、実行の見出しを検める `SYSTEM_PARAMETER_RANGES.INTEGRITY_TOMBSTONE_RETENTION_DAYS` の写しである。写しの一致はホストの試験が DDL を読んで確かめる (本パッケージはホストの DDL の置き場所を知らない)。
+監査は API サーバー の中で走り、`td_integrity_audit_run` / `td_integrity_audit_quantity` / `td_integrity_audit_finding` へ記録する。ホストはその行を読み、次の形でコンソールへ渡す。記録の語彙 (下の表の `IntegrityStoreSchema` から `IntegrityRepairSkipReasonSchema` までの 12 の列挙と `IntegrityFindingItemClassSchema`) と区分の方針 (`INTEGRITY_CLASS_POLICY`) は各表の CHECK 制約の写しであり、実行の行の制約が持つ削除印の保持日数の範囲は、実行の見出しを検める `SYSTEM_PARAMETER_RANGES.INTEGRITY_TOMBSTONE_RETENTION_DAYS` の写しである。写しの一致はホストの試験が DDL を読んで確かめる (本パッケージはホストの DDL の置き場所を知らない)。
 
 命令の語彙 (`IntegrityCommandSchema` / `IntegrityCommandFailureCodeSchema` と命令ごとのその部分集合) はコンソールの契約の持ち物で、DDL に写しを持たない。全てのスキーマは `.strict()` で、未知の鍵と鍵の欠落を拒む (最初の頁で省く `IntegrityFindingsQuerySchema.after` を除く)。`null` は宣言した項目 (測っていない・まだ無い) だけが持てる。
 
@@ -100,11 +100,11 @@ Transport- and DB-agnostic storage metadata AI enrichment core: canonical types,
 
 - 契約が運ぶ項目についての CHECK 制約の規則。契約が運ばない列の規則 (完了した実行の段、中止した実行の中止の要求) は DB に任せる。
 - ホストが読むときの一意の鍵 (組ごとに量 1 つ、所見は記録順)。
-- 制約は持たないが、書き手 (quants-api) と読み手 (ホスト) が保証する規則: 概況の各区画の実行は読み手が選んだ状態を持つ (`active` は `RUNNING`、`lastCompleted` は `COMPLETED`、`newerUnsuccessful` は `FAILED` / `CANCELLED` / `ABANDONED`)、`SCAN` の量は修復の件数を持たない、`DOCUMENTS` の段は範囲を持たない、`nextAfter` は頁の最後の行の `sequence`、不成功の `REPAIR` の `hasNewerRepair` は真。
+- 制約は持たないが、書き手 (API サーバー) と読み手 (ホスト) が保証する規則: 概況の各区画の実行は読み手が選んだ状態を持つ (`active` は `RUNNING`、`lastCompleted` は `COMPLETED`、`newerUnsuccessful` は `FAILED` / `CANCELLED` / `ABANDONED`)、`SCAN` の量は修復の件数を持たない、`DOCUMENTS` の段は範囲を持たない、`nextAfter` は頁の最後の行の `sequence`、不成功の `REPAIR` の `hasNewerRepair` は真。
 
 これらを破る値は書き手か読み手の欠陥であり、契約は描かずに拒む。
 
-実行の UID (`runUid` / `basisRunUid`、所見の要求と応答の `runUid` を含む) は 16 進の桁を大小文字を問わず受け入れ、小文字へ直して返す (RFC 9562 は桁を大小文字を問わず読み、小文字で書く)。quants-api は小文字で発行し、SQL Server の `uniqueidentifier` は tedious から大文字で届くが、契約を通した後は 1 つの実行が 1 つの綴りを持つ (コンソールは実行を文字列の等しさで比べる)。ホストの読み手が綴りを直す必要は無い。
+実行の UID (`runUid` / `basisRunUid`、所見の要求と応答の `runUid` を含む) は 16 進の桁を大小文字を問わず受け入れ、小文字へ直して返す (RFC 9562 は桁を大小文字を問わず読み、小文字で書く)。API サーバー は小文字で発行し、SQL Server の `uniqueidentifier` は tedious から大文字で届くが、契約を通した後は 1 つの実行が 1 つの綴りを持つ (コンソールは実行を文字列の等しさで比べる)。ホストの読み手が綴りを直す必要は無い。
 
 契約の時刻 (`readAt`・`startedAt`・`heartbeatAt` など) の前後は、`Date.parse` でなく公開する `isStrictlyEarlier(earlier, later)` で比べる (`Date.parse` はミリ秒までしか保たず、100 ns 違う 2 つの時刻を等しいと見る)。両方が契約の受ける時刻で `earlier` が `later` より厳密に前のときだけ `true` を返し、時差 (`Z`・`±HH:mm`・`±HHmm`)・秒の省略・1 秒未満の全ての桁を読んで比べる。どちらかが契約の受ける時刻でなければどちらの向きにも `false` なので、`!isStrictlyEarlier(a, b)` は「`a` が `b` の後か同時」ではない。比べる前に値を契約 (`IntegrityAuditOverviewSchema` など) で検める。契約自身も同じ関数で、`finishedAt` と `heartbeatAt` が `startedAt` より前でないことを検める。
 
@@ -137,7 +137,7 @@ Transport- and DB-agnostic storage metadata AI enrichment core: canonical types,
 | `FLAG_DRIFT`・`DETACHED`・`UNKEYED` | `DISCREPANCY` | `NONE` |
 | `MISSING`・`COUNT_MISMATCH` | `DISCREPANCY` | `REPROJECT` |
 
-判定 (`IntegrityVerdictSchema`) は `DISCREPANCY` の量を数え、`CONSISTENT` になれるのは扱いに依らず全ての量が測れたときだけ (測れた不整合が 1 つでも正なら、他の量の未測定に依らず `INCONSISTENT`)。判定の規則は quants-api が持ち、この契約は判定と量の突き合わせをしない。判定とタイルは単位 (`IntegrityUnitSchema`) の違う量を足さない。単位を混ぜた唯一の和は、不成功の修復の `repairAppliedItems` (適用した点とノードの数) である。
+判定 (`IntegrityVerdictSchema`) は `DISCREPANCY` の量を数え、`CONSISTENT` になれるのは扱いに依らず全ての量が測れたときだけ (測れた不整合が 1 つでも正なら、他の量の未測定に依らず `INCONSISTENT`)。判定の規則は API サーバー が持ち、この契約は判定と量の突き合わせをしない。判定とタイルは単位 (`IntegrityUnitSchema`) の違う量を足さない。単位を混ぜた唯一の和は、不成功の修復の `repairAppliedItems` (適用した点とノードの数) である。
 
 | Schema | Rules checked across fields / 項目の間で検める規則 |
 | --- | --- |
@@ -155,7 +155,7 @@ Transport- and DB-agnostic storage metadata AI enrichment core: canonical types,
   - 中止 (`IntegrityCancelFailureCodeSchema`): `DEPLOYMENT_DISABLED` / `RUN_ALREADY_FINISHED` / `FORBIDDEN` / `UPSTREAM_FAILED` (中止も共有の DB の実行の行を書くので、実行の切替を課される (修復の切替は課さない)。実行を始めることも根拠を名指すことも無い)
   - 命令の語彙の型は `IntegrityCommandFailureCodeFor<Command>` で引ける。画面の文の表は命令ごとにこの型で漏れなく書ける。
 - 表が名指す `code` は、その行の状態を持つ (`DEPLOYMENT_DISABLED` は 503、`RUN_ALREADY_ACTIVE` / `BASIS_INVALID` / `RUN_ALREADY_FINISHED` は 409、`FORBIDDEN` は 403)。例外は状態の無い `FORBIDDEN` だけ (ホストはトークンを持たない命令を送らずに拒むので、応答が無い)。`UPSTREAM_FAILED` は表に無い全ての失敗で、来た状態を持つか、応答が無ければ `status: null`。違反は `status` の問題として拒む。
-- (状態, 業務コード) → `code` の表は `integrityCommandCodes.json` だけが持つ (このリポジトリの中では quants-api の試験も同じファイルを読む。公開する成果物は表を埋め込み、表と各行を凍結する。各行はモジュールの読み込みの時に検め、`UPSTREAM_FAILED` へ写す行・他の鍵を持つ行・300〜599 の外の状態の行があれば読み込みが投げる)。行の `code` がどの命令のものかは表でなく命令ごとの語彙が決める。
+- (状態, 業務コード) → `code` の表は `integrityCommandCodes.json` だけが持つ (このリポジトリの中では API サーバー の試験も同じファイルを読む。公開する成果物は表を埋め込み、表と各行を凍結する。各行はモジュールの読み込みの時に検め、`UPSTREAM_FAILED` へ写す行・他の鍵を持つ行・300〜599 の外の状態の行があれば読み込みが投げる)。行の `code` がどの命令のものかは表でなく命令ごとの語彙が決める。
 - `integrityCommandFailureCodeOf(command, status, errorCode)` は、状態が等しく、業務コードが `null` か等しく、`code` がその命令の語彙である最初の行の `code` を、その命令の語彙の型で返す。業務コードが `null` の行 (`403` → `FORBIDDEN`) はその状態の全ての業務コードに一致する。その命令について一致する行の無い組 (もう一方の命令だけの語彙へ写す組、`503` / `5030` と `503` / `5032` を含む) は `UPSTREAM_FAILED`。返した `code` は、命令と応答の状態とともに `IntegrityCommandFailureSchema` が受け入れる失敗になる。
 
   | `status` | `errorCode` | `code` | 開始 | 中止 |
@@ -178,7 +178,7 @@ Transport- and DB-agnostic storage metadata AI enrichment core: canonical types,
 | `INTEGRITY_RUN_RETENTION_COUNT` | 2〜100 |
 | `POLICY_CONFLICT_MAX_TIE_GROUP_SIZE` | 2〜60 |
 
-- 表の正本は `src/systemParameterRanges.json` の 1 つ。他の言語のホストは自分の写しを持ち、このリポジトリの中ではその試験がこのファイルを読んで一致を確かめる (quants-api の `PARAMETER_RANGES`)。公開する成果物は表を埋め込む。
+- 表の正本は `src/systemParameterRanges.json` の 1 つ。他の言語のホストは自分の写しを持ち、このリポジトリの中ではその試験がこのファイルを読んで一致を確かめる (API サーバー の `PARAMETER_RANGES`)。公開する成果物は表を埋め込む。
 - `SYSTEM_PARAMETER_RANGES` は表と各値域を凍結してあり、型も値域まで読み取り専用である (プロセスの中の読み手の 1 つが値域を広げ、他の書き手と読み手の拒否を外すことができない)。
 - `INTEGRITY_TOMBSTONE_RETENTION_DAYS` の値域は、実行の行の制約 (保持日数の範囲) と実行の見出しの契約 (`IntegrityRunHeaderSchema.tombstoneRetentionDays`) の範囲でもある。制約はこの表の写しなので、値域を変えるときは制約も同じ変更で改める (ホストの試験が一致を検める)。
 - 表が抑えるパラメータは全て整数である。整数でないパラメータは、項目が型を宣言するまで表に加えられない。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiquants/enrichment-core",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Storage metadata AI enrichment core: canonical schemas, RFC 9562 UUIDv7, and API client SDK.",
   "keywords": [
     "enrichment",
@@ -62,9 +62,9 @@
     "build": "tsup && node ../../.config/scripts/strip-dts-comments.mjs dist",
     "build:watch": "tsup --watch",
     "dev": "tsup --watch",
-    "publish:patch": "pnpm run typecheck && pnpm run --if-present test && pnpm version patch --no-git-tag-version --no-git-checks && pnpm publish --no-git-checks",
-    "publish:minor": "pnpm run typecheck && pnpm run --if-present test && pnpm version minor --no-git-tag-version --no-git-checks && pnpm publish --no-git-checks",
-    "publish:major": "pnpm run typecheck && pnpm run --if-present test && pnpm version major --no-git-tag-version --no-git-checks && pnpm publish --no-git-checks",
+    "publish:patch": "pnpm run typecheck && pnpm run --if-present test && pnpm run build && node ../../.config/scripts/check-publish-leaks.mjs && pnpm version patch --no-git-tag-version --no-git-checks && pnpm publish --no-git-checks",
+    "publish:minor": "pnpm run typecheck && pnpm run --if-present test && pnpm run build && node ../../.config/scripts/check-publish-leaks.mjs && pnpm version minor --no-git-tag-version --no-git-checks && pnpm publish --no-git-checks",
+    "publish:major": "pnpm run typecheck && pnpm run --if-present test && pnpm run build && node ../../.config/scripts/check-publish-leaks.mjs && pnpm version major --no-git-tag-version --no-git-checks && pnpm publish --no-git-checks",
     "typecheck": "tsc --noEmit",
     "clean": "rimraf dist",
     "lint": "biome lint src/",