# Generated from the package source. Do not edit.
"""What produced a result, written as facts for the `quantum` module.

A result computed outside the store is recorded as a `quantum.Result` that
names the circuit it is about, the circuit it came from and the device it was
computed for, each with the digest its producer read, and the producer, its
settings, its seed and the outcome. The module's rules then conclude whether
the result still holds against what the store holds.

DIGESTS. The store compares digests and never computes one, so every digest is
written here, and each is the SHA-256 of the exact text it names:

- `text_digest`: a circuit's text, as it was written into the store. For a
  source or compiled circuit that is its OpenQASM 2.0; for a circuit you run
  as a list of steps, those steps as `steps_text` writes them.
- `snapshot_digest`: a calibration snapshot, which is two files. Each file's
  name and digest are hashed together, in name order, so a snapshot's digest
  can be checked against the SHA-256 sums of its two files.
- `code_version`: the code that produced a result, as each file's name and the
  start of its digest.

A digest is the writer's to keep true. Whoever rewrites a circuit's gates writes
its digest again in the same program.

NAMES. A circuit the store holds only as a digest — a source a compiler was
given, a circuit you ran as steps — is named by its digest (`digest_name`), so
two different circuits never share a name and one circuit two writers name is
one subject. Named by its writer instead, as `c0`, two writers' `c0` would be
two circuits under one name: each writer's `update` keeps its own digest, the
field holds both, and every result that reads either stops holding. A compiled
circuit keeps its writer's label, since its gates name it."""

import hashlib
import json
import pathlib
from dataclasses import dataclass
FIELDS: ...

def text_digest(text: str) -> str:
    ...

def digest_name(digest: str) -> str:
    """The subject a circuit known only by its digest is named: `c_` and the
    digest's first 16 hex digits."""
    ...

def steps_text(steps: list[list]) -> str:
    """A circuit of steps as one line of JSON, which is the text its digest is of."""
    ...

def snapshot_digest(directory: pathlib.Path) -> str:
    ...

def code_version(*paths: pathlib.Path) -> str:
    ...

@dataclass
class Result:
    """One result, as the fields `quantum.Result` holds. A field left None is
    not written, never as a placeholder: an absent field is what the rules read
    as a result naming no source or no device."""
    circuit: str
    digest: str
    outcome: str
    source: str | None = None
    source_digest: str | None = None
    device: str | None = None
    device_digest: str | None = None
    producer: str | None = None
    settings: str | None = None
    seed: int | None = None

def lines(module: str, name: str, r: Result, writer: str) -> list[str]:
    """The DKE Python lines that record result `name`, through `writer`."""
    ...

def circuit_line(module: str, circuit: str, digest: str, writer: str) -> str:
    """The line that records a circuit's digest."""
    ...