@futdevpro/fsm-dynamo 1.15.18 → 1.15.21

package/__documentations/2026-06-01-fr047-fc-foundation.md

@@ -0,0 +1,48 @@
+# FR-047 — function-calling foundation in dynamo-fsm (2026-06-01)
+
+**Parent**: `__agent/feature-requests/FR-047-provider-agnostic-function-calling.md` (+ Phase 1) and `FR-048-per-model-agnostic-settings.md`
+**Versions**: `01.15.17` (Phase 1 + registry), `01.15.18` (adultContent), `01.15.19` (export-bug fix)
+**Scope**: `src/_modules/ai` (agnostic core + provider model submodules), `package.json` (exports)
+
+## What
+
+The SDK-free agnostic AI core gained the full function-calling vocabulary + a per-model capability registry, plus a reserved per-model settings extension point. No execution logic here — that lives in dynamo-nts (Phase 2+).
+
+### 01.15.17 — Phase 1 vocabulary + registry foundation + FR-048 reservation
+- Tool models: `DyFM_AI_Tool`, `DyFM_AI_ToolCall`, `DyFM_AI_ToolResult`, `DyFM_AI_ToolHandler`/`DyFM_AI_ToolHandlers`.
+- `DyFM_AI_Message` + `DyFM_AI_LLM_Response` gained optional tool fields (`toolCalls`, `toolCallId`, `stopReason`); `DyFM_AI_MessageRole.tool` added.
+- `DyFM_AI_ModelType` extended: `Image`, `Audio`.
+- Per-model registry: `DyFM_AI_ModelInfo` + `DyFM_AI_ModelCapabilities` + the 5 provider const arrays (`DyFM_OAI_Models`, `DyFM_AAI_Models`, `DyFM_GAI_Models`, `DyFM_LAI_Models`, `DyFM_FdpAI_Models`) — verified 2026-06-01 against official provider docs.
+- `DyFM_AI_ModelRegistry_Util` (`findModelInfo`, `modelSupportsTools`) — takes the registry array as a param so the agnostic core imports NO provider submodule (keeps it SDK-free).
+- FR-048: `DyFM_AI_ModelSettingsSchema` reserved field on `DyFM_AI_ModelInfo` + thorough docs (per-model settings system; NOT implemented).
+
+### 01.15.18 — adultContent capability
+- `DyFM_AI_ModelCapabilities.adultContent: boolean` — can the model generate adult / uncensored / NSFW content. For content-routing + age-gating (e.g. Adventor mature mode). All 21 registered models = `false` (mainstream cloud is content-filtered; local/FdpAI conservative / model-dependent).
+
+### 01.15.19 — subpath export-bug fix
+- `package.json` `exports` + `typesVersions`: `./ai/google` and `./ai/local` pointed at non-existent `_modules/ai/_modules/google`/`local` folders; the real folders are `google-ai`/`local-ai`. Fixed the targets → `@futdevpro/fsm-dynamo/ai/google` and `./ai/local` now resolve. Unblocks dynamo-nts Phase 5 (Google).
+
+## Why
+
+Function calling needed to live in the strategic provider-agnostic layer (not only the legacy OpenAI-specific `FDPNTS_GPT_ControlService`). dynamo-fsm owns the vendor-neutral vocabulary + the model registry; dynamo-nts owns the execution (agent-loop + per-provider translators). This commit set delivers the fsm half so nts can build against it.
+
+## Design notes
+
+- All changes additive/non-breaking except the export-path fix (corrects a latent resolution bug) and the new required `adultContent` capability (all registry consts updated in the same release).
+- Capability honesty: `functionCalling` (and `adultContent`) are per-model; unknown/local models default conservative (`false`) — never assume capability.
+- Tool-handler runner semantics (never-throw, errors returned as strings to the model) are defined by the type + implemented in dynamo-nts.
+
+## Tests
+
+`pnpm test` (build-base + jasmine): **1302 specs / 0 failures / 70 pending** across the releases. New: `ai-model-registry.util.spec.ts` (findModelInfo + modelSupportsTools, incl. unknown-id → false).
+
+## What's NOT here
+
+- The agent-loop + provider translators (`requestWithTools`, `runToolLoop`, OpenAI/Anthropic/Gemini tool translators) — dynamo-nts (FR-047 Phase 2–5).
+- The per-model settings reconciler — FR-048 (reserved only).
+
+## Cross-references
+
+- `__agent/feature-requests/FR-047-*.md`, `FR-048-per-model-agnostic-settings.md`
+- `documentations/guidelines/development/ai-per-model-settings.md`
+- dynamo-nts Phase 2+3 (agent-loop + OpenAI translator) — implemented in parallel.

