# Solution: Flash LLM core evaluation

## Выбранный подход

Один parameterized Comfy API workflow выполняет ровно один model call и
сохраняет raw string. TypeScript harness строит immutable request matrix,
генерирует prompts/workflows, хеширует входы и локально оценивает уже
сохранённые ответы. Provider не получает authority над rules, RNG, state или
event log.

## Архитектура и поток данных

```text
preregistered manifest
  -> role fixture + prompt template
  -> one OpenRouterLLMNode
  -> SaveText raw artifact
  -> SHA-256 + response metadata
  -> safe JSON boundary
  -> role-specific deterministic scorer
  -> human narration review + sequential billing audit
  -> derived scorecard
```

Scenario использует richer authoring contract. Intent и narration используют
runtime vertical-slice contracts. Между ними нет скрытого compiler/mapping:
это три независимые eval lanes.

## Структура прототипа

- `manifest.ts` — exact models/languages/roles/repeat/seed и request IDs.
- `prompts.ts` и `prompts/*.txt` — role fixtures и versioned instructions.
- `evaluation.ts` — Comfy workflow builder, safe parse и deterministic scorers.
- `run.ts` — `prepare`, `status` и `evaluate` CLI.
- `run.test.ts` — manifest, workflow, trust-boundary и scoring behavior.
- `artifacts/raw/` — immutable provider replies, optional telemetry,
  `manual-review.json` и `billing-audit.json` после разрешённого запуска.
- `artifacts/derived/` — versioned preflight manifests, run protocols, job logs
  и scorecards.

## Требования

- macOS или Linux с network access;
- Node.js 24.14.0 и npm 11.9.0;
- Codex CLI 0.145.0;
- зависимости root `package-lock.json`;
- authenticated official `comfy-cloud` MCP;
- Comfy `OpenRouterLLMNode` и `SaveText`;
- credits только после отдельного согласия на pre-registered matrix и soft cap.

## Установка

Из корня репозитория:

```bash
npm ci
```

## Запуск

Локальная подготовка, не расходующая credits:

```bash
node RnD/technical/2026-07-26-flash-llm-core-evaluation/prototype/run.ts prepare
```

Default CLI paths по-прежнему указывают на исторические preflight-v1/run-1
artifacts и не используются для новых correction runs. Default `evaluate`
читает `artifacts/raw/run-1`:

```bash
node RnD/technical/2026-07-26-flash-llm-core-evaluation/prototype/run.ts evaluate
```

Historical correction run-2 использовал отдельный preflight-v2: 8 paid
scenario+intent jobs и 4 byte-identical narration files из run-1. Позднейший
audit обнаружил answer leakage/false positives, поэтому его model-selection
вывод superseded.

Current run-3 использует protocol revision 3 и custom paths для подготовки и
оценки:

```bash
node --input-type=module -e '
import {
  evaluateSavedResponses,
  prepareEvaluation,
} from "./RnD/technical/2026-07-26-flash-llm-core-evaluation/prototype/run.ts";
await prepareEvaluation(
  "RnD/technical/2026-07-26-flash-llm-core-evaluation/artifacts/derived/preflight-v3",
);
await evaluateSavedResponses(
  "RnD/technical/2026-07-26-flash-llm-core-evaluation/artifacts/raw/run-3",
  "RnD/technical/2026-07-26-flash-llm-core-evaluation/artifacts/derived/run-3-scorecard.json",
);
'
```

Run-3 reruns all 12 provider cells; prior outputs не переиспользуются.
Parallel OAuth dry-run получил refresh-token race, после чего dry-run
повторялся строго последовательно. Paid execution был одним
`submit_batch` на 12 jobs, не sequential per-job billing workflow.

Scorecard schema `flash-core-eval-scorecard/v2` не может выдать strict `pass`,
пока:

1. все 12 raw responses не оценены;
2. все четыре narration cells не имеют human score `0`, `1` или `2` в
   `manual-review.json`, а выбранная модель не получила `2` на обоих языках;
3. `billing-audit.json` не содержит ровно 12 последовательных balance
   before/after records в порядке manifest и подтверждённую дельту не выше
   согласованных 15 credits.

