# Generated by tools/gen_stubs.py from the package source. Do not edit.
# `make stubs` regenerates; test/test_stubs.py refuses any difference.
"""Writing facts into a DKE store, correctly, for kinds this file never heard of.

A fact producer has two halves. One READS a world and knows a domain: what a
function is, what a row of a CSV means, which column is the identity. The other
turns whatever was read into a DKE Python program that records it. Only the
first is domain-specific, and this module is the second, with `code`'s
vocabulary removed: nothing here names a Function, a Call or a Dependency.

WHY IT IS ITS OWN FILE. The parts below are the ones that are easy to get
subtly wrong, and wrong in the direction that does not announce itself. A
broken reader produces no facts, which is loud. A broken fact-writer produces
PLAUSIBLE facts: every query still answers, and the answers are wrong. Two of
the three disciplines here were paid for by a defect that shipped
(`update` vs `remember`; a subject that moves between runs), so they live once,
are guarded once, and cannot drift per producer.

THE THREE DISCIPLINES, in the order they bite:

1. A SUBJECT MUST NOT MOVE between runs. `Ids` mints one identifier per
   qualified name, the same one every time, and disambiguates the collision
   that sanitizing creates rather than letting two things share a subject. A
   subject that moves silently corrupts every query that joined on it.

2. THE WRITE VERB IS `update`, NOT `remember`. See `FactProgram.put`.

3. A LOAD SAYS WHETHER IT FINISHED. See `open_load`/`close_load`. DKE commits
   per claim, so a load that stops part-way leaves a store that looks coherent
   and is missing rows, and every query answers from it with full confidence.
   The marker is what makes an interrupted load DETECTABLE rather than merely
   recoverable.

4. AN OPTIONAL CELL IS NEVER WRITTEN AS AN EMPTY STRING. A rule that reads the
   ABSENCE of a cell is silenced by a value stored everywhere, even a falsy
   one. This module cannot enforce that — only the caller knows which cells its
   rules read by absence — but `table()` is shaped so the row can carry a
   placeholder while the write stays conditional, which is what makes the
   discipline expressible at all.

Nothing here talks to the network and nothing spawns a process. `test_ingest.py`
asserts that over every module the package ships rather than over a named list,
with one exemption — `dke.client`, which exists to talk to the wire — and the
exemption is checked in both directions, so it cannot outlive its reason. What
matters for this file is unchanged and is asserted separately: nothing the
producing half imports reaches that module, so writing facts still needs no key."""

import hashlib

def sanitize(name: str) -> str:
    """A qualified name reduced to one identifier.

    A store subject is a single identifier, so `pkg.mod.func` cannot be a
    subject as written. Every character that is not a letter, digit or
    underscore becomes an underscore. That is lossy — `a.b` and `a_b` both
    become `a_b` — so `Ids` below detects the collision and disambiguates
    rather than letting two distinct names share one subject."""
    ...

class Ids:
    """Qualified name → stable, unique subject id.

    Stable across runs: the same qualified name always yields the same id, so
    re-ingesting reconciles the existing cells instead of minting a second set
    beside them. Unique: when sanitizing collapses two distinct names onto one
    identifier, the loser takes a short hash of its true name rather than
    silently overwriting the winner."""
    def __init__(self) -> None:
        ...
    def get(self, qual: str) -> str:
        ...

