@inflexa-ai/harness 0.16.0 → 0.18.0

package/dist/prompts/target-assessment/investigation/claim-reverification.js

@@ -0,0 +1,49 @@
+export const claimReverificationBrief = `# Task: re-verify one organ liability claim
+
+You are given a corroborated organ liability claim, the mechanism proposed for
+it, the objection raised against it, and the evidence the assessment collected
+for that organ. Decide what survives.
+
+You are adjudicating, not summarising. Weigh the objection against the evidence
+and say which of them the record actually supports.
+
+## The verdict vocabulary
+
+- \`upheld\` — the objection was answered by the evidence, and the claim stands as
+  proposed.
+- \`weakened\` — the objection lands, but the claim is not eliminated: it holds in
+  a narrower form, or with lower confidence in its mechanism.
+- \`overturned\` — the objection is decisive; the evidence does not support the
+  claim as stated.
+- \`undetermined\` — the record settles neither side. This is a real verdict, not a
+  refusal to answer, and it is correct whenever the evidence is genuinely silent.
+
+The verdict is your read of the record in words. There is no score, no
+threshold, and no arithmetic — do not attempt to derive one, and do not describe
+the claim as passing or failing a bar.
+
+Nothing you return removes a claim from the assessment. An \`overturned\` verdict
+is recorded and read; it does not delete the organ, and you should therefore
+never soften a verdict to protect a liability from disappearing.
+
+## Support for the verdict
+
+Cite the records that carry your verdict — the ones you actually relied on, from
+the evidence you were given or from the objection's counter-evidence.
+
+If nothing in the record carries the verdict, return support state \`unknown\`
+with a one-line reason. That is a complete answer, expected often, and always
+preferable to a locator you are not certain of. The verdict itself is still
+recorded.
+
+## Do NOT
+
+- Do NOT cite a publication identifier, accession, or regulatory reference that
+  was not in the material you were given.
+- Do NOT report support as \`scored\` while noting the evidence is thin. Thin is
+  \`unknown\` with that as the reason.
+- Do NOT restate the objection as the verdict. Say what the record supports.
+- Do NOT return \`upheld\` merely because the claim was corroborated by several
+  sources — whether those sources are independent is exactly what the objection
+  may be contesting.
+- Do NOT assume anything about what ran before you or what will run after.`;

package/dist/prompts/target-assessment/investigation/index.d.ts

@@ -0,0 +1,3 @@
+export { mechanismProposalBrief } from "./mechanism-proposal.js";
+export { adversarialCritiquePrompt } from "./adversarial-critique.js";
+export { claimReverificationBrief } from "./claim-reverification.js";

package/dist/prompts/target-assessment/investigation/index.js

@@ -0,0 +1,3 @@
+export { mechanismProposalBrief } from "./mechanism-proposal.js";
+export { adversarialCritiquePrompt } from "./adversarial-critique.js";
+export { claimReverificationBrief } from "./claim-reverification.js";

package/dist/prompts/target-assessment/investigation/mechanism-proposal.d.ts

@@ -0,0 +1 @@
+export declare const mechanismProposalBrief: string;

package/dist/prompts/target-assessment/investigation/mechanism-proposal.js

