@happyvertical/smrt-education 0.0.0-stage → 0.57.0

package/AGENTS.md

@@ -0,0 +1,32 @@
+# smrt-education
+
+Catalog objects are optional-tenant scoped and have no generated REST, CLI, MCP,
+or AI surface. Applications use `CatalogService`, supplying their actor-bound
+authorization decision and the trusted `TenantCollection.withTenantCatalogReadScope`
+adapter from smrt-users. That read scope may widen only an allowlisted catalog
+collection's `list` to self, ancestors, and globals; it never authorizes a get,
+write, raw query, sibling, or descendant read.
+
+`personal-use-copy` courses and all `answer-key` lesson assets are private
+family material. Do not publish them, promote them, or expose them through a
+learner-facing result. `LessonAsset` is the sole owner join for lesson files;
+do not add asset-id fields to lesson subclasses.
+
+Learner objects require exact tenant ownership and close generated surfaces.
+`LearnerService` owns actor/resource authorization and transactional planning and
+start-progress; see [learner contract](agents/learner-service.md). Guardian
+relationships require a host decision about their type and effective terms.
+Never expose direct collection writes as learner handlers, reset progress on a
+retry, or treat an unscored nullable decimal as zero.
+
+Submission capture, guardian grading and private PDF packet splitting use
+`SubmissionService`; see [submission contract](agents/submission-service.md).
+Keep asset metadata on the same transaction and compensate only newly planned
+files after rollback; never expose source URIs or accept learner grade patches.
+
+Validation: `pnpm --filter @happyvertical/smrt-education test`,
+`test:postgres`, `typecheck`, and `build`.
+
+Source import: [host boundary and transaction contract](agents/source-import.md).
+`SourceImportService` requires host opt-in, matching active actor/tenant and
+explicit licensing authorization; never add a system/global write bypass.

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,140 @@
-# Temporary Holding Version
+# @happyvertical/smrt-education
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Preview education catalog models and authorized catalog reads for s-m-r-t.
+The package represents courses, ordered sections, lessons, and lesson-owned files.
+It supplies catalog structure and authorized learner planning/progress workflows.
+Applications authenticate actors and decide guardian permissions.
+
+## Install
+
+```sh
+pnpm add @happyvertical/smrt-education
+```
+
+Use the package with the core, users, profiles, tenancy, and assets packages.
+Apply application migrations before using the catalog collections.
+Runtime catalog operations do not create application schema.
+
+## Models and collections
+
+| Model | Purpose |
+| --- | --- |
+| `CourseSource` | Host-managed adapter policy and sharing ceiling |
+| `Course` | Course metadata, license, status, and optional owning tenant |
+| `ExternalCourse` | External course subtype sharing the Course table |
+| `AuthoredCourse` | Authored course subtype sharing the Course table |
+| `CourseSection` | Ordered section belonging to a course |
+| `Lesson` | Ordered lesson belonging to a section |
+| `Reading`, `Video`, `Worksheet`, `Exercise` | Lesson subtypes |
+| `LessonAsset` | Lesson-owned file join with a relationship such as printable or answer-key |
+| `Learner` | A required User/Person identity and guarded settings in one family tenant |
+| `Curriculum` | A learner plan for a distinct period |
+| `Enrollment` | One course in a curriculum |
+| `LessonProgress` | One lesson in an enrollment, with nullable score and separate history |
+
+Each exported model has a corresponding exported collection.
+Course and lesson subtypes use single-table inheritance.
+Sections and lessons sort by `sortOrder`, with identifier ordering for ties.
+Lesson files belong in `LessonAsset`; lesson subtypes do not carry asset-id fields.
+
+## Basic integration
+
+1. Create the course, section, lesson, and lesson-asset collections with the
+   application's database executor.
+2. Supply those collections, a request-bound `TenantCollection`, and the host's
+   actor-bound permission resolver to `CatalogService`.
+3. Enable tenancy and establish the authenticated actor's active tenant context.
+4. Call `findVisible` with that tenant's canonical identifier and the actor's
+   user identifier to list the ordinary catalog.
+5. Call `projectCourse` with the same context and a visible course identifier
+   to obtain its ordered sections, lessons, and allowed asset joins.
+
+The [catalog service integration tests](src/__tests__/catalog-service.test.ts)
+provide executable examples of collection setup, `withTenant`, and service reads.
+See the [integration contract](agents/catalog-service.md) for host responsibilities.
+The authorizer must make a trusted server-side permission decision for the actor;
+a caller-supplied boolean is not a substitute for authentication or authorization.
+
+## Privacy and ownership
+
+Ordinary catalog reads can include the active tenant, its ancestors, and globals.
+The supplied tenancy capability widens only the allowlisted catalog list reads.
+It does not grant generic get, write, raw query, sibling, or descendant access.
+
+Personal-use copies require an owning tenant and cannot be published.
+Their owner and license kind cannot be changed after creation.
+`includePrivate` requires a separate host grant and returns only the active
+owner's personal copies, never an ancestor's or global private copy.
+The shared Tenant model has no family/group discriminator; hosts provision
+family tenants and authorize their guardian workflows.
+
+Learner projections remove worksheet answer URLs and answer-key asset joins.
+`includeAnswerKeys` requires a separate host permission.
+Every projected child must have the selected course's exact owning tenant.
+Stored inconsistent section, lesson, and asset links are excluded.
+Generated REST, CLI, MCP, and AI operations are closed for these models.
+
+## Learner workflows
+
+Create `LearnerService` with the application's root database executor and trusted
+learner/catalog authorizers. In the authenticated actor's exact `withTenant`
+context, an authorized guardian can `createCurriculum` and `enroll`; a learner
+can `getLearner`, `startLesson`, and `listProgress` for their own work.
+Guardian access requires a same-tenant directed `ProfileRelationship` plus the
+host's permission decision. Sibling membership does not grant access.
+
+Repeated starts preserve the existing progress, including attempts and scores.
+A new curriculum/year creates a distinct enrollment and fresh progress history.
+An unscored lesson has `bestScore: null`, distinct from zero. The service does
+not accept score or completion patches; `SubmissionService` owns guardian grading.
+Use `withTransaction` and its callback service to compose atomic operations.
+Results are plain data views, so no transaction-bound model handle escapes.
+
+The [learner integration contract](agents/learner-service.md) describes required
+identity provisioning, catalog permissions, supported workflows and limitations.
+The [executable learner workflows](src/__tests__/learner-workflows.ts) test this
+integration on both SQLite and PostgreSQL.
+
+## Submissions and worksheet packets
+
+`SubmissionService` captures tenant-owned uploads, reviews or attests work with
+optional guardian scores, signs authorized asset claims, and splits private
+PDF packets by page range. It reuses learner ownership and transaction checks.
+See the [submission integration contract](agents/submission-service.md) for
+inputs, retry rules, signing requirements and external-storage compensation.
+
+## Source imports
+
+`SourceImportService` imports Easy Peasy pages as private family pointers after
+explicit host terms acceptance. Hosts inject the page fetcher and authorize the
+active actor, family/group destination and licensing evidence. Re-import refreshes
+URLs in place without deleting lessons or learner history. No lesson text or PDFs
+are mirrored. See the [source integration contract](agents/source-import.md) and
+[source behavior matrix](../../docs/test-matrix/3967-education-sources.md).
+
+## Recipes
+
+`EducationCatalogRecipe` declares `education.catalog`; `EducationLearnerRecipe`
+declares `education.learner`.
+Its course navigation and model declarations support application composition.
+A recipe does not grant permission to expose model CRUD or private material.
+
+## Database support and validation
+
+SQLite and PostgreSQL exercise catalog persistence and child ownership guards.
+The real ancestor hierarchy integration is exercised on SQLite.
+DuckDB tests cover Course-only persistence: existing core DDL gates reject
+catalog child update-cascade and Asset/Tenant self-referential foreign keys.
+Use SQLite or PostgreSQL for full catalog schemas; those gates remain intact.
+
+Run the package's `test`, `test:postgres`, `typecheck`, and `build` scripts.
+The [behavior matrix](../../docs/test-matrix/3966-education-catalog.md) records
+regressions, dialect coverage, and the existing DuckDB setup limitations.
+
+## Related documentation
+
+- [Package agent guidance](AGENTS.md)
+- [Core persistence](../core/README.md)
+- [Users and tenant hierarchy](../users/README.md)
+- [Tenant isolation](../tenancy/README.md)
+- [Assets](../assets/README.md)