package/__documentations/2026-06-01-fr047-fr048-code-review-findings.json

@@ -0,0 +1,159 @@
+{
+  "review_date": "2026-06-01",
+  "scope": {
+    "repo": "NPM-packages/dynamo-fsm",
+    "branch": "master",
+    "range": "HEAD~3..HEAD + uncommitted",
+    "commits": [
+      "08e8859 feat(ai): FR-047 P1 provider-agnostic function-calling vocabulary + per-model registry; FR-048 settings-schema reservation",
+      "de1da9b feat(ai): add adultContent (uncensored/NSFW) per-model capability",
+      "6a4ce9c fix(ai): FR-047 P5 — correct ./ai/google + ./ai/local subpath export targets"
+    ],
+    "files_changed_src_only": 30,
+    "insertions": 940,
+    "deletions": 12
+  },
+  "tool": {
+    "skill": "code-review",
+    "effort": "high",
+    "finder_angles": 7,
+    "verifier_votes_per_candidate": 1,
+    "candidate_raw_count": 31,
+    "candidate_after_dedup": 17,
+    "candidates_confirmed": 12,
+    "candidates_plausible": 4,
+    "candidates_refuted": 1,
+    "output_cap": 10
+  },
+  "findings": [
+    {
+      "rank": 1,
+      "verdict": "CONFIRMED",
+      "severity": "correctness",
+      "file": "src/_modules/ai/_modules/open-ai/_enums/oai-model.enum.ts",
+      "line": 19,
+      "summary": "gptImage_1 = 'gpt-image-1' enum-entry (commented as 'current') has no matching DyFM_OAI_Models registry entry",
+      "failure_scenario": "modelSupportsTools(DyFM_OAI_Models, DyFM_OAI_Model.gptImage_1) returns false via the `?? false` default; findModelInfo returns undefined — image generation routed via tools path silently skipped"
+    },
+    {
+      "rank": 2,
+      "verdict": "CONFIRMED",
+      "severity": "correctness",
+      "file": "src/_modules/ai/_modules/anthropic/_enums/aai-model.enum.ts",
+      "line": 11,
+      "summary": "claude_3_5_sonnet_latest in enum but NOT in DyFM_AAI_Models registry (only 3 GA entries registered)",
+      "failure_scenario": "Default DyFM_AI_CallSettings using claude_3_5_sonnet_latest → modelSupportsTools returns false → tool-calling silently disabled on a still-live API model"
+    },
+    {
+      "rank": 3,
+      "verdict": "CONFIRMED",
+      "severity": "correctness",
+      "file": "src/_modules/ai/_modules/google-ai/_enums/gai-model.enum.ts",
+      "line": 11,
+      "summary": "gemini_1_5_pro_latest (legacy) in enum but NOT in DyFM_GAI_Models registry",
+      "failure_scenario": "findModelInfo(DyFM_GAI_Models, gemini_1_5_pro_latest) returns undefined → callers assuming default model lookup always succeeds break on legacy code paths"
+    },
+    {
+      "rank": 4,
+      "verdict": "CONFIRMED",
+      "severity": "correctness",
+      "file": "src/_modules/ai/_collections/ai-model-registry.util.ts",
+      "line": 27,
+      "summary": "modelSupportsTools silently defaults to false for unknown/typo/deprecated model IDs — no warn or log",
+      "failure_scenario": "Consumer passes typo or live-but-unregistered model → returns false → tool routing silently dropped with no diagnostic; bug invisible until runtime tool-flow fails"
+    },
+    {
+      "rank": 5,
+      "verdict": "CONFIRMED",
+      "severity": "correctness",
+      "file": "src/_modules/ai/_modules/anthropic/_enums/aai-model.enum.ts",
+      "line": 5,
+      "summary": "Legacy/retired model IDs mixed with active ones in same enum, distinguished only by code comments (applies to aai/gai/oai enums)",
+      "failure_scenario": "Consumer code uses an enum entry that looks valid (it's in the enum public API) but is registry-missing → silent miss; no enum-level segregation between 'active' and 'deprecated' tiers"
+    },
+    {
+      "rank": 6,
+      "verdict": "CONFIRMED",
+      "severity": "correctness",
+      "file": "src/_modules/ai/_models/ai-message.interface.ts",
+      "line": 6,
+      "summary": "DyFM_AI_Message.content is required (non-optional string); when role='assistant' + toolCalls populated, content is semantically empty per OpenAI/Anthropic/Gemini specs",
+      "failure_scenario": "Callers must hard-code `content: ''` workaround on every tool-call message; downstream validation may reject valid tool-request messages"
+    },
+    {
+      "rank": 7,
+      "verdict": "CONFIRMED",
+      "severity": "correctness",
+      "file": "src/_modules/ai/_models/ai-model-info.interface.ts",
+      "line": 37,
+      "summary": "settingsSchema?: DyFM_AI_ModelSettingsSchema reserved on every model but populated on ZERO of the 21 registry entries — ghost contract",
+      "failure_scenario": "Phase 2 reconciler reading settingsSchema sees undefined → treats as 'no constraints' instead of 'constraints not yet modeled'; silently accepts temperature/topP on Opus 4.7+ which hard-fails HTTP 400"
+    },
+    {
+      "rank": 8,
+      "verdict": "PLAUSIBLE",
+      "severity": "correctness",
+      "file": "src/_modules/ai/_models/ai-llm-response.interface.ts",
+      "line": 16,
+      "summary": "Both legacy finishReason and new stopReason fields present; no doc marks authoritative source",
+      "failure_scenario": "Provider translator populates only stopReason; legacy consumer checks finishReason === 'tool_use' → condition fails silently → tool flow not triggered"
+    },
+    {
+      "rank": 9,
+      "verdict": "PLAUSIBLE",
+      "severity": "altitude",
+      "file": "src/_modules/ai/_models/ai-tool.interface.ts",
+      "line": 1,
+      "summary": "New tool-vocab interfaces (DyFM_AI_Tool, ToolCall, ToolResult, ToolHandler) exported but ZERO callers in dynamo-fsm — abstraction unverified for FR-048",
+      "failure_scenario": "Shape may not fit all 5 providers (OpenAI type:'function' wrapper, Anthropic input_schema, Gemini functionDeclarations); mismatch discovered in Phase 2 forces API redesign mid-flight"
+    },
+    {
+      "rank": 10,
+      "verdict": "CONFIRMED",
+      "severity": "removed-behavior",
+      "file": "pipeline.cicd.config.json",
+      "line": 1,
+      "summary": "Uncommitted root-level pipeline.cicd.config.json deletion (-128 lines) — .dynamo/pipeline.cicd.config.json must fully cover before commit",
+      "failure_scenario": "Any external workflow / GitHub Actions / script with hardcoded './pipeline.cicd.config.json' reference 404s; the dmc migration covers the runner CI path but not stale external references"
+    }
+  ],
+  "dropped_below_cap": [
+    {
+      "file": "src/_modules/ai/index.ts",
+      "summary": "No meta-barrel aggregating the 5 provider model-registries → Phase 2 must hardcode 5 imports",
+      "severity": "altitude"
+    },
+    {
+      "file": "src/_modules/ai/_models/ai-model-capabilities.interface.ts",
+      "summary": "Capability matrix (9 fields) copy-pasted across 21 models in 5 const-files → N+1 edits required",
+      "severity": "reuse"
+    },
+    {
+      "file": "src/_modules/ai/_models/ai-model-capabilities.interface.ts:31",
+      "summary": "adultContent is a POLICY flag mixed into the FEATURE capability matrix — future policy flags scatter ad-hoc",
+      "severity": "altitude"
+    },
+    {
+      "file": "package.json",
+      "summary": "Naming inconsistency: anthropic (no hyphen) vs open-ai/google-ai/local-ai/fdp-ai → invites future export-path typos",
+      "severity": "altitude"
+    },
+    {
+      "file": "src/_modules/ai/_collections/ai-model-registry.util.ts:17",
+      "summary": "findModelInfo uses Array.find O(N) on every call; tool-routing + capability check = 2× O(N) per request",
+      "severity": "efficiency"
+    },
+    {
+      "file": "src/_modules/ai/_modules/{provider}/index.ts (×5)",
+      "summary": "Barrel exports *-models.const full registry → consumer wanting only enum bundles all const-tables (~519 lines, ~8-12 kB)",
+      "severity": "efficiency"
+    }
+  ],
+  "refuted": [
+    {
+      "candidate": "oai-models.const.ts:235 gptImage_2 missing maxOutputTokens",
+      "reason": "maxOutputTokens? is optional on DyFM_AI_ModelInfo (line 52); no type-level contract violation, no crash guarantee on undefined access"
+    }
+  ],
+  "structural_root_cause": "Top-10 findings #1-5 all symptoms of one structural mismatch: enum-entries and registry-entries are NOT in sync. Mitigation options: (A) move legacy entries to *-legacy.enum.ts, (B) add { strict: true } mode to modelSupportsTools, (C) build-time TS guard test verifying every enum-tag has a registry-entry. Any combination addresses #1-5 + #11 (meta-barrel) in a single follow-up commit."
+}

