@futdevpro/fsm-dynamo 1.15.21 → 1.15.22

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

@@ -1,159 +0,0 @@
-{
-  "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."
-}