@@ -0,0 +1,49 @@
+import { ORGAN_SYSTEMS } from "../../../contracts/organ-system.js";
+// Interpolated rather than restated, so the prompt cannot name an organ the
+// schema will reject.
+const organTokens = ORGAN_SYSTEMS.join(", ");
+export const mechanismProposalBrief = `# Task: propose a mechanism for one organ liability
+
+You are given ONE canonical organ token and the evidence this assessment has
+already collected about that organ — the sources that raised a signal for it,
+what each of them said, and the record each signal came from. Propose how the
+assessed target could produce a liability in that organ.
+
+The organ is supplied to you and is already one of: ${organTokens}. You are not
+asked to choose an organ and you must not reassign the claim to another one.
+
+## What a proposal is
+
+- One mechanism, stated plainly: what the target does, in which cells or tissue,
+  and how that becomes the observed liability.
+- Grounded in the evidence you were handed. Every record you were given carries
+  a locator; cite the locators of the records your mechanism actually rests on.
+- Scaled to the observation. A mechanism must operate at the same biological
+  scale as the signal it explains — do not explain a clinical adverse-event
+  signal with developmental or tissue-homeostasis biology.
+
+## Reporting no mechanism costs you nothing
+
+If the evidence supports no mechanism, say so: return no mechanism statement and
+a support reason explaining what was missing. That is a complete, correct answer
+and it is preferred over a plausible-sounding story.
+
+If you can state a mechanism but cannot point at a record that supports it,
+return the statement with support state \`unknown\` and a one-line reason. An
+unknown support is a normal outcome, not a penalty, and it is always cheaper
+than a citation you are not certain of.
+
+## Do NOT
+
+- Do NOT cite a publication identifier, accession, or regulatory reference that
+  was not in the evidence you were given. A locator you produced from memory is
+  a fabrication even when the paper exists.
+- Do NOT report support as \`scored\` while explaining in prose that the evidence
+  is weak or indirect. Weak or indirect support is \`unknown\` with that as the
+  reason.
+- Do NOT restate the evidence back as the mechanism. "Several sources report
+  hepatic signals" is an observation; a mechanism says why.
+- Do NOT propose a mechanism for a different organ, a different target, or a
+  drug class rather than the target.
+- Do NOT assume anything about what ran before you or what will run after. Work
+  from what you were handed.`;

package/dist/prompts/target-assessment/tox-voice/index.d.ts

@@ -1,4 +1,4 @@
 export { toxVoiceCore } from "./core.js";
 export { toxVoiceExemplars, type SectionType } from "./exemplars.js";
-export { toxVoiceVocabulary, type OrganSystem, type LiabilityFraming, type HedgePhrase, type BannedTerm } from "./vocabulary.js";
+export { toxVoiceVocabulary, type LiabilityFraming, type HedgePhrase, type BannedTerm } from "./vocabulary.js";
 export { buildVoiceCritique, type VoiceProbe } from "./critique.js";

package/dist/prompts/target-assessment/tox-voice/vocabulary.d.ts

@@ -1,15 +1,18 @@
 /**
- * Tox-voice canon. Lists are intentionally not exhaustive — they are the
- * minimum surface the deterministic voice probe enforces. Editorial
- * judgment in the agent prompts covers the long tail.
+ * Tox-voice canon. The stylistic lists are intentionally not exhaustive —
+ * they are the minimum surface the deterministic voice probe enforces, and
+ * editorial judgment in the agent prompts covers the long tail.
+ *
+ * `organSystems` is the exception: it is closed, because it is a projection
+ * of the canonical organ vocabulary rather than a list of its own. Prose and
+ * structured fields must name the same organs.
  */
 export declare const toxVoiceVocabulary: {
-    readonly organSystems: readonly ["hepatobiliary", "renal", "cardiac", "vascular", "haematologic", "central nervous system", "peripheral nervous system", "respiratory", "gastrointestinal", "reproductive", "endocrine", "musculoskeletal", "dermatologic", "ocular", "immunologic"];
+    readonly organSystems: string[];
     readonly liabilityFraming: readonly ["on-target liability", "off-target liability", "secondary pharmacology", "class liability", "mechanism-related", "exaggerated pharmacology", "target-organ toxicity"];
     readonly hedgePhrases: readonly ["the data are consistent with", "the data suggest", "human relevance is uncertain", "human relevance remains to be established", "interpretation is limited by", "no causal inference is supported", "the available evidence is consistent with", "the available evidence does not support", "translatability to humans is unclear", "species differences"];
     readonly banned: readonly ["groundbreaking", "cutting-edge", "state-of-the-art", "best-in-class", "first-in-class", "revolutionary", "leverages", "leveraging", "robust", "powerful", "seamlessly", "cleanly", "elegant", "unparalleled", "demonstrates the power of", "showcases", "unlocks", "enables breakthrough", "very promising", "extremely", "incredibly", "highly innovative"];
 };
-export type OrganSystem = (typeof toxVoiceVocabulary.organSystems)[number];
 export type LiabilityFraming = (typeof toxVoiceVocabulary.liabilityFraming)[number];
 export type HedgePhrase = (typeof toxVoiceVocabulary.hedgePhrases)[number];
 export type BannedTerm = (typeof toxVoiceVocabulary.banned)[number];