package/agents/catalog-service.md

@@ -0,0 +1,45 @@
+# Catalog service integration
+
+`EducationCatalogRecipe` is a cookbook declaration, not permission to expose
+model CRUD. Hosts construct `CatalogService` with a `CourseCollection`, their
+request-bound `TenantCollection`, and a permission resolver adapter. They call
+`findVisible({ tenantId, actorUserId })` for a learner projection and pass
+`includePrivate: true` only after a guardian-level
+`education.catalog.read-private` grant. The service enters
+`TenantCollection.withTenantCatalogReadScope` for the Course collection; that
+scope is limited to `list`, active family ancestors, and global rows.
+
+Private copies are returned only when their tenant exactly matches the active
+request tenant, even with the private-read grant. Ancestor and global private
+rows are excluded. Projection also excludes each section, lesson, and asset
+join whose tenant differs from the selected course, including malformed stored
+links that predate the model save guards.
+
+The shared Tenant model has no family/group kind discriminator. Hosts provision
+family tenants and authorize guardian authoring for those tenants; the catalog
+enforces a non-null owning tenant, immutable personal-copy tenant/license, and
+prohibits `published` personal copies on create and update. Hierarchy position
+is not a family classification. This is a new package with no deployed catalog
+rows to migrate. If a host imports invalid published personal copies, correct
+them to `draft` or `archived` under the original owner before normal saves; never
+relabel or promote them. Read ownership checks remain enforced for invalid rows.
+
+The host resolves sections, lessons, and LessonAsset rows only after selecting
+an authorized visible course, preserving the course tenant and excluding
+`answer-key` relationships from learner projections. Guardian authoring and
+asset linking use host handlers that make the same permission decision; no
+generated REST, CLI, MCP, or AI operation may bypass those handlers.
+
+Ownership checks use SQL tenant identity predicates so native UUID driver values
+cannot reject an unchanged owner. Course-only persistence is exercised on DuckDB;
+full catalog child/asset schemas inherit core's current DuckDB rejection of
+ON UPDATE CASCADE and self-referential foreign keys. Use SQLite or PostgreSQL for
+those schemas; no schema gate is relaxed by this package.
+
+Private-course visibility is a mandatory collection SQL predicate applied before
+`limit` and `offset`, including selected-column reads. Caller options cannot
+replace that predicate. Video constructor options are reapplied after subtype
+field initialization, matching Worksheet. LessonAsset's explicit natural key is
+`(tenant_id, lesson_id, asset_id, relationship)`; same-owner and null-owner retries
+retain one join identity. Core's cross-owner guard remains in place. A hostile
+stored join cannot reserve the legitimate owner's key or be overwritten by it.

