@happyvertical/smrt-ingestion 0.57.33 → 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
@@ -133,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
@@ -686,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