package/dist/prompts/target-assessment/tox-voice/vocabulary.js

@@ -1,26 +1,15 @@
 /**
- * Tox-voice canon. Lists are intentionally not exhaustive — they are the
- * minimum surface the deterministic voice probe enforces. Editorial
- * judgment in the agent prompts covers the long tail.
+ * Tox-voice canon. The stylistic lists are intentionally not exhaustive —
+ * they are the minimum surface the deterministic voice probe enforces, and
+ * editorial judgment in the agent prompts covers the long tail.
+ *
+ * `organSystems` is the exception: it is closed, because it is a projection
+ * of the canonical organ vocabulary rather than a list of its own. Prose and
+ * structured fields must name the same organs.
  */
+import { ORGAN_SYSTEMS, ORGAN_SYSTEM_LABELS } from "../../../contracts/organ-system.js";
 export const toxVoiceVocabulary = {
-    organSystems: [
-        "hepatobiliary",
-        "renal",
-        "cardiac",
-        "vascular",
-        "haematologic",
-        "central nervous system",
-        "peripheral nervous system",
-        "respiratory",
-        "gastrointestinal",
-        "reproductive",
-        "endocrine",
-        "musculoskeletal",
-        "dermatologic",
-        "ocular",
-        "immunologic",
-    ],
+    organSystems: ORGAN_SYSTEMS.map((organ) => ORGAN_SYSTEM_LABELS[organ]),
     liabilityFraming: [
         "on-target liability",
         "off-target liability",

package/dist/providers/__fixtures__/session.d.ts

@@ -1,16 +1,17 @@
 /**
  * Test-only harness `RequestSession` builder. Not a `*.test.ts` file, so the test
  * runner ignores it; imported by harness unit tests that need a session but never
- * read its (opaque) auth. The auth is the trivial local one — the harness never
- * inspects it. Managed-adapter tests that exercise `getAuth` / the managed seams
- * use the managed builder in `compose/__fixtures__/session.ts` instead.
+ * read its (opaque) auth. `auth` defaults to the trivial local value the harness
+ * never inspects; an embedder whose adapters downcast `auth` to a concrete type
+ * overrides it rather than re-declaring the whole session shape.
  */
-import type { RequestSession, Scope } from "../../auth/types.js";
+import type { AuthContext, RequestSession, Scope } from "../../auth/types.js";
 export interface SessionOverrides {
     user?: string;
     scope?: Scope;
     agentId?: string;
     callPath?: readonly string[];
+    auth?: AuthContext;
 }
 /** Build a fully-populated harness `RequestSession` for tests, with per-field overrides. */
 export declare function makeSession(overrides?: SessionOverrides): RequestSession;

package/dist/providers/__fixtures__/session.js

@@ -1,9 +1,9 @@
 /**
  * Test-only harness `RequestSession` builder. Not a `*.test.ts` file, so the test
  * runner ignores it; imported by harness unit tests that need a session but never
- * read its (opaque) auth. The auth is the trivial local one — the harness never
- * inspects it. Managed-adapter tests that exercise `getAuth` / the managed seams
- * use the managed builder in `compose/__fixtures__/session.ts` instead.
+ * read its (opaque) auth. `auth` defaults to the trivial local value the harness
+ * never inspects; an embedder whose adapters downcast `auth` to a concrete type
+ * overrides it rather than re-declaring the whole session shape.
  */
 import { makeLocalAuth } from "../../auth/local-auth-context.js";
 /** Build a fully-populated harness `RequestSession` for tests, with per-field overrides. */
@@ -15,6 +15,6 @@ export function makeSession(overrides = {}) {
             agentId: overrides.agentId ?? "conversation-agent",
             callPath: overrides.callPath ?? ["conversation-agent"],
         },
-        auth: makeLocalAuth(),
+        auth: overrides.auth ?? makeLocalAuth(),
     };
 }