package/agents/learner-service.md

@@ -0,0 +1,101 @@
+# Learner service boundary
+
+`Learner`, `Curriculum`, `Enrollment`, and `LessonProgress` require an exact
+owning tenant. Their generated API, CLI, MCP, and AI operations are closed.
+The corresponding collections and model saves are trusted server persistence
+APIs, not request handlers. Hosts must not wrap them in generic learner CRUD.
+
+## Identity and authority
+
+Provision a Person Profile, a linked User, and an active Membership before
+creating a Learner with explicit `tenantId`, `userId`, and `profileId`. User
+email is optional. Learner identity cannot be reassigned after creation.
+Guardianship is a directed `ProfileRelationship`, not a Learner `parentId`.
+The shared Tenant has no family discriminator: “family” means a tenant that
+the host has provisioned and authorized for this purpose.
+
+Construct `LearnerService(db, authorizeLearner, authorizeCatalog)` with one
+root database executor and trusted server-side authorizers. Enable tenancy
+and establish `withTenant({ tenantId, userId }, callback)` from authenticated
+credentials. Every request must match that active actor and tenant exactly;
+missing context, spoofed identifiers, and super-admin bypass contexts fail.
+Both the actor and learner must hold active memberships in that exact tenant.
+A learner's User must still link to the learner's Person Profile.
+
+For a different actor, supply `guardianRelationshipId`. The service checks
+that this relationship is owned by the active tenant and directed from the
+actor's User Profile to the learner's Profile. `authorizeLearner` receives
+`own`, `action`, and the verified `relationshipTypeId`; the host must check
+that the type represents guardianship, its terms are effective, and that
+its permission policy allows the action. An arbitrary relationship is not a
+guardian grant. Missing relationships and host denials/exceptions fail closed.
+Same-tenant membership alone never grants sibling access.
+
+## Supported workflow
+
+- `getLearner` returns authorized learner metadata and parsed settings.
+- `createCurriculum` creates a **planned** curriculum for an authorized guardian.
+  A learner cannot plan their own curriculum. Title is required.
+- `enroll` requires that guardian authority and a matching tenant curriculum.
+  It returns the existing enrollment for the same curriculum/course unchanged.
+- `startLesson` allows the learner or authorized guardian to create their own
+  enrollment's lesson progress in `in_progress`. It derives learner identity
+  from the validated enrollment. Repeated starts return existing state without
+  resetting counters, scores, completion, or timestamps.
+- `listProgress` reads only the validated learner/enrollment and lessons still
+  visible in that enrollment's course. Inconsistent persisted links fail
+  closed or are omitted from the list.
+
+Service results are data-only views, with no persistence or database methods.
+Extra request fields are never model patches: a learner cannot set score,
+attempt count, or completion status through this API. Curriculum activation,
+completion transitions and dashboard aggregation are not supported by this
+base service. SubmissionService extends its owning transaction/auth boundary for
+capture and guardian grading; see [submission contract](submission-service.md).
+Direct model writes require trusted authority.
+
+Catalog visibility and child ownership reuse `CatalogService` on the same
+executor. Learner operations request private-inclusive catalog access, so the
+host catalog authorizer must permit both `education.catalog.read` and
+`education.catalog.read-private` for the supported enrollment workflow.
+Private copies remain restricted to the exact owner. The service constructs a
+whitelisted catalog request; caller options and answer-key flags are discarded.
+Answer keys are never requested or returned. A catalog grant does not grant learner authorization.
+
+## Transactions and history
+
+`withTransaction(async transaction => ...)` composes service operations on the
+callback's transaction-bound service. Use that service for every operation in
+the unit. Throwing rolls back its curriculum, enrollment, and progress writes.
+The callback's service closes when the transaction ends and rejects later calls.
+A failed mutation poisons the unit even if the callback catches its rejection;
+queued mutations are cancelled. Callback failure stops pending work and waits for
+already-running mutations to settle before rollback releases the executor. On
+success, already-enqueued mutations finish before commit. Do not retain the
+callback's service beyond the callback. The constructor
+accepts a root database; callers composing work use this method instead of
+passing an unmanaged transaction handle.
+
+PostgreSQL locks the parent curriculum/enrollment row before find-or-create.
+Embedded writes use the core transaction queue. Concurrent mutations inside
+one callback transaction are ordered on that connection, so duplicate starts
+within a `Promise.all` also return the same row. Database natural-key constraints
+arbitrate enrollment `(tenant_id, curriculum_id, course_id)` and progress
+`(tenant_id, enrollment_id, lesson_id)` identities. Explicit storage conflict
+keys include the tenant prefix because core does not add it to explicit keys.
+The logical keys required by #3968 remain curriculum/course and enrollment/lesson:
+immutable parent ownership and parent-tenant checks reject any second tenant
+for the same parent. The storage prefix cannot create a second valid logical row. Ordinary repeated and concurrent calls
+return one row; an aborted workflow can be retried. No in-memory process lock
+is used for PostgreSQL concurrency.
+
+A new year is a new curriculum and enrollment, producing independent progress.
+Unscored `bestScore` persists as null; score zero is a real score. Scores are
+nullable decimals in [0,1]; counters are nonnegative safe integers. Settings
+are stored as JSON text and accessed through guarded `getSettings`/`setSettings`.
+
+The shared executable workflows in `src/__tests__/learner-workflows.ts` run
+against SQLite and PostgreSQL, including actor/resource/context denial,
+concurrent creation, rollback, history preservation, and zero/null scores.
+Full DuckDB schemas remain blocked by existing upstream DDL restrictions;
+no full learner workflow support on DuckDB is claimed.

