仕様・利用条件・制約
仕様・JSON Schema・利用条件・制約
Section titled “仕様・JSON Schema・利用条件・制約”ai-coreはReactを使わないアクション、提案レビュー、UIデータ検証、チャットプロトコル、 出力解析の正本です。react-aiがUI用に参照します。グラフ計算はtask-graph、 グラフを使うエージェント実行・DBアダプター・スキーマ/DDL連携はdata-engineに残します。 ai-coreからこれらへ依存しません。engineの既存AI入口は同じ実装を再exportします。
JSON Schemaと入力検証
Section titled “JSON Schemaと入力検証”ActionToolInputSchemaはアプリケーションが用意するobjectルートのJSON Schemaです。
engine固有の拡張型への依存はありません。TypeScript型だけでモデルの入力を検証することは
できません。defineActionToolは構造検証後に必須のparseInputを実行し、handlerの型を
確定します。失敗すれば処理を実行しません。
tool入力では同期draft-07（既定）と2020-12を利用できます。2020-12なら
$schema: 'https://json-schema.org/draft/2020-12/schema'を明示します。
その他のdraftやasyncのtoolスキーマは拒否します。properties、required、
additionalProperties、文字数・数値の制約などを明示してください。
必須化や未知キーの禁止は自動ではありません。未知キーを禁止するなら
additionalProperties: falseが必要です。tool境界では型変換、default挿入、キー削除をしません。
不正なスキーマは設定時のコンパイルで例外になり、データ不適合は検証失敗として返します。
未知のx-*キーを書くだけでは業務ルール・認可・DB制約・UI動作は実装されません。
構造検証後の業務検証・認可はアプリケーション側が用意します。
remoteスキーマの自動取得はありません。参照はローカルで解決し、コンパイル後の変更には
新しいスキーマobjectを渡してください。
/validationのcreateAjvValidatorが共通AJV実装です。engineもこれを参照します。
既定は非coercionですが、明示的なajvOptionsによって入力を変更する設定は可能です。
draft・locale・返されたAjv instanceの扱いはJSDocを確認してください。
Ajvの実行時コンパイルには関数生成を許可するホストが必要です。CSP/edge環境の制約は
個別に確認してください。
JSONの制限と実行の利用条件
Section titled “JSONの制限と実行の利用条件”toolのスキーマ・引数・公開出力は、元データから分離して凍結した有限JSONです。 plain object/配列、文字列、有限数値、boolean、nullを受け入れます。 accessor、独自prototype、toJSON、関数、undefined、疎配列、循環、非有限数値は拒否します。 1つの値につき深さ64、訪問値10,000、JSON化後のJavaScript UTF-16コード単位1,000,000が上限です。 UTF-8のバイト数ではありません。JSON解析前のリクエストサイズ制限も別に必要です。
登録やtool公開は自動ではありません。公開対象を明示し、mapOutputで外部へ渡してよい値だけを
検証・選択します。登録差し替えで出力型が変わり得るため、公開処理はunknownを受け取ります。
bridgeのcallIdはセッション内で重複拒否され、maxCallsの既定は1000です。古いIDは追い出しません。
会話が変われば新しいセッションを作成します。closeやキャンセルで開始済みの副作用は戻りません。
キャンセルは協調動作で、処理がsettleするまで実行ロックを維持します。
これらは認可、永続的な重複排除、DB transaction、プロセスをまたぐロックの代わりにはなりません。
Generative UI
Section titled “Generative UI”v1文書はversion: 1、空でないid、最大32件の平坦なblocksを持ちます。
blockには一意のid、明示登録されたtype、objectのdataが必要です。
実行可能HTML、React node、callbackをモデルから受け取りません。
validateGenerativeUIDocumentは文書外形と有限JSONを検証し、アプリ固有のcomponent dataは
検証しません。createGenerativeUIContractは登録ごとのデータ検証と対応する応答スキーマを生成します。
component schemaはinline・同期・draft-07・objectルートに限定します。 参照、ID、anchor、draft指定、asyncの予約キーは再帰的に拒否します。 最大32種類の一意なcomponentを登録でき、型変換やdefault挿入はしません。 block IDの一意性とJSONの上限は、生成JSON Schemaだけでは表現できないため実行時にも検証します。 各AIモデルのスキーマ対応範囲にはアプリ側の調整が必要な場合があります。 業務検証・認可はアプリ、React描画はreact-aiとアプリが担当します。
提案・チャット・出力
Section titled “提案・チャット・出力”提案v1は明示したprimitiveフィールドが対象で、object/配列の変更は非対応です。 レビュー判断・変更前値・versionを確認し、選択したbatchの1件が失敗すれば実行用の部分結果を返しません。 保存時にはサーバーでも原子的なversion確認・transactionが必要です。事前確認後の競合は防げません。
チャットアダプターはOpenAI互換/AI SDKのstreamを共通イベントへ変換し、tool呼び出しと結果を
受け渡しますが、toolを自動実行しません。URL・header・モデル設定・transportは明示します。
特権APIキーはサーバーに保管してください。maxResponseCharsの既定はデコード後1,000,000文字、
設定上限は10,000,000文字です。終了・エラー・キャンセルを検証しますが、実サービスや全プロトコルの
動作を保証するものではありません。
extractAgentMessageTextは完了したagent messageのJSONLを抽出し、見つからなければ元の文字列を返します。
出力の実行や、実際のタスク完了・正当性の判定は行いません。
bun run verifyは依存境界、テストを含む型検査、単体テスト、ESM/CJSビルド、
Node/Bun tarball consumer、Node型の有無双方の厳密なNodeNext型解決、browser bundleを検証します。
consumerへengine・DB・storage・Reactは導入しません。README・機能ガイド・JSDocはこのリポジトリが正本です。
apps/docsは同じcheckoutのローカルMarkdownを使い、開発と本番で同じビルドを行います。
初回の公開順序とlockfileはRELEASING.mdを確認してください。
同期createAjvValidatorはdraft-07/2020-12双方でasync schemaを実行前に拒否します。schema設定エラーは例外、同期データ不適合はvalid:falseです。このAPIで非同期検証を実行することはできません。