package/dist/report-model/block-walk.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The one walk over a block tree.
+ *
+ * A block kind decides where a reference sits, which prose carries a free numeral, and whether the block
+ * holds children. Three consumers need that same knowledge: the mechanical validator, the draft finish,
+ * and the draft operations. A switch for each consumer is a switch that a ninth block kind can miss in
+ * silence, because each arm returns and none of them fails to build. Thus the walk lives here one time.
+ *
+ * The walk reads a finished `Block` tree and a relaxed `DraftBlock` tree alike. The two differ only in the
+ * section rules, and the section arm reads the children of either one.
+ *
+ * The walk resolves nothing and it opens no file. It reports what the tree holds, and a caller decides
+ * which part it needs.
+ */
+import type { Block } from "../contracts/report-blocks.js";
+import type { Reference } from "../contracts/report-reference.js";
+import type { DraftBlock } from "./draft.js";
+/** A block of a finished report, or a block of a draft. The atoms are the same shape in both. */
+export type AnyBlock = Block | DraftBlock;
+/**
+ * One reference that the walk met, tied to the block that carries it.
+ *
+ * `encodingColumns` is present for a `chart` only. A chart names its axes as free strings, thus the names
+ * must be matched against the table that the binding resolves to. Nothing else can catch a chart that
+ * plots a column which does not exist. The match needs the resolved rows, thus only a value-tier consumer
+ * reads this field.
+ */
+export interface CollectedReference {
+    blockId: string;
+    reference: Reference;
+    encodingColumns?: string[];
+}
+/** An advisory warning about the content of one block. A warning never makes a report invalid. */
+export interface ReportWarning {
+    blockId: string;
+    kind: "free-numeral";
+    detail: string;
+}
+/** What one walk over a block tree found. */
+export interface BlockWalk {
+    /** Each reference, in document order, tied to the block that carries it. */
+    references: CollectedReference[];
+    /** Each id that more than one block holds, named one time, in sorted order. */
+    repeatedIds: string[];
+    /** Each free numeral that prose carries. */
+    warnings: ReportWarning[];
+}
+/** Warn for each free-standing numeral that the prose of one block carries. */
+export declare function numeralWarnings(blockId: string, prose: string): ReportWarning[];
+/**
+ * Walk a block tree, and report each reference, each repeated id, and each free numeral.
+ *
+ * An id is what makes a block addressable, thus an amend by id is well defined only while each id belongs
+ * to one block. The walk is pre-order, thus the references follow the document order.
+ */
+export declare function walkBlocks(blocks: readonly AnyBlock[]): BlockWalk;

package/dist/report-model/block-walk.js

@@ -0,0 +1,89 @@
+/**
+ * The one walk over a block tree.
+ *
+ * A block kind decides where a reference sits, which prose carries a free numeral, and whether the block
+ * holds children. Three consumers need that same knowledge: the mechanical validator, the draft finish,
+ * and the draft operations. A switch for each consumer is a switch that a ninth block kind can miss in
+ * silence, because each arm returns and none of them fails to build. Thus the walk lives here one time.
+ *
+ * The walk reads a finished `Block` tree and a relaxed `DraftBlock` tree alike. The two differ only in the
+ * section rules, and the section arm reads the children of either one.
+ *
+ * The walk resolves nothing and it opens no file. It reports what the tree holds, and a caller decides
+ * which part it needs.
+ */
+/**
+ * A free-standing token that looks like a number, with an optional decimal part and an optional percent
+ * sign.
+ *
+ * The left boundary keeps the digits of a name out of the warnings. The domain prose is dense with a
+ * symbol such as `TP53`, `CD8`, or `IL6`, and without the boundary each one warns for its digits and
+ * buries the real free figures.
+ *
+ * The check is advisory only. A natural-language numeral is brittle to police, because a numeral in prose
+ * can be a real free-standing figure or a harmless part of a name. Thus a hit warns, and it never fails
+ * the report.
+ */
+const NUMERAL_PATTERN = /(?<![A-Za-z0-9])-?\d+(?:\.\d+)?%?/g;
+/** Warn for each free-standing numeral that the prose of one block carries. */
+export function numeralWarnings(blockId, prose) {
+    const warnings = [];
+    for (const match of prose.matchAll(NUMERAL_PATTERN)) {
+        warnings.push({ blockId, kind: "free-numeral", detail: match[0] });
+    }
+    return warnings;
+}
+/**
+ * Walk a block tree, and report each reference, each repeated id, and each free numeral.
+ *
+ * An id is what makes a block addressable, thus an amend by id is well defined only while each id belongs
+ * to one block. The walk is pre-order, thus the references follow the document order.
+ */
+export function walkBlocks(blocks) {
+    const references = [];
+    const warnings = [];
+    const seenIds = new Set();
+    const repeated = new Set();
+    const visit = (block) => {
+        if (seenIds.has(block.id)) {
+            repeated.add(block.id);
+        }
+        else {
+            seenIds.add(block.id);
+        }
+        switch (block.kind) {
+            case "section":
+                for (const child of block.blocks) {
+                    visit(child);
+                }
+                return;
+            case "text":
+                warnings.push(...numeralWarnings(block.id, block.content.prose));
+                return;
+            case "claim":
+                warnings.push(...numeralWarnings(block.id, block.content.prose));
+                for (const binding of block.bindings) {
+                    references.push({ blockId: block.id, reference: binding });
+                }
+                return;
+            case "metric":
+                references.push({ blockId: block.id, reference: block.value });
+                return;
+            case "chart": {
+                const encoding = block.encoding;
+                const encodingColumns = [encoding.x, encoding.y, encoding.group, encoding.value].filter((column) => column !== undefined);
+                references.push({ blockId: block.id, reference: block.binding, encodingColumns });
+                return;
+            }
+            case "table":
+            case "figure":
+            case "citation":
+                references.push({ blockId: block.id, reference: block.binding });
+                return;
+        }
+    };
+    for (const block of blocks) {
+        visit(block);
+    }
+    return { references, repeatedIds: [...repeated].sort(), warnings };
+}