package/agents/source-import.md

@@ -0,0 +1,63 @@
+# Source import integration
+
+`SourceImportService` is a server-side host boundary, with no generated REST,
+CLI, MCP or AI operation. Recipes remain metadata only. Provision a closed
+`CourseSource` in the owning tenant, then construct the service with the root
+SQL database and an actor-bound `SourceImportAuthorizer`. Enable tenancy and
+call within `withTenant({ tenantId, userId })`; the request must match both.
+Missing context, a different actor/tenant and super-admin bypass fail closed.
+
+Register Easy Peasy only after the host operator accepts its terms, using
+`registerEasyPeasy({ termsAccepted: true, fetchPage })`. Do not derive that
+boolean from an HTTP request. `fetchPage(url, { redirect: 'error' })` must reject
+redirects, bound time/size and return `{ html, url }`. It fetches the page only,
+never a PDF. The service checks the approved HTTPS URL before fetching, checks
+the response URL, limits HTML to 2 million characters, then parses the complete
+page before any write. There is no automatic registration or network access. Structural h1–h6 headings delimit day content, including trailing Resources
+sections; ordinary non-lesson bold instructions do not. Supported
+heading blocks are h1–h6 or a lesson marker as the first bold run in a
+paragraph/list item.
+Recognizable markers outside that layout, including multiple markers in one
+paragraph, fail closed rather than silently assigning a PDF to the wrong day.
+
+The authorizer must verify the authenticated actor's management grant and the
+provisioned tenant's family/group classification. Tenant has no built-in kind;
+neither hierarchy position nor client input establishes a family. Authorization
+is required before fetch and again inside the transaction; callbacks must be
+read-only decisions, since a rolled-back contention retry can call them again.
+
+`sharing` is a ceiling: private permits private-family import only; group and
+global permit private-family or group import. Group imports additionally require
+nonblank host-recorded `config.licenseEvidence` and an explicit host grant that
+validates that permission. Global/null destinations are unsupported and rejected;
+there is no global/system bypass. Widening a source never promotes existing
+imports. Private imports are draft `personal-use-copy` courses and retain the
+catalog's immutable owner/license and no-publication protection. A host may
+create a new licensed group source and import there after receiving permission.
+
+Use a stable `courseRef` independent of source URLs. Identities derive from the
+owning tenant, source row ID, course reference and lesson day; retain the source
+row when updating policy. Changes to titles/page/PDF URLs update in place.
+Missing days are retained, not deleted, so enrollment, progress, submission and
+asset foreign keys remain valid. A changed lesson kind fails the whole import
+rather than replacing a row. Only title and pointer fields are refreshed; body,
+answer keys, learner state and manually authored settings are never replaced.
+The packet URL is returned as a source link and is not downloaded or mirrored.
+
+All source policy rechecks and catalog mutations use collections bound to the
+same SQL transaction. Embedded writes use the public write queue; PostgreSQL
+serializes an import identity with a transaction-scoped advisory lock. Only
+rolled-back busy/serialization/deadlock errors retry (at most three retries),
+without repeating fetch. Connection-invalidated and other failures propagate.
+Do not wrap the service in a caller transaction if the caller expects a durable
+commit before returning; any outer transaction remains the caller's boundary.
+
+SQLite and PostgreSQL integration tests exercise real transactions and rollback.
+Full catalog children remain unavailable on DuckDB due to core's existing
+ON UPDATE CASCADE/self-referential schema limitations documented in
+[catalog-service.md](catalog-service.md); no alternate schema is substituted.
+Tests use synthetic local HTML and an injected fetch callback, never the network.
+
+Generic “Printable” and “Printables” labels identify lesson PDFs; course packets
+require explicit packet/whole-course/complete-course wording. Only actual href
+attributes supply pointers; data-href metadata does not.