class FactProgram:
    """A DKE Python program that records facts, assembled line by line.

    The caller supplies rows and says which cell each column goes to; this
    supplies the program around them — the import, the row-form loop, the
    write verb, and the string escaping.

    What it emits is a PROGRAM, not a definition: statements at top level that
    a store's `run` accepts as submitted. It wrapped its writes in an entry
    function until 2026-08-22, which meant `run` refused the output of every
    producer built on this and a caller had to compile the facts as a module
    and then invoke them — two steps, one of them leaving a module in the
    store that was never reasoning. Nothing needed the wrapper.

    Nothing here knows what a kind is FOR. `module` is the reasoning module
    whose kinds are being written into and `source` is the provenance every
    claim carries, and both are the caller's to choose."""
    def __init__(self, module: str, source: str='ingest') -> None:
        ...
    def comment(self, text: str='') -> None:
        """One comment line. An empty argument writes a bare `#`, which is what
        a paragraph break looks like in a generated header."""
        ...
    def open(self) -> None:
        """Emit the import. Everything written after this is a top-level
        statement of the program."""
        ...
    def q(self, s: str) -> str:
        """One string literal, escaped for the DKE Python source we emit."""
        ...
    def put(self, attr: str, value: str) -> str:
        """One cell write, as a line of the program.

        `update`, not `remember`, because `update` is the verb whose CONTRACT
        is what a re-running producer means. The Reference defines it as
        "supersedes the claim; establishes one on an empty cell" — replace my
        own earlier reading, and work the first time too. That is the whole of
        a producer's intent, stated rather than relied upon.

        `remember` is defined as "Permissive", and MEASURED 2026-08-21 on both
        the dev and production engines it is exactly that: writing a changed
        value to a cell this same source already wrote SUCCEEDS, and the
        transcript renders the call as `update`. So the older reason for this
        choice — that `remember` refuses on a re-assert and aborts the load at
        the first changed value — does not reproduce, on either stage, and is
        not repeated here. What survives is the better reason: a producer
        should ask for supersession by name instead of depending on another
        verb being lenient, and a reader of a generated program should be able
        to see which of the two was meant.

        Claims from OTHER sources are untouched either way — supersession is
        per-source — so nothing here resolves a conflict the store is holding.
        That is deliberate: a producer revises its own reading and has no
        standing to settle anyone else's."""
        ...
    def table(self, name: str, rows: list[str], body: list[str]) -> None:
        """A row list plus the loop that walks it.

        The claims travel as DATA, not as statements. A path segment naming a
        variable in scope resolves to that variable's VALUE, so the subject can
        come out of a row and one written `update` serves the whole table. The
        claims are identical either way; what changes is that the program stops
        growing with the input. Measured at 3,000 subjects × 3 fields, the row
        form is ~3.5x smaller as source — and the response is bounded rather
        than not, because the wire caps repeated executions of ONE line while N
        distinct written lines each keep their own transcript entry.

        Nothing is emitted for an empty table: `for r in []` cannot infer an
        element type, and a table with no rows has no claims to make."""
        ...
    def load_marker(self, key: str, stamp: int, kind: str='Load') -> None:
        """Record that this load STARTED, how many rows it means to write, and —
        only if it reaches the end — that it FINISHED.

        WHY A MARKER AT ALL. DKE commits per claim. A load that stops part-way —
        a dropped connection, a service restart mid-run, a refusal on some other
        slot — leaves a store holding a coherent-looking set of facts that is
        simply missing some, and every query answers from it confidently. In the
        case that produced this, the store held 1629 functions where the producer
        emitted 1798 while two other kinds still carried the PREVIOUS run's rows,
        so it read as neither ingest and said so nowhere. Re-running repairs it,
        because `put` writes `update`; but recoverable is not detectable, and
        nothing could tell you there was anything to recover.

        WHAT MAKES IT SOUND: the producer is trusted to say "I finished" and
        NEVER to say "I failed". The `completed` write is the LAST statement of
        the program, so an interrupted load is detected by the ABSENCE of its
        effect — and absence needs no cooperation from a run that has already
        died. The failure mode here was a producer that never got to say
        anything at all, which is exactly the case a completion-report design
        misses and this one catches.

        THE INTERRUPTION IS AT RUN TIME, NOT GENERATION TIME, which is why one
        call places both halves. The emitted program always contains both
        writes; what an interrupted load loses is the EXECUTION of the last one.
        So the ordering that matters is structural — `started` is inserted at the
        slot `open` recorded and `completed` is appended by `render` — and a
        caller cannot get it wrong by emitting one more table afterwards.

        WHY THE MARKER IS PER SOURCE, not per run. The question a reader asks is
        "did the last load of this source finish", so one subject per source
        answers it directly and does not grow without bound. An interrupted
        second run leaves `completed` holding the FIRST run's stamp, which is
        older than the `started` this writes — so the interrupted state is
        `completed < started` and nothing has to be deleted to express it. A
        first load that never finishes leaves no `completed` cell at all, which
        reads as `empty` and is the same answer.

        `declared` is counted from the rows `table` was given, not passed in: a
        number the caller states separately is a second copy of a fact the
        program already holds, and the two would eventually disagree. It is
        written UP FRONT, because its whole use is telling a reader how much an
        interrupted load was going to write — recorded at the end it would only
        ever describe loads that finished. It is also what distinguishes an
        interrupted load from one that legitimately wrote fewer facts because
        the source shrank: the second has `completed >= started` and a smaller
        `declared`, the first has neither.

        `stamp` is the caller's: any strictly increasing integer works, epoch
        milliseconds being the obvious one. It is a parameter rather than a call
        to the clock so a generated program is reproducible and a test can
        assert on its bytes.

        THE MARKER KIND IS UNQUALIFIED, and that is the one design choice worth
        the paragraph. Every other cell this class writes is prefixed with the
        module (`code.Function.…`). This one is not, because reading a
        module-qualified path REQUIRES importing that module — the compiler says
        so in as many words — and this marker exists to be read exactly when a
        load may have failed. Making "did the last load finish" depend on first
        loading the reasoning is backwards. It is also the right altitude: any
        fact producer has this problem, so the marker sits below every module
        rather than inside one.

        `kind` is a parameter for the cost that choice carries: an unqualified
        kind shares the store's top-level namespace, so a customer whose own
        module declares `Load` can move this out of the way. Nothing here can
        detect that collision, which is why the escape is a parameter rather
        than a promise."""
        ...
    def render(self) -> str:
        """The finished program.

        A reader that finds nothing still produces a program, and it should be
        one that runs and records nothing rather than one that fails to
        compile. At top level that needs no special case: the program is its
        import and no statements, which is valid and has no effects. It needed
        one while the writes sat inside an entry function, because an empty
        function body is a syntax error rather than a no-op."""
        ...