package/dist/report-model/draft-finish.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The finish of a draft.
+ *
+ * An edit refuses what is wrong. The finish refuses what is missing. Thus the finish gates the whole
+ * draft one time: the full document schema, the unique ids, and the structural tier over every reference.
+ *
+ * The finish opens no file, and it reads the snapshot alone. Thus it runs the structural tier only, and
+ * the value tier stays in the gate of the report pipeline. The chart encoding-column match needs the rows
+ * behind a binding, thus it stays with the value tier.
+ *
+ * The free-numeral scan needs no file, thus the finish runs it and reports each hit as a warning. A
+ * warning never makes a draft invalid, and it rides beside the outcome in either case. Without the
+ * channel a caller could not read the one signal that catches a figure typed into prose with no metric
+ * block behind it.
+ *
+ * The result is plain data. A gap is an expected outcome, not an error, thus the finish never throws. On
+ * a pass the finish gives the valid document, and it does not change the draft.
+ */
+import { type ReportDocument } from "../contracts/report-blocks.js";
+import type { UnresolvedReference } from "../contracts/report-reference.js";
+import { type ReportWarning } from "./block-walk.js";
+import type { DraftDocument } from "./draft.js";
+import type { ReportSnapshot } from "./reference-resolver.js";
+/** A schema conformance gap, reduced to a path and a message. */
+export interface SchemaGap {
+    kind: "schema";
+    path: string;
+    message: string;
+}
+/** A duplicate id gap. More than one block holds the id. */
+export interface DuplicateIdGap {
+    kind: "duplicate-id";
+    id: string;
+}
+/** An unresolved reference gap. It ties the block that carries the reference to the reason it did not resolve. */
+export interface UnresolvedReferenceGap {
+    kind: "unresolved-reference";
+    blockId: string;
+    failure: UnresolvedReference;
+}
+/** One completeness gap of a draft. The kind set is closed. */
+export type FinishGap = SchemaGap | DuplicateIdGap | UnresolvedReferenceGap;
+/**
+ * The finish result. On a pass it gives the valid document. On a fail it gives each gap. The warnings
+ * ride along in either case, because a warning is advisory and it never decides the outcome.
+ */
+export type FinishResult = {
+    valid: true;
+    document: ReportDocument;
+    warnings: ReportWarning[];
+} | {
+    valid: false;
+    gaps: FinishGap[];
+    warnings: ReportWarning[];
+};
+/**
+ * Finish a draft. The finish validates the schema, the unique ids, and the structural resolution of each
+ * reference, and it reports each gap as data. It warns about each free numeral in prose.
+ */
+export declare function finishDraft(draft: DraftDocument, snapshot: ReportSnapshot): FinishResult;