package/agents/submission-service.md

@@ -0,0 +1,122 @@
+# Submission and paper workflow
+
+Construct `SubmissionService(db, authorizeLearner, authorizeCatalog, {storage,
+storeOptions?, signAsset?})` from trusted server configuration. It extends
+`LearnerService`: the same active actor/tenant, memberships, linked person,
+directed guardian relationship and host permission checks apply. The host must
+allow `education.learner.submit`, `education.learner.grade` or
+`education.learner.packet` as appropriate. Grade and packet actions always reject
+the learner's own identity, even if the host authorizer returns true.
+
+The protected transaction/auth hooks are internal owning-service extension
+points. They are not handler APIs. All public service results remain data-only.
+Use the callback's service in `withTransaction`; escaped services are closed.
+Submission operations share its serial queue, poison-on-failure behavior and
+PostgreSQL enrollment lock. No runtime schema creation occurs.
+
+## Capture and grading
+
+`captureSubmission` takes the learner request, `enrollmentId`, `lessonId`, a
+nonempty stable `requestKey`, and `pages` containing `name`, `mimeType` and Buffer
+`data`. Each upload becomes a fresh Asset owned by the learner's profile and
+exact tenant, joined solely through `SubmissionAsset`. Up to 100 uploads of
+25 MiB each are accepted (JPEG, PNG, WebP, or PDF). It atomically creates the
+submission/asset metadata and moves only that enrollment's progress to
+`submitted`, incrementing attempts once. Caller status, score, grader, asset ID,
+and answer-key flags are never patches. Equal request-key/content retries return
+the existing submission; altered retries fail. Submitted/review/complete/skipped
+progress rejects new captures. Content includes ordered filenames, MIME types,
+bytes and notes. Hosts should impose tighter request/body limits as needed.
+
+`reviewSubmission` accepts an existing authorized submission and optional score
+and feedback. `attestLesson` creates/reuses an Attestation for a matching progress
+item without requiring uploads. Both require a verified guardian and create a
+new guardian Grade, set submission to `graded` and progress to `complete`.
+Omitted/null score is unscored; zero is a real score. The latest guardian grade
+wins over auto/AI/instructor proposals, and its score replaces progress's score.
+Review history is retained. ExternalCompletion is available for trusted server
+persistence; phase-zero learner handlers cannot forge reported scores. Online
+submissions and automatic grading are not implemented.
+
+`getSubmission` returns only submission metadata, page asset IDs and the selected
+grade. It does not include catalog answers, extracted answers, storage paths,
+model objects, or database handles.
+
+## Storage and signed routes
+
+The service creates an AssetRuntime bound to the operation's transaction. It
+requires a resolved URI whose filename retains the fresh asset UUID and MIME
+extension; custom resolvers may choose its provider/directory but must route
+that URI to the corresponding unique file. Shared existing locators are
+rejected before preservation or cleanup registration. It plans and persists
+that unique asset URI before writing, registering that new
+asset for cleanup before the provider can partially write. After rollback,
+files are removed through the runtime store. Before deletion, the root database
+must confirm that no asset owner committed: uncertain commit/read failures never
+cause committed bytes to be removed. Only this operation's newly created assets
+are candidates; pre-existing files are never adopted into its cleanup ledger.
+
+Database metadata is atomic; external storage uses compensation, not a database
+transaction. If cleanup cannot complete, `SubmissionStorageCleanupError` contains
+fresh asset IDs and the original cause. Operators must reconcile those IDs in
+the configured `education-page/<id>.<extension>` storage namespace (custom
+resolvers must retain their routing audit). A successful retry uses fresh IDs
+and cannot delete or reuse orphaned bytes. Process termination may also leave
+unreferenced files; hosts need storage orphan reconciliation. Do not suppress
+cleanup failures or claim crash-safe distributed atomicity.
+
+`signSubmissionAsset` verifies the submission/enrollment/learner ownership and
+its noun join, then verifies the Asset's tenant and learner profile before
+calling the configured trusted signer. Claims contain actor, tenant, learner,
+enrollment, submission, asset and a five-minute expiry; no static source URI is
+returned. The host signs every claim and its serving endpoint must verify the
+signature, expiry, current actor/tenant and object authorization before serving.
+A bearer URL must never become a cross-family or sibling access bypass.
+
+## Personal worksheet packets
+
+`splitWorksheetPacket` takes the guardian learner request, exact-owned
+`personal-use-copy` `courseId`, PDF bytes and ranges `{lessonId, firstPage,
+lastPage}`. Page bounds are inclusive and one-based. Ranges must be in bounds,
+disjoint and target distinct Worksheet lessons in that private course. The
+50 MiB / 100-range limits are enforced before PDF parsing. `pdf-lib` extracts
+actual pages into independent PDFs and records private printable LessonAssets.
+All resulting metadata commits together; storage failure compensates new PDFs.
+The source packet is not retained. No shared/global course is accepted and no
+answer-key join is created. A successful repeated packet upload intentionally
+adds another printable version; a failed upload can be retried safely.
+
+Shared integration workflows run on SQLite and real PostgreSQL. Full DuckDB
+workflow support remains outside the existing supported schema boundary.
+
+## Private asset boundary
+
+Captured pages and split packet pages use `Asset.accessMode: 'private'` from their
+initial insert. Ordinary generated Asset REST/MCP operations cannot list, hydrate,
+update or delete them, including through the parent STI model. The service opens
+an exact tenant/actor/learner-owner/asset-ID capability only after its normal learner
+relationship checks. A host's signed serving route must repeat authorization and
+open that exact capability before loading the asset. See the owning
+[private asset contract](../../assets/agents/private-assets.md).
+
+Storage must be private (including provider ACLs). Public HTTP(S) source locators
+are rejected; a hidden URL alone cannot protect publicly accessible bytes. Apply
+the manifest migration adding `assets.access_mode` before deploying this runtime;
+legacy ordinary assets retain the public default. Runtime creates no schema.
+
+Private lesson files must already be private Assets in the same tenant. Saving
+an answer-key join, or any join under a personal-use-copy course, requires the
+host's exact actor/owner/asset capability; a public asset is never automatically
+promoted. Packet splitting retains this capability while creating each join.
+Persisted course tenant/license and section/lesson parent identity cannot change;
+create new structure and explicitly re-author its joins instead. Mandatory
+write predicates enforce this even for natural-key adoption and concurrent writes.
+Ordinary content and metadata refresh remains supported. This
+prevents existing public material being reclassified by moving its parent.
+
+For pre-existing invalid joins, an authorized host must inventory private-material
+joins and remove invalid associations, recreate the bytes in private storage as a
+new privately classified Asset, then re-author the join under its exact capability.
+Do not merely hide the URI, mutate access_mode with raw SQL, or delete shared
+public bytes. This repair requires explicit storage/ownership authorization;
+normal runtime does not migrate existing records.

