@moldea.ai/adapter-google-genai 3.0.0 → 3.0.1

package/README.md

@@ -8,7 +8,7 @@ The package implements the official `google-genai` runtime adapter for `@moldea.
 
 ## Supported target
 
-Version `3.0.0` supports:
+Version `3.0.1` supports:
 
 - Repository Format version `1`
 - `@moldea.ai/core ^4.0.0`
@@ -60,3 +60,12 @@ pnpm --filter @moldea.ai/adapter-google-genai build
 ```
 
 Tests are colocated with their owning modules. Canonical conformance fixtures live under `/fixtures/adapter-google-genai`.
+
+## Documentation
+
+These guides are included in the installed package. Open only the page relevant to your task.
+
+- [Package overview](docs/index.md)
+- [Verified target](docs/verified-target.md)
+- [Evidence and diagnostics](docs/evidence-and-diagnostics.md)
+- [Limitations](docs/limitations.md)

package/docs/evidence-and-diagnostics.md

@@ -0,0 +1,30 @@
+---
+title: Evidence and diagnostics
+description: Evidence kinds, stable diagnostics, conservative ambiguity, and cascade suppression.
+order: 20
+---
+
+# Evidence and diagnostics
+
+The target may emit `runtime-package`, `language`, `runtime-pattern`, `instruction-loader`, `tool-registration`, and `schema` evidence. Records identify only safe scalar metadata and logical source references.
+
+## Diagnostic catalog
+
+| Code                                               | Stable message                                                                                             |
+| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `GOOGLE_GENAI_PACKAGE_MANIFEST_INVALID`            | The owning package manifest is invalid for Google Gen AI dependency detection.                             |
+| `GOOGLE_GENAI_SDK_VERSION_UNSUPPORTED`             | The observed Google Gen AI SDK dependency range is disjoint from the supported range.                      |
+| `GOOGLE_GENAI_SOURCE_TEXT_INVALID`                 | The referenced Google Gen AI source file is not valid normalized text.                                     |
+| `GOOGLE_GENAI_SOURCE_SYNTAX_INVALID`               | The referenced Google Gen AI source file contains invalid TypeScript syntax.                               |
+| `GOOGLE_GENAI_RUNTIME_AGENT_SYMBOL_NOT_FOUND`      | The declared runtime-agent symbol was not found.                                                           |
+| `GOOGLE_GENAI_INSTRUCTION_LOADER_SYMBOL_NOT_FOUND` | The declared instruction-loader symbol was not found.                                                      |
+| `GOOGLE_GENAI_TOOL_REGISTRATION_SYMBOL_NOT_FOUND`  | The declared tool-registration symbol was not found.                                                       |
+| `GOOGLE_GENAI_TOOL_INPUT_SCHEMA_SYMBOL_NOT_FOUND`  | The declared tool input-schema symbol was not found.                                                       |
+| `GOOGLE_GENAI_INSTRUCTION_LOADER_NOT_WIRED`        | The declared instruction loader is not wired to the detected Google Gen AI generate-content configuration. |
+| `GOOGLE_GENAI_TOOL_REGISTRATION_NOT_WIRED`         | The declared tool registration is not wired to the detected Google Gen AI function-declaration collection. |
+| `GOOGLE_GENAI_TOOL_NAME_MISMATCH`                  | The declared tool name does not match the detected Google Gen AI function name.                            |
+| `GOOGLE_GENAI_TOOL_NAME_INVALID`                   | The detected Google Gen AI function name violates the supported SDK declaration limit.                     |
+| `GOOGLE_GENAI_TOOL_INPUT_SCHEMA_NOT_WIRED`         | The declared tool input schema is not wired to the detected function declaration's parameters JSON schema. |
+| `GOOGLE_GENAI_FUNCTION_DECLARATION_LIMIT_EXCEEDED` | The detected Google Gen AI function-declaration collection exceeds the supported SDK declaration limit.    |
+
+Invalid text or syntax suppresses derived symbol and relationship diagnostics for that source. Missing symbols suppress their derived wiring diagnostics. Unsupported or dynamic requests, configurations, collections, containers, registrations, or schema values suppress negative relationship diagnostics when they could contain the declared relationship. Independently proved package, name, and collection-limit diagnostics remain observable.

package/docs/index.md