Manifest schema v2 включает `protocolRevision: 3`, поэтому run-3 logical
`manifestHash`
`a758d221a63eb2f2600af570d8431764597bd8c3ae75d4960d94d8963e0ebfb8`
отличается от prior revisions. Полный preflight-v3 manifest SHA
`9780519911a6c7fc2ed3d6efacf292899a321d8156c0c36ec71ff3c553c2d8f3`
дополнительно связывает каждый prompt/workflow hash и является bundle
identity.

До scorer amendment canonical scorecard имел SHA-256
`08236755f6113150d5f24a8a13cf6457c7a96b8aebc16ac945a454b3fbbf2665`.
Его полные serialized bytes восстановлены после review в
`artifacts/derived/run-3-scorecard-pre-amendment.json`; hash совпадает с
зафиксированным до regeneration. Artifact помечен как byte-exact
reconstruction, а не original write-once snapshot.

Run-3 manual review и billing audit отсутствуют, поэтому scorecard остаётся
`inconclusive`. Agent semantic audit хранится отдельно и не является
`reviewerKind: "human"`.

Минимальные формы дополнительных raw artifacts:

```json
{
  "schemaVersion": "flash-core-eval-manual-review/v1",
  "manifestHash": "run-3 logical manifestHash",
  "reviewerKind": "human",
  "reviewedAt": "ISO-8601 timestamp",
  "scores": {
    "narration-request-id": 2
  }
}
```

```json
{
  "schemaVersion": "flash-core-eval-billing-audit/v1",
  "manifestHash": "run-3 logical manifestHash",
  "approvedAt": "ISO-8601 timestamp",
  "approvedCapCredits": 15,
  "jobs": [
    {
      "requestId": "manifest request id",
      "balanceBeforeCredits": 0,
      "balanceAfterCredits": 0,
      "checkedAt": "ISO-8601 timestamp"
    }
  ]
}
```

Значения баланса в примере показывают только тип поля, а не ожидаемый или
фактический расход.

## Тестирование

```bash
node --test RnD/technical/2026-07-26-flash-llm-core-evaluation/prototype/run.test.ts
npm run test:technical
npm run typecheck
npm run validate:technical
```

## Конфигурация

Секретов и environment variables нет. OAuth управляется Codex/Comfy MCP и не
сохраняется в study. Exact generation parameters находятся в immutable
manifest:

- `seed: 20260726`;
- `reasoning_effort: off`;
- один call на workflow.

`OpenRouterLLMNode` не exposes output-token cap; этот факт нельзя маскировать
как hard budget.

Preregistered cost protocol требовал live `get_billing_status` до первого
workflow run. Generation tools позднее стали доступны, но billing method в
текущем toolset отсутствовал; поэтому run-1/run-2/run-3 credit delta остаётся
Unknown, а наличие строки `enabled, OAuth` само по себе billing audit не
доказывает.

## Ограничения и безопасность

- Paid execution не запускается из unit tests или `npm run check`.
- Raw artifacts не содержат user data: только original test fixtures.
- JSON fences, prose around JSON и malformed shapes отклоняются.
- Model-proposed difficulty проверяется против fixed oracle; current runtime
  contract ещё не derives difficulty из trusted scenario policy.
- Narration получает actor projection и committed event, но runtime пока не
  имеет отдельной event-projection функции для произвольной аудитории.
- Balance polling — soft control, не atomic spend cap.
- Missing/invalid manual или billing evidence принудительно оставляет outcome
  `inconclusive`; nullable provider telemetry отдельно публикуется как Unknown.
- Run-3 logical hash включает protocol revision, а полный manifest file SHA
  дополнительно связывает prompt/workflow hashes.
- Scenario compiler доказывает structural graph validity, но не исполняет
  free-text exit predicates и не измеряет story coherence/host fit.
- Privacy check обнаруживает exact hidden tokens, но не translated/paraphrased
  leakage.
- Regex scorer не закрывает open-ended grounding hallucinations; agent semantic
  audit не заменяет human naturalness review.

## Условия переноса в production

Ни одна модель run-3 не прошла bilingual 6/6, поэтому provider winner не
выбран. Нужны multi-seed repeats, executable/coherence scenario evaluation,
semantic + human narration grounding, paraphrase-aware privacy corpus,
provider retry/error telemetry, hard output/cost control, event visibility
projection, trusted difficulty policy и authoring-to-runtime compiler. Перенос
оформляется отдельной production-задачей.