> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usedino.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Deterministic Engine

> How Dino produces reproducible results, same input, same output, every time.

Most API tools: run twice, get different results. Dino: run twice, get the same results.

This is not a marketing claim. It is an engineering constraint enforced across every module, every test, every release.

## Why Determinism Matters

API quality tools that produce flaky results get disabled. The pattern is always the same:

1. The tool reports 5 issues on Monday
2. The same tool reports 3 different issues on Tuesday;  nothing has changed
3. Team stops trusting the tool
4. Team turns off the tool in CI
5. API quality degrades silently

Dino breaks this cycle. If `dino scan` finds 3 issues today; it finds the same 3 issues tomorrow, unless your API has changed. When a new finding appears, it is genuinely new.

## How We Enforce It

<Steps>
  <Step title="Injectable Seams">
    No module in Dino calls `Date.now()`, `Math.random()`, or `setTimeout` directly. Every source of non-determinism is injected through explicit interfaces:

    * **Clock**: all timestamps are generated by an injectable clock. Test control time. Production uses the system clock. But the code never reaches for it directly.
    * **RandomSource**: any randomness flows through an injectable source. Tests use seeded random. Production uses crypto random.
    * **Timer**: timeouts and delays are handled by an injectable timer. Tests advance time without waiting.

    A bare `Date.now()` in any module is a CI failure.
  </Step>

  <Step title="Stable Fingerprints">
    Every finding has a fingerprint, a stable hash derived from the finding's content, not from when or where it was found.

    Same API state = same fingerprints. This means:

    * Diff between scans shows real changes, not noise
    * CI can gate on "new findings only" without false positives
    * Historical tracking works because identifiers are stable
  </Step>

  <Step title="Snapshot Pinning">
    Schema snapshots are immutable once captured. Diffs, lints, and changelogs compare against pinned baselines, not live re-fetches.

    This eliminates race conditions: your API changing between scan start and comparison.
  </Step>
</Steps>

## AI Reasoning Is Additive

<AccordionGroup>
  <Accordion title="The deterministic engine runs first">
    All findings, fingerprints, health scores, and diffs are computed before AI reasoning touches anything. The AI layer receives findings as input — it does not produce them.
  </Accordion>

  <Accordion title="AI enhances, never overrides">
    AI descriptions are additive metadata. They make findings easier to understand. They don't change what was found, how it was scored, or whether it passes a gate.
  </Accordion>

  <Accordion title="No AI = same findings">
    Disable AI reasoning entirely, or if the AI provider is down — Dino produces the same findings with the same fingerprints. You lose natural-language explanations. You keep everything else.
  </Accordion>
</AccordionGroup>

<Info>
  The `@dino/reasoning` package is optional. The core pipeline discovery, agent execution, catalogue, and report have zero AI dependencies.
</Info>

## What We Test For

<CardGroup cols={2}>
  <Card title="3,000+ tests" icon="flask-vial">
    Over 3,000 tests across 420+ suites. Unit, contract, integration, invariant, and fault injection.
  </Card>

  <Card title="False output is P0" icon="bug">
    A wrong-but-clean result —Dino reports "all clear" when issues exist —is our highest-priority bug class, treated as a production incident.
  </Card>

  <Card title="Test isolation" icon="shield">
    Every suite runs with `randomize: true`. The test order is shuffled on every run. Order-dependent tests fail in CI.
  </Card>

  <Card title="Boundary contracts" icon="file-contract">
    Critical modules have boundary-contract tests that verify behaviour at trust boundaries where input enters and output leaves.
  </Card>
</CardGroup>

### The False Output Problem

False output is the #1 defect class in API quality tools:

* Tool says your API handles nulls correctly. It does not.
* The tool says rate limiting is enforced. It is not.
* Tool says no breaking changes. There are three.

The result is worse than having no tool at all;  you end up with false confidence. We treat every false output as a P0 bug: regression testing, root-cause fix, recurrence verification.

<Note>
  We don't claim zero false outputs. We claim false output is our most aggressively hunted bug class. When you find one, file an issue, and we will treat it as urgent.
</Note>

## What This Means in Practice

Run `dino scan` today. Note the findings and fingerprints. Run it tomorrow without changing your API. You get:

* Same number of findings
* Same fingerprints
* Same health scores
* Same report structure

Change one field, add a nullable argument, deprecate a mutation, and remove a type. Run again:

* Same findings for everything that didn't change
* New findings only for the parts that changed
* A clean diff showing exactly what's different

Same input, same output. Different input, precisely different output.