@happyvertical/smrt-education 0.57.37 → 0.57.38

package/AGENTS.md

@@ -37,3 +37,7 @@ never create learning evidence, and blank exercises need explicit work intent.
 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.
+
+Family-owned unassigned originals and audited learner adoption use
+[FamilyIntakeService](agents/family-intake.md). Keep family source scope immutable;
+assignment alone never creates learning history or grants learner inbox access.

package/agents/family-intake.md

@@ -0,0 +1,97 @@
+# Family intake
+
+`FamilyIntakeService` retains guardian-only originals before a learner is known.
+The host supplies a trusted actor/tenant and a current family authorizer; each
+read, original download, assignment and adoption revalidates this authority on
+the service's exact executor. Learners cannot browse the family inbox. Generated
+CRUD, CLI, MCP and AI surfaces remain closed.
+
+Retain the whole document with its source identity, delivery key, immutable hash
+and original private assets. Source delivery retries must preserve identical
+content and provenance. Email and scanner adapters are separate host configuration;
+this service does not configure or select them. Trusted candidate DTOs and their
+quoted evidence are advisory. A guardian's active learner preference, visible
+marks, uncertain names or a first-page guess never establish ownership. Mixed
+learner PDFs stay unresolved until an explicit whole-document assignment is safe.
+
+Assignment records an immutable guardian decision with a revision and request
+key. It does not create learner work. Adoption freezes that assignment and borrows
+the exact original assets through learner photo ownership joins; it never rewrites
+source confidentiality or creates grades. The existing photo resolution and
+completed-work capture preconditions still apply. Existing derived capture copies
+are permitted. Once adopted, a receipt cannot silently change learners; recovery
+requires a separate explicit policy. An unadopted attribution can be corrected by
+another audited decision with the current revision.
+
+Family ownership retains originals beyond generic receipt expiry. Adoption does
+not transfer or delete that ownership. Cleanup and rollback must preserve shared
+retained bytes and compensate only newly created files. Every access checks the
+original hash before adoption or download.
+
+Validation uses shared family workflows on real SQLite and isolated PostgreSQL;
+no AI providers, scanner/email services or containers are required.
+
+Import `FamilyIntakeService`, `receiveFamilyIntake` and
+`retainFamilyIntakeReceipt` from `@happyvertical/smrt-education/ingestion`.
+The bridge uses the fixed `familyIntakeScopeId(tenantId)` namespace and public
+`getReceiptSource` to retain authoritative delivery identity. This namespace is
+never an authorization grant. The host's `IngestionService.authorize` callback
+must call the same current family authorizer on every operation, including direct
+`getEvidence`, `readEvidence` and `getReceiptSource` calls. For example, await
+`family.authorizeFamilyIntake({ tenantId: scope.tenantId, actorUserId: scope.actorId })`
+then return true; propagate denial. Actor equality or tenant membership alone is
+insufficient. This protects raw envelopes and rejected/unretained originals as
+well as adopted receipts. Adoption permits only normal authorized learner work
+reads; it never grants the learner generic family ingestion access. A receive that
+succeeds before education retention fails is repaired by retrying the same
+receipt, never by inventing another delivery identity.
+
+Deploy manifest migrations for all three FamilyIntake models and the nullable
+`WorkbookPhotoIntake.familyIntakeId` FK before use. There is no runtime DDL.
+Adoption commits its immutable audit and exact photo/original joins atomically;
+the family asset remains the sole original owner. Existing derived submission
+copies use normal capture compensation. The exact adoption audit is required
+when validating borrowing joins, reads and immutable family-scope analysis.
+`countFamilyIntakes` counts unadopted receipts across the full inbox, while
+`listFamilyIntakes` pages the complete receipt history.
+
+After adoption, use the returned `photoIntakeId` with ordinary photo
+resolution/capture methods. Family-scope photo analysis checks the exact adopted
+item/learner binding; learner-scoped uploads retain their existing strict scope.
+The existing submission/assessment ingestion handlers still revalidate the
+captured learner/attempt. Temporary ingestion expiry does not prevent manual
+resolution/capture from retained education originals; re-analysis of an expired
+receipt needs a separately authorized retained-input orchestration.
+
+This initial contract assigns a whole receipt/document. It does not split a
+mixed-child PDF, automatically infer a child or configure a source adapter.
+Future range adoption must preserve original hashes and page provenance; the
+retained immutable originals remain available for such an explicit workflow.
+
+Source-tree retention includes image/PDF attachments beneath metadata envelopes.
+A supported-media descendant of another supported original (for example a PDF's
+page thumbnail) stays in the evidence graph but is not duplicated as learner
+work. Photo identification and captured-work analysis preservation use this same
+original-selection convention, so retained attachment hashes remain authoritative
+after adoption and retries. The immutable graph retains only IDs, parent IDs, media types and hashes;
+it does not copy email bodies, arbitrary headers or credentials into public
+source metadata. A source image such as an email logo is not automatically
+classified as completed work. Whole-document attribution/classification remains
+an explicit guardian decision; ambiguous mixed contents need resolution.
+
+Custom source adapters must follow this supported convention: metadata parents
+contain independent original attachments; descendants of supported media are
+renditions of that media. Extraction outputs already live separately from source
+evidence. An adapter that uses media-child relationships for independently
+authored attachments is unsupported by this bridge until its role is explicitly
+established; do not claim complete attachment fidelity for that shape or infer
+roles from first-page content. Full immutable evidence lineage is retained even
+when a rendition is excluded from capture pages.
+
+The bridge rejects an entire receipt containing an unsupported independent
+original, including a mixed PDF/TIFF bundle, before family retention. Generic
+source originals remain available for recovery; no partial family receipt or
+adoption is created. Hosts must acknowledge successful family import only after
+family retention succeeds and surface failed source imports. Known JSON
+metadata wrappers and media descendants under the supported rendition convention
+are not independent originals.

