@happyvertical/smrt-education 0.57.32 → 0.57.34

package/agents/workbook-service.md

@@ -0,0 +1,355 @@
+# Physical workbook contract
+
+`WorkbookService` extends `SubmissionService` with the same actor-bound authorization,
+private asset runtime, transaction executor and guardian Grade boundary. Both
+LearnerAuthorizer and CatalogAuthorizer receive the active executor. Host session
+heartbeats and current permission checks must use that supplied executor, including
+nested guardian review; a captured outer pool can wait on its own transaction.
+CatalogService obtains the executor through the public collection.db getter and
+fails closed when its four catalog collections do not share the same handle. It is an
+additive API; existing Submission/Grade consumers retain their contracts. The six
+closed `Workbook*` models are package-manifest models. Apply normal application
+schema migrations before using them; the service never creates runtime schema.
+
+A guardian calls `resolveWorkbookActivity` with an explicit learner, workbook key,
+title, edition (empty means unknown), page key and printed page label. Keys identify
+the physical copy/edition and page occurrence, including section/side where needed.
+Names and photo hashes do not establish identity. A conflicting reuse fails. One
+private personal-use-copy course/enrollment per learner/workbook supplies internal
+submission scaffolding. The public page API needs no course-building workflow.
+
+`captureWorkbookWork` owns original files through SubmissionAsset and creates an
+immutable attempt with source SHA-256 hashes, actual page bounds, actor, capture
+time, assistance, correction predecessor/episode, policy version and effective
+review-required flag. Assistance defaults to `unknown`. Capture retries reuse the
+same Submission/attempt and reject changed bytes or help claims. A correction
+requires the same learner/activity/current predecessor and stays in the same
+practice episode. Analysis/reanalysis adds revisions, never practice attempts.
+Existing LessonProgress.attempts remains a compatibility capture counter.
+
+The workbook review-required policy defaults on and is shared by its pages.
+`setWorkbookFeedbackPolicy` uses expected policy version; existing capture snapshots
+remain unchanged. Policy changes cannot erase prior disclosure. Guarded capture,
+policy and decision writes serialize on the learner within the active transaction.
+Ingestion target resolution acquires that learner lock before the enrollment lock,
+matching capture/review order. Guardian apply follows authorized timeline cursors
+when locating a preserved assessment on an older attempt.
+Composite mutations also use the education transaction's serialized composite
+queue, allowing inherited queued capture/review writes without queue recursion.
+Any swallowed mutation error still aborts the complete transaction and file rollback
+uses the inherited fresh-file compensation ledger.
+
+## Structured assessment and real ingestion
+
+`WorkbookAssessment` version 1 has stable question IDs, original/corrected prompt
+and answer text, explicit result/reason, nullable points, feedback, retained source
+anchors and curated concept mappings. An anchor names an owned asset plus SHA-256,
+one-based verified page (or null for a whole-file PDF source) and normalized
+x/y/width/height rectangle. Ingestion proposals never generate rectangles: the
+service uses [0,0,1,1] and explicit source/page grounding with limitations. The provider wire contract
+contains evidenceId only, with no page/rect selector. An image is a known single
+page; PDF questions retain a whole original-file anchor with page:null, not a
+claim about page 1. Extraction metadata remains provenance, never a model page
+localization grant. Fictitious PDF
+pages and foreign files fail. Missing, illegible, unsupported and absent questions
+are unassessed; unassessed points stay null. Marking certainty, mapping certainty,
+mapping review provenance and evidence limitations are distinct; absent certainty
+is explicitly persisted as unknown. Reviewed overrides append new bodies and keep
+original AI text inspectable.
+
+The configurable vocabulary is trusted server configuration, not AI-created labels.
+The default `WORKBOOK_MATH_VOCABULARY` has addition, subtraction and place value.
+Other subjects may use an explicit curated `workbookVocabulary` on WorkbookService,
+the ingestion handler factory and preservation helper. Unknown concept IDs fail;
+zero mapped concepts is valid. AI mappings are proposed, guardian mappings reviewed.
+Known question IDs are pinned across captures; exact prompts are pinned within a
+capture's reanalysis only. Correction transcriptions come from the new capture,
+so earlier answer-bearing prompts cannot override corrected work. Immutable
+historical prompts remain unchanged. The public `getWorkbookQuestionIdentity`
+returns IDs only: historical prompt text can itself include a learner response.
+Handlers use printed number/occurrence/subpart when present; unnumbered tasks use
+answer-free printed-task slugs with visible-task occurrence/subpart, never output
+array position or learner answers. They
+read prompt, answer, feedback and marks exclusively from current evidence. New
+prompts should contain printed task text without the learner response. An absent
+or ambiguously matched known question is unassessed/not_present with an explicit
+limitation. Missing, duplicate, invented or foreign IDs reject the proposal; a
+changed question order does not change identity. The ID check does not establish
+semantic equivalence of printed tasks; uncertain correspondence requires human
+review rather than an invented match.
+A different page/question requires explicit new activity identity, never AI retargeting.
+
+`captureEducationIntake` accepts optional `workbookActivityId`/`assistance` when its
+service is WorkbookService. It preserves the existing return SubmissionView and
+binds the workbook attempt/policy before the host queues processing.
+`educationIntakeHandlers({workbookActivityId,...})` advertises a bounded JSON question
+schema to real ingestion generation. Assessed results require reason none;
+unassessed reasons require null points. Per-question outcomes must agree with
+points. Correctness is independent of scoring: readable objectively solvable
+arithmetic may be assessed without a printed rubric. When no point allocation is
+evidenced, both `points` and `possiblePoints` remain null for every result,
+including incorrect; never invent weights or mix null/numeric values. The
+aggregate still counts correct/incorrect results while its score remains null.
+Incorrect earns zero only when the possible-point allocation is known.
+Model aggregate scores/narratives are not requested or trusted: exact
+count summaries and points scores are computed from validated questions without
+rounding or invented partial credit. Default legacy handlers remain compatible.
+`preserveWorkbookIntakeAnalysis` reads the public immutable completed generation,
+checks its exact submission and offered workbook schema, maps cited original
+ingestion evidence by hash/order to retained education-owned files and imports one
+validated proposal. Provider/model/version, configuration/rubric, source analysis
+pin and proposal digest are durable provenance. Pending/failed processing produces
+no assessment. Malformed/ambiguous/foreign-source proposals return typed needs_review with no
+education revision or Grade. The host can offer retry/review without a route 500.
+Authorization, durable-source integrity and database failures still throw. Repeated
+transfer is idempotent by analysis attempt. Preservation must complete before host
+scratch retention cleanup; there is no automatic retention bypass in this API.
+The ingestion handler can apply only an exact previously preserved proposal through
+guardian review; it never grants AI grade authority. No prose parsing is used. The generation configuration carries bounded source
+hash/page-support provenance from the completed extraction before it ceases to be
+the current analysis. This uses public ingestion APIs and is pinned by its
+configuration digest; question anchors always use honest source-only grounding.
+
+## Authority, visibility and history
+
+`recordWorkbookAnalysis` accepts authorized submit context and writes provisional
+AI revisions only. `reviewWorkbookAssessment` requires guardian authority, exact
+source revision, expected current guardian head and stable request key. It appends
+an immutable guardian revision recording sourceRevisionId, superseded head, actor,
+time and decision reason. Changed retries conflict. Review of the current capture
+uses the existing guardian Grade/progress boundary. Historical annotation changes
+its evidence authority only and cannot grade or reopen its successor. Reanalysis
+after a guardian decision remains provisional. A guardian can invalidate an outcome
+with an unassessed replacement and a stated reason; old AI does not regain authority.
+
+`releaseWorkbookFeedback` separately releases an exact revision using expected
+current guardian head. New stale releases fail; accepted retry requests replay their
+original result after later decisions. Release creates no Grade. With the gate off,
+AI feedback is visible as provisional while authoritative grading still requires a
+guardian. Gate-on learners receive no unreleased assessment payloads, scores or
+hints. WorkbookService's ordinary getSubmission also redacts Grade for own learners;
+hosts must route workbook reads through this service and prevent legacy routes from
+serving workbook grades. Guardian history is complete; learners see only their own
+work and visible revisions. Answer keys/source storage URIs never enter these DTOs.
+
+`acknowledgeWorkbookFeedbackDelivery` is an authenticated own-learner acknowledgment
+for an exact currently visible feedback revision. It deduplicates per actor/revision
+and rejects withheld, foreign, sibling and guardian acknowledgments. Immutable
+delivery events record actor/time and mean rendered/delivered, never read or understood.
+
+`getWorkbookTimeline` uses education rows/assets without reading ingestion. It lists
+newest captures/revisions first, includes all releases/delivery events and provides
+cursor pagination (1–100, default 25). A guardian revisionId selector locates its
+containing capture for evidence links. Guardian source IDs/actors/reasons remain
+inspectable. Released historical revisions remain visible after supersession.
+
+`getConceptEvidenceSummary` is guardian-only for this milestone. It recomputes from
+current guardian revisions, separates provisional observations, and reports independent,
+assisted and unknown evidence. Correction captures remain one episode; they cannot
+be extra independent demonstrations. Every observation cites capture, question,
+revision, episode, result, assistance and time. Unassessed work is excluded from
+error/correct counts. Descriptive cues cite actual evidence: needs practice, improving
+on this item, needs a fresh independent check, not enough evidence. No mastery
+percentage, generic score comparison, hidden threshold or predictive label is used.
+
+## Preserved processing status and retention
+
+`getWorkbookPreservationState` authorizes exact actor/learner/activity/submission
+and returns only the intake ID plus retained assessment/analysis IDs and the
+interpretation revision. It contains no questions, scores, feedback or hidden
+assessment payloads. New AI provenance records `analysisRevision` from the
+completed interpretation snapshot, separately from its extraction-source pin.
+
+`preserveWorkbookIntakeAnalysis` checks this education-owned state and the public
+content-free ingestion item revision before requesting raw completed analysis.
+An exact already-preserved revision returns `retained` immediately. Guardian
+review, release, corrections and receipt expiry therefore do not force a stale
+proposal reread or prevent durable education history from loading. The public
+ingestion stale-snapshot guard remains unchanged and still rejects the old raw
+snapshot after guardian grading. A genuinely new valid analysis can append a new
+provisional revision; a novel stale analysis returns `needs_review/stale_analysis`
+and creates no mark. Legacy retained rows without interpretation revision remain
+readable when scratch is stale/unavailable or the public
+ProposalsNotConfiguredError reports removed provider read configuration. A novel
+analysis with no provider read configuration returns unavailable without import; an authorized current snapshot whose
+attempt ID is already retained is also skipped before retry reconstruction.
+
+Only the exact public scratch `Intake unavailable` response is translated to
+retained history, or `unavailable` for a capture with no retained assessment,
+after independent education authorization. Missing/pending current analysis may
+return pending or retained. Unexpected configuration, integrity and database
+failures still throw. This does not widen scratch access: no stale or unavailable
+raw proposal is read, imported or used as grade authority. Hosts must also render
+the authorized education timeline independently of optional scratch processing.
+
+## Compatibility API privacy boundary
+
+Workbook feedback is projected only from the revision/release workflow. The base
+`SubmissionService` recognizes authoritative `WorkbookActivity` lesson ownership,
+including calls through a plain service instance. Own-learner compatibility views
+withhold Grade and grade-derived status; learner progress projections withhold
+bestScore/completedAt and do not let completion alter next-lesson selection.
+Guardian and ordinary non-workbook projections retain their existing behavior.
+This applies in both feedback policy modes; direct feedback remains provisional
+and does not authorize compatibility Grade disclosure.
+
+Generic capture/resubmission rejects workbook enrollment or lesson scaffolding,
+including idempotent retries. Only the protected exact-activity owning workflow
+can capture workbook work. Hosts must call public
+`assertNonWorkbookSubmissionScope` before legacy intake receipt creation and when
+reading an old legacy binding, using authoritative enrollment, lesson and
+predecessor selectors. `WorkbookWorkflowRequiredError` is a controlled denial.
+The browser's optional workbook flag is never authority. Authenticated original
+asset delivery remains a separate read authorization path.
+
+## Validation and limits
+
+`src/__tests__/workbook-workflows.ts` is the shared SQLite/PostgreSQL contract suite;
+`workbook-service.test.ts` runs SQLite, and `workbook.optional.test.ts` runs against
+an available isolated PostgreSQL database. Workers never provision service stacks.
+Run package test/typecheck/build; the integration owner runs test:postgres and the
+integrated review. Synthetic provider DTO tests establish transfer integrity, not
+real handwriting accuracy. Actual provider/sample and app restart/retention
+acceptance remain separate integration evidence. Family deletion/export/backup
+policy and automatic lesson generation are not implemented by this milestone.
+
+## Identity-independent work
+
+[Photo intake](photo-intake.md#marking-before-filing) may own an explicit unfiled
+work unit. Its nullable workbook FK is constrained to an exact retained receipt;
+private enrollment/worksheet routing is technical rather than bibliographic.
+The same attempt/assessment/review/release and concept-evidence contracts apply.
+`filing` is optional on legacy-shaped DTOs and explicit on current projections.
+Append-only filing changes display association only; it never moves immutable
+learning evidence or changes captured review policy. Ordinary identified workbook
+identity and generated-surface restrictions remain unchanged.
+
+### Unnumbered visible questions
+
+A printed question number is not required for marking. On the first valid
+assessment, an unnumbered task may use `u:<short printed-task slug>:<occurrence/subpart>`
+from current answer-free task text and unambiguous visible task identity. The
+occurrence distinguishes tasks in the source, never positions in a generated
+questions array. Responses, computed solutions and changing evidence UUIDs cannot
+supply identity. Printed IDs remain useful where present; both forms share the
+existing nonempty/unique ID schema and 200-character bound.
+
+Once preserved, the exact ID set remains pinned on reanalysis and correction.
+Reordering output does not renumber tasks. A cropped, duplicate or illegible task
+whose correspondence cannot be established remains `unassessed/not_present` with
+a limitation on its known ID; it cannot be silently relabeled as another task.
+Historical IDs are correspondence hints, not evidence of current responses.
+Missing IDs, collisions, changed ID sets and same-capture prompt remapping still
+fail closed. The framework never inserts omitted provider IDs or parses prose to
+repair malformed proposals.
+
+### Semantic identity visibility
+
+Question IDs can contain printed task text. Own-learner identity reads and
+operation discovery therefore require release of the **selected exact revision**
+on a guardian-origin source attempt. An unrelated revision or another attempt's
+release is insufficient. Ordinary own-origin IDs remain available for legitimate
+current-work marking and corrections without exposing withheld grades/feedback.
+
+Correction ancestry is checked completely under the same tenant, learner,
+activity and practice episode. Each guardian-origin ancestor must have an exact
+released revision publishing the compatible immutable ID set before a descendant
+can expose those semantic IDs. Matching published ID sets preserve already public
+historical snapshots after a later private head, without aliases or rewritten IDs.
+Missing, corrupt or cyclic ancestry fails closed; there is no depth cutoff that
+silently skips earlier source guards. Current descendant release never grants
+rights to a hidden ancestor.
+
+The same boundary governs child correction capture, timeline payloads and delivery
+acknowledgments, including legacy/trusted-produced descendants. Raw provisional
+revision writes/returns cannot probe or replay guardian-origin private content;
+authorized guardians retain processing/history access, and own-origin correction
+marking remains supported once ancestral source identity is published. Schema,
+ID collision/remapping rules and immutable stored history remain unchanged.
+
+The offered marking schema mirrors the assessment validator: assessed results use
+`markingCertainty` clear/unknown; `uncertain` marking requires `unassessed`, an
+allowed non-none reason and both point fields null. This is not a conversion of
+provider output: contradictory results remain refused. Mapping certainty remains
+independent. Visible but overwritten/ambiguous responses can stay unassessed while
+other clearly visible questions are assessed in the same valid proposal.
+
+### Observed assessment layout
+
+Optional `WorkbookAssessment.layout` version 1 describes observed sections in source
+order and zero-based row/column question placements. It is advisory, with fixed
+`provenance: 'observed'`; it never establishes identity or verified geometry.
+Sections reference a retained source asset and a physical one-based observed page,
+or null when unknown. A whole-file PDF anchor may support an observed page within
+its retained page count while keeping its original anchor page null. Every placed
+question must anchor the section's exact source. Multiple question IDs may share a
+cell. When every placement in a cell has an explicit `part`, sort by part then
+original question array index for ties. If any placement in that cell omits
+`part`, the whole cell follows original question array order. Partial placement is valid. Missing `readingOrder` preserves original
+question order for a flattened display.
+
+The browser-safe `normalizeWorkbookObservedLayout` copies only bounded known
+fields: at most 32 sections and 200 placements, 1–8 columns, rows 0–199, parts
+0–31, section IDs up to 64 characters and labels up to 200. Duplicate section IDs
+or question placements, invalid source/page/placement references and malformed
+metadata discard the complete optional layout and retain `layoutOmission: 'invalid'`.
+Valid answers and normal assessment validation remain independent. Owning analysis
+and guardian writes both normalize against the current capture's source hashes;
+a correction cannot inherit a previous capture's source layout. Default guardian
+copies retain valid layout and safe omission markers. Bodies remain immutable JSON
+inside existing revision privacy and exact release boundaries; no migration or
+additional learner visibility is introduced.
+
+Focused shared SQLite/PostgreSQL cases live in
+`src/__tests__/workbook-layout-workflows.ts`, with SQLite in
+`workbook-layout-service.test.ts` and isolated PostgreSQL in
+`workbook-layout.optional.test.ts`. Pure bounds/reference cases are in
+`workbook-layout.test.ts`. Integration runs the PostgreSQL wrapper under its
+existing isolated database lifecycle.
+
+Generation carries optional `layout` as advisory JSON so malformed presentation
+cannot make valid question answers fail the generic schema. Its described wire
+shape uses original evidence IDs; the bridge maps those IDs to retained assets
+and then calls the strict owner normalizer. Within existing transport/JSON resource
+limits, wrong types, unknown versions and conflicting metadata are omitted with
+only the safe marker, while answers retain their normal strict validation. Layout
+never establishes a question ID, a source authorization or a verified region.
+
+
+### Same-capture reread context
+
+`getWorkbookQuestionContext` returns authorized canonical `{id,prompt}` only
+from the exact current attempt's identity revision. Generation preserves those
+strings verbatim for the existing strict same-capture prompt invariant, while
+rereading learner responses and any observed layout from current evidence. This
+context is not an answer key or authority for answers. A correction without its
+own revision receives predecessor IDs only; predecessor prompts are never copied.
+Exact source/revision and full correction-ancestry visibility apply to both paths,
+including own-learner reads. No historical rows are rewritten and absent layout
+remains valid. `getWorkbookQuestionIdentity` remains the IDs-only public API.
+
+Canonical prompts follow ordinary assessment payload visibility, including
+captured review policy and exact guardian revision release even for learner-owned
+sources; source/ancestry authorization alone does not publish guardian edits.
+For ingestion callbacks only, the engine supplies current `analysisRevision` from
+its owned item row. Context selection ignores AI materialized by that exact
+current-attempt revision, so preserving a proposal does not invalidate its own
+completed snapshot or preview. It never ignores guardian decisions, predecessor
+revisions or another interpretation. Direct reads omit this engine pin and retain
+normal current revision visibility; browser/upload fields cannot supply the pin.
+
+### Observed answer-region overlays
+
+Optional `answerRegions` version1/provenance observed/coordinateSpace
+`display-oriented` carries one approximate rect `[x,y,width,height]` per question,
+with exact retained asset/page1 and observationId. Rects are normalized to the
+whole EXIF-oriented image; they never change question IDs, grading, anchors or
+layout, and never claim verified geometry. Images only in this version; PDFs or
+unknown positions omit regions. Direct malformed metadata is omitted with safe
+`answerRegionsOmission: invalid`; marking/layout survive independently.
+
+Vision catalogs originate in the existing opt-in extraction call. Generation
+references exact evidence/observation IDs, never supplies coordinates. The bridge
+copies catalog rectangles from the extraction-pinned configuration with matching
+source hash. Guardian copies retain them; correction sources must match current
+anchors. Existing exact release and ancestry privacy apply to the complete body.

package/agents/workbook-test-matrix.md

@@ -0,0 +1,74 @@
+# Workbook behavior/test matrix
+
+Design derived from the approved Hearth workbook plan (2026-10-22), learning-record
+contract and WB-001–WB-019 preparation packet (2026-10-23). Feature-class additive
+schema/API change, Refs #4334. Named risk: private learner evidence, authorization,
+concurrency and structured external model output. Compatibility workbook captures now require their owning workflow; ordinary non-workbook Submission/Grade behavior is unchanged.
+
+Every row uses current actor-bound service context, exact tenant/learner resources,
+and the same authorization callback executor as persistence. Shared command C:
+`pnpm --filter @happyvertical/smrt-education exec vitest run workbook-service.test.ts`.
+Shared command P: `pnpm --filter @happyvertical/smrt-education test:postgres` (integration
+owner provisions PostgreSQL). Source assertions live in `workbook-workflows.ts` and
+are shared without dialect-dependent logic. Worker evidence is SQLite/Node26;
+PostgreSQL execution is explicitly pending integration, never inferred from skips.
+
+| Behavior/invariant | Reachable trigger | Positive case | Negative/failure case | Actor/context | Data executor/transaction | Supported runtime/dialect | External contract edge | Test level | Validation command |
+|---|---|---|---|---|---|---|---|---|---|
+| Explicit workbook/page identity | Guardian resolves named physical workbook | Same keys return same activity; repeated label in different section and edition stays distinct; pages share workbook enrollment | Changed title/edition on same key rejected; learner cannot plan | Guardian allowed; learner, sibling, foreign denied | Serialized composite write, learner row lock and unique key; rollback test | Node26 SQLite/PostgreSQL | User-confirmed keys, no photo matching | Service integration | C, P |
+| Durable capture and policy snapshots | Own learner uploads/corrects | Private assets/hashes/page bounds, retained policyVersion; correction retains episode | Changed retry bytes/help; wrong predecessor; transaction abort leaves no authoritative workbook activity | Own learner/guardian allowed; exact ownership rechecked | Existing capture/storage compensation inside education transaction | Node26 SQLite/PostgreSQL | SubmissionPage MIME/bytes; absent assistance defaults unknown | Service integration | C, P; inherited submission rollback suite |
+| Immutable review/authority | Guardian confirms/overrides exact revision | Immutable AI + guardian revisions; source revision, reason, actor/time retained; current review makes Grade | Learner grading; stale expected head; update/delete immutable history rejected; historical review cannot grade successor | Guardian grade required | Both queues serialized; same-scope concurrent decisions; swallowed failure rolls back Grade/revision | Node26 SQLite/PostgreSQL | Unknown result enum, malformed points/JSON, foreign sources fail | Service integration | C, P |
+| Feedback policy/release/delivery | Timeline, explicit release, authenticated render acknowledgment | Gate-off AI provisional; gate-on exact release; historical availability retained; render dedup per actor/revision | Withheld payload absent; ordinary getSubmission grade redacted; stale release/head/changed retry; guardian cannot attest learner delivery | Guardian full history; own learner projected; sibling/foreign denied | Immutable release/delivery transaction; no Grade on release/direct mode | Node26 SQLite/PostgreSQL | Missing optional certainty defaults unknown, request keys bounded | Service integration | C, P |
+| Durable timeline and evidence locator | Education activity read after new service instance | Full history loads without ingestion reference, cursor and exact revision selector | Unknown cursor/revision and learner selector denied; no source URI | Exact tenant/learner; guardian revision locator | Read projection from education rows/assets only | Node26 SQLite/PostgreSQL | Ingestion service absent entirely for history | Service integration; actual restart/retention remains app acceptance | C, P |
+| Real question DTO transfer | Public completed generation preservation helper | Provider/model/config/source pin retained; evidence IDs mapped by retained original hash; duplicate import reuses revision, reanalysis keeps attempt | Pending/failed creates no assessment; malformed unsupported+incorrect and unassessed/zero return typed needs_review; contradicted model totals are ignored and exact2of4 yields0.5; hallucinated rectangles discarded; foreign evidence or changed source rejected | Authorized submit bound exact activity/submission/intake | Ingestion read before education transaction, append-only education revision | Node26 SQLite/PostgreSQL | Strict handler JSON schema; no prose parser; model vocabulary cannot mint concepts | Contract + real education persistence; provider accuracy N/A here (synthetic DTO) | C, P; real provider QA integration separately |
+| Unknown is not wrong | Unreadable, unanswered, absent or context-free question | Explicit unassessed/null points, unknown help | Unknown enum/concept, out-of-page anchor, uncertain marking with score, unanswered zero rejected | Authorized submit; guardian confirms evidence | Validated immutable body before save | Node26 SQLite/PostgreSQL | Bounded schema/anchors/concepts; original asset hash and actual PDF page bound | Service integration | C, P |
+| Descriptive learning evidence | Guardian summary after wrong→assisted correction | Independent first incorrect separated from assisted correct; one episode; exact question/revision citations | Retry/reanalysis does not create practice; unassessed excluded from error counts; corrections never independent | Guardian-only first milestone | Deterministic fresh reduction over effective guardian revisions; provisional separate | Node26 SQLite/PostgreSQL | Curated server vocabulary; mapping proposed until guardian review | Reducer exercised through persisted service | C, P |
+
+Evidence outputs are external to source:
+`/Users/will/Work/tmp/hearth-upgrade-20261025/evidence/education-workbook/`.
+The coordinator records exact final commit and integrated review/PG/app/provider
+results. These synthetic contract tests do not establish handwriting accuracy,
+actual device camera quality, deliberate deletion/export or backup/restore policy.
+
+Real synthetic provider regression (2026-10-25): unsupported+incorrect is rejected,
+model score0.75/three-correct narrative is ignored when question evidence is2of4,
+whole-source geometry replaces unverified generated rectangles and PDF source-only
+anchors have page:null. The shared workbook suite covers these as executable
+regressions. A completed structured proposal rejected on educational semantics
+remains in ingestion history. Malformed wire responses may retain only safe
+diagnostics; without raw values a page-minimum failure cannot identify null
+versus zero or prove a generic validator defect.
+
+The source-only wire regression uses the public IngestionService preview API
+and its generic handler schema validator on a real retained workbook receipt.
+A JSON-roundtripped evidenceId-only proposal is accepted; malformed result/reason
+and an extra page selector are rejected. Image anchors are page1; PDF source-only
+anchors remain page:null. No conclusion about the unknown malformed provider
+page value is inferred from the earlier minimum diagnostic.
+
+Executor affinity regression: direct catalog read/private/answer-key callbacks
+receive the exact shared public collection.db executor. Mixed catalog executors
+fail before host authorization. Nested workbook guardian review asserts catalog
+and learner callbacks share the same active transaction. A real PostgreSQL plus
+SessionService heartbeat regression belongs to the host integration lane; synthetic
+SQLite affinity alone is not proof that a pooled session lock can never deadlock.
+
+Preservation regression uses actual public IngestionService generation with an
+injected synthetic generator and actual WorkbookService persistence. It proves
+the raw stale-snapshot guard still rejects after grading while preservation skips
+the imported revision, allows a genuinely new provisional reanalysis, and keeps
+review/release/correction history and child feedback gates intact after public
+receipt expiry. Legacy stale/unavailable scratch is retained; novel stale analysis
+is not imported; unexpected database errors propagate. This is service-integrity
+evidence, not live-provider accuracy evidence.
+
+Independent-review privacy regression (WB-PRIVACY-1/2): the shared suite exercises
+plain LearnerService/SubmissionService and WorkbookService after guardian review
+before release, in both policy modes. getSubmission, capture retry, listProgress,
+assignmentLessons, startLesson and nextLessons do not disclose Grade, score or
+grade-derived completion to the own learner. Generic capture/resubmission and
+legacy preflight reject workbook enrollment/lesson/predecessor scopes without
+creating submissions or grades; legitimate owning-workflow retries and corrections
+still work. Guardian projections and ordinary non-workbook captures/retries remain
+unchanged. The app signed-session PostgreSQL lane separately exercises legacy
+host/upload/review routes and asserts no new receipts, submissions or grades.

package/dist/catalog-acquisition-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog-acquisition-service.d.ts","sourceRoot":"","sources":["../src/catalog-acquisition-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,qBAAqB,EAErB,gBAAgB,EAChB,mBAAmB,EACpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,uBAAuB;IACtC,WAAW,CACT,UAAU,EAAE,MAAM,GACjB,OAAO,CACR,CAAC,mBAAmB,GAAG;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,IAAI,GAAG,IAAI,CAAA;KAAE,CAAC,GAAG,SAAS,CAC7E,CAAC;IACF,YAAY,CAAC,KAAK,EAAE;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,sBAAsB,GAAG,SAAS,CAAC,CAAC;IAChD,eAAe,CAAC,KAAK,EAAE;QACrB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC,wBAAwB,GAAG,SAAS,CAAC,CAAC;IAClD,iBAAiB,CACf,KAAK,EAAE,IAAI,CAAC,wBAAwB,EAAE,IAAI,CAAC,GAAG;QAAE,KAAK,EAAE,UAAU,CAAA;KAAE,GAClE,OAAO,CAAC,wBAAwB,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,gBAAgB,CAAC;CAC7B;AASD,gGAAgG;AAChG,qBAAa,yBAAyB;IAElC,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAFN,KAAK,EAAE,uBAAuB,EAC9B,OAAO,EAAE,qBAAqB,EAC9B,MAAM,gBAAsB;IAGzC,OAAO,CACX,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,wBAAwB,CAAC;CAgErC"}
+{"version":3,"file":"catalog-acquisition-service.d.ts","sourceRoot":"","sources":["../src/catalog-acquisition-service.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,qBAAqB,EAErB,gBAAgB,EAChB,mBAAmB,EACpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,uBAAuB;IACtC,WAAW,CACT,UAAU,EAAE,MAAM,GACjB,OAAO,CACR,CAAC,mBAAmB,GAAG;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,IAAI,GAAG,IAAI,CAAA;KAAE,CAAC,GAAG,SAAS,CAC7E,CAAC;IACF,YAAY,CAAC,KAAK,EAAE;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,sBAAsB,GAAG,SAAS,CAAC,CAAC;IAChD,eAAe,CAAC,KAAK,EAAE;QACrB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC,wBAAwB,GAAG,SAAS,CAAC,CAAC;IAClD,iBAAiB,CACf,KAAK,EAAE,IAAI,CAAC,wBAAwB,EAAE,IAAI,CAAC,GAAG;QAAE,KAAK,EAAE,UAAU,CAAA;KAAE,GAClE,OAAO,CAAC,wBAAwB,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,gBAAgB,CAAC;CAC7B;AASD,gGAAgG;AAChG,qBAAa,yBAAyB;IAElC,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAFN,KAAK,EAAE,uBAAuB,EAC9B,OAAO,EAAE,qBAAqB,EAC9B,MAAM,gBAAsB;IAGzC,OAAO,CACX,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,wBAAwB,CAAC;CAgFrC"}

package/dist/catalog-capability.d.ts

@@ -0,0 +1,21 @@
+import type { CatalogAcquisitionCapabilityDecision, CatalogResourceRepresentation, CatalogSourceRecord } from './catalog-contracts.js';
+/** Closed observed MIME mapping; icons and file names never establish a format. */
+export declare const CATALOG_REPRESENTATION_MEDIA_TYPES: {
+    readonly pdf: "application/pdf";
+    readonly zip: "application/zip";
+    readonly docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+};
+/** Bound and validate a complete Content-Type before retaining its canonical token. */
+export declare function catalogRepresentationMediaType(value: string): string;
+export declare function catalogRepresentationFormat(mediaType: string): keyof typeof CATALOG_REPRESENTATION_MEDIA_TYPES | undefined;
+export declare class CatalogRepresentationError extends Error {
+    readonly code = "invalid-representation-metadata";
+    constructor();
+}
+/** Missing/null is legacy; malformed present data always throws, never becomes absence. */
+export declare function normalizeCatalogRepresentation(value: unknown): CatalogResourceRepresentation | undefined;
+/** Read-only preselection guard for NEW downloads. It does not authorize legal use or pinned-byte printing. */
+export declare function evaluateCatalogAcquisitionCapability(resource: Pick<CatalogSourceRecord, 'availableFormats' | 'representation'>, format: string, limits?: {
+    maxBytes?: number;
+}): CatalogAcquisitionCapabilityDecision;
+//# sourceMappingURL=catalog-capability.d.ts.map

package/dist/catalog-capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-capability.d.ts","sourceRoot":"","sources":["../src/catalog-capability.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oCAAoC,EACpC,6BAA6B,EAC7B,mBAAmB,EACpB,MAAM,wBAAwB,CAAC;AAEhC,mFAAmF;AACnF,eAAO,MAAM,kCAAkC;;;;CAIrC,CAAC;AACX,uFAAuF;AACvF,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CASpE;AACD,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,MAAM,GAChB,MAAM,OAAO,kCAAkC,GAAG,SAAS,CAK7D;AAED,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,QAAQ,CAAC,IAAI,qCAAqC;;CAKnD;AAiBD,2FAA2F;AAC3F,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,OAAO,GACb,6BAA6B,GAAG,SAAS,CA4F3C;AAED,+GAA+G;AAC/G,wBAAgB,oCAAoC,CAClD,QAAQ,EAAE,IAAI,CAAC,mBAAmB,EAAE,kBAAkB,GAAG,gBAAgB,CAAC,EAC1E,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7B,oCAAoC,CA4CtC"}

package/dist/catalog-contracts.d.ts

@@ -14,6 +14,44 @@ export interface CatalogLicenseEvidence {
     /** Operations expressly authorized by the source evidence. */
     permittedOperations?: CatalogOperation[];
 }
+/** Observed bytes and NEW acquisition support; independent of legal permissions. */
+interface CatalogRepresentationMetadata {
+    byteLength: number;
+    validators: {
+        etag: string;
+        lastModified: string;
+    };
+}
+export type CatalogResourceRepresentation = CatalogRepresentationMetadata & ({
+    format: 'pdf' | 'zip' | 'docx';
+    mediaType: 'application/pdf' | 'application/zip' | 'application/vnd.openxmlformats-officedocument.wordprocessingml.document';
+    acquisition: {
+        status: 'supported';
+        maxBytes: number;
+    } | {
+        status: 'unsupported-format';
+    } | {
+        status: 'size-limit';
+        maxBytes: number;
+    };
+} | {
+    format: 'unknown';
+    /** Null records an absent header; otherwise the observed canonical MIME token. */
+    mediaType: string | null;
+    acquisition: {
+        status: 'unknown-format';
+        reason: 'missing-content-type' | 'unrecognized-content-type';
+    };
+});
+export type CatalogAcquisitionCapabilityDecision = {
+    allowed: true;
+    verification: 'observed' | 'legacy';
+} | {
+    allowed: false;
+    reason: 'format-unavailable' | 'unsupported-format' | 'unknown-format' | 'size-limit' | 'invalid-representation-metadata';
+    maxBytes?: number;
+    byteLength?: number;
+};
 /** A provider's durable source record. It remains distinct after deduplication. */
 export interface CatalogSourceRecord {
     providerId: string;
@@ -32,6 +70,7 @@ export interface CatalogSourceRecord {
     resourceType?: string;
     parentStableId?: string;
     availableFormats?: string[];
+    representation?: CatalogResourceRepresentation;
     licenseEvidence: CatalogLicenseEvidence;
     visibility: CatalogVisibility;
 }
@@ -92,4 +131,5 @@ export interface CatalogActor {
     actorUserId: string;
     roles: readonly string[];
 }
+export {};
 //# sourceMappingURL=catalog-contracts.d.ts.map

package/dist/catalog-contracts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog-contracts.d.ts","sourceRoot":"","sources":["../src/catalog-contracts.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"catalog-contracts.d.ts","sourceRoot":"","sources":["../src/catalog-contracts.ts"],"names":[],"mappings":"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"}

package/dist/catalog-database-sync-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog-database-sync-store.d.ts","sourceRoot":"","sources":["../src/catalog-database-sync-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAK5D,OAAO,KAAK,EACV,mBAAmB,EACnB,qBAAqB,EACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AA2ClE,wEAAwE;AACxE,qBAAa,wBAAyB,YAAW,gBAAgB;IACnD,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,iBAAiB;IAE5C,aAAa,CACjB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC;IAQvC,cAAc,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAyB3D,MAAM,CAAC,MAAM,EAAE,mBAAmB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkCjE,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAazE"}
+{"version":3,"file":"catalog-database-sync-store.d.ts","sourceRoot":"","sources":["../src/catalog-database-sync-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAM5D,OAAO,KAAK,EACV,mBAAmB,EACnB,qBAAqB,EACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AA2ClE,wEAAwE;AACxE,qBAAa,wBAAyB,YAAW,gBAAgB;IACnD,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,iBAAiB;IAE5C,aAAa,CACjB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC;IAQvC,cAAc,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAyB3D,MAAM,CAAC,MAAM,EAAE,mBAAmB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqCjE,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAazE"}

package/dist/catalog-models.d.ts

@@ -1,5 +1,5 @@
 import { SmrtObject } from '@happyvertical/smrt-core';
-import type { CatalogLicenseState, CatalogVisibility } from './catalog-contracts.js';
+import type { CatalogLicenseState, CatalogResourceRepresentation, CatalogVisibility } from './catalog-contracts.js';
 /** Globally visible provider registration. Hosts configure adapters and credentials out of band. */
 export declare class CatalogProvider extends SmrtObject {
     providerId: string;
@@ -21,6 +21,10 @@ export declare class CatalogResource extends SmrtObject {
     resourceType: string;
     parentStableId: string;
     availableFormats: string;
+    /** Serialized observed representation; JSON null is legacy absence. */
+    representation: string;
+    getRepresentation(): CatalogResourceRepresentation | undefined;
+    setRepresentation(value: CatalogResourceRepresentation | undefined): void;
     licenseEvidence: string;
     licenseState: CatalogLicenseState;
     visibility: CatalogVisibility;

package/dist/catalog-models.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog-models.d.ts","sourceRoot":"","sources":["../src/catalog-models.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,UAAU,EAAQ,MAAM,0BAA0B,CAAC;AAE/E,OAAO,KAAK,EACV,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,wBAAwB,CAAC;AAIhC,oGAAoG;AACpG,qBACa,eAAgB,SAAQ,UAAU;IAClB,UAAU,SAAM;IAChB,IAAI,SAAM;IACrC,MAAM,UAAQ;CACf;AAED,oFAAoF;AACpF,qBACa,eAAgB,SAAQ,UAAU;IAClB,UAAU,SAAM;IAChB,QAAQ,SAAM;IACd,QAAQ,SAAM;IACzC,YAAY,SAAM;IACS,KAAK,SAAM;IACtC,mBAAmB,SAAM;IACzB,MAAM,SAAM;IACZ,QAAQ,SAAQ;IAChB,MAAM,SAAQ;IACd,QAAQ,SAAM;IACd,YAAY,SAAM;IAClB,cAAc,SAAM;IACpB,gBAAgB,SAAQ;IACxB,eAAe,SAAQ;IACvB,YAAY,EAAE,mBAAmB,CAAa;IAC9C,UAAU,EAAE,iBAAiB,CAAa;IAC1C,8EAA8E;IAC9E,aAAa,SAAM;IACnB,WAAW,SAAM;CAClB;AAED,0FAA0F;AAC1F,qBACa,gBAAiB,SAAQ,UAAU;IAC9C,kEAAkE;IACvC,UAAU,SAAM;IAC3C,MAAM,SAAM;IACZ,kFAAkF;IAClF,KAAK,SAAM;IACX,QAAQ,UAAS;IACjB,MAAM,UAAS;IACf,WAAW,SAAM;IACjB,aAAa,SAAK;IAClB,QAAQ,SAAQ;IAChB,gBAAgB,SAAM;CACvB;AAED,mFAAmF;AACnF,qBAEa,gBAAiB,SAAQ,UAAU;IAClC,QAAQ,SAAM;IACyB,UAAU,SAAM;IACxC,gBAAgB,SAAM;IACtB,gBAAgB,SAAM;CAClD;AAED,yFAAyF;AACzF,qBAEa,kBAAmB,SAAQ,UAAU;IACpC,QAAQ,SAAM;IACyB,UAAU,SAAM;IACf,WAAW,SAAM;IAC1C,QAAQ,SAAM;IACd,MAAM,SAAM;IACZ,MAAM,SAAM;IACvC,WAAW,SAAM;IACjB,OAAO,SAAM;CACd"}
+{"version":3,"file":"catalog-models.d.ts","sourceRoot":"","sources":["../src/catalog-models.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,UAAU,EAAQ,MAAM,0BAA0B,CAAC;AAG/E,OAAO,KAAK,EACV,mBAAmB,EACnB,6BAA6B,EAC7B,iBAAiB,EAClB,MAAM,wBAAwB,CAAC;AAIhC,oGAAoG;AACpG,qBACa,eAAgB,SAAQ,UAAU;IAClB,UAAU,SAAM;IAChB,IAAI,SAAM;IACrC,MAAM,UAAQ;CACf;AAED,oFAAoF;AACpF,qBACa,eAAgB,SAAQ,UAAU;IAClB,UAAU,SAAM;IAChB,QAAQ,SAAM;IACd,QAAQ,SAAM;IACzC,YAAY,SAAM;IACS,KAAK,SAAM;IACtC,mBAAmB,SAAM;IACzB,MAAM,SAAM;IACZ,QAAQ,SAAQ;IAChB,MAAM,SAAQ;IACd,QAAQ,SAAM;IACd,YAAY,SAAM;IAClB,cAAc,SAAM;IACpB,gBAAgB,SAAQ;IACxB,uEAAuE;IACvE,cAAc,SAAU;IAExB,iBAAiB,IAAI,6BAA6B,GAAG,SAAS;IAG9D,iBAAiB,CAAC,KAAK,EAAE,6BAA6B,GAAG,SAAS,GAAG,IAAI;IAKzE,eAAe,SAAQ;IACvB,YAAY,EAAE,mBAAmB,CAAa;IAC9C,UAAU,EAAE,iBAAiB,CAAa;IAC1C,8EAA8E;IAC9E,aAAa,SAAM;IACnB,WAAW,SAAM;CAClB;AAED,0FAA0F;AAC1F,qBACa,gBAAiB,SAAQ,UAAU;IAC9C,kEAAkE;IACvC,UAAU,SAAM;IAC3C,MAAM,SAAM;IACZ,kFAAkF;IAClF,KAAK,SAAM;IACX,QAAQ,UAAS;IACjB,MAAM,UAAS;IACf,WAAW,SAAM;IACjB,aAAa,SAAK;IAClB,QAAQ,SAAQ;IAChB,gBAAgB,SAAM;CACvB;AAED,mFAAmF;AACnF,qBAEa,gBAAiB,SAAQ,UAAU;IAClC,QAAQ,SAAM;IACyB,UAAU,SAAM;IACxC,gBAAgB,SAAM;IACtB,gBAAgB,SAAM;CAClD;AAED,yFAAyF;AACzF,qBAEa,kBAAmB,SAAQ,UAAU;IACpC,QAAQ,SAAM;IACyB,UAAU,SAAM;IACf,WAAW,SAAM;IAC1C,QAAQ,SAAM;IACd,MAAM,SAAM;IACZ,MAAM,SAAM;IACvC,WAAW,SAAM;IACjB,OAAO,SAAM;CACd"}

package/dist/catalog-read-service.d.ts

@@ -1,4 +1,4 @@
-import type { CatalogActor, CatalogLicenseEvidence, CatalogSourceRecord } from './catalog-contracts.js';
+import type { CatalogActor, CatalogLicenseEvidence, CatalogResourceRepresentation, CatalogSourceRecord } from './catalog-contracts.js';
 import { CatalogPolicy } from './catalog-policy.js';
 export interface CatalogReadStore {
     search(input: {
@@ -28,6 +28,7 @@ export interface CatalogResourceView {
     resourceType?: string;
     parentStableId?: string;
     availableFormats?: string[];
+    representation?: CatalogResourceRepresentation;
     license: Pick<CatalogLicenseEvidence, 'state' | 'identifier' | 'version' | 'attribution' | 'exceptions' | 'retrievedAt'>;
 }
 export declare class CatalogReadService {

package/dist/catalog-read-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog-read-service.d.ts","sourceRoot":"","sources":["../src/catalog-read-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,sBAAsB,EACtB,mBAAmB,EACpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,KAAK,EAAE;QACZ,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC,SAAS,CAAC,mBAAmB,GAAG;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,EAAE,CAAC,CAAC;CAChE;AAED,yGAAyG;AACzG,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,OAAO,EAAE,IAAI,CACX,sBAAsB,EACpB,OAAO,GACP,YAAY,GACZ,SAAS,GACT,aAAa,GACb,YAAY,GACZ,aAAa,CAChB,CAAC;CACH;AAED,qBAAa,kBAAkB;IAE3B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBADN,KAAK,EAAE,gBAAgB,EACvB,MAAM,gBAAsB;IAGzC,MAAM,CACV,KAAK,EAAE,YAAY,EACnB,MAAM,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GAChE,OAAO,CAAC,mBAAmB,EAAE,CAAC;IASjC,OAAO,CAAC,IAAI;CA6Cb"}
+{"version":3,"file":"catalog-read-service.d.ts","sourceRoot":"","sources":["../src/catalog-read-service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,YAAY,EACZ,sBAAsB,EACtB,6BAA6B,EAC7B,mBAAmB,EACpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,KAAK,EAAE;QACZ,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC,SAAS,CAAC,mBAAmB,GAAG;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,EAAE,CAAC,CAAC;CAChE;AAED,yGAAyG;AACzG,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,cAAc,CAAC,EAAE,6BAA6B,CAAC;IAC/C,OAAO,EAAE,IAAI,CACX,sBAAsB,EACpB,OAAO,GACP,YAAY,GACZ,SAAS,GACT,aAAa,GACb,YAAY,GACZ,aAAa,CAChB,CAAC;CACH;AAED,qBAAa,kBAAkB;IAE3B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBADN,KAAK,EAAE,gBAAgB,EACvB,MAAM,gBAAsB;IAGzC,MAAM,CACV,KAAK,EAAE,YAAY,EACnB,MAAM,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GAChE,OAAO,CAAC,mBAAmB,EAAE,CAAC;IASjC,OAAO,CAAC,IAAI;CAiDb"}