package/dist/__smrt-register__.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=__smrt-register__.d.ts.map

package/dist/__smrt-register__.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"__smrt-register__.d.ts","sourceRoot":"","sources":["../src/__smrt-register__.ts"],"names":[],"mappings":""}

package/dist/catalog-service.d.ts

@@ -0,0 +1,50 @@
+import type { TenantCollection } from '@happyvertical/smrt-users';
+import type { Course, CourseSection, Lesson } from './catalog.js';
+import type { CourseCollection, CourseSectionCollection, LessonAssetCollection, LessonCollection } from './collections.js';
+import type { LessonAsset } from './lesson-assets.js';
+/** The application-owned decision that permits a catalog view for one tenant. */
+export type TenantCatalogReadScope = TenantCollection['withTenantCatalogReadScope'];
+export type CatalogActorContext = Parameters<Parameters<TenantCatalogReadScope>[0]['authorize']>[0];
+export type CatalogAuthorizer = (request: Omit<CatalogActorContext, 'mode'> & {
+    action: 'education.catalog.read' | 'education.catalog.read-private' | 'education.catalog.answer-key.read' | 'education.catalog.manage';
+}) => boolean | Promise<boolean>;
+export interface CatalogReadRequest {
+    tenantId: string;
+    actorUserId: string;
+    includePrivate?: boolean;
+    options?: Omit<Parameters<CourseCollection['list']>[0], 'where'>;
+}
+export interface CatalogProjection {
+    course: Course;
+    sections: Array<{
+        section: CourseSection;
+        lessons: Array<{
+            lesson: Lesson;
+            assets: LessonAsset[];
+        }>;
+    }>;
+}
+export declare class CatalogAuthorizationError extends Error {
+    constructor();
+}
+/**
+ * The only package-level family → group → global catalog read boundary.
+ * Generated surfaces are closed; callers must supply both an application
+ * authorization decision and the narrowly-scoped tenancy capability.
+ */
+export declare class CatalogService {
+    private readonly courses;
+    private readonly sections;
+    private readonly lessons;
+    private readonly assets;
+    private readonly tenants;
+    private readonly authorize;
+    constructor(courses: CourseCollection, sections: CourseSectionCollection, lessons: LessonCollection, assets: LessonAssetCollection, tenants: Pick<TenantCollection, 'withTenantCatalogReadScope'>, authorize: CatalogAuthorizer);
+    findVisible(request: CatalogReadRequest): Promise<Course[]>;
+    /** Project one already-visible course without exposing answer-key assets by default. */
+    projectCourse(request: CatalogReadRequest & {
+        courseId: string;
+        includeAnswerKeys?: boolean;
+    }): Promise<CatalogProjection | null>;
+}
+//# sourceMappingURL=catalog-service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-service.d.ts","sourceRoot":"","sources":["../src/catalog-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,KAAK,EACV,gBAAgB,EAChB,uBAAuB,EACvB,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,iFAAiF;AACjF,MAAM,MAAM,sBAAsB,GAChC,gBAAgB,CAAC,4BAA4B,CAAC,CAAC;AACjD,MAAM,MAAM,mBAAmB,GAAG,UAAU,CAC1C,UAAU,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CACnD,CAAC,CAAC,CAAC,CAAC;AAEL,MAAM,MAAM,iBAAiB,GAAG,CAC9B,OAAO,EAAE,IAAI,CAAC,mBAAmB,EAAE,MAAM,CAAC,GAAG;IAC3C,MAAM,EACF,wBAAwB,GACxB,gCAAgC,GAChC,mCAAmC,GACnC,0BAA0B,CAAC;CAChC,KACE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,OAAO,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;CAClE;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,KAAK,CAAC;QACd,OAAO,EAAE,aAAa,CAAC;QACvB,OAAO,EAAE,KAAK,CAAC;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,WAAW,EAAE,CAAA;SAAE,CAAC,CAAC;KAC3D,CAAC,CAAC;CACJ;AAED,qBAAa,yBAA0B,SAAQ,KAAK;;CAKnD;AAUD;;;;GAIG;AACH,qBAAa,cAAc;IAEvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAIxB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBART,OAAO,EAAE,gBAAgB,EACzB,QAAQ,EAAE,uBAAuB,EACjC,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,qBAAqB,EAC7B,OAAO,EAAE,IAAI,CAC5B,gBAAgB,EAChB,4BAA4B,CAC7B,EACgB,SAAS,EAAE,iBAAiB;IAEzC,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAuDjE,wFAAwF;IAClF,aAAa,CACjB,OAAO,EAAE,kBAAkB,GAAG;QAC5B,QAAQ,EAAE,MAAM,CAAC;QACjB,iBAAiB,CAAC,EAAE,OAAO,CAAC;KAC7B,GACA,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;CA+DrC"}