package/dist/report-model/draft-finish.js

@@ -0,0 +1,56 @@
+/**
+ * The finish of a draft.
+ *
+ * An edit refuses what is wrong. The finish refuses what is missing. Thus the finish gates the whole
+ * draft one time: the full document schema, the unique ids, and the structural tier over every reference.
+ *
+ * The finish opens no file, and it reads the snapshot alone. Thus it runs the structural tier only, and
+ * the value tier stays in the gate of the report pipeline. The chart encoding-column match needs the rows
+ * behind a binding, thus it stays with the value tier.
+ *
+ * The free-numeral scan needs no file, thus the finish runs it and reports each hit as a warning. A
+ * warning never makes a draft invalid, and it rides beside the outcome in either case. Without the
+ * channel a caller could not read the one signal that catches a figure typed into prose with no metric
+ * block behind it.
+ *
+ * The result is plain data. A gap is an expected outcome, not an error, thus the finish never throws. On
+ * a pass the finish gives the valid document, and it does not change the draft.
+ */
+import { ReportDocumentSchema } from "../contracts/report-blocks.js";
+import { walkBlocks } from "./block-walk.js";
+import { validateReferenceStructure } from "./structural-validation.js";
+/**
+ * Finish a draft. The finish validates the schema, the unique ids, and the structural resolution of each
+ * reference, and it reports each gap as data. It warns about each free numeral in prose.
+ */
+export function finishDraft(draft, snapshot) {
+    const gaps = [];
+    const parsed = ReportDocumentSchema.safeParse(draft);
+    if (!parsed.success) {
+        for (const issue of parsed.error.issues) {
+            gaps.push({
+                kind: "schema",
+                path: issue.path.map((segment) => String(segment)).join("."),
+                message: issue.message,
+            });
+        }
+    }
+    // The walk reads the draft tree, not the parse result. The draft is already typed, thus the walk stays
+    // well-defined even when the schema parse fails, and a caller still gets the id and reference gaps.
+    const { references, repeatedIds, warnings } = walkBlocks(draft.sections);
+    for (const id of repeatedIds) {
+        gaps.push({ kind: "duplicate-id", id });
+    }
+    for (const entry of references) {
+        const result = validateReferenceStructure(entry.reference, snapshot);
+        if (result.isErr()) {
+            gaps.push({ kind: "unresolved-reference", blockId: entry.blockId, failure: result.error });
+        }
+    }
+    // A schema failure always pushes a gap. Thus an empty gap list means the parse passed. The
+    // `parsed.success` test also narrows the type for the document return.
+    if (!parsed.success || gaps.length > 0) {
+        return { valid: false, gaps, warnings };
+    }
+    return { valid: true, document: parsed.data, warnings };
+}