@@ -0,0 +1,21 @@
+---
+title: Google Gen AI runtime adapter
+navigationTitle: Overview
+description: Deterministic evidence and diagnostics for the verified direct Google Gen AI models.generateContent target.
+order: 0
+---
+
+# Google Gen AI runtime adapter
+
+`@moldea.ai/adapter-google-genai` implements the official `google-genai` runtime adapter for Core. It statically inspects explicitly bound TypeScript source through Core's source-neutral repository reader.
+
+```typescript
+import { googleGenAiAdapter } from '@moldea.ai/adapter-google-genai';
+import { createCore } from '@moldea.ai/core';
+
+const core = createCore({ adapters: [googleGenAiAdapter] });
+```
+
+The package is available with one technical target covering TypeScript ESM using direct `models.generateContent` calls with npm `@google/genai >=2.17.1`, Repository Format version `1`, and Core `^4.0.0`.
+
+The adapter never imports or calls the Google Gen AI SDK, executes no repository code, requires no credentials, and makes no network request. Its only public export is the immutable `googleGenAiAdapter` singleton.

package/docs/limitations.md

@@ -0,0 +1,21 @@
+---
+title: Boundaries and limitations
+description: Unsupported APIs, source forms, provider behavior, and the deterministic security boundary.
+order: 30
+---
+
+# Boundaries and limitations
+
+The current target does not claim support for:
+
+- JavaScript, Python, CommonJS, or non-ESM source
+- legacy `@google/generative-ai`
+- `generateContentStream`, chats, live sessions, or the Interactions API
+- callable tools, MCP conversion, automatic function execution, or provider/server tool relationships
+- configuration or clients returned by factories
+- arbitrary compiler resolution, path aliases, package exports, directory indexes, or re-export graphs
+- alternative `FunctionDeclaration.parameters` schemas
+- response-schema, tool-output-schema, or agent input/output-schema evidence
+- backend, project, location, API version, authentication mode, model, contents, response, retry, or transport validation
+
+Package detection uses nearest manifests rather than lockfiles or installed modules. Static dependency ranges are observations, not proof of an installed build. Each invocation sees one declared agent and bounded logical repository operations, not a complete agent collection or project body index. The adapter never executes source, reads host files or environment variables, initializes tools, or contacts Google services.

package/docs/verified-target.md

@@ -0,0 +1,28 @@
+---
+title: Verified target
+description: Exact package, language, generate-content, instruction, function-declaration, schema, and provider-limit behavior.
+order: 10
+---
+
+# Verified target
+
+The canonical Runtime Compatibility Matrix defines technical target `typescript-models-generate-content-2`.
+
+## Runtime boundary
+
+- TypeScript ESM `.ts`, `.tsx`, and `.mts` files
+- named runtime value imports of `GoogleGenAI` from `@google/genai`
+- the nearest owning manifest declaring `@google/genai >=2.17.1`
+- a module-local `const` client constructed directly with `new GoogleGenAI(...)`
+- a directly exported runtime-agent function containing exact non-computed `client.models.generateContent({ ... })` calls
+- one exact object-literal request argument
+
+`config` is resolved only as a direct object literal. `systemInstruction` and `tools` are classified independently inside it. Positive evidence is existential across supported calls; a negative wiring diagnostic requires every candidate to prove the relationship absent with no dynamic or unsupported candidate that could contain it.
+
+## Function declarations
+
+The tool path is `config.tools[].functionDeclarations[]`. Inline literals and immutable module-local `const` arrays and objects are supported. Arrays with holes or spreads, mutation, aliases, escapes, dynamic candidates, computed properties, and unknown container fields keep the affected relationship unresolved.
+
+A supported declaration has a static `name`, optional static `description`, optional `parametersJsonSchema`, and optional uninterpreted `behavior`, `response`, and `responseJsonSchema`. The alternative `parameters` field is unsupported. Only a directly exported bound `const` object can establish manifest tool-registration and schema evidence; inline and unexported declarations still participate in closure and count checks.
+
+Names must match `^[A-Za-z_][A-Za-z0-9_.:-]*$` and contain 1–128 Unicode scalar values. Every closed `functionDeclarations` collection permits at most 512 occurrences.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moldea.ai/adapter-google-genai",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "Deterministic runtime evidence and diagnostics for direct Google Gen AI SDK integrations.",
   "homepage": "https://github.com/moldea-ai/packages/tree/main/projects/adapter-google-genai#readme",
   "bugs": {
@@ -18,6 +18,7 @@
   "files": [
     "cover.png",
     "dist",
+    "docs",
     "LICENSE",
     "README.md"
   ],