package/__documentations/2026-06-01-fr047-fr048-code-review.md

@@ -0,0 +1,153 @@
+# 2026-06-01 — Code Review: FR-047 + FR-048 (provider-agnostic AI vocabulary)
+
+## Summary
+
+Code review futott a `dynamo-fsm` master branchen az utolsó 3 commit-ra (FR-047 + FR-048) + 1 uncommitted root pipeline-config deletion-re. Az effort-szint **high**: 7 finder angle × ≤6 candidate → 1-vote verify (recall-biased) → top-10 finding.
+
+### Scope
+
+- **Range**: `HEAD~3..HEAD` (master, no upstream divergence)
+- **Commits**:
+  - `08e8859` feat(ai): FR-047 P1 provider-agnostic function-calling vocabulary + per-model registry; FR-048 settings-schema reservation
+  - `de1da9b` feat(ai): add adultContent (uncensored/NSFW) per-model capability
+  - `6a4ce9c` fix(ai): FR-047 P5 — correct ./ai/google + ./ai/local subpath export targets
+- **Uncommitted**: `pipeline.cicd.config.json` (root) -128 sor delete (dmc migracio takaritas)
+- **Source-diff stat**: 30 fajl, 940 inserciol / 12 deletes (build/ artifact kizarva)
+
+### Tool
+
+A `/code-review` skill (high effort), local execution. Phase 1 — 7 párhuzamos finder agent (Explore type):
+- **3 correctness angle**: line-by-line scan, removed-behavior auditor, cross-file tracer
+- **3 cleanup angle**: reuse, simplification, efficiency
+- **1 altitude angle**: depth check
+
+Phase 2 — 1-vote verifier batch agent (recall-biased), 17 candidate → 16 survivor (1 REFUTED).
+
+## Top-10 Finding (ranked most-severe first)
+
+A teljes JSON output `__documentations/2026-06-01-fr047-fr048-code-review-findings.json`-ben. Itt a Hunglish summary:
+
+### 1. `gptImage_1` enum-entry registry-mentes (CONFIRMED)
+
+**Fajl**: `src/_modules/ai/_modules/open-ai/_enums/oai-model.enum.ts:19`
+
+A `DyFM_OAI_Model.gptImage_1 = 'gpt-image-1'` enum-ben szerepel + komment szerint **"current"** (nem deprecated), de a `DyFM_OAI_Models` registry-ben NEM kap entry-t.
+
+**Failure scenario**: `modelSupportsTools(DyFM_OAI_Models, DyFM_OAI_Model.gptImage_1)` → false (a util `?? false`-szal default-ol). `findModelInfo` undefined. Az image generation tools-on-keresztul rutalas silent-skip.
+
+### 2. `claude_3_5_sonnet_latest` enum + nincs registry (CONFIRMED)
+
+**Fajl**: `src/_modules/ai/_modules/anthropic/_enums/aai-model.enum.ts:11`
+
+A `DyFM_AAI_Models` registry csak 3 GA entry-t tartalmaz; a deprecated `claude_3_5_sonnet_latest` az enum-ben van, registry-bol kimaradt.
+
+**Failure scenario**: Default `DyFM_AI_CallSettings` ami a `claude_3_5_sonnet_latest`-et hasznalja → `modelSupportsTools` false → tool-calling silent-disable egy meg-mindig-elo API modelen.
+
+### 3. `gemini_1_5_pro_latest` enum + nincs registry (CONFIRMED)
+
+**Fajl**: `src/_modules/ai/_modules/google-ai/_enums/gai-model.enum.ts:11`
+
+Ugyanaz a minta mint #2 — google oldalon.
+
+### 4. `modelSupportsTools` silent-false unknown-ID-ra (CONFIRMED)
+
+**Fajl**: `src/_modules/ai/_collections/ai-model-registry.util.ts:27`
+
+`Array.find()` → `?? false` minta. Tipo, deprecated, vagy live-but-unregistered model esten → `false` warn/log nelkul.
+
+**Failure scenario**: Diagnozis nelkul lehetetlen kideriteni miert nem hivodik a tool-routing. Egy `{ strict: true }` mode vagy `DyFM_Log.warn` flegging hianyzik.
+
+### 5. Legacy + active enum-tagok keveredtek (CONFIRMED)
+
+**Fajlok**: `aai/gai/oai-model.enum.ts`
+
+Csak komment kulonbozteti meg az active es retired model-ID-kat. Az enum public API-jaban mindketto egyformanak latszik. A #1-3 ennek tuneti megnyilvanulasa.
+
+**Tervezet fix**: `*-legacy.enum.ts` kulon fajl, vagy minden retired enum-tag mellé `@deprecated` JSDoc tag.
+
+### 6. `DyFM_AI_Message.content` required, de tool-calls esetn ures (CONFIRMED)
+
+**Fajl**: `src/_modules/ai/_models/ai-message.interface.ts:6`
+
+`content: string` (non-optional). Mikor `role='assistant'` + `toolCalls` populalva → a content semantically ures OpenAI/Anthropic/Gemini API-knal.
+
+**Failure scenario**: Caller hard-coded `content: ''` workaround minden tool-call message-en; downstream "content empty" validator visszadobhatja a tool-request message-eket.
+
+### 7. `settingsSchema` ghost contract (CONFIRMED)
+
+**Fajl**: `src/_modules/ai/_models/ai-model-info.interface.ts:37`
+
+`settingsSchema?: DyFM_AI_ModelSettingsSchema` reserved minden modelen, de a 21 registry entry kozul EGYIK SEM populalja.
+
+**Failure scenario**: Phase 2 (FR-048) reconciler reading `settingsSchema` undefined → "no constraints" semantikat olvas a "constraints not yet modeled" helyett → silent-accept `temperature` parameter Opus 4.7+ hivason → HTTP 400 hard-fail.
+
+### 8. `finishReason` vs `stopReason` dual-field (PLAUSIBLE)
+
+**Fajl**: `src/_modules/ai/_models/ai-llm-response.interface.ts:16`
+
+Mindketto optional. Legacy `finishReason` + new `stopReason`. Doc-mentes melyik az authoritative.
+
+**Failure scenario**: Provider translator csak `stopReason`-t populalja → legacy consumer `finishReason === 'tool_use'`-t check-el → condition false → tool flow miss.
+
+### 9. Tool-vocab interfaces 0-caller (PLAUSIBLE)
+
+**Fajl**: `src/_modules/ai/_models/ai-tool.interface.ts`
+
+Uj `DyFM_AI_Tool`, `DyFM_AI_ToolCall`, `DyFM_AI_ToolResult`, `DyFM_AI_ToolHandler` exportalt **dynamo-fsm-bol**, de **ZERO caller** sajat-projekten belul. Az abstrakcio nem validalt.
+
+**Failure scenario**: A shape lehet hogy nem fer ra a 5 provider mind-egyikere (OpenAI `type:'function'` wrapper, Anthropic `input_schema`, Gemini `functionDeclarations`). FR-048 mid-flight API redesign-kenyszer.
+
+### 10. Root pipeline.cicd.config.json -128 sor (CONFIRMED, uncommitted)
+
+**Fajl**: `pipeline.cicd.config.json` (root, delete)
+
+A `.dynamo/pipeline.cicd.config.json` fully fedi, DE barmely external workflow / GitHub Actions / script ami hardcoded `./pipeline.cicd.config.json` ref-fel → 404.
+
+## Levágott (cleanup-class — kovetkezo iteracio)
+
+A skill rule: "Correctness bugs always outrank cleanup and altitude findings when the output cap forces a cut." Ezert a top-10 keret felett kihagyott 6 valid finding:
+
+| # | Fajl | Issue |
+|---|---|---|
+| 11 | `src/_modules/ai/index.ts` | No meta-barrel a 5 provider model-registry-re; Phase 2 hardcodes 5 imports |
+| 12 | `ai-model-capabilities.interface.ts` + 5 const-fajl | Capability matrix copy-paste 21 model × 9 mező — N+1 edit kotelezo |
+| 13 | `ai-model-capabilities.interface.ts:31` | `adultContent` policy-flag feature-capabilities matrix-ban; jovobeli policy flags scatterolnek |
+| 14 | `package.json` exports | Naming inconsistency: `anthropic` (no hyphen) vs `open-ai/google-ai/local-ai/fdp-ai` |
+| 15 | `ai-model-registry.util.ts:17` | O(N) `Array.find` registry lookup vs O(1) Map |
+| 16 | Provider `index.ts` (×5) | Tree-shake loss: barrel pulls all 5 const-tables (~519 lines) for single-provider consumer |
+
+## REFUTED (1 db)
+
+| # | Fajl | Reason |
+|---|---|---|
+| - | `oai-models.const.ts:235` gptImage_2 missing maxOutputTokens | Verified: `maxOutputTokens?` optional a `DyFM_AI_ModelInfo` interface-en, no type-level contract violation, no crash |
+
+## Strukturalis tanulsag (kozos pattern a #1-5 mogott)
+
+A top-10 elso 5 finding mind UGYANARRA a strukturalis hiba-mintara mutat: **az enum-tagok es a registry-entries nincsenek szinkronban**. Tervezet javitas:
+
+**Opció A** (defensive): minden enum-entry-nek legyen registry-entry, deprecated-eket `*-legacy.enum.ts`-be kulonitsd el.
+
+**Opció B** (strict-mode): `modelSupportsTools(models, id, { strict: true })` — unknown ID-ra throw vagy `DyFM_Log.warn`.
+
+**Opció C** (build-time validation): TS guard-test ami compile-time verifikalja hogy minden enum-tag registry-entry-vel jar.
+
+Mind a 3 megoldhato — a #1-5 + #11 (meta-barrel) kombo eseten egy follow-up commit lefedi.
+
+## Stat
+
+| | |
+|---|---|
+| **Specs** | 1302 spec / 0 failure (TypeScript + jasmine) |
+| **TS compile** | ✓ (0 error) |
+| **Diff scope** | 30 src fajl / 940 ins / 12 del (build/ kizarva) |
+| **Finder agents** | 7 (parallel) |
+| **Verifier agents** | 1 (batch over 17 candidates) |
+| **Output cap** | 10 finding (skill default) |
+| **Time** | ~15 min full pipeline |
+
+## Reference
+
+- Skill: `code-review` (high effort)
+- Skill instrukciok: 3 correctness + 3 cleanup + 1 altitude angle × ≤6 candidates per angle; 1-vote verify per candidate; recall-biased PLAUSIBLE default; REFUTED only constructible from code
+- Workflow: lokal jasmine `npx jasmine --config=spec/support/jasmine.json` → 1302/0