package/dist/report-model/draft-operations.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The pure operations that compose a draft report document.
+ *
+ * An operation takes the draft, an operation value, and the pinned snapshot. It gives a new draft, or a
+ * typed refusal in the error channel. It mutates nothing. Thus a refused operation leaves the input draft
+ * as it was.
+ *
+ * An operation validates the delta only. It parses the new payload with the draft grammar. It scans the
+ * ids that the payload brings, and it resolves each new reference against the snapshot with the
+ * structural tier. The completeness rules gate one time, at the finish.
+ *
+ * The candidate shares each untouched branch with the input draft. An operation rebuilds only the path to
+ * the edit. Thus the input stays intact, and the memory cost stays small.
+ *
+ * A destination names an anchor, not an index. An index breaks when the tree changes under the agent, and
+ * an anchor id stays stable.
+ */
+import { type Result } from "neverthrow";
+import type { UnresolvedReference } from "../contracts/report-reference.js";
+import { type DraftBlock, type DraftDocument, type DraftSectionBlock } from "./draft.js";
+import type { ReportSnapshot } from "./reference-resolver.js";
+/**
+ * The closed set of refusal reasons. Each operation gives a subset of these.
+ *
+ * `unknown-target` means that no block holds an id that the operation named. `conflicting-destination`
+ * means that the destination named two places at one time. The two are separate because the repair
+ * differs: the first sends the agent to the outline for a correct id, and the second tells it to drop one
+ * of the fields it gave.
+ */
+export type DraftRefusalReason = "malformed-block" | "duplicate-id" | "unknown-target" | "conflicting-destination" | "unresolved-reference" | "cycle" | "atom-at-root" | "not-a-section" | "payload-kind-mismatch";
+/**
+ * A typed refusal. It carries the reason and a prose detail. The `unresolved-reference` reason also
+ * carries each reference that the snapshot does not resolve.
+ */
+export type DraftRefusal = {
+    reason: Exclude<DraftRefusalReason, "unresolved-reference">;
+    detail: string;
+} | {
+    reason: "unresolved-reference";
+    detail: string;
+    unresolved: UnresolvedReference[];
+};
+/** The place inside a parent. The default place is `end`. An anchor names a sibling id. */
+export type DraftPlace = "start" | "end" | {
+    before: string;
+} | {
+    after: string;
+};
+/** The destination of an add or a move. `parentId` names a section, or the root when it is absent. */
+export interface DraftDestination {
+    parentId?: string;
+    place?: DraftPlace;
+}
+/** The add operation value. The payload can be an atom, or a section that carries children. */
+export interface AddOperation {
+    block: unknown;
+    destination?: DraftDestination;
+}
+/**
+ * The change operation value. A `title` retitles a section target. A `block` replaces an atom target.
+ * The operation stamps the target id on the block, thus an id mismatch is unrepresentable.
+ */
+export type ChangeOperation = {
+    targetId: string;
+} & ({
+    title: string;
+} | {
+    block: unknown;
+});
+/** The remove operation value. It names one block by its id. */
+export interface RemoveOperation {
+    targetId: string;
+}
+/** The move operation value. It names one block, and a destination with the shape of the add destination. */
+export interface MoveOperation {
+    targetId: string;
+    destination?: DraftDestination;
+}
+/**
+ * Set the title of the document.
+ *
+ * A title carries no id and no reference, thus it needs none of the shared checks and it cannot refuse.
+ * The document schema requires a non-empty title, and the finish reports an empty one as a gap.
+ */
+export declare function setTitle(draft: DraftDocument, title: string): DraftDocument;
+/**
+ * Add a block at a destination.
+ *
+ * The root admits a section only, thus an atom at the root refuses. The validation covers the payload and
+ * each of its descendants.
+ */
+export declare function addBlock(draft: DraftDocument, operation: AddOperation, snapshot: ReportSnapshot): Result<DraftDocument, DraftRefusal>;
+/**
+ * Change one block by its id.
+ *
+ * A section target takes a title, and its children stay as they are. An atom target takes a full block,
+ * and a kind change is permitted. A payload that does not match the target kind refuses.
+ */
+export declare function changeBlock(draft: DraftDocument, operation: ChangeOperation, snapshot: ReportSnapshot): Result<DraftDocument, DraftRefusal>;
+/**
+ * Remove one block by its id.
+ *
+ * A removed section takes its whole subtree. A removed id is free for a later add.
+ */
+export declare function removeBlock(draft: DraftDocument, operation: RemoveOperation, snapshot: ReportSnapshot): Result<DraftDocument, DraftRefusal>;
+/**
+ * Move one block to a destination.
+ *
+ * The moved block keeps its subtree. A section must not move into its own subtree, thus a move into the
+ * subtree refuses with a cycle. A move with the moved block as its own anchor refuses.
+ */
+export declare function moveBlock(draft: DraftDocument, operation: MoveOperation, snapshot: ReportSnapshot): Result<DraftDocument, DraftRefusal>;
+/** One block, the path of child indices from the root to the block, and the section that holds it. */
+export interface Located {
+    block: DraftBlock;
+    path: number[];
+    /** The section that holds the block, or `undefined` when the block sits at the root. */
+    parent?: DraftSectionBlock;
+}
+/**
+ * Find a block by its id, with the path from the root. The search visits each block one time.
+ *
+ * The read surface needs the same search, thus this is the one find-by-id in the draft model.
+ */
+export declare function locate(document: DraftDocument, id: string): Located | undefined;