package/dist/catalog.d.ts

@@ -1,4 +1,4 @@
-import { SmrtObject } from '@happyvertical/smrt-core';
+import { SmrtObject, type SmrtSaveOptions } from '@happyvertical/smrt-core';
 export type CourseLicenseKind = 'own-work' | 'open-license' | 'personal-use-copy' | 'licensed-for-sharing';
 export type CourseModality = 'online' | 'printable' | 'kit' | 'video' | 'game' | 'mixed';
 export type CourseStatus = 'draft' | 'published' | 'archived';
@@ -25,7 +25,7 @@ export declare class Course extends SmrtObject {
     status: CourseStatus;
     constructor(options?: Record<string, unknown>);
     /** A personal copy remains pinned to its original family and license. */
-    save(): Promise<this>;
+    save(options?: SmrtSaveOptions): Promise<this>;
 }
 export declare class ExternalCourse extends Course {
 }
@@ -37,7 +37,7 @@ export declare class CourseSection extends SmrtObject {
     title: string;
     sortOrder: number;
     constructor(options?: Record<string, unknown>);
-    save(): Promise<this>;
+    save(options?: SmrtSaveOptions): Promise<this>;
 }
 export declare class Lesson extends SmrtObject {
     tenantId: string | null;
@@ -52,7 +52,7 @@ export declare class Lesson extends SmrtObject {
     externalRef: string;
     externalUrl: string;
     constructor(options?: Record<string, unknown>);
-    save(): Promise<this>;
+    save(options?: SmrtSaveOptions): Promise<this>;
 }
 export declare class Reading extends Lesson {
 }

package/dist/catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,UAAU,EAEX,MAAM,0BAA0B,CAAC;AAGlC,MAAM,MAAM,iBAAiB,GACzB,UAAU,GACV,cAAc,GACd,mBAAmB,GACnB,sBAAsB,CAAC;AAC3B,MAAM,MAAM,cAAc,GACtB,QAAQ,GACR,WAAW,GACX,KAAK,GACL,OAAO,GACP,MAAM,GACN,OAAO,CAAC;AACZ,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,WAAW,GAAG,UAAU,CAAC;AAC9D,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,UAAU,CAAC;AAwB9E,qBAEa,MAAO,SAAQ,UAAU;IACN,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAClC,KAAK,SAAM;IACtC,OAAO,SAAM;IACb,WAAW,SAAM;IACjB,SAAS,SAAY;IACrB,SAAS,SAAM;IACf,SAAS,SAAM;IACf,OAAO,SAAM;IACb,WAAW,EAAE,iBAAiB,CAAc;IAC5C,WAAW,SAAM;IACjB,UAAU,SAAM;IAChB,OAAO,SAAM;IACb,IAAI,SAAM;IACV,QAAQ,SAAK;IACb,QAAQ,SAAK;IACb,UAAU,SAAO;IACjB,gBAAgB,SAAK;IACrB,QAAQ,EAAE,cAAc,CAAY;IACpC,MAAM,EAAE,YAAY,CAAW;gBACnB,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;IAKjD,yEAAyE;IAC1D,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAyCrC;AAED,qBACa,cAAe,SAAQ,MAAM;CAAG;AAE7C,qBACa,cAAe,SAAQ,MAAM;CAAG;AAE7C,qBAEa,aAAc,SAAQ,UAAU;IACb,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IACnB,QAAQ,SAAM;IAC7B,KAAK,SAAM;IACtC,SAAS,SAAK;gBACF,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;IAIlC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAmBrC;AAED,qBAEa,MAAO,SAAQ,UAAU;IACN,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IACZ,SAAS,SAAM;IACrC,KAAK,SAAM;IACtC,IAAI,SAAM;IACV,SAAS,SAAK;IACd,gBAAgB,SAAK;IACrB,UAAU,SAAO;IACjB,QAAQ,EAAE,cAAc,CAAY;IACpC,cAAc,EAAE,oBAAoB,CAAY;IAChD,WAAW,SAAM;IACjB,WAAW,SAAM;gBACL,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;IAIlC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAmBrC;AAED,qBACa,OAAQ,SAAQ,MAAM;CAAG;AACtC,qBACa,KAAM,SAAQ,MAAM;IAC/B,QAAQ,SAAM;gBACF,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAIlD;AACD,qBACa,SAAU,SAAQ,MAAM;IACnC,YAAY,SAAM;IAClB,SAAS,SAAM;IACf,KAAK,SAAK;IACD,cAAc,EAAE,oBAAoB,CAAY;gBAC7C,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAIlD;AACD,qBACa,QAAS,SAAQ,MAAM;CAAG"}
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,UAAU,EACV,KAAK,eAAe,EAErB,MAAM,0BAA0B,CAAC;AAGlC,MAAM,MAAM,iBAAiB,GACzB,UAAU,GACV,cAAc,GACd,mBAAmB,GACnB,sBAAsB,CAAC;AAC3B,MAAM,MAAM,cAAc,GACtB,QAAQ,GACR,WAAW,GACX,KAAK,GACL,OAAO,GACP,MAAM,GACN,OAAO,CAAC;AACZ,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,WAAW,GAAG,UAAU,CAAC;AAC9D,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,UAAU,CAAC;AAwB9E,qBAEa,MAAO,SAAQ,UAAU;IACN,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAClC,KAAK,SAAM;IACtC,OAAO,SAAM;IACb,WAAW,SAAM;IACjB,SAAS,SAAY;IACrB,SAAS,SAAM;IACf,SAAS,SAAM;IACf,OAAO,SAAM;IACb,WAAW,EAAE,iBAAiB,CAAc;IAC5C,WAAW,SAAM;IACjB,UAAU,SAAM;IAChB,OAAO,SAAM;IACb,IAAI,SAAM;IACV,QAAQ,SAAK;IACb,QAAQ,SAAK;IACb,UAAU,SAAO;IACjB,gBAAgB,SAAK;IACrB,QAAQ,EAAE,cAAc,CAAY;IACpC,MAAM,EAAE,YAAY,CAAW;gBACnB,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;IAKjD,yEAAyE;IAC1D,IAAI,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;CAyC9D;AAED,qBACa,cAAe,SAAQ,MAAM;CAAG;AAE7C,qBACa,cAAe,SAAQ,MAAM;CAAG;AAE7C,qBAEa,aAAc,SAAQ,UAAU;IACb,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IACnB,QAAQ,SAAM;IAC7B,KAAK,SAAM;IACtC,SAAS,SAAK;gBACF,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;IAIlC,IAAI,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;CAmB9D;AAED,qBAEa,MAAO,SAAQ,UAAU;IACN,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IACZ,SAAS,SAAM;IACrC,KAAK,SAAM;IACtC,IAAI,SAAM;IACV,SAAS,SAAK;IACd,gBAAgB,SAAK;IACrB,UAAU,SAAO;IACjB,QAAQ,EAAE,cAAc,CAAY;IACpC,cAAc,EAAE,oBAAoB,CAAY;IAChD,WAAW,SAAM;IACjB,WAAW,SAAM;gBACL,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;IAIlC,IAAI,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;CAmB9D;AAED,qBACa,OAAQ,SAAQ,MAAM;CAAG;AACtC,qBACa,KAAM,SAAQ,MAAM;IAC/B,QAAQ,SAAM;gBACF,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAIlD;AACD,qBACa,SAAU,SAAQ,MAAM;IACnC,YAAY,SAAM;IAClB,SAAS,SAAM;IACf,KAAK,SAAK;IACD,cAAc,EAAE,oBAAoB,CAAY;gBAC7C,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAIlD;AACD,qBACa,QAAS,SAAQ,MAAM;CAAG"}