@happyvertical/smrt-ingestion 0.57.32 → 0.57.34

package/EXTRACTION.md

@@ -48,7 +48,46 @@ time, falling back to actual rendered-page OCR for empty pages. Embedded text
 is not evidence that every visual element was understood. TIFF is actually
 decoded page-by-page with sharp to PNG; each result cites its original TIFF page.
 Animated non-TIFF images are unsupported. Ordinary image OCR and scene vision
-are separately configured. Speech uses source-level text unless actual segment
+are separately configured. Vision alone prepares an EXIF-oriented, full-frame
+image inside a 2048-pixel edge without cropping or upscaling. Opaque inputs use
+JPEG quality 85 (80 only when needed); alpha inputs retain transparency in PNG.
+A 512 KiB encoded-image cap bounds base64 transport to about 700 KiB per image.
+If neither high-quality JPEG encoding fits, or transparent PNG exceeds the cap,
+extraction returns `limit` before a vision provider call. It never shrinks further,
+drops a page, or silently flattens transparency. Original decode pixel limits,
+native-memory isolation, deadlines and authorization apply before downsizing.
+OCR, including PDF fallback, keeps its existing full-resolution PNG coordinates.
+
+Trusted `visionImageLimits?: {maxEdge?, maxEncodedBytes?}` may tighten defaults
+(edge 256–2048; encoded bytes 1024–524288). Adapter construction rejects expanded
+or invalid limits. Use a new extraction configuration revision when adopting this
+policy or changing its bounds. `imagePreparations` records `vision-image-v1`, the
+bounds, source dimensions/orientation, derivative dimensions/format/quality/bytes
+and source/page location. Evidence still identifies the unchanged retained bytes.
+This is lossy provider preparation, not a claim that all text detail survives.
+Small handwriting can become unreadable; the vision instruction requires honest
+unreadable observations. Vision also separates printed questions/solved examples
+from learner handwriting, preserves observed responses even when incorrect, and
+reports matching lines only with visibly traceable endpoints. Unreadable or
+uncertain responses/endpoints remain unknown; arithmetic solutions and expected
+matches must not be reported as observations. The generic scene/text instruction,
+untrusted-image instruction boundary and prohibition on actions still apply.
+Observation text preserves visible sections/headings, columns/rows, task parts,
+reading order, and their text/response associations. Unclear structure or reading
+order is explicitly unknown; the prompt forbids invented layout, boxes,
+coordinates, or verified geometry. A physical source page is identified only
+when known, otherwise unknown; a visible printed page number is separate and
+does not establish the physical source page. These are textual observations,
+not a new structured generic layout contract. Assessment-specific consumers may
+derive bounded advisory layout metadata from them under their own contracts.
+Hosts adopting this observation prompt must use a new extraction configuration
+revision; `vision-image-v1` versions image preparation, not prompt behavior.
+Synthetic request tests verify these instructions reach the provider, not remote
+recognition quality. Hosts must verify their intended model on representative
+work and retain manual access to originals. No point weights or assessment
+content may be invented to compensate for lost detail.
+
+Speech uses source-level text unless actual segment
 timestamps are returned; absent speech confidence calibration is unknown.
 
 Confidence and boxes are explicitly null unless an OCR provider advertises and
@@ -91,6 +130,21 @@ boundaries for mixed/scanned PDF, Unlimited-OCR, camera observations, message
 attachments, audio timestamps and malformed/partial output. These fixtures are
 not real remote-provider integrations and are not the ADR evaluation corpus.
 
