@vostride/agent-qa-knowledge-local 0.0.0-stage → 0.2.1

package/dist/mark-evidence-plan-BCkYN07i.d.cts

@@ -0,0 +1,1014 @@
+import { EmbeddingProfile, QuarantineLedgerEvent, QuarantineEntryState, VerdictClass, Verdict, RecordFrontmatter, BundleManifest, BundleProvenance, BundleRelations, BundleOutcomeEvent, ArtifactsIndex, ScreenState, MeasurementBaseline, MeasurementObservation, TrustPriorTable, DerivedTrustState, GateLine, RecordId, Anchor, BundleStatus, ScopeKey, IndexEntry, AuthoringBrief, ServedRetrievalTraceV1, InspectFilter, InspectRecordView, RecordChange, KnowledgeRecordShowResult, GateReceipt, EvidenceToken, MarkReceipt, CompletedRunHandoff } from '@vostride/agent-qa-schema';
+import { AuthoringReadPort } from '@vostride/agent-qa-agent';
+import { KnowledgeHintReader } from '@vostride/agent-qa-runner';
+import { DatabaseSync } from 'node:sqlite';
+
+/**
+ * D-02's types-only memidex embedding seam from memory.md §5.2.
+ *
+ * Phase 376 binds the real implementation without changing rebuild logic. The fake embedder in
+ * Phase 375 Plan 06 is the first implementer, keeping this phase free of model runtime code.
+ */
+interface EmbedderPort {
+    /**
+     * Embed a canonical document rendering using the profile's document prefix (D-02, §5.2).
+     * Phase 376 supplies the runtime; callers never observe prefix application.
+     */
+    embedDocument(rendering: string): Promise<Float32Array>;
+    /**
+     * Embed a query rendering using the profile's query prefix (D-02, §5.2).
+     * Phase 376 supplies the runtime through the same rebuild-logic-neutral contract.
+     */
+    embedQuery(rendering: string): Promise<Float32Array>;
+}
+
+declare const INDEX_DB_FILE = "knowledge.db";
+/** Any other stamp resets the index. */
+declare const INDEX_SCHEMA_VERSION = 2;
+/**
+ * Phase 377 D-04 rendering epoch.
+ *
+ * Bump only when contextual-rendering bytes change. A stale stamp remains durable through writer
+ * open, forces one full render/vector pass, and is advanced only when that pass succeeds.
+ */
+declare const INDEX_RENDERING_SCHEMA_VERSION = 2;
+/**
+ * Projection tables every readable index must expose.
+ *
+ * Per-profile vec tables are deliberately excluded: vec0 is a conditional
+ * capability, while operation-time failover and the next rebuild heal a lost
+ * capability-specific table.
+ */
+declare const REQUIRED_INDEX_TABLES: readonly ["records", "fts_records", "anchors", "graph_nodes", "graph_edges", "meta"];
+/**
+ * Writer busy timeout in milliseconds.
+ *
+ * PROVISIONAL 2000 pending Phase 375 contention measurements. The value may be
+ * tuned, but the constant-driven shape remains internal and config-free.
+ */
+declare const WRITER_BUSY_TIMEOUT_MS = 2000;
+/**
+ * Reader busy timeout in milliseconds.
+ *
+ * PROVISIONAL 500 pending Phase 375 contention measurements. The value may be
+ * tuned, but the constant-driven shape remains internal and config-free.
+ */
+declare const READER_BUSY_TIMEOUT_MS = 500;
+/**
+ * Number of committed bundles between passive WAL checkpoints.
+ *
+ * PROVISIONAL 32 pending Phase 375 write-volume measurements. The value may be
+ * tuned, but the constant-driven shape remains internal and config-free.
+ */
+declare const CHECKPOINT_EVERY_N_BUNDLES = 32;
+type VecCapability = 'vec0' | 'brute';
+interface IndexWriterHandle {
+    db: DatabaseSync;
+    vec: VecCapability;
+    readonly renderingEpochStale: boolean;
+    completeRenderingEpoch(): void;
+    checkpointPassive(): void;
+    close(): void;
+}
+interface IndexReaderConnection {
+    db: DatabaseSync;
+    vec: VecCapability;
+}
+/** Durable writer work that can be inspected without opening a mutable index connection. */
+interface IndexMaintenanceState {
+    indexAbsent: boolean;
+    pendingEmbeddings: number;
+    renderingEpochStale: boolean;
+    vectorReconciliationOutstanding: boolean;
+}
+type IndexHealth = {
+    ok: true;
+} | {
+    ok: false;
+    probe: 'quick-check' | 'projection-schema' | 'schema-version';
+    reason: string;
+};
+interface IndexOpenOptions {
+    /** D-12 test seam. Production callers resolve sqlite-vec's pinned prebuild. */
+    vecLoadablePath?: string;
+}
+interface IndexReaderOpenOptions extends IndexOpenOptions {
+    /**
+     * For a probe that only ASKS about the index and releases the connection at once (`doctor`).
+     * With no `-wal` beside the database, no connection holds it in WAL mode and the writer's close
+     * checkpointed every page into the main file, so the open is `mode=ro&immutable=1` and SQLite
+     * creates no `-wal`/`-shm` (432-09 #5). With a `-wal` present the open is the ordinary read-only
+     * one, so a live writer's frames are still read. Serving readers never set it.
+     */
+    inspectCheckpointedImmutably?: boolean;
+}
+declare function indexDbPath(knowledgeRoot: string): string;
+/**
+ * Inspect bounded durable maintenance facts without bootstrapping, migrating, or restamping.
+ *
+ * Absence is a valid schedulable state. Once the database exists, malformed or incomplete
+ * projection schemas throw so callers cannot mistake an unreadable index for convergence.
+ */
+declare function readIndexMaintenanceState(knowledgeRoot: string): IndexMaintenanceState;
+declare function resolveVecCapability(db: DatabaseSync, loadablePath?: string): VecCapability;
+declare function vecTableName(profile: EmbeddingProfile): string;
+/** Stable identity persisted in meta and used to select a closed-list profile. */
+declare function embeddingProfileKey(profile: EmbeddingProfile): string;
+/**
+ * Resolve the one active profile authority from the derived index's meta stamp.
+ *
+ * This is RESEARCH Pattern 5 step 1: Plan 07 flips this stamp atomically. D-18
+ * keeps M2 selection closed to schema-owned constants, so absent, unknown, or
+ * pre-bootstrap metadata always falls back to the ratified default.
+ */
+declare function resolveActiveProfile(db: DatabaseSync): EmbeddingProfile;
+declare function openIndexWriter(knowledgeRoot: string, opts?: IndexOpenOptions): IndexWriterHandle;
+declare function openIndexReaderConnection(knowledgeRoot: string, opts?: IndexReaderOpenOptions): IndexReaderConnection;
+declare function probeIndexHealth(db: DatabaseSync): IndexHealth;
+
+/** The ledger's fixed name directly under the committed knowledge root — never caller-supplied. */
+declare const QUARANTINE_LEDGER_FILENAME = "quarantine.jsonl";
+/** One line the read refused, surfaced as data so a caller can print or audit it. */
+interface RefusedQuarantineLine {
+    /** 1-based, so it matches what an editor shows the human who has to fix the file. */
+    lineNumber: number;
+    reason: string;
+}
+interface QuarantineLedgerRead {
+    events: readonly QuarantineLedgerEvent[];
+    refusedLines: readonly RefusedQuarantineLine[];
+}
+/** The ledger's absolute path under one knowledge root. */
+declare function quarantineLedgerPath(knowledgeRoot: string): string;
+/**
+ * Read every event the committed ledger carries, in file order.
+ *
+ * A missing ledger is an EMPTY ledger — no test is quarantined and run behavior is byte-identical
+ * to pre-390 (the FLAK-03 empty-input edge). Blank lines are skipped silently; they are whitespace,
+ * not damage. Everything else that fails is refused and reported.
+ *
+ * Throws {@link QuarantineLedgerVersionError} (typed) when a line declares a schemaVersion this
+ * build cannot consume — committed truth hard-fails rather than degrading silently.
+ */
+declare function readQuarantineLedger(knowledgeRoot: string): QuarantineLedgerRead;
+/**
+ * Fold the event log into current per-entry state. PURE — identical `(events, now)` inputs answer
+ * identically, and no clock is read.
+ *
+ * Per key, in event order: `entered` opens (or re-opens — D-10's re-entry needs no special rule,
+ * the sliding window self-heals) a window carrying owner/expiry/fingerprint/class; `renewed`
+ * extends the expiry and claims the owner when one is supplied; either released kind closes it.
+ *
+ * TWO OF THE ANSWERED FIELDS ARE HISTORY, NOT WINDOW FACTS (390-18). `enteredCount` is how many
+ * `entered` events this key has accumulated — a renewal extends a window rather than opening one,
+ * so it never increments — and `firstEnteredAt` is the first of those events' instant. They are
+ * DERIVED here from bytes the log already holds: no new event kind carries them, no migration
+ * exists for them and {@link CURRENT_QUARANTINE_LEDGER_SCHEMA_VERSION} is unmoved by them. A
+ * reader meeting two new fields on a versioned artifact's state type will reasonably ask whether
+ * the file format moved; it did not, and every ledger written before this fold existed answers
+ * both questions correctly on its next read. This is the question D-03 chose an append-only log to
+ * make free, finally being asked.
+ *
+ * THE TWO INSTANTS ANSWER DIFFERENT QUESTIONS and their names are close enough to be a drift
+ * hazard, so: `enteredAt` is WHEN THIS WINDOW OPENED, which is the fact `expiresAt` and the
+ * computed state are about; `firstEnteredAt` is WHEN THIS TEST'S QUARANTINE HISTORY BEGAN, which
+ * is the fact a human triaging it needs (and the key `triageOrder` sorts on, so that a test on its
+ * seventh re-entry cannot present as the newest thing in the queue).
+ *
+ * A renewal can extend an OPEN window — quarantined or lapsed — but NEVER re-opens a CLOSED one
+ * (390-11 / WR-04). A release is the operator's decision, and re-entry has its own event:
+ * `operations.add` already routes a released entry to the `entered` branch, so honoring a `renewed`
+ * against a closed window would only ever resurrect a suppression a human deliberately ended. That
+ * case is reachable solely through the committed file's documented human-editability (D-12) — no
+ * code path authors it — which is exactly why the fold, not the verb, is where it has to be
+ * refused. The guard keys on the EVENT state, never the computed one: a lapsed entry still carries
+ * `eventState: 'quarantined'` (expiry is applied after this loop), so D-11's renew-an-expired-entry
+ * behavior is untouched.
+ *
+ * `'expired'` is then COMPUTED, never read from an event: an open window whose `expiresAt` is at or
+ * before `now` answers `'expired'`. Its suppression has stopped — the test fails builds again — and
+ * the entry stays LISTED, renewable and releasable (D-11).
+ *
+ * SCOPE OF THAT GUARANTEE, stated because it is narrower than it reads: the lapse ends THIS
+ * window, not the suppression. A fingerprint still crossing the threshold re-enters on the very
+ * next fold with a fresh full-lifetime deadline, so a permanently failing test costs one red build
+ * per lifetime and no human decision, indefinitely. Nothing in this fold or in the ladder bounds
+ * that repetition (measured 2026-08-06; pinned in `cli/src/__tests__/quarantine-lifecycle.e2e.test.ts`'s
+ * multi-cycle leg, and made legible to a human by plan 390-18's re-entry counter). What the lapse
+ * IS, honestly: a 30-day review cadence on an indefinitely renewable suppression.
+ *
+ * `now` is an ISO-8601 instant, compared on the same scale the events are stamped on.
+ */
+declare function foldQuarantineLedgerState(events: readonly QuarantineLedgerEvent[], now: string): QuarantineEntryState[];
+/** What an append answers: how many lines it wrote. */
+type QuarantineAppendOutcome = {
+    kind: 'appended';
+    lines: number;
+};
+
+/**
+ * Visibility floor (D-06): distinct occurrence ordinals at which a fingerprint becomes suspected
+ * flaky. Pinned, never config — retune from operational evidence in this source, where the change
+ * is reviewable.
+ */
+declare const QUARANTINE_FLAG_FLOOR = 2;
+/**
+ * `memory.md` §9.5's locked trigger, verbatim: the same fingerprint at three distinct ordinals
+ * inside the window escalates. Pinned constant with no config key (386 D-15) — retune it here.
+ */
+declare const QUARANTINE_ESCALATE_THRESHOLD = 3;
+/**
+ * D-10's exit: M consecutive PASSING distinct build ordinals release a quarantined test. Five is
+ * symmetric with the detection window by design (~17% escape odds for a 30%-failure flake) and sits
+ * inside LAST_OUTCOMES_LIMIT, so no window widening is needed. Retune from operational evidence.
+ */
+declare const QUARANTINE_AUTO_EXIT_PASSES = 5;
+/**
+ * D-11's default lifetime in days. On lapse suppression STOPS and the entry stays listed as
+ * `expired`.
+ *
+ * This is a REVIEW CADENCE, not a cap, and the difference is the fact somebody retuning the number
+ * most needs: a still-crossing fingerprint re-enters with a fresh `expiryFrom(now)` on the very
+ * next fold, indefinitely and with no attenuation. Measured over four full cycles (2026-08-06): 4
+ * `entered` lines, 4 distinct deadlines, 0 released, cycle 4 indistinguishable from cycle 1. So
+ * raising this number lengthens the gap between red builds; it does not change how many there
+ * eventually are. A human deadline in a human-reviewed file; retune from operational evidence,
+ * never from config.
+ */
+declare const QUARANTINE_DEFAULT_EXPIRY_DAYS = 30;
+/** What escalation does with a verdict class. */
+type QuarantineDisposition = 'auto-quarantine' | 'escalate-only';
+/**
+ * The class gate, as a TOTAL function over the closed verdict vocabulary (D-05).
+ *
+ * `satisfies Record<VerdictClass, QuarantineDisposition>` is the load-bearing part: adding a ninth
+ * member to VERDICT_CLASSES makes this object a compile error until its quarantine disposition is
+ * decided. A `Set` of three names would have compiled forever while silently treating every future
+ * class as escalate-only by accident rather than by decision.
+ */
+declare const QUARANTINE_CLASS_DISPOSITIONS: {
+    readonly flake: "auto-quarantine";
+    readonly environment: "auto-quarantine";
+    readonly timeout: "auto-quarantine";
+    readonly app_bug: "escalate-only";
+    readonly test_bug: "escalate-only";
+    readonly config_error: "escalate-only";
+    readonly llm_error: "escalate-only";
+    readonly unknown: "escalate-only";
+};
+/**
+ * Exactly `eval-and-core-types.md` §A9's A3 routing, DERIVED from the disposition table rather
+ * than spelled a second time (388 C13) — the set and the table can never disagree about a class.
+ */
+declare const AUTO_QUARANTINE_CLASSES: readonly VerdictClass[];
+/**
+ * Whether the deterministic floor may decide this KIND of failure AT ALL. Never sufficient on
+ * its own: since 390-19 the floor arm also requires the crossing's own `sameBuildPassAndFail`,
+ * so no class auto-quarantines on the floor's word alone. The pre-390-19 gloss on this line said
+ * otherwise and was the same false-reachability shape 390-25 removed from the corpus header.
+ */
+type QuarantineFloorEligibility = 'floor-eligible' | 'authored-required';
+/**
+ * The SECOND total table over the same closed vocabulary (390-16, G-390-3).
+ *
+ * The disposition table above answers "may this class ever auto-quarantine". It cannot answer the
+ * other question, because the answer is not a property of the class name: is the EVIDENCE behind
+ * the class a statement about THIS TEST, or about the run it happened to be in? This table answers
+ * that, and it is a table rather than `if (cls === 'environment' || cls === 'timeout')` for exactly
+ * the reason D-05 gave for the first one — a rule stated over a subset of its own input domain
+ * compiles forever while treating every future class as an accident. A ninth member of
+ * VERDICT_CLASSES is a compile error here until someone decides its floor eligibility.
+ *
+ * This table is ONE OF TWO CONJUNCTS on the floor arm since 390-19. It licenses a CLASS; the
+ * crossing's `sameBuildPassAndFail` supplies the per-test EVIDENCE. Neither alone may silence a
+ * failing test on the deterministic floor's word.
+ *
+ * Per class, with the reasoning that decides it:
+ *
+ *  - `timeout` → FLOOR-ELIGIBLE (re-decided by 390-19 / G-390-5, and the row that carries the LIVE
+ *    floor path). This row used to read authored-required because "exceeded the budget" is
+ *    per-test but semantically THIN — as consistent with an infinite spinner as with flakiness.
+ *    Thinness is exactly what a same-build pass∧fail cures: a test that passed and failed at the
+ *    same build ordinal is flaky by direct observation, whatever the budget did. So `timeout` may
+ *    now be decided on the floor's word PLUS the signature, and NEVER on the floor's word alone.
+ *  - `environment` → AUTHORED-REQUIRED, on its own merits, unchanged. Two of its three arms are
+ *    RUN-SCOPED probe reads (`baselineProbe.error !== undefined`, `baselineProbe.status >= 500`)
+ *    that fire before any per-test signal. One down staging dependency classifies every failing
+ *    member of a suite identically; the measured blast radius was 6 of 6 tests under one shared
+ *    30-day deadline. A flapping dependency produces same-build pass∧fail across MANY tests at
+ *    once, so the signature does not make a run-scoped observation per-test — read the branch-order
+ *    paragraph below before treating this row as the containment, because it is not.
+ *  - `flake` → FLOOR-ELIGIBLE on the class's own merits, AND THIS ROW DECIDES NOTHING. Say it out
+ *    loud, because G-390-5 exists precisely because a row nobody could reach was described as the
+ *    mechanism keeping FLAK-01 alive. `classifyRootCause` mints `flake` only inside its
+ *    `outcome === 'passed' || outcome === 'healed'` arm — the test LITERALLY passed on retry, so
+ *    the class IS the signature — but a member that passed carries no `failure` row
+ *    (`projection/run-outcomes.ts`'s `...(passed ? {} : { failure })` spread) and a
+ *    `QuarantineDetectionFailure` is built only from `test.failure`. So no crossing can carry class
+ *    `flake` AND producer `deterministic-classifier`: every `flake` crossing the pipeline can build
+ *    is authored, and is admitted by the FIRST disjunct. `timeout` is the row that is
+ *    reachable-and-deciding on the floor path; this one is correct and inert.
+ *  - THE FIVE ESCALATE-ONLY CLASSES → AUTHORED-REQUIRED. They never reach the auto-quarantine
+ *    branch today, so this value is not observable — which is precisely why it is the strict one.
+ *    It makes authored-required the DEFAULT for any future widening of the disposition table, so a
+ *    later one-line class flip cannot silently also license the floor (T-390-16-04).
+ *
+ * THE BRANCH-ORDER FACT THAT KILLS THE CLASS-BASED CONTAINMENT, measured at HEAD against
+ * `classifyRootCause` (`runner/src/run/root-cause.ts`). Its arms run in this order: the presence
+ * rule, then the `passed || healed` arm that mints `flake`, then the `outcome === 'timeout'` arm —
+ * WHICH RETURNS — and only THEN the `baselineProbe` reads that mint `environment`. So a hung or
+ * flapping staging dependency does NOT arrive classed `environment` for the members that blew their
+ * deadline: it arrives classed `timeout`, the class this table now licenses. The run-scoped
+ * objection stated on the `environment` row above applies VERBATIM to those `timeout` members.
+ *
+ * DRAW THE CONCLUSION HERE RATHER THAN LEAVING IT TO BE INFERRED: every class the floor can mint on
+ * a FAILING member (`timeout`, `environment`, `unknown`) is reachable from a RUN-SCOPED cause, so
+ * THIS TABLE CANNOT BE THE CONTAINMENT FOR MASS AUTO-QUARANTINE AND MUST NOT BE READ AS ONE.
+ * Keeping `environment` strict contains `environment`; it does not contain the hazard.
+ * QUARANTINE_FLOOR_AUTO_QUARANTINE_CAP does — a per-run COUNT, which is the form 390-16's
+ * motivating observation (one probe failure, 6 of 6 tests) actually took. A reader who inherits the
+ * older framing — that `environment` is THE run-scoped class and `timeout` is the per-test one —
+ * will re-derive exactly the defect this round closes: a true-sounding containment sentence about a
+ * path the code does not take.
+ *
+ * WHY NOT flip the disposition table instead. That is wrong in both directions: it would disable
+ * auto-quarantine for genuinely ANALYZED environment/timeout failures, and it would leave
+ * floor-minted `flake` firing. The consistent rule — the one 390-05 already ratified once when it
+ * made `unknown` escalate-only — is that a quarantine decision requires per-test EVIDENCE, and
+ * `producer` plus `sameBuildPassAndFail` are what make that rule expressible.
+ */
+declare const QUARANTINE_FLOOR_ELIGIBILITY: {
+    readonly flake: "floor-eligible";
+    readonly environment: "authored-required";
+    readonly timeout: "floor-eligible";
+    readonly app_bug: "authored-required";
+    readonly test_bug: "authored-required";
+    readonly config_error: "authored-required";
+    readonly llm_error: "authored-required";
+    readonly unknown: "authored-required";
+};
+/**
+ * One failed fingerprint this run contributed, with the recurrence the projection answered for it.
+ * Test identity travels beside the fingerprint because a crossing has to name the test it
+ * quarantines; the recurrence itself is keyed `(product, fingerprint)` (D-07).
+ */
+interface QuarantineDetectionFailure {
+    product: string;
+    filePath: string;
+    testName: string;
+    fingerprint: string;
+    verdictClass: VerdictClass;
+    /**
+     * WHICH pipeline authored `verdictClass` on the CROSSING run (390-16). The floor-eligibility
+     * gate reads this beside the class, because for some classes the class alone does not say
+     * whether the evidence is about this test or about the whole run.
+     *
+     * WHY THE CROSSING RUN'S PRODUCER, and not all three occurrence ordinals'. Gating on every
+     * ordinal in the window would need a new `producer` column on `run_fingerprint_windows` plus an
+     * index rebuild — cheap in itself, since L12 makes the projection a gitignored rebuildable
+     * derivation — but it is a strictly larger change that buys nothing: the crossing run is the one
+     * AUTHORING the `entered` line, so its evidence is the evidence the entry rests on. Recorded
+     * here so the next reader does not have to re-derive the choice (T-390-16-05, accepted).
+     */
+    producer: Verdict['producer'];
+    /**
+     * THE PER-TEST FLAKE SIGNATURE for this crossing (390-19 / G-390-5): did this test both pass and
+     * not pass at some ONE build ordinal? Computed by `hasSameBuildPassAndFail` over the per-test
+     * outcome window the projection already keeps (`run_test_outcomes`.`last_outcomes_json`), so it
+     * is read off bytes this phase computes rather than invented for the gate.
+     *
+     * REQUIRED, not optional, on purpose: `tsc --noEmit` then enumerates every construction site,
+     * which is the completeness oracle 390-16 did not have and the reason its widening shipped with
+     * an unreachable arm.
+     *
+     * ITS THREE HONEST BOUNDS, so nobody reads a set field as a stronger claim than it is:
+     *
+     *  1. The window is CAPPED at LAST_OUTCOMES_LIMIT entries, so this is "a same-build pass∧fail
+     *     within the recorded window", never "ever".
+     *  2. IT IS CONTEMPORANEOUS, and that bound is ENFORCED, not advisory (390-24, WR-05). The fold
+     *     hands this predicate only the outcomes inside `[windowFloor(buildOrdinal), buildOrdinal]`
+     *     — the crossing's OWN recurrence window, same floor `fingerprintRecurrence` counts over —
+     *     so a same-build pass∧fail OLDER than that window answers false by construction. A
+     *     since-fixed flake episode therefore cannot license the floor arm for a new hard
+     *     regression. The scope lives at the construction site (`run-outcomes.ts`), named below.
+     *  3. WHAT IT TAKES TO PRODUCE ONE IN THE REAL WORLD — this is not a common event. An in-run
+     *     RETRY does NOT produce it: the member-runner collapses retries into a single member
+     *     outcome and `countedOutcome` maps `healed` to a PASS, so one applied run leaves exactly
+     *     ONE entry per member. Two entries at one ordinal therefore require TWO SEPARATE APPLIED
+     *     RUNS carrying the same `handoff.buildOrdinal` — in practice a CI job re-run without an
+     *     ordinal bump. Every claim in this phase that the floor path is "live without an analysis
+     *     budget" is true only under that condition, and this phase has already overstated
+     *     reachability three times.
+     */
+    sameBuildPassAndFail: boolean;
+    /** DISTINCT build ordinals inside the window carrying this fingerprint. */
+    occurrenceOrdinals: number;
+    /** DISTINCT build ordinals inside the window carrying ANY failure — the honest denominator. */
+    windowOrdinals: number;
+}
+/** One recorded outcome, ordinal-keyed. Mirrors the projection's per-test outcome window entry. */
+interface QuarantineOrdinalOutcome {
+    buildOrdinal: number;
+    passed: boolean;
+}
+/** One quarantined test's recent outcome window — the auto-exit's only input. */
+interface QuarantineDetectionTestWindow {
+    product: string;
+    filePath: string;
+    testName: string;
+    /** May carry several entries per ordinal (two runs in one build); order is irrelevant. */
+    ordinals: readonly QuarantineOrdinalOutcome[];
+}
+interface EvaluateQuarantineDetectionInput {
+    failures: readonly QuarantineDetectionFailure[];
+    testWindows: readonly QuarantineDetectionTestWindow[];
+    /** The ledger folded against this same `now` — the suppression and exit input. */
+    entries: readonly QuarantineEntryState[];
+    /** ISO-8601 instant. The ONLY way wall clock enters this rule. */
+    now: string;
+}
+/** A crossing the caller must SHOW: flagged, or escalated-and-deliberately-not-quarantined. */
+interface QuarantineDetectionSighting {
+    product: string;
+    filePath: string;
+    testName: string;
+    fingerprint: string;
+    verdictClass: VerdictClass;
+    /**
+     * The crossing run's producer, carried onto the sighting so an operator can ACT on it — and
+     * RENDERED on the curation tail's withheld line since 390-22 / WR-03. Until then this docstring
+     * claimed the field existed so an operator could tell two causes apart on that line, and the
+     * field never reached the line: the claim was true of the shape and false of the operator. It is
+     * reduced here to what the render delivers.
+     *
+     * `escalatedNotQuarantined` has THREE distinct causes, and the producer separates the first two:
+     * a class that is never auto-quarantinable (run `analyze-run` and it still will not be), versus a
+     * class that would have been had a verdict been authored (run `analyze-run` and it will be).
+     * Those read identically on the curation tail's line unless the producer travels with the
+     * sighting.
+     *
+     * THE THIRD CAUSE, ADDED BY 390-19, AND THE FACT THAT THIS FIELD DOES NOT DISTINGUISH IT: the
+     * crossing was admissible on the floor arm but QUARANTINE_FLOOR_AUTO_QUARANTINE_CAP was already
+     * spent on this run. The information gap is bounded — an operator sees the withheld line either
+     * way, the build fails either way, and the identity crosses again on the next applied run — so no
+     * field is added to carry it, which would widen this shape and the cli render inside the very
+     * round that is closing a containment defect. Recorded as a STATED RESIDUAL instead, because a
+     * docstring that enumerates causes and misses one is the defect class this whole round closes.
+     */
+    producer: Verdict['producer'];
+    occurrenceOrdinals: number;
+    windowOrdinals: number;
+}
+interface QuarantineDetectionResult {
+    /** Lifecycle events to append, entered-then-released, each group identity-sorted. */
+    events: QuarantineLedgerEvent[];
+    /** At the flag floor: suspected flaky, no state change, no ledger write (D-06). */
+    flagged: QuarantineDetectionSighting[];
+    /** Escalated but class-gated away from auto-quarantine — the build keeps failing (D-05). */
+    escalatedNotQuarantined: QuarantineDetectionSighting[];
+}
+/**
+ * The ladder, evaluated over one run's failures and the current ledger state.
+ *
+ * ORDERING IS DETERMINISTIC ON ANY HOST — entered events (identity-sorted) then released-auto
+ * events (identity-sorted) — so the committed ledger's bytes are a function of ledger CONTENT and
+ * not of projection iteration order. What makes that true rather than merely stated is
+ * {@link compareQuarantineIdentity}: a TOTAL order over {@link quarantineIdentityKey} by code
+ * unit. Total is the load-bearing word. A comparator that answers 0 for two DISTINCT identities
+ * hands the decision back to the caller's iteration order, because `Array.prototype.sort` is
+ * stable — so a zero here would falsify this paragraph directly. Code units also make the answer a
+ * property of the strings rather than of the machine's locale and ICU build.
+ *
+ * Both sorts below and `operations.ts`'s `triageOrder` share that one comparator; the fingerprint
+ * tiebreak uses the same `compareBytes` primitive. There is one ordering rule in this subsystem and
+ * it is spelled once (390-22 / WR-06).
+ *
+ * Suppression is keyed on ledger STATE, not on the existence of an entry: only `'quarantined'`
+ * suppresses a fresh `entered`. An `'expired'` entry has already stopped suppressing (D-11) and a
+ * `'released'` one closed its window, so a fresh crossing re-enters in both cases — D-10's stated
+ * "re-entry needs no special rule". The repeated `entered` lines are the ledger's own record that
+ * this test has been here before, which is exactly the history D-03 chose an event log to keep.
+ */
+declare function evaluateQuarantineDetection(input: EvaluateQuarantineDetectionInput): QuarantineDetectionResult;
+
+interface LoadedBundle {
+    frontmatter: RecordFrontmatter;
+    summary: string;
+    body: string;
+    manifest: BundleManifest;
+    provenance: BundleProvenance;
+    relations: BundleRelations;
+    events: BundleOutcomeEvent[];
+    artifactsIndex: ArtifactsIndex;
+    screenStates: ScreenState[];
+}
+type LoadBundleOutcome = {
+    kind: 'loaded';
+    bundle: LoadedBundle;
+} | {
+    kind: 'not-found';
+} | {
+    kind: 'incomplete';
+} | {
+    kind: 'version-error';
+    reason: string;
+} | {
+    kind: 'invalid';
+    reason: string;
+};
+interface IntegrityReport {
+    ok: boolean;
+    violations: string[];
+}
+declare const GATES_REL_PATH = "evidence/gates.jsonl";
+interface Measurements {
+    baseline: MeasurementBaseline;
+    observations: MeasurementObservation[];
+}
+/**
+ * Read D-03's baseline-first append stream. Absence is normal for non-measurement
+ * bundles; any present malformed line fails loudly through the strict schemas.
+ */
+declare function readMeasurements(bundleDir: string): Measurements | undefined;
+/** 416 D-03/D-04: absence is normal; a present receipt must attest this bundle and its bytes. */
+declare function readGateReceipts(bundleDir: string, bundleId: string): GateLine[] | undefined;
+declare function loadBundle(bundleDir: string): LoadBundleOutcome;
+declare function verifyBundleIntegrity(bundleDir: string): IntegrityReport;
+/**
+ * Phase 375 consumes this exact disk-derived projection seam; no model-produced scalar enters it.
+ */
+declare function deriveBundleTrust(loaded: LoadedBundle, priors?: TrustPriorTable): DerivedTrustState;
+
+interface KnowledgeHit {
+    bundleId: string;
+    product: string;
+    kind: LoadedBundle['frontmatter']['kind'];
+    subtype: string | null;
+    status: BundleStatus;
+    trust: number;
+    validity: DerivedTrustState['validity'];
+    summary: string;
+    embeddingInput: string;
+}
+interface ScanBundlesOptions {
+    knowledgeRoot: string;
+    priors?: TrustPriorTable;
+    text?: string;
+    anchor?: Anchor;
+    product?: string;
+    k?: number;
+}
+interface ScanBundleByIdOptions {
+    knowledgeRoot: string;
+    priors?: TrustPriorTable;
+    bundleId: string;
+}
+type CanonicalBundleAnchorLookup = {
+    kind: 'resolved';
+    bundleId: RecordId;
+    product: string;
+    anchors: Anchor[];
+} | {
+    kind: 'unresolved';
+    reason: 'not-found';
+} | {
+    kind: 'unresolved';
+    reason: 'invalid';
+    detail: string;
+};
+interface EnumeratedBundleDir {
+    product: string;
+    dir: string;
+}
+/** Enumerate bundle directories in stable product-then-directory order. */
+declare function enumerateBundleDirs(knowledgeRoot: string): EnumeratedBundleDir[];
+/** The single withdrawn-fact firewall reused by degraded and indexed reader paths. */
+declare function isServable(trust: Pick<DerivedTrustState, 'status' | 'validity'>): boolean;
+declare function scanBundles(opts: ScanBundlesOptions): KnowledgeHit[];
+declare function scanBundleById(opts: ScanBundleByIdOptions): KnowledgeHit | undefined;
+/**
+ * Trusted, read-only lookup for post-verdict attribution. Unlike scanBundleById this deliberately
+ * ignores serving lifecycle state: a handoff may outlive a candidate's promotion, supersession, or
+ * deprecation. Canonical bytes still have to parse and pass the complete integrity oracle.
+ */
+declare function readCanonicalBundleAnchors(input: {
+    knowledgeRoot: string;
+    bundleId: RecordId;
+}): CanonicalBundleAnchorLookup;
+
+declare const REBUILD_MARKER_FILE = ".rebuild-requested";
+type RebuildReason = 'absent' | 'corrupt' | 'locked' | 'schema-version';
+interface RebuildRequest {
+    reason: RebuildReason;
+    detail: string;
+    /** D-17 diagnostic operations metadata only; never an input to validity or serving decisions. */
+    requestedAt: string;
+}
+interface RequestRebuildOptions {
+    knowledgeRoot: string;
+    reason: RebuildReason;
+    detail: string;
+}
+type ReadRebuildRequestOutcome = {
+    present: false;
+} | {
+    present: true;
+    request: RebuildRequest | undefined;
+};
+/**
+ * Write the first rebuild signal atomically; later signals never overwrite its diagnostic cause.
+ */
+declare function requestRebuild(opts: RequestRebuildOptions): void;
+/** Read a marker through a strict disk-boundary guard; malformed bytes remain a bare signal. */
+declare function readRebuildRequest(knowledgeRoot: string): ReadRebuildRequestOutcome;
+/** Consume the durable rebuild signal. Clearing an absent marker is intentionally a no-op. */
+declare function clearRebuildRequest(knowledgeRoot: string): void;
+
+interface KnowledgeSearchOptions {
+    product?: string;
+    k?: number;
+}
+interface DenseSearchOptions extends KnowledgeSearchOptions {
+    k: number;
+}
+type DenseHit = KnowledgeHit & {
+    distance: number;
+};
+interface KnowledgeReader {
+    /** Current serving face; permanently changes to scan after an index operation failure. */
+    readonly source: 'index' | 'scan';
+    /** Current vector capability; changes to none when the serving face degrades to scan. */
+    readonly vec: VecCapability | 'none';
+    getById(bundleId: string): KnowledgeHit | undefined;
+    searchLexical(text: string, opts?: KnowledgeSearchOptions): KnowledgeHit[];
+    lookupAnchor(anchor: Anchor, opts?: KnowledgeSearchOptions): KnowledgeHit[];
+    searchDense(embedding: Float32Array, opts: DenseSearchOptions): DenseHit[];
+    recheck(hits: readonly KnowledgeHit[]): KnowledgeHit[];
+    close(): void;
+}
+interface OpenKnowledgeReaderOptions {
+    /** Neutral host data retained across every read and index-to-scan transition. */
+    priors?: TrustPriorTable;
+    /** D-12 test seam. Production callers resolve sqlite-vec's pinned prebuild. */
+    vecLoadablePath?: string;
+}
+/**
+ * Which face the derived index presents to a reader RIGHT NOW (407 D-17).
+ *
+ * `scan` carries the reason the ladder degraded, the detail the rebuild request would have
+ * quoted, and whether the file was there at all — `absent` and `corrupt` are the same word to a
+ * serving caller but different operator situations, and `doctor` says which.
+ */
+type IndexFace = {
+    source: 'index';
+} | {
+    source: 'scan';
+    reason: RebuildReason;
+    detail: string;
+    filePresent: boolean;
+};
+interface ClassifyIndexFaceOptions extends OpenKnowledgeReaderOptions {
+    /** `IndexReaderOpenOptions.inspectCheckpointedImmutably`: the probe only, never the facade. */
+    inspectCheckpointedImmutably?: boolean;
+}
+/**
+ * The degrade ladder as a PURE READ (407 D-17, T-407-10).
+ *
+ * ONE ladder, ONE core, two callers. {@link openKnowledgeReader} below is the SERVING facade: it
+ * keeps the connection the core blessed and keeps the side effect — a degraded open still writes
+ * the durable D-07 rebuild request. This function is the PROBE half: the identical checks in the
+ * identical order over the identical core, but it releases the connection and writes no marker,
+ * because its other callers are the retrieval-rung resolver that `doctor` and the runner's
+ * evidence recorder invoke, and the local composition root's knowledge probes. A probe that
+ * requested a rebuild would make merely ASKING about the index a mutation of the knowledge root;
+ * a probe that returned a live handle would make every `doctor` call a connection leak. The probe
+ * hands back a face, never a handle — only the serving facade holds a connection.
+ */
+declare function classifyIndexFace(knowledgeRoot: string, opts?: ClassifyIndexFaceOptions): IndexFace;
+/**
+ * The SERVING facade: classify once, then serve from the connection the classifier blessed.
+ *
+ * 407-13 (CR-02): this used to call the pure probe and then open a SECOND connection of its own,
+ * so a lock acquired in the gap between the probe's close and this open degraded a healthy index
+ * — writing the durable rebuild marker and dropping every later retrieval in the process to
+ * bundle scan on nothing but contention. It also let `resolveRetrievalRung` report `memidex` while
+ * the reader it was describing served `bundle-scan`, the exact banner/reality disagreement D-17's
+ * one-fold rule exists to prevent. The facade must never close what it is about to reopen: there
+ * is one open on the healthy path and no window for a lock to arrive in.
+ */
+declare function openKnowledgeReader$1(knowledgeRoot: string, opts?: OpenKnowledgeReaderOptions): KnowledgeReader;
+
+interface OpenServingKnowledgeReaderConfig {
+    knowledgeRoot: string;
+    /** Neutral host data, snapshotted when this reader is opened. */
+    priors?: TrustPriorTable;
+    product?: string;
+    scopeDefaults?: {
+        asOfBuild?: number;
+        /** Known containing scopes for member requests (for example, the owning suite). */
+        parentScopes?: readonly ScopeKey[];
+    };
+    budgets?: {
+        recordCap?: number;
+    };
+}
+interface IndexRow {
+    bundle_id: string;
+    product: string;
+    scope_tier: string;
+    scope_key: string;
+}
+interface HydratedEntry {
+    dir: string;
+    bundle: LoadedBundle;
+    entry: IndexEntry;
+}
+/** @deprecated The safe serving reader reports misses as `undefined` and never throws this. */
+declare class KnowledgeRecordNotFoundError extends Error {
+    readonly recordId: RecordId;
+    constructor(recordId: RecordId);
+}
+/** Shared serving internal: scope-laddered index rows (also feeds the authoring reader). */
+declare function readIndexRows(config: OpenServingKnowledgeReaderConfig, scope?: ScopeKey): IndexRow[];
+/** Shared serving internal: integrity-checked bundle hydration (also feeds the authoring reader). */
+declare function hydrateRows(config: OpenServingKnowledgeReaderConfig, rows: readonly IndexRow[], audit: boolean): HydratedEntry[];
+declare function openKnowledgeReader(config: OpenServingKnowledgeReaderConfig): KnowledgeHintReader;
+declare function openKnowledgeReader(knowledgeRoot: string, opts?: OpenKnowledgeReaderOptions): KnowledgeReader;
+
+/**
+ * The bundle facts the matcher folds. `LoadedBundle` satisfies this structurally, so the reader
+ * passes hydrated entries straight through; tests construct the narrow shape directly.
+ */
+interface ProcedureMatchCandidate {
+    entry: IndexEntry;
+    bundle: {
+        summary: string;
+        body: string;
+        events: readonly BundleOutcomeEvent[];
+        provenance: BundleProvenance;
+    };
+}
+
+/**
+ * Screenless authoring-brief assembly (ABRF-01/ABRF-02, D-13/D-15/D-16).
+ *
+ * The 4th serving channel: facts/cautions/procedures from already-hydrated store entries plus
+ * projection-ranked exemplar TEST REFERENCES — no ScreenState anywhere in the signature. The
+ * assembly is pure (snapshot inputs only, no wall-clock, no file reads) and deterministic on the
+ * zero-embedder lexical floor: intent tokens drive the lexical relevance leg, `page:`/`flow:`
+ * target anchors drive the anchor leg, and dense scores join only as an optional additive term.
+ *
+ * Locked tight-budget precedence (Pitfall 8 — deliberately NOT the run brief's L0-L2 tiers):
+ * caution > procedure > exemplar > fact. Buckets admit in that order against one shared
+ * admission ledger; once a bucket sheds anything, every lower-precedence bucket is shed whole,
+ * so an exemplar can never be dropped before a fact at the same budget.
+ */
+
+/**
+ * PROVISIONAL exemplar cap (D-15's "~3-5"). Internal constitution value in the
+ * retrieval/constants.ts style — never a config key; M3 owns calibration.
+ */
+declare const AUTHORING_EXEMPLAR_CAP = 4;
+/** PROVISIONAL top-N procedures served to the authoring consumer (D-15). */
+declare const AUTHORING_PROCEDURE_CAP = 5;
+/**
+ * PROVISIONAL bounded-excerpt budget in UTF-16 code units (D-16). The excerpt is title +
+ * outcome outline composed from projection-known metadata — never test file content.
+ */
+declare const AUTHORING_EXCERPT_CHAR_BUDGET = 240;
+/** Hydrated store entry: `LoadedBundle`-backed entries satisfy this structurally. */
+type AuthoringEntryCandidate = ProcedureMatchCandidate;
+/** One run-outcome projection row (381-05 tables), read through the index reader connection. */
+interface AuthoringExemplarRow {
+    filePath: string;
+    testName: string;
+    passes: number;
+    failures: number;
+    heals: number;
+    flakeCount: number;
+    /** Resolved by the hydrating reader from the committed quarantine ledger (390 D-02). */
+    quarantined: boolean;
+    /** Last-N window entries — ordinals only, wall-clock never. */
+    lastOutcomes: readonly {
+        buildOrdinal: number;
+        passed: boolean;
+    }[];
+    /** canonicalJson(normalizeAnchor(...)) keys — the ABRF-02 byte-deterministic encoding. */
+    anchorKeys: readonly string[];
+}
+/** A test reference in the caller-supplied discovery universe (refs only, never content). */
+interface AuthoringTestRef {
+    filePath: string;
+    testName: string;
+}
+interface AssembleAuthoringBriefInput {
+    /** Already-hydrated entries; the reader's SQL scope ladder has applied the scope walls. */
+    entries: readonly AuthoringEntryCandidate[];
+    /** Per-test outcome counters + exercised-anchor sets from the run-outcome projection. */
+    projectionRows: readonly AuthoringExemplarRow[];
+    /**
+     * D-15 never-run discovery universe: test references the CALLER knows about (the consumer
+     * owns the filesystem; M4 passes its authored shelf, the M2 reader passes projection-known
+     * identities). Refs absent from the projection surface flagged `unverifiedOutcomes`,
+     * discounted, never dropped — and still work against an EMPTY projection.
+     */
+    knownTests?: readonly AuthoringTestRef[];
+    intent: string;
+    scope: ScopeKey;
+    /** `page:`/`flow:` anchors derived from scope + intent by the caller — never a ScreenState. */
+    targetAnchors: readonly Anchor[];
+    budget: number;
+    /** Optional additive dense-leg scores keyed by record id, present only when an embedder is up. */
+    denseScoreByRecordId?: ReadonlyMap<string, number>;
+}
+/**
+ * The §10.6 authoring brief together with its serve-time trace (D-16). The 4th channel returns the
+ * composite for the same reason the run brief does — capture is generic at the SEAM, so 393/394
+ * inherit it by destructuring rather than by re-implementing it.
+ */
+interface AssembledAuthoringBrief {
+    readonly brief: AuthoringBrief;
+    readonly trace: ServedRetrievalTraceV1;
+}
+/**
+ * Pure screenless assembly over already-loaded snapshot inputs. Retrieval SQL, hydration,
+ * budgets-as-plain-numbers, and the projection read all live at the composition boundary
+ * (`createAuthoringReader`); nothing here touches a connection, the clock, or the filesystem.
+ *
+ * The trace's `rank` is the candidate's 1-based position in the ONE admission walk below —
+ * caution, then procedure, then exemplar, then fact — which is the actual total order this
+ * assembly serves in. Everything the ledger admits becomes a served line; everything it sheds
+ * becomes a cut candidate, bounded by the pinned top-K.
+ */
+declare function assembleAuthoringBrief(input: AssembleAuthoringBriefInput): AssembledAuthoringBrief;
+
+/**
+ * PROVISIONAL authoring-brief budget, computed as a plain number at this composition boundary
+ * (377 D-07 lineage: budgets are numbers passed down, never config reads inside assemblies).
+ */
+declare const AUTHORING_BRIEF_DEFAULT_BUDGET = 2000;
+/** PROVISIONAL dense candidate cap pending authoring-channel retrieval telemetry. */
+declare const AUTHORING_DENSE_K = 32;
+interface AuthoringReaderDependencies {
+    /** Consumer-owned test inventory crossing this boundary as identity refs only. */
+    discoverKnownTests?: () => readonly AuthoringTestRef[];
+    /** Test/integration seam; production omission uses denseLeg's automatic acquisition ladder. */
+    embedder?: EmbedderPort;
+    /**
+     * ISO-8601 instant the quarantine fold compares expiry against (390 D-11). A seam rather than a
+     * clock read inside the fold: `'expired'` is COMPUTED from this value, so pinning an expiry
+     * boundary one second either side has to be possible without waiting for wall time. Production
+     * omission reads the clock ONCE per brief, at this composition boundary.
+     */
+    now?: () => string;
+}
+/** Open the screenless authoring channel over the same store config as the serving reader. */
+declare function createAuthoringReader(config: OpenServingKnowledgeReaderConfig, deps?: AuthoringReaderDependencies): AuthoringReadPort;
+
+interface InspectRecordsOptions {
+    knowledgeRoot: string;
+    filter: InspectFilter;
+}
+type InspectionTrustState = Pick<DerivedTrustState, 'status' | 'counters' | 'validity'>;
+/**
+ * Project ONE loaded bundle and its already-derived trust into the maintenance view.
+ *
+ * Extracted from the fold below so `showRecord` renders the SAME view rather than a second
+ * one built to the same description. The two would have agreed on the day they were written;
+ * the first field to disagree afterwards would have been one nobody compares, and a reviewer
+ * reading a record's detail page beside a record's row would have had no way to tell which of
+ * the two was lying. `bundle.events` is taken as given, so an as-of caller passes the bundle
+ * with its visible events already narrowed and this function has no opinion about time.
+ */
+declare function toInspectRecordView(entry: EnumeratedBundleDir, bundle: LoadedBundle, trust: InspectionTrustState): InspectRecordView;
+/**
+ * Fold canonical committed bundles into maintenance views. Explicit non-live status filters and
+ * as-of queries enable audit visibility; an unqualified query retains the serving firewall.
+ */
+declare function inspectRecords(options: InspectRecordsOptions): InspectRecordView[];
+
+interface DiffSinceOptions {
+    knowledgeRoot: string;
+    sinceOrdinal: number;
+}
+/** Pure build-ordinal fold over committed bundle outcomes and content-free purge receipts. */
+declare function diffSince(options: DiffSinceOptions): RecordChange[];
+
+interface ShowRecordOptions {
+    knowledgeRoot: string;
+    recordId: string;
+}
+/**
+ * Show one record, or report by name that nothing is committed under that id.
+ *
+ * A knowledge root with no bundles — or no `memory/` directory at all — is an ordinary
+ * `not-found`, because the enumerator already treats a missing tree as empty. That is the
+ * FUNC-04 empty edge: an empty store answers, it does not throw.
+ */
+declare function showRecord(options: ShowRecordOptions): KnowledgeRecordShowResult;
+
+type KnowledgeMaintenanceScanIssue = 'directory-read' | 'non-directory-entry' | 'bundle-load' | 'bundle-integrity' | 'receipt-read' | 'receipt-invalid';
+/** Fail-closed maintenance read error: callers must never render a partial clean-looking view. */
+declare class KnowledgeMaintenanceScanError extends Error {
+    readonly name = "KnowledgeMaintenanceScanError";
+    readonly issue: KnowledgeMaintenanceScanIssue;
+    readonly path: string;
+    constructor(issue: KnowledgeMaintenanceScanIssue, path: string, detail: string);
+}
+
+type CanaryPostureFacts = {
+    kind: 'found';
+    gate1PassOrdinal?: number;
+    gate1PassDigest?: string;
+    /** Existing active authority cites this Gate-1 receipt; not admission eligibility. */
+    lowerTrustActiveGate1Digest?: string;
+    latestAttributionOrdinal?: number;
+    latestGate2Ordinal?: number;
+    activeInScope: number;
+    lowerTrustActiveInScope: number;
+} | {
+    kind: 'not-found';
+};
+interface StandingReceiptDigest {
+    candidateId: string;
+    gate: GateReceipt['gate'];
+    verdict: GateReceipt['verdict'];
+    /** Gate 3 is user evidence and has no corpus citation. */
+    corpusDigest?: string;
+    producedAtOrdinal: number;
+}
+interface LowerTrustShare {
+    product: string;
+    active: number;
+    lowerTrust: number;
+}
+declare function canaryPostureFactsFor(input: {
+    knowledgeRoot: string;
+    candidateId: string;
+    scope: ScopeKey;
+    resolveTrustPriors?: () => TrustPriorTable | undefined;
+}): CanaryPostureFacts;
+declare function standingReceiptDigestsFor(input: {
+    knowledgeRoot: string;
+}): StandingReceiptDigest[];
+declare function lowerTrustSharesFor(input: {
+    knowledgeRoot: string;
+    resolveTrustPriors?: () => TrustPriorTable | undefined;
+}): LowerTrustShare[];
+
+declare const MARK_EVIDENCE_TOKEN_PREFIX = "mark:";
+interface PlanMarkEvidenceInput {
+    knowledgeRoot: string;
+    /** markId is optional: a preview plans ephemeral effects; a resumed writer supplies it to see durable ones. */
+    mark: Pick<MarkReceipt, 'runId' | 'kind'> & {
+        markId?: string;
+    };
+    servedRecordIds: readonly string[];
+    /** Historical observation hashes require the original member/step coordinates. */
+    handoff?: CompletedRunHandoff;
+    /** Host-derived chainJobIdsForRun(runId, idSource).curateMemory; never guessed here. */
+    curationJobIds?: readonly string[];
+}
+type MarkEvidenceEffect = {
+    direction: 'confirm';
+    alreadyAppended: boolean;
+} | {
+    direction: 'overturn';
+    overturnsEvidenceToken: EvidenceToken;
+    overturnsCurationJobId: string;
+    alreadyAppended: boolean;
+};
+type MarkEvidenceTarget = {
+    recordId: string;
+    kind: 'unreadable';
+} | {
+    recordId: string;
+    kind: 'effects';
+    productKey: string;
+    served: boolean;
+    buildOrdinal: number;
+    effects: MarkEvidenceEffect[];
+};
+interface MarkEvidencePlan {
+    targets: MarkEvidenceTarget[];
+    /** Without the handoff, opaque historical canary hashes cannot all be correlated. */
+    correlationIncomplete?: true;
+}
+type AppendMarkEvidenceOutcome = {
+    confirmed: number;
+    overturned: number;
+    skipped: {
+        recordId: string;
+        reason: 'bundle-unreadable' | 'already-appended';
+    }[];
+    /** Without the handoff, opaque historical canary hashes cannot all be correlated. */
+    correlationIncomplete?: true;
+};
+declare function markEvidenceEvent(effect: MarkEvidenceEffect, markId: string, buildOrdinal: number): BundleOutcomeEvent;
+declare function planMarkEvidence(input: PlanMarkEvidenceInput): MarkEvidencePlan;
+/** The outcome an append executing this plan reports, with duplicates counted only on resume. */
+declare function projectMarkEvidenceOutcome(plan: MarkEvidencePlan, options: {
+    includeAlreadyAppended: boolean;
+}): AppendMarkEvidenceOutcome;
+
+export { type Measurements as $, type AppendMarkEvidenceOutcome as A, INDEX_SCHEMA_VERSION as B, CHECKPOINT_EVERY_N_BUNDLES as C, type DenseHit as D, type EmbedderPort as E, type IndexHealth as F, GATES_REL_PATH as G, type IndexWriterHandle as H, type IndexReaderConnection as I, type InspectRecordsOptions as J, type KnowledgeReader as K, type LoadedBundle as L, type IntegrityReport as M, type KnowledgeHit as N, KnowledgeMaintenanceScanError as O, type KnowledgeMaintenanceScanIssue as P, type QuarantineAppendOutcome as Q, type RefusedQuarantineLine as R, KnowledgeRecordNotFoundError as S, type KnowledgeSearchOptions as T, type LoadBundleOutcome as U, type VecCapability as V, type LowerTrustShare as W, MARK_EVIDENCE_TOKEN_PREFIX as X, type MarkEvidenceEffect as Y, type MarkEvidencePlan as Z, type MarkEvidenceTarget as _, type IndexFace as a, verifyBundleIntegrity as a$, type OpenKnowledgeReaderOptions as a0, type OpenServingKnowledgeReaderConfig as a1, type PlanMarkEvidenceInput as a2, QUARANTINE_AUTO_EXIT_PASSES as a3, QUARANTINE_CLASS_DISPOSITIONS as a4, QUARANTINE_DEFAULT_EXPIRY_DAYS as a5, QUARANTINE_ESCALATE_THRESHOLD as a6, QUARANTINE_FLAG_FLOOR as a7, QUARANTINE_LEDGER_FILENAME as a8, type QuarantineDetectionFailure as a9, foldQuarantineLedgerState as aA, indexDbPath as aB, inspectRecords as aC, isServable as aD, loadBundle as aE, lowerTrustSharesFor as aF, markEvidenceEvent as aG, openIndexReaderConnection as aH, openIndexWriter as aI, openKnowledgeReader as aJ, planMarkEvidence as aK, probeIndexHealth as aL, projectMarkEvidenceOutcome as aM, quarantineLedgerPath as aN, readCanonicalBundleAnchors as aO, readGateReceipts as aP, readMeasurements as aQ, readQuarantineLedger as aR, requestRebuild as aS, resolveActiveProfile as aT, resolveVecCapability as aU, scanBundleById as aV, scanBundles as aW, showRecord as aX, standingReceiptDigestsFor as aY, toInspectRecordView as aZ, vecTableName as a_, type QuarantineDetectionResult as aa, type QuarantineDetectionTestWindow as ab, type QuarantineDisposition as ac, type QuarantineLedgerRead as ad, type QuarantineOrdinalOutcome as ae, READER_BUSY_TIMEOUT_MS as af, REBUILD_MARKER_FILE as ag, REQUIRED_INDEX_TABLES as ah, type ReadRebuildRequestOutcome as ai, type RebuildReason as aj, type RequestRebuildOptions as ak, type ScanBundleByIdOptions as al, type ScanBundlesOptions as am, type ShowRecordOptions as an, type StandingReceiptDigest as ao, WRITER_BUSY_TIMEOUT_MS as ap, assembleAuthoringBrief as aq, canaryPostureFactsFor as ar, classifyIndexFace as as, clearRebuildRequest as at, createAuthoringReader as au, deriveBundleTrust as av, diffSince as aw, embeddingProfileKey as ax, enumerateBundleDirs as ay, evaluateQuarantineDetection as az, type QuarantineDetectionSighting as b, type HydratedEntry as b0, type IndexRow as b1, QUARANTINE_FLOOR_ELIGIBILITY as b2, type QuarantineFloorEligibility as b3, hydrateRows as b4, readIndexRows as b5, readIndexMaintenanceState as c, type RebuildRequest as d, AUTHORING_BRIEF_DEFAULT_BUDGET as e, AUTHORING_DENSE_K as f, AUTHORING_EXCERPT_CHAR_BUDGET as g, AUTHORING_EXEMPLAR_CAP as h, AUTHORING_PROCEDURE_CAP as i, AUTO_QUARANTINE_CLASSES as j, type AssembleAuthoringBriefInput as k, type AssembledAuthoringBrief as l, type AuthoringEntryCandidate as m, type AuthoringExemplarRow as n, openKnowledgeReader$1 as o, type AuthoringReaderDependencies as p, type AuthoringTestRef as q, readRebuildRequest as r, type CanaryPostureFacts as s, type CanonicalBundleAnchorLookup as t, type DenseSearchOptions as u, type DiffSinceOptions as v, type EnumeratedBundleDir as w, type EvaluateQuarantineDetectionInput as x, INDEX_DB_FILE as y, INDEX_RENDERING_SCHEMA_VERSION as z };