@ai-matrx/agents 0.18.1 → 0.19.1

package/dist/sources/runtime/index.d.cts

@@ -60,6 +60,14 @@ interface SourceDraft {
     notes?: string[] | undefined;
     /** The person asked to wait for the clean version before anything runs. */
     waitForClean?: boolean | undefined;
+    /**
+     * Where the picked parts sit in the Source (label + pages), remembered when
+     * they are picked. A Source still being cleaned lists its raw pages; when the
+     * clean version lands its parts have NEW ids, and the pick is carried over by
+     * page from here (verify-3: "0 characters · 4 of 21 parts"). Persisted with
+     * the draft, so it survives a reload.
+     */
+    pickedParts?: SourcePickedPart[] | undefined;
     /**
      * What the person handed over, kept ONLY while the Source is still landing
      * (or failed) so a reload or a failure never loses it: the pasted text, the
@@ -68,6 +76,13 @@ interface SourceDraft {
      */
     input?: SourceIntakeInput | undefined;
 }
+/** One picked part as the person saw it: its id, its label, and the pages it covers. */
+interface SourcePickedPart {
+    id: string;
+    label: string;
+    /** First and last page it covers, when the Source has pages. */
+    pages?: [number, number] | undefined;
+}
 type SourceCardStatus = "pending" | "resolving" | "ready" | "error";
 /** One card: the draft, its lifecycle, and what the server measured. */
 interface SourceCardModel {
@@ -131,7 +146,7 @@ declare function deliveryPatch(delivery: SourceDelivery): Pick<SourceRefOptions,
 interface DeliveryWords {
     /** The choice's name on a control. */
     label: string;
-    /** One sentence under the control: what happens, in plain words. */
+    /** Two or three words under the control: what happens (copy law R9). */
     hint: string;
     /** The short phrase a summary line uses. */
     summary: string;
@@ -241,7 +256,7 @@ declare const MAX_KEPT_TEXT_KNOB: {
     readonly key: "max_kept_draft_chars";
 };
 /** Said on a pasted card whose text is too large (or the limit unreadable) to keep for a reload. */
-declare const NOT_KEPT_FOR_RELOAD = "Too large to keep on this device, so it will not come back if the page reloads before it is added.";
+declare const NOT_KEPT_FOR_RELOAD = "Too large to restore if the page reloads before it is added.";
 /**
  * A landing stopped only because no organization is chosen yet. The card
  * waits; the moment one is set the intake lands every waiting card again from
@@ -356,7 +371,13 @@ interface SourcePlanEntry {
     formLabel: string;
     /** Characters of the chosen form before parts/cap. */
     formChars: number;
-    /** Characters the model receives for this Source (grounding headers included). */
+    /**
+     * THE one size of this Source — the same number its card and the header show
+     * (`sourceEntryChars`: the chosen form or picked parts, capped). What a person
+     * sees; `sentChars` is only the budget's exact wire length.
+     */
+    chars: number;
+    /** Characters the model receives for this Source (grounding headers included) — the budget's measure. */
     sentChars: number;
     sentTokens: number;
     /** True when parts are known, so `sentChars` is exact; false = the text body only. */
@@ -370,6 +391,9 @@ interface SourcePlanEntry {
 type BudgetVerdict = "empty" | "fine" | "heavy" | "too_much";
 interface SourcePlan {
     entries: SourcePlanEntry[];
+    /** THE one size of what goes in (sum of `chars` of the Sources whose text goes in) — shown to the person. */
+    chars: number;
+    /** The exact wire length the budget is judged on (grounding headers included). */
     sentChars: number;
     sentTokens: number;
     /** Window the verdict is judged against. */
@@ -512,6 +536,10 @@ declare function createFetchSourcesTransport(options: FetchSourcesTransportOptio
  */
 
 declare const EMPTY_SOURCE_SET_STATE: SourceSetState;
+/** Said when a Source's parts were re-read (the clean version landed) and the pick was carried over by page. */
+declare const PARTS_MATCHED_BY_PAGE = "The clean version is ready \u2014 your parts were matched to it by page.";
+/** Said when a pick could not be carried over to the Source's new parts: the whole Source goes in until parts are chosen again. */
+declare const PARTS_NOT_MATCHED = "The clean version is ready, but your parts could not be matched to it \u2014 choose parts again. Until then the whole Source goes in.";
 /** Said on the one card kept when the same Source lands twice. */
 declare const SAME_SOURCE_AGAIN = "You added this again \u2014 it is the same Source, so it is listed once.";
 declare function isSourceDraft(value: unknown): value is SourceDraft;
@@ -540,6 +568,10 @@ declare function settleCard(state: SourceSetState, id: string, patch: Partial<So
 }, options?: {
     defaultForm?: string | undefined;
 }): SourceSetState;
+/**
+ * A card that failed has ONE state — failed. Its last measurement goes, so it
+ * can never also say "Still being read" (verify-3: a stored PDF showed both).
+ */
 declare function failCard(state: SourceSetState, id: string, sentence: string): SourceSetState;
 /** Back to landing (after a reload or a failure). */
 declare function restartCard(state: SourceSetState, id: string): SourceSetState;
@@ -548,10 +580,35 @@ declare function updateCardDraft(state: SourceSetState, id: string, patch: Parti
 declare function removeCard(state: SourceSetState, id: string): SourceSetState;
 /** Change the pointer's choices (form, parts, cap, delivery). */
 declare function updateCardRef(state: SourceSetState, id: string, options: SourceRefOptions): SourceSetState;
+/**
+ * Remember where the picked parts sit (label + pages) from the card's current
+ * measurement, so a pick survives the Source being re-split (raw pages → clean
+ * parts). No parts picked = nothing remembered.
+ */
+declare function rememberPickedParts(card: SourceCardModel): SourceCardModel;
+/**
+ * A fresh measurement listed NEW parts (the clean version landed, so the raw
+ * pages the person picked no longer exist by id). Carry the pick over by page:
+ * every new part that covers a page the old pick covered goes in. When the old
+ * pick's pages are unknown, the pick is cleared and the card says so — never
+ * "0 characters · 4 of 21 parts" with nothing ticked (verify-3, 11d/11e).
+ */
+declare function carryPickedParts(card: SourceCardModel, entry: SourceManifestEntry): SourceCardModel;
 declare function setCardWaitForClean(state: SourceSetState, id: string, wait: boolean): SourceSetState;
 declare function setSourceTopic(state: SourceSetState, topic: string): SourceSetState;
-/** Apply a set the review returned (forms, parts, caps, delivery) — and its topic. */
-declare function applyReviewedSourceSet(state: SourceSetState, set: SourceSet): SourceSetState;
+/**
+ * What the person removed in "Review what goes in": the Sources that went INTO
+ * the review (`reviewed`) and did not come back in its answer — keyed by
+ * `sourceKey`. A Source that landed while the review was open is never in
+ * `reviewed`, so it is never removed by it (verify-4 V4-F #3).
+ */
+declare function removedInReview(reviewed: SourceSet, answer: SourceSet): Set<string>;
+/**
+ * Apply a set the review returned (forms, parts, caps, delivery) — and its
+ * topic. Pass `reviewed` (the set that was sent INTO the review) and every
+ * Source removed there leaves the list, bound by its own card id.
+ */
+declare function applyReviewedSourceSet(state: SourceSetState, set: SourceSet, reviewed?: SourceSet): SourceSetState;
 /** The server measured the ready Sources: each ready card takes its entry. */
 declare function applyManifest(state: SourceSetState, manifest: SourceManifest): SourceSetState;
 /**
@@ -581,6 +638,24 @@ declare function selectSourceSet(state: SourceSetState, options?: {
  * picked parts, capped — measured against each card's CURRENT pointer.
  */
 declare function selectTotalChars(state: SourceSetState): number;
+/**
+ * THE one size of one Source (verify-3: one Source read 109k, 115k, 108k and
+ * 106k on four screens): the contract's rule — the chosen form, or the picked
+ * parts, capped by `max_chars` — measured against the card's CURRENT pointer.
+ * The card, the header total (`selectTotalChars`) and the review (`SourcePlanEntry.chars`)
+ * all read this. Null when it is not measured or cannot go in.
+ */
+declare function sourceEntryChars(entry: SourceManifestEntry, ref: SourceRef): number | null;
+declare function sourceCardChars(card: Pick<SourceCardModel, "draft" | "manifest">): number | null;
+/**
+ * THE one state of one Source card, derived once: its own lifecycle wins
+ * (adding, waiting for an organization, failed); only a card that landed takes
+ * the server's measured state. Never two states at once.
+ */
+type SourceCardState = "adding" | "waiting_for_organization" | "failed" | "unmeasured" | SourceManifestEntry["state"];
+declare function sourceCardState(card: Pick<SourceCardModel, "status" | "error" | "manifest">): SourceCardState;
+/** The server's measured state to show on a card — only for a card that landed (null otherwise). */
+declare function sourceCardMeasuredState(card: Pick<SourceCardModel, "status" | "error" | "manifest">): SourceManifestEntry["state"] | null;
 /** Every Source finished landing (nothing pending) and none failed. */
 declare function selectSettled(state: SourceSetState): boolean;
 /** How many more Sources fit under the host's max (Infinity when there is none). */
@@ -690,8 +765,14 @@ interface SourceSetController extends SourceSetActions {
     toSourceSet(options?: {
         targetModelId?: string | undefined;
     }): SourceSet;
-    /** Apply a set the review returned (forms, parts, caps, delivery). */
-    applySourceSet(set: SourceSet): void;
+    /**
+     * Apply a set the review returned (forms, parts, caps, delivery). Pass
+     * `reviewed` — the set sent INTO the review — and every Source removed there
+     * leaves the list too (only those; one that landed meanwhile stays).
+     */
+    applySourceSet(set: SourceSet, options?: {
+        reviewed?: SourceSet | undefined;
+    }): void;
     /** POST /sources/resolve — the grounded text for a generator, named as the cards name them. */
     resolve(options?: {
         targetModelId?: string | undefined;
@@ -856,15 +937,33 @@ interface SourceIntakeDeps<Body extends SourceLandingBodyBase = SourceLandingBod
 interface SourceIntake {
     addPastedText(text: string, name?: string): Promise<void>;
     addWebPage(url: string): Promise<void>;
-    /** A page the host's web picker already read (and the scraper landed); null id = land its text instead. */
+    /**
+     * A page the host's web picker already read (and the scraper landed); null id
+     * = land its text instead. `pendingId` = the card `beginWebPage` made when the
+     * read started — it is settled instead of a new card being added.
+     */
     addScrapedPage(page: {
         url: string;
         title: string;
         text: string;
         processedDocumentId: string | null;
-    }): Promise<void>;
+    }, pendingId?: string | null): Promise<void>;
+    /**
+     * The host's web picker STARTED reading a link: a card with the link kept
+     * appears at once, so a reload mid-read brings it back and lands it (verify-3
+     * 12a/12b: a reload while a page was read lost it, link and all). Finish it
+     * with `addScrapedPage(page, id)`; if the person drops the preview, remove it;
+     * if the picker goes away mid-read, `resume(card)` lands it through the web door.
+     */
+    beginWebPage(url: string): string;
     /** Files the host's uploader already uploaded. */
     addUploaded(files: readonly UploadedSourceFile[], kind: SourceKindId): Promise<void>;
+    /**
+     * A recording made in place (the Voice Pad) that is already written out: it
+     * lands as text, but it IS a recording — its card and review say "Recording",
+     * never "Pasted text" — and it keeps its name ("Recording 3:41 PM").
+     */
+    addRecordedText(text: string, name?: string): Promise<void>;
     /** A recording already uploaded — written out, then landed. */
     addUploadedRecording(file: UploadedSourceFile): Promise<void>;
     /** Something the person already has (Use existing / search). Returns false when already picked. */
@@ -956,4 +1055,4 @@ declare function lookAtFileCards(cards: readonly SourceCardModel[], ctx: {
     signal: AbortSignal;
 } & FileRecoveryDeps): Promise<boolean>;
 
-export { type BudgetVerdict, DELIVERY_CHOICES, DELIVERY_WORDS, type DeliveryWords, EMPTY_SOURCE_SET_STATE, type FetchSourcesTransportOptions, type FileRecoveryDeps, type FileSourceContext, type FileSourceStatus, type FileSourceStep, HEAVY_SHARE, KEEP_WAITING_FOR_ORGANIZATION, MAX_KEPT_TEXT_KNOB, NOT_KEPT_FOR_RELOAD, type PartMatchIds, type PersistedSourceCard, type PersistedSourceInput, type PlanInput, RELOADED_RESUMING, RELOADED_WHILE_ADDING, type ReloadedCard, SAME_SOURCE_AGAIN, SOURCE_CHARS_PER_TOKEN, type ScrapedSourcePage, type SourceAssociationEdge, type SourceAssociationResult, type SourceAttachTarget, type SourceAttachTo, type SourceCallOptions, type SourceCardModel, type SourceCardStatus, SourceDelivery, type SourceDoorCalls, SourceDoorError, type SourceDoorPath, type SourceDraft, type SourceDraftStorage, type SourceFileRunner, type SourceIntake, type SourceIntakeDeps, type SourceIntakeDoors, type SourceIntakeInput, type SourceKindId, type SourceLandingAnswer, type SourceLandingBodyBase, type SourceLandingNotice, type SourcePart, type SourcePartsSearchResult, type SourcePlan, type SourcePlanEntry, type SourcePlanStatus, type SourceSetActions, type SourceSetAdapter, type SourceSetConfig, type SourceSetController, type SourceSetMeta, type SourceSetState, type SourceSetStore, type SourceTileId, type SourceTransportOptions, type SourcesClient, type SourcesTransport, type UploadedSourceFile, WAITING_FOR_ORGANIZATION, type YouTubeTranscriptResult, addPendingCard, addReadyCard, allowedDeliveries, applyManifest, applyReviewedSourceSet, cardsToResume, cardsWaitingForOrganization, chosenForm, continueAfterOrganization, createFetchSourcesTransport, createMemorySourceDraftStorage, createMemorySourceSetStore, createSourceIntake, createSourceSetController, createSourcesClient, deliveryChoicesFor, deliveryPatch, deliverySwitchedNote, draftKindForToken, estimateSourceTokens, failCard, fileCardHeldForOrganization, fileSourcePollDelayMs, findParts, fitCardDeliveries, fitDelivery, hasSourceRef, isAskableFileCard, isSourceDraft, isWaitingFileCard, isWordQuery, lookAtFileCards, matchesPart, nextFileStep, partPages, planSourceReview, readPersistedSourceInput, readySourceRefs, registeredFileEdge, reloadedCard, removeCard, renderedPartChars, restartCard, restoredCards, resumableInput, resumeInterrupted, sameSourceRef, selectSettled, selectSourceSet, selectTotalChars, setCardWaitForClean, setSourceTopic, settleCard, sourceAttachTargets, sourceDelivery, sourceKey, sourceRecoveryGuards, sourceRoomLeft, toPersistedSourceInput, updateCardDraft, updateCardRef, uploadCutOffSentence, withDefaultForm, withDisplayNames };
+export { type BudgetVerdict, DELIVERY_CHOICES, DELIVERY_WORDS, type DeliveryWords, EMPTY_SOURCE_SET_STATE, type FetchSourcesTransportOptions, type FileRecoveryDeps, type FileSourceContext, type FileSourceStatus, type FileSourceStep, HEAVY_SHARE, KEEP_WAITING_FOR_ORGANIZATION, MAX_KEPT_TEXT_KNOB, NOT_KEPT_FOR_RELOAD, PARTS_MATCHED_BY_PAGE, PARTS_NOT_MATCHED, type PartMatchIds, type PersistedSourceCard, type PersistedSourceInput, type PlanInput, RELOADED_RESUMING, RELOADED_WHILE_ADDING, type ReloadedCard, SAME_SOURCE_AGAIN, SOURCE_CHARS_PER_TOKEN, type ScrapedSourcePage, type SourceAssociationEdge, type SourceAssociationResult, type SourceAttachTarget, type SourceAttachTo, type SourceCallOptions, type SourceCardModel, type SourceCardState, type SourceCardStatus, SourceDelivery, type SourceDoorCalls, SourceDoorError, type SourceDoorPath, type SourceDraft, type SourceDraftStorage, type SourceFileRunner, type SourceIntake, type SourceIntakeDeps, type SourceIntakeDoors, type SourceIntakeInput, type SourceKindId, type SourceLandingAnswer, type SourceLandingBodyBase, type SourceLandingNotice, type SourcePart, type SourcePartsSearchResult, type SourcePickedPart, type SourcePlan, type SourcePlanEntry, type SourcePlanStatus, type SourceSetActions, type SourceSetAdapter, type SourceSetConfig, type SourceSetController, type SourceSetMeta, type SourceSetState, type SourceSetStore, type SourceTileId, type SourceTransportOptions, type SourcesClient, type SourcesTransport, type UploadedSourceFile, WAITING_FOR_ORGANIZATION, type YouTubeTranscriptResult, addPendingCard, addReadyCard, allowedDeliveries, applyManifest, applyReviewedSourceSet, cardsToResume, cardsWaitingForOrganization, carryPickedParts, chosenForm, continueAfterOrganization, createFetchSourcesTransport, createMemorySourceDraftStorage, createMemorySourceSetStore, createSourceIntake, createSourceSetController, createSourcesClient, deliveryChoicesFor, deliveryPatch, deliverySwitchedNote, draftKindForToken, estimateSourceTokens, failCard, fileCardHeldForOrganization, fileSourcePollDelayMs, findParts, fitCardDeliveries, fitDelivery, hasSourceRef, isAskableFileCard, isSourceDraft, isWaitingFileCard, isWordQuery, lookAtFileCards, matchesPart, nextFileStep, partPages, planSourceReview, readPersistedSourceInput, readySourceRefs, registeredFileEdge, reloadedCard, rememberPickedParts, removeCard, removedInReview, renderedPartChars, restartCard, restoredCards, resumableInput, resumeInterrupted, sameSourceRef, selectSettled, selectSourceSet, selectTotalChars, setCardWaitForClean, setSourceTopic, settleCard, sourceAttachTargets, sourceCardChars, sourceCardMeasuredState, sourceCardState, sourceDelivery, sourceEntryChars, sourceKey, sourceRecoveryGuards, sourceRoomLeft, toPersistedSourceInput, updateCardDraft, updateCardRef, uploadCutOffSentence, withDefaultForm, withDisplayNames };

package/dist/sources/runtime/index.d.ts

@@ -60,6 +60,14 @@ interface SourceDraft {
     notes?: string[] | undefined;
     /** The person asked to wait for the clean version before anything runs. */
     waitForClean?: boolean | undefined;
+    /**
+     * Where the picked parts sit in the Source (label + pages), remembered when
+     * they are picked. A Source still being cleaned lists its raw pages; when the
+     * clean version lands its parts have NEW ids, and the pick is carried over by
+     * page from here (verify-3: "0 characters · 4 of 21 parts"). Persisted with
+     * the draft, so it survives a reload.
+     */
+    pickedParts?: SourcePickedPart[] | undefined;
     /**
      * What the person handed over, kept ONLY while the Source is still landing
      * (or failed) so a reload or a failure never loses it: the pasted text, the
@@ -68,6 +76,13 @@ interface SourceDraft {
      */
     input?: SourceIntakeInput | undefined;
 }
+/** One picked part as the person saw it: its id, its label, and the pages it covers. */
+interface SourcePickedPart {
+    id: string;
+    label: string;
+    /** First and last page it covers, when the Source has pages. */
+    pages?: [number, number] | undefined;
+}
 type SourceCardStatus = "pending" | "resolving" | "ready" | "error";
 /** One card: the draft, its lifecycle, and what the server measured. */
 interface SourceCardModel {
@@ -131,7 +146,7 @@ declare function deliveryPatch(delivery: SourceDelivery): Pick<SourceRefOptions,
 interface DeliveryWords {
     /** The choice's name on a control. */
     label: string;
-    /** One sentence under the control: what happens, in plain words. */
+    /** Two or three words under the control: what happens (copy law R9). */
     hint: string;
     /** The short phrase a summary line uses. */
     summary: string;
@@ -241,7 +256,7 @@ declare const MAX_KEPT_TEXT_KNOB: {
     readonly key: "max_kept_draft_chars";
 };
 /** Said on a pasted card whose text is too large (or the limit unreadable) to keep for a reload. */
-declare const NOT_KEPT_FOR_RELOAD = "Too large to keep on this device, so it will not come back if the page reloads before it is added.";
+declare const NOT_KEPT_FOR_RELOAD = "Too large to restore if the page reloads before it is added.";
 /**
  * A landing stopped only because no organization is chosen yet. The card
  * waits; the moment one is set the intake lands every waiting card again from
@@ -356,7 +371,13 @@ interface SourcePlanEntry {
     formLabel: string;
     /** Characters of the chosen form before parts/cap. */
     formChars: number;
-    /** Characters the model receives for this Source (grounding headers included). */
+    /**
+     * THE one size of this Source — the same number its card and the header show
+     * (`sourceEntryChars`: the chosen form or picked parts, capped). What a person
+     * sees; `sentChars` is only the budget's exact wire length.
+     */
+    chars: number;
+    /** Characters the model receives for this Source (grounding headers included) — the budget's measure. */
     sentChars: number;
     sentTokens: number;
     /** True when parts are known, so `sentChars` is exact; false = the text body only. */
@@ -370,6 +391,9 @@ interface SourcePlanEntry {
 type BudgetVerdict = "empty" | "fine" | "heavy" | "too_much";
 interface SourcePlan {
     entries: SourcePlanEntry[];
+    /** THE one size of what goes in (sum of `chars` of the Sources whose text goes in) — shown to the person. */
+    chars: number;
+    /** The exact wire length the budget is judged on (grounding headers included). */
     sentChars: number;
     sentTokens: number;
     /** Window the verdict is judged against. */
@@ -512,6 +536,10 @@ declare function createFetchSourcesTransport(options: FetchSourcesTransportOptio
  */
 
 declare const EMPTY_SOURCE_SET_STATE: SourceSetState;
+/** Said when a Source's parts were re-read (the clean version landed) and the pick was carried over by page. */
+declare const PARTS_MATCHED_BY_PAGE = "The clean version is ready \u2014 your parts were matched to it by page.";
+/** Said when a pick could not be carried over to the Source's new parts: the whole Source goes in until parts are chosen again. */
+declare const PARTS_NOT_MATCHED = "The clean version is ready, but your parts could not be matched to it \u2014 choose parts again. Until then the whole Source goes in.";
 /** Said on the one card kept when the same Source lands twice. */
 declare const SAME_SOURCE_AGAIN = "You added this again \u2014 it is the same Source, so it is listed once.";
 declare function isSourceDraft(value: unknown): value is SourceDraft;
@@ -540,6 +568,10 @@ declare function settleCard(state: SourceSetState, id: string, patch: Partial<So
 }, options?: {
     defaultForm?: string | undefined;
 }): SourceSetState;
+/**
+ * A card that failed has ONE state — failed. Its last measurement goes, so it
+ * can never also say "Still being read" (verify-3: a stored PDF showed both).
+ */
 declare function failCard(state: SourceSetState, id: string, sentence: string): SourceSetState;
 /** Back to landing (after a reload or a failure). */
 declare function restartCard(state: SourceSetState, id: string): SourceSetState;
@@ -548,10 +580,35 @@ declare function updateCardDraft(state: SourceSetState, id: string, patch: Parti
 declare function removeCard(state: SourceSetState, id: string): SourceSetState;
 /** Change the pointer's choices (form, parts, cap, delivery). */
 declare function updateCardRef(state: SourceSetState, id: string, options: SourceRefOptions): SourceSetState;
+/**
+ * Remember where the picked parts sit (label + pages) from the card's current
+ * measurement, so a pick survives the Source being re-split (raw pages → clean
+ * parts). No parts picked = nothing remembered.
+ */
+declare function rememberPickedParts(card: SourceCardModel): SourceCardModel;
+/**
+ * A fresh measurement listed NEW parts (the clean version landed, so the raw
+ * pages the person picked no longer exist by id). Carry the pick over by page:
+ * every new part that covers a page the old pick covered goes in. When the old
+ * pick's pages are unknown, the pick is cleared and the card says so — never
+ * "0 characters · 4 of 21 parts" with nothing ticked (verify-3, 11d/11e).
+ */
+declare function carryPickedParts(card: SourceCardModel, entry: SourceManifestEntry): SourceCardModel;
 declare function setCardWaitForClean(state: SourceSetState, id: string, wait: boolean): SourceSetState;
 declare function setSourceTopic(state: SourceSetState, topic: string): SourceSetState;
-/** Apply a set the review returned (forms, parts, caps, delivery) — and its topic. */
-declare function applyReviewedSourceSet(state: SourceSetState, set: SourceSet): SourceSetState;
+/**
+ * What the person removed in "Review what goes in": the Sources that went INTO
+ * the review (`reviewed`) and did not come back in its answer — keyed by
+ * `sourceKey`. A Source that landed while the review was open is never in
+ * `reviewed`, so it is never removed by it (verify-4 V4-F #3).
+ */
+declare function removedInReview(reviewed: SourceSet, answer: SourceSet): Set<string>;
+/**
+ * Apply a set the review returned (forms, parts, caps, delivery) — and its
+ * topic. Pass `reviewed` (the set that was sent INTO the review) and every
+ * Source removed there leaves the list, bound by its own card id.
+ */
+declare function applyReviewedSourceSet(state: SourceSetState, set: SourceSet, reviewed?: SourceSet): SourceSetState;
 /** The server measured the ready Sources: each ready card takes its entry. */
 declare function applyManifest(state: SourceSetState, manifest: SourceManifest): SourceSetState;
 /**
@@ -581,6 +638,24 @@ declare function selectSourceSet(state: SourceSetState, options?: {
  * picked parts, capped — measured against each card's CURRENT pointer.
  */
 declare function selectTotalChars(state: SourceSetState): number;
+/**
+ * THE one size of one Source (verify-3: one Source read 109k, 115k, 108k and
+ * 106k on four screens): the contract's rule — the chosen form, or the picked
+ * parts, capped by `max_chars` — measured against the card's CURRENT pointer.
+ * The card, the header total (`selectTotalChars`) and the review (`SourcePlanEntry.chars`)
+ * all read this. Null when it is not measured or cannot go in.
+ */
+declare function sourceEntryChars(entry: SourceManifestEntry, ref: SourceRef): number | null;
+declare function sourceCardChars(card: Pick<SourceCardModel, "draft" | "manifest">): number | null;
+/**
+ * THE one state of one Source card, derived once: its own lifecycle wins
+ * (adding, waiting for an organization, failed); only a card that landed takes
+ * the server's measured state. Never two states at once.
+ */
+type SourceCardState = "adding" | "waiting_for_organization" | "failed" | "unmeasured" | SourceManifestEntry["state"];
+declare function sourceCardState(card: Pick<SourceCardModel, "status" | "error" | "manifest">): SourceCardState;
+/** The server's measured state to show on a card — only for a card that landed (null otherwise). */
+declare function sourceCardMeasuredState(card: Pick<SourceCardModel, "status" | "error" | "manifest">): SourceManifestEntry["state"] | null;
 /** Every Source finished landing (nothing pending) and none failed. */
 declare function selectSettled(state: SourceSetState): boolean;
 /** How many more Sources fit under the host's max (Infinity when there is none). */
@@ -690,8 +765,14 @@ interface SourceSetController extends SourceSetActions {
     toSourceSet(options?: {
         targetModelId?: string | undefined;
     }): SourceSet;
-    /** Apply a set the review returned (forms, parts, caps, delivery). */
-    applySourceSet(set: SourceSet): void;
+    /**
+     * Apply a set the review returned (forms, parts, caps, delivery). Pass
+     * `reviewed` — the set sent INTO the review — and every Source removed there
+     * leaves the list too (only those; one that landed meanwhile stays).
+     */
+    applySourceSet(set: SourceSet, options?: {
+        reviewed?: SourceSet | undefined;
+    }): void;
     /** POST /sources/resolve — the grounded text for a generator, named as the cards name them. */
     resolve(options?: {
         targetModelId?: string | undefined;
@@ -856,15 +937,33 @@ interface SourceIntakeDeps<Body extends SourceLandingBodyBase = SourceLandingBod
 interface SourceIntake {
     addPastedText(text: string, name?: string): Promise<void>;
     addWebPage(url: string): Promise<void>;
-    /** A page the host's web picker already read (and the scraper landed); null id = land its text instead. */
+    /**
+     * A page the host's web picker already read (and the scraper landed); null id
+     * = land its text instead. `pendingId` = the card `beginWebPage` made when the
+     * read started — it is settled instead of a new card being added.
+     */
     addScrapedPage(page: {
         url: string;
         title: string;
         text: string;
         processedDocumentId: string | null;
-    }): Promise<void>;
+    }, pendingId?: string | null): Promise<void>;
+    /**
+     * The host's web picker STARTED reading a link: a card with the link kept
+     * appears at once, so a reload mid-read brings it back and lands it (verify-3
+     * 12a/12b: a reload while a page was read lost it, link and all). Finish it
+     * with `addScrapedPage(page, id)`; if the person drops the preview, remove it;
+     * if the picker goes away mid-read, `resume(card)` lands it through the web door.
+     */
+    beginWebPage(url: string): string;
     /** Files the host's uploader already uploaded. */
     addUploaded(files: readonly UploadedSourceFile[], kind: SourceKindId): Promise<void>;
+    /**
+     * A recording made in place (the Voice Pad) that is already written out: it
+     * lands as text, but it IS a recording — its card and review say "Recording",
+     * never "Pasted text" — and it keeps its name ("Recording 3:41 PM").
+     */
+    addRecordedText(text: string, name?: string): Promise<void>;
     /** A recording already uploaded — written out, then landed. */
     addUploadedRecording(file: UploadedSourceFile): Promise<void>;
     /** Something the person already has (Use existing / search). Returns false when already picked. */
@@ -956,4 +1055,4 @@ declare function lookAtFileCards(cards: readonly SourceCardModel[], ctx: {
     signal: AbortSignal;
 } & FileRecoveryDeps): Promise<boolean>;
 
-export { type BudgetVerdict, DELIVERY_CHOICES, DELIVERY_WORDS, type DeliveryWords, EMPTY_SOURCE_SET_STATE, type FetchSourcesTransportOptions, type FileRecoveryDeps, type FileSourceContext, type FileSourceStatus, type FileSourceStep, HEAVY_SHARE, KEEP_WAITING_FOR_ORGANIZATION, MAX_KEPT_TEXT_KNOB, NOT_KEPT_FOR_RELOAD, type PartMatchIds, type PersistedSourceCard, type PersistedSourceInput, type PlanInput, RELOADED_RESUMING, RELOADED_WHILE_ADDING, type ReloadedCard, SAME_SOURCE_AGAIN, SOURCE_CHARS_PER_TOKEN, type ScrapedSourcePage, type SourceAssociationEdge, type SourceAssociationResult, type SourceAttachTarget, type SourceAttachTo, type SourceCallOptions, type SourceCardModel, type SourceCardStatus, SourceDelivery, type SourceDoorCalls, SourceDoorError, type SourceDoorPath, type SourceDraft, type SourceDraftStorage, type SourceFileRunner, type SourceIntake, type SourceIntakeDeps, type SourceIntakeDoors, type SourceIntakeInput, type SourceKindId, type SourceLandingAnswer, type SourceLandingBodyBase, type SourceLandingNotice, type SourcePart, type SourcePartsSearchResult, type SourcePlan, type SourcePlanEntry, type SourcePlanStatus, type SourceSetActions, type SourceSetAdapter, type SourceSetConfig, type SourceSetController, type SourceSetMeta, type SourceSetState, type SourceSetStore, type SourceTileId, type SourceTransportOptions, type SourcesClient, type SourcesTransport, type UploadedSourceFile, WAITING_FOR_ORGANIZATION, type YouTubeTranscriptResult, addPendingCard, addReadyCard, allowedDeliveries, applyManifest, applyReviewedSourceSet, cardsToResume, cardsWaitingForOrganization, chosenForm, continueAfterOrganization, createFetchSourcesTransport, createMemorySourceDraftStorage, createMemorySourceSetStore, createSourceIntake, createSourceSetController, createSourcesClient, deliveryChoicesFor, deliveryPatch, deliverySwitchedNote, draftKindForToken, estimateSourceTokens, failCard, fileCardHeldForOrganization, fileSourcePollDelayMs, findParts, fitCardDeliveries, fitDelivery, hasSourceRef, isAskableFileCard, isSourceDraft, isWaitingFileCard, isWordQuery, lookAtFileCards, matchesPart, nextFileStep, partPages, planSourceReview, readPersistedSourceInput, readySourceRefs, registeredFileEdge, reloadedCard, removeCard, renderedPartChars, restartCard, restoredCards, resumableInput, resumeInterrupted, sameSourceRef, selectSettled, selectSourceSet, selectTotalChars, setCardWaitForClean, setSourceTopic, settleCard, sourceAttachTargets, sourceDelivery, sourceKey, sourceRecoveryGuards, sourceRoomLeft, toPersistedSourceInput, updateCardDraft, updateCardRef, uploadCutOffSentence, withDefaultForm, withDisplayNames };
+export { type BudgetVerdict, DELIVERY_CHOICES, DELIVERY_WORDS, type DeliveryWords, EMPTY_SOURCE_SET_STATE, type FetchSourcesTransportOptions, type FileRecoveryDeps, type FileSourceContext, type FileSourceStatus, type FileSourceStep, HEAVY_SHARE, KEEP_WAITING_FOR_ORGANIZATION, MAX_KEPT_TEXT_KNOB, NOT_KEPT_FOR_RELOAD, PARTS_MATCHED_BY_PAGE, PARTS_NOT_MATCHED, type PartMatchIds, type PersistedSourceCard, type PersistedSourceInput, type PlanInput, RELOADED_RESUMING, RELOADED_WHILE_ADDING, type ReloadedCard, SAME_SOURCE_AGAIN, SOURCE_CHARS_PER_TOKEN, type ScrapedSourcePage, type SourceAssociationEdge, type SourceAssociationResult, type SourceAttachTarget, type SourceAttachTo, type SourceCallOptions, type SourceCardModel, type SourceCardState, type SourceCardStatus, SourceDelivery, type SourceDoorCalls, SourceDoorError, type SourceDoorPath, type SourceDraft, type SourceDraftStorage, type SourceFileRunner, type SourceIntake, type SourceIntakeDeps, type SourceIntakeDoors, type SourceIntakeInput, type SourceKindId, type SourceLandingAnswer, type SourceLandingBodyBase, type SourceLandingNotice, type SourcePart, type SourcePartsSearchResult, type SourcePickedPart, type SourcePlan, type SourcePlanEntry, type SourcePlanStatus, type SourceSetActions, type SourceSetAdapter, type SourceSetConfig, type SourceSetController, type SourceSetMeta, type SourceSetState, type SourceSetStore, type SourceTileId, type SourceTransportOptions, type SourcesClient, type SourcesTransport, type UploadedSourceFile, WAITING_FOR_ORGANIZATION, type YouTubeTranscriptResult, addPendingCard, addReadyCard, allowedDeliveries, applyManifest, applyReviewedSourceSet, cardsToResume, cardsWaitingForOrganization, carryPickedParts, chosenForm, continueAfterOrganization, createFetchSourcesTransport, createMemorySourceDraftStorage, createMemorySourceSetStore, createSourceIntake, createSourceSetController, createSourcesClient, deliveryChoicesFor, deliveryPatch, deliverySwitchedNote, draftKindForToken, estimateSourceTokens, failCard, fileCardHeldForOrganization, fileSourcePollDelayMs, findParts, fitCardDeliveries, fitDelivery, hasSourceRef, isAskableFileCard, isSourceDraft, isWaitingFileCard, isWordQuery, lookAtFileCards, matchesPart, nextFileStep, partPages, planSourceReview, readPersistedSourceInput, readySourceRefs, registeredFileEdge, reloadedCard, rememberPickedParts, removeCard, removedInReview, renderedPartChars, restartCard, restoredCards, resumableInput, resumeInterrupted, sameSourceRef, selectSettled, selectSourceSet, selectTotalChars, setCardWaitForClean, setSourceTopic, settleCard, sourceAttachTargets, sourceCardChars, sourceCardMeasuredState, sourceCardState, sourceDelivery, sourceEntryChars, sourceKey, sourceRecoveryGuards, sourceRoomLeft, toPersistedSourceInput, updateCardDraft, updateCardRef, uploadCutOffSentence, withDefaultForm, withDisplayNames };