+### Host OCR data
+
+`@happyvertical/pdf` probes its Kreuzberg provider on import and logs
+`Kreuzberg could not initialize Tesseract language 'eng'` when no `eng`
+traineddata is found. Ingestion's suites do not route through Kreuzberg (PDF
+extraction uses `unpdf` or injected fixtures), so on its own this warning does
+not explain a test failure. Hosts that run Kreuzberg OCR need Tesseract
+language data: install `tesseract-ocr-eng` (Debian/Ubuntu) or `tesseract`
+(Homebrew), or place `eng.traineddata` from
+[tessdata_fast](https://github.com/tesseract-ocr/tessdata_fast) in a directory
+and export `TESSDATA_PREFIX` pointing at it. The SDK checks
+`TESSDATA_PREFIX`, then `tesseract --list-langs`, then the common
+`/usr/share`, `/usr/local/share` and Homebrew `tessdata` directories; on
+hosts without those paths (for example NixOS), set `TESSDATA_PREFIX`.
+
 No live Unlimited-OCR, speech recognition or vision quality run is claimed.
 No recorded-human-audio recognition accuracy, real camera-scene quality,
 calibrated confidence, table extraction, or automatic-action acceptance is
@@ -118,3 +172,24 @@ truncation only. The adapter never bypasses the SDK to recover hidden fields.
 The missing SDK metadata is tracked in [happyvertical/ocr#144](https://github.com/happyvertical/ocr/issues/144).
 AI vision retains reported truncation when supplied by its SDK. Missing provider
 cost is unknown, not zero; no cost estimate is invented.
+
+### Optional observed image regions
+
+Trusted SDK configuration `observeAnswerRegions: true` asks the SAME existing
+vision request for JSON observations plus an optional bounded region catalog.
+Default off preserves ordinary text observations. This prompt/protocol adoption
+requires a new host configurationRevision (Hearth uses
+`hearth-paper-v5-answer-regions`); no model change or extra automatic request.
+
+Catalog rectangles are approximate direct visual observations, not verified boxes:
+version1, coordinateSpace display-oriented, at most64 regions with short id/text
+and finite normalized positive `[x,y,width,height]` inside the entire upright
+EXIF-oriented uncropped image. Fit-inside resize preserves full-frame mapping;
+never infer locations from columns/task numbers. Initial source images only,
+not PDF raster fallback. Missing, uncertain or malformed catalog data is omitted
+while valid observation text survives. A catalog that alone would exceed the
+retained output byte budget is omitted. Existing total token/native/input limits
+still apply; usage includes numeric vision_* counters when the provider reports
+them. Tests prove exactly one SDK call and synthetic oriented alignment, not remote
+model quality. imagePreparations records original orientation/dimensions and sent
+format/dimensions/bytes; immutable source hashes/bytes remain unchanged.

package/PROPOSALS.md

@@ -133,11 +133,16 @@ absent or no offered candidate matches. On required-only schema refusals, the
 validator computes the absent required set and corrects a mismatched model
 declaration; the instruction guides the model without making its declaration
 authoritative. Absent optional fields stay out
-of both `args` and `missingFields`. The model prefers `no_action` when no
+of both `args` and `missingFields`, rather than being sent as null (unless the field explicitly permits null). Suggestion objects contain exactly the required envelope keys, with handler arguments nested only inside `args`. Alternatives mean genuinely competing OTHER choices, not a list of offered choices: use `[]` when none exist and never list the selected handler itself. The SDK response schema excludes that handler key from each suggestion variant while retaining other handler and candidate keys (#4395). Existing malformed or ambiguous outputs remain refused/pending; no self-alternative is stripped after generation. The model prefers `no_action` when no
 offered handler's description fits the document's role, and `unknown` when the
 evidence cannot be interpreted (#4290). Domain routing, such as which received
 documents an application ignores, belongs in host handler descriptions or
-reviewer guidance, not in this text. The text is not persisted. It is not part
+reviewer guidance, not in this text. Keep these shared instructions concise: the
+maintained reference host pins the complete SDK request to an 8 KiB wire/input
+budget. That budget includes schema and transport overhead; adding repeated prose
+can prevent a valid small request from reaching its provider. The frozen
+evaluation checks the real envelope without raising its budget (#4395).
+The text is not persisted. It is not part
 of the frozen interpretation configuration, the input, catalog or output
 digests, or the stored generation output, so a package release that changes it
 leaves stored attempts readable and previewable unchanged. New attempts send the
@@ -145,6 +150,45 @@ new text, but their digests do not record it; a host that needs provenance to
 tell the two apart bumps its own `promptVersion`, which, like any configuration
 change, makes earlier attempts read as stale (`GenerationSnapshotStaleError`).
 
+Each suggestion's `explanation` is one or two plain sentences stating what the
+document is and why the handler fits, with no deliberation, self-correction or
+restating of the rules, and is bounded at 300 code points (#4331,
+`PROPOSAL_EXPLANATION_LIMIT`). Two such sentences run about 150-250
+characters; the bound keeps a verbose model from spending its output budget
+(and hitting the `length` finish reason) on prose instead of arguments. A
+reply cut at the token limit is still refused (`finish_reason`) and partial
+JSON is never salvaged; the grammar bound and the instruction are what keep
+replies under the limit. The provider schema and the validator carry the same `maxLength`, so the provider
+copy still accepts a superset of the validator (#4261), and a grammar backend
+enforces the bound while decoding. In the provider schema `explanation` is the
+last suggestion property, after `handlerId`, `handlerVersion`, `args`,
+`evidence`, `alternatives` and `missingFields`, and the top-level keys are
+`outcome`, `suggestions`, `splits` in that order; `required` lists the same
+order. That order predates #4331 and is now pinned by a test, so explanation
+prose cannot precede the arguments. xgrammar emits object properties in schema `properties` order unless
+`any_order` is set (its default is `false`, and vLLM does not set it), and
+llguidance fixes property order to the `properties` map, then `required`. A provider
+that ignores the schema can still return a longer explanation: fresh output is
+normalized after the list deduplication above and before validation, cutting
+it to 299 code points plus `…` on a code-point boundary, so a long explanation
+never fails validation (the raw output-size and SDK `output_limit` checks
+still run first). The value-free count is recorded as
+`provenance.explanationsTruncated`, absent when zero and removed with
+`duplicatesRemoved` whenever the suggestions are discarded. It counts only
+replies from providers that ignore the schema: on a grammar backend such as
+vLLM the string closes at 300 code points with no marker, and nothing is
+counted. The cut happens
+before the invented-target echo check, so an echo beyond the bound is no
+longer seen; explanation text is never a target or authority.
+
+Replay: the bound, the property order and the instruction text feed no digest.
+The response schema is built per request and never persisted; the frozen
+interpretation configuration holds versions, identities, the catalog digest and
+`limits`, none of which include the explanation bound. Stored attempts are read
+as persisted, never re-validated or re-cut, so an earlier attempt with an
+explanation of up to 2000 characters still reads, previews and replays with
+its original `output_digest`. New attempts' digests cover the bounded form.
+
 A trusted custom `ProposalGenerator` must likewise honor cancellation, bound its
 response, and explicitly declare validated `complete` or `unknown` completion.
 The SDK currently normalizes missing/unknown finish reasons to `stop`
@@ -386,6 +430,44 @@ phrase. Transport failures through the OpenAI SDK already carried
 problem, and other non-SDK errors contribute the transport facts above. The
 category is unchanged (`unavailable`).
 
+### Host suggestion review (`reviewSuggestion`)
+
+A host's own checks on a generated suggestion (a label that is not the invoice
+date, an amount that is not in the document) can hold it and leave a record a
+reviewer sees:
+
+```ts
+proposals: {
+  // ...
+  reviewSuggestion: ({ suggestion, handler, evidence }) => ({
+    hold: true,                        // optional; forces needs_review
+    reasons: ['total_not_in_text'],    // optional; <= 8 codes, /^[a-z][a-z0-9_.-]{0,47}$/
+    prefilled: ['billDate'],           // optional; names declared in handler.argsSchema.properties
+  }),
+},
+```
+
+The hook is trusted, server-only and optional. It runs once per validated
+suggestion, after validation and before the decision gate, with deep copies of
+the suggestion, its offered handler and the retained evidence text. It cannot
+change `args`, `missingFields`, evidence or the outcome except through `hold`,
+and it can never upgrade: `hold` sets the suggestion (and a `proposals` outcome)
+to `needs_review`; absent or `hold: false` leaves the validator's disposition.
+
+The result is stored as `suggestion.hostReview` (`{held, reasons, prefilled}`)
+and counted in `provenance.hostReview` (`{annotated, held}`); both are absent
+when the hook records nothing. Values cannot be stored: unknown keys, free-text
+or over-long reasons, `prefilled` names that are not argument names, and any
+reason code containing one of the suggestion's own argument values (3+
+characters) make the result invalid. An invalid result, a throw, a rejection or
+a hook slower than `limits.timeoutMs` holds the suggestion with the fixed code
+`host_review_invalid` or `host_review_failed`; the error text is discarded.
+`ReviewView` shows "Checked by the shop: ..." under the arguments.
+
+Like `failureCapture`, the hook is not public read configuration and never enters
+frozen configuration or digests. Hosts keep it synchronous-cheap: it runs inside
+the generation lease.
+
 ### Failed-attempt capture (opt-in, #4285)
 
 The value-free reason cannot show what the model actually sent. A host that
@@ -609,3 +691,51 @@ Interpretation output uses the exported `GenerationAnalysisOutput` wrapper at
 An explicit feedback `retrieve` denial omits optional examples and feedback
 provenance and continues generation. Item/execution denials, unexpected failures,
 and revocation after examples were selected still fail closed before disclosure.
+
+## Storage-safe provider text (#4393)
+
+After the normal output-byte ceiling, generation validates decoded JSON object
+keys and nested string values for PostgreSQL's unsupported NUL and unpaired
+UTF-16 surrogate characters. A refusal is `malformed_output` with a fixed,
+value-free reason, before either accepted or refused suggestion arguments can be
+retained. Provider content is never stripped, repaired or treated as authority.
+Literal backslash-u text and valid supplementary Unicode remain unchanged.
+
+The generic `completeAnalysis` publication boundary independently checks the
+whole result, including provider metadata and diagnostics. An invalid result
+records the exact current fenced attempt as `needs_attention/malformed_output`
+on the same authorized executor and completes its dispatch; it produces no
+completed analysis, proposal or execution. Originals remain readable, and a
+fresh authorized analysis revision can retry without rewriting the failed one.
+Existing byte limits and current authority/fence checks still apply.
+
+Optional failed-attempt capture uses the existing private, reviewer-authorized
+host redaction policy. Unsupported generated JSON can be retained there as its
+JSON-escaped diagnostic representation; it is never copied into a successful
+proposal or returned in ordinary snapshot payloads. Without an enabled redactor,
+no raw diagnostic text is retained. Shared foundation/proposal tests exercise
+SQLite and actual PostgreSQL JSONB writes, invalid keys and values, lone high/low
+surrogates, valid emoji/literal escapes, source retention, retry and capture policy.
+
+
+## Descriptive candidate context
+
+A discovery candidate may include optional `context`, a plain JSON object of
+untrusted descriptive data. It is never instructions or new authority. Keep the
+label concise: context does not create extra entity choices. Validation rejects
+non-JSON values, lossy coercions, unsafe Unicode, cycles, depth over32 and context
+exceeding the existing `maxInputBytes`. The complete offered input still uses the
+same total byte budget. Invalid authorized context fails closed; denied candidates
+and their context never reach generation. Absent context preserves the old wire.
+
+Context is snapshotted and included in the candidate key/digest and generator
+contract. Hosts must bind any context changes to their current target revision;
+current target checks retain their existing live executor/authorization boundary.
+Education binds canonical same-capture prompt context to its target revision digest.
+
+The engine exposes read-only `HandlerContext.analysisRevision` and forwards the
+same current item revision to target authorization on its shared executor. This
+pin comes from the owned intake row, not handler arguments, browser input or model
+output. An owner may use it to avoid treating that generation's own materialized
+result as an independent change to its input context; ordinary unrelated changes
+and current authority/revision checks still invalidate stale snapshots.

package/dist/chunks/{execution-BxkUOtLf.js → execution-DKWz2cz0.js}

@@ -6875,12 +6875,14 @@ var IntakeExecutionService = class IntakeExecutionService {
 				db,
 				scope: this.scope,
 				itemId: String(item.id),
+				analysisRevision: Number(item.analysis_revision),
 				policy,
 				assertTarget: async (model, targetId, revision) => {
 					await this.config.assertTarget({
 						db,
 						scope: this.scope,
 						itemId: String(item.id),
+						analysisRevision: Number(item.analysis_revision),
 						model,
 						id: targetId,
 						...revision === void 0 ? {} : { revision }
@@ -6930,6 +6932,7 @@ var IntakeExecutionService = class IntakeExecutionService {
 				db,
 				scope: this.scope,
 				itemId,
+				analysisRevision: context.analysisRevision,
 				model,
 				id: id2
 			})), requireReview);
@@ -7141,7 +7144,7 @@ var IntakeExecutionService = class IntakeExecutionService {
 		if (!Array.isArray(references)) throw new Error("Feedback lineage unavailable");
 		if (references.length === 0) return;
 		if (!this.options.feedback) throw new Error("Feedback configuration unavailable");
-		const { IntakeFeedbackService } = await import("./feedback-D69e1hX5.js").then((n) => n.r);
+		const { IntakeFeedbackService } = await import("./feedback-DHcSKgVU.js").then((n) => n.r);
 		await new IntakeFeedbackService(this.options, this).assertActionLineage(String(bound.action.id), db, String(bound.proposal.id));
 	}
 	async getAction(actionId) {
@@ -7230,6 +7233,7 @@ var IntakeExecutionService = class IntakeExecutionService {
 						db,
 						scope: this.scope,
 						itemId,
+						analysisRevision: Number(bound.item.analysis_revision),
 						model: target.model,
 						id: target.id
 					})).revision !== target.revision) {
@@ -7804,6 +7808,7 @@ var IntakeExecutionService = class IntakeExecutionService {
 				db,
 				scope: this.scope,
 				itemId: String(item.id),
+				analysisRevision: Number(item.analysis_revision),
 				model,
 				id: result[field]
 			});
@@ -7834,6 +7839,7 @@ var IntakeExecutionService = class IntakeExecutionService {
 				db,
 				scope: this.scope,
 				itemId: String(bound.item.id),
+				analysisRevision: Number(bound.item.analysis_revision),
 				model,
 				id: result[field]
 			});
@@ -8004,6 +8010,7 @@ var IntakeExecutionService = class IntakeExecutionService {
 							db: this.db,
 							scope: this.scope,
 							itemId: String(send.bound.item.id),
+							analysisRevision: Number(send.bound.item.analysis_revision),
 							model,
 							id: targetId,
 							...revision === void 0 ? {} : { revision }
@@ -8622,7 +8629,11 @@ var IntakeExecutionService = class IntakeExecutionService {
 			...this.config,
 			assertTarget: async (target) => {
 				try {
-					return await this.config.assertTarget(target);
+					const item = await this.item(target.db, target.itemId);
+					return await this.config.assertTarget({
+						...target,
+						analysisRevision: Number(item.analysis_revision)
+					});
 				} catch {
 					throw new IntakeAccessDeniedError();
 				}
@@ -8718,4 +8729,4 @@ async function continueIntakeReview(service, actionId, task) {
 //#endregion
 export { __toESM as A, storedFailureCapture as C, generationSnapshotRead as D, discoveryTransaction as E, listReadGate as O, prepareFailureCapture as S, completeWithFailureCapture as T, HandlerArgumentsInvalidError as _, resolveIntakePolicy as a, FAILURE_CAPTURE_MAX_BYTES as b, HANDLER_ARGUMENT_ISSUE_LIMIT as c, schemaOwnedPath as d, require_ajv as f, GenerationSourceStaleError as g, GenerationSnapshotStaleError as h, intakeBindingDigest as i, __exportAll as k, HANDLER_ARGUMENT_PATH_LIMIT as l, redactedCeiling as m, IntakeExecutionService as n, feedbackActionTransaction as o, UNFINISHED_ACTION_STATES as p, continueIntakeReview as r, feedbackDiscoveryContext as s, IntakeAccessDeniedError as t, describeArgumentRefusal as u, ProposalsNotConfiguredError as v, analysisLeaseRemaining as w, assertFailureCapture as x, FAILURE_CAPTURE_DEFAULT_MAX_BYTES as y };
 
-//# sourceMappingURL=execution-BxkUOtLf.js.map
+//# sourceMappingURL=execution-DKWz2cz0.js.map