@happyvertical/smrt-education 0.57.37 → 0.57.38

package/dist/smrt-knowledge.json

@@ -3,18 +3,19 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-education",
-  "packageVersion": "0.57.37",
+  "packageVersion": "0.57.38",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "13a3f757f18cc0cfed8d07ffc42cda60e62cf40766265cc23d08ed0482704806",
-    "packageJson": "8707ae756fce4cae2c1ad80e92b1352ecd85386f1b7f6b58c925cfba44e5d19b",
-    "agents": "bf8b00b31d2dfc9394ab1766421bbeb2dcc5326db3ea60ecc9922b6800f21f48",
+    "manifest": "f63db1cd3e8bf488aa731aed6f5b4cb1ff6791a221b9bac788a2a6ce223abe1c",
+    "packageJson": "5075accbaa27c88f5eff6b23f3462dcb8ddd4c50b862775a1720809f73cfe2c1",
+    "agents": "dd188ff6cfca738bf1dcc08ef4e86c8870c8add515092d971c9a2befd3568942",
     "moduleDoc:agents/learner-service.md": "7da70d214547eb78fbf058e997599cc80ab86f5bb55748bd158a9a4b30070d3b",
     "moduleDoc:agents/submission-service.md": "8e63b83ac84628d5e5ddacbb6a47077c0e65eee3da87518d9bf6e30fb8348336",
     "moduleDoc:agents/workbook-service.md": "3ca3fb60d39daf76b94ec668fc19dc67aa7e090b7f44412bed5c9d92e8efaf5a",
     "moduleDoc:agents/photo-intake.md": "3b7057201ee30b2361aad23ea52e8a55c8ed5354e7a7e4a8193b7de17ca2f0db",
-    "moduleDoc:agents/source-import.md": "30ee823589d655442bcf1abcd86a2132172065b4bc5e3c4d89b1e8b7afcc66bc"
+    "moduleDoc:agents/source-import.md": "30ee823589d655442bcf1abcd86a2132172065b4bc5e3c4d89b1e8b7afcc66bc",
+    "moduleDoc:agents/family-intake.md": "540b6d37f438496acb0208b6ac7258264e2142bce3d2f986967b7741606fe4f7"
   },
   "exports": [
     ".",
@@ -59,7 +60,7 @@
     "smrt"
   ],
   "risks": [
-    "cross-package-refs:6",
+    "cross-package-refs:8",
     "sensitive-fields-excluded",
     "sti-inheritance"
   ],
@@ -741,6 +742,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -923,6 +927,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -1094,6 +1101,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -1166,6 +1176,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -1306,6 +1319,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -1448,6 +1464,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -1585,6 +1604,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -1735,6 +1757,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -1866,6 +1891,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -2501,6 +2529,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         },
         {
@@ -2568,6 +2599,401 @@
       "tags": [],
       "risks": []
     },
+    {
+      "name": "FamilyIntake",
+      "qualifiedName": "@happyvertical/smrt-education:FamilyIntake",
+      "collection": "familyintakes",
+      "description": "Family-owned receipt, independent of learner attribution and ingestion expiry.",
+      "tableName": "family_intakes",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "itemId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "actorUserId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "ownerProfileId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-profiles:Profile",
+          "columnType": "UUID"
+        },
+        {
+          "name": "contentDigest",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "sourceJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "ownerProfileId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-profiles:Profile",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "delete",
+        "save"
+      ],
+      "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "save",
+          "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
+          "returns": "Promise<this>"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "item_id"
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "delete",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:FamilyIntake"
+        },
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:FamilyIntake"
+        }
+      ],
+      "relationshipFeatures": [
+        "crossPackageRef",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "FamilyIntakeCollection",
+      "qualifiedName": "@happyvertical/smrt-education:FamilyIntakeCollection",
+      "collection": "familyintakes",
+      "tableName": "family_intakes",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "FamilyIntakeAsset",
+      "qualifiedName": "@happyvertical/smrt-education:FamilyIntakeAsset",
+      "displayLabelField": "name",
+      "collection": "familyintakeassets",
+      "description": "Sole family owner join; adoption borrows this exact immutable original.",
+      "tableName": "family_intake_assets",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "intakeId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "FamilyIntake",
+          "columnType": "UUID"
+        },
+        {
+          "name": "assetId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-assets:Asset",
+          "columnType": "UUID"
+        },
+        {
+          "name": "name",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "mimeType",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "sha256",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "position",
+          "type": "integer",
+          "required": true,
+          "columnType": "INTEGER",
+          "default": 0
+        }
+      ],
+      "relationships": [
+        {
+          "name": "intakeId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "FamilyIntake",
+          "columnType": "UUID"
+        },
+        {
+          "name": "assetId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-assets:Asset",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "delete",
+        "save"
+      ],
+      "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "save",
+          "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
+          "returns": "Promise<this>"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "intake_id",
+        "asset_id"
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "delete",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:FamilyIntakeAsset"
+        },
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:FamilyIntakeAsset"
+        }
+      ],
+      "relationshipFeatures": [
+        "crossPackageRef",
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "FamilyIntakeAssetCollection",
+      "qualifiedName": "@happyvertical/smrt-education:FamilyIntakeAssetCollection",
+      "collection": "familyintakeassets",
+      "tableName": "family_intake_assets",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "FamilyIntakeDecision",
+      "qualifiedName": "@happyvertical/smrt-education:FamilyIntakeDecision",
+      "collection": "familyintakedecisions",
+      "description": "Append-only attribution/adoption audit; no marks or learning outcomes.",
+      "tableName": "family_intake_decisions",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "intakeId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "FamilyIntake",
+          "columnType": "UUID"
+        },
+        {
+          "name": "requestKey",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "sequence",
+          "type": "integer",
+          "required": true,
+          "columnType": "INTEGER",
+          "default": 0
+        },
+        {
+          "name": "actorUserId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "bodyJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "intakeId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "FamilyIntake",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "delete",
+        "save"
+      ],
+      "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "save",
+          "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
+          "returns": "Promise<this>"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "intake_id",
+        "request_key"
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "delete",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:FamilyIntakeDecision"
+        },
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:FamilyIntakeDecision"
+        }
+      ],
+      "relationshipFeatures": [
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "FamilyIntakeDecisionCollection",
+      "qualifiedName": "@happyvertical/smrt-education:FamilyIntakeDecisionCollection",
+      "collection": "familyintakedecisions",
+      "tableName": "family_intake_decisions",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "Learner",
       "qualifiedName": "@happyvertical/smrt-education:Learner",
@@ -2652,6 +3078,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         },
         {
@@ -2768,6 +3197,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -2898,6 +3330,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -3034,6 +3469,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -3130,6 +3568,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -3299,6 +3740,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -3376,6 +3820,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -3567,6 +4014,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         },
         {
@@ -3765,6 +4215,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -3923,6 +4376,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -4011,6 +4467,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -4145,6 +4604,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         },
         {
@@ -4269,6 +4731,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -4436,6 +4901,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -4615,6 +5083,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -4800,6 +5271,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -4982,6 +5456,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -5141,6 +5618,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -5286,6 +5766,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -5363,6 +5846,13 @@
           "related": "Learner",
           "columnType": "UUID"
         },
+        {
+          "name": "familyIntakeId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "FamilyIntake",
+          "columnType": "UUID"
+        },
         {
           "name": "itemId",
           "type": "text",
@@ -5389,6 +5879,13 @@
           "required": true,
           "related": "Learner",
           "columnType": "UUID"
+        },
+        {
+          "name": "familyIntakeId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "FamilyIntake",
+          "columnType": "UUID"
         }
       ],
       "methods": [
@@ -5404,6 +5901,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -5556,6 +6056,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -5695,6 +6198,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -5828,6 +6334,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -5885,14 +6394,14 @@
   "surfaces": [],
   "prompts": [],
   "relationshipsV2": {
-    "foreignKeyFields": 70,
-    "crossPackageRefFields": 6,
+    "foreignKeyFields": 73,
+    "crossPackageRefFields": 8,
     "junctionCollections": 2,
     "hierarchicalObjects": 0,
     "polymorphicAssociations": 0,
-    "uuidColumns": 298
+    "uuidColumns": 320
   },
-  "agentDoc": "# smrt-education\n\nCatalog objects are optional-tenant scoped and have no generated REST, CLI, MCP,\nor AI surface. Applications use `CatalogService`, supplying their actor-bound\nauthorization decision and the trusted `TenantCollection.withTenantCatalogReadScope`\nadapter from smrt-users. Catalog authorization receives the exact shared collection\nexecutor; live session/permission checks must use that executor. That read scope may widen only an allowlisted catalog\ncollection's `list` to self, ancestors, and globals; it never authorizes a get,\nwrite, raw query, sibling, or descendant read.\n\n`personal-use-copy` courses and all `answer-key` lesson assets are private\nfamily material. Do not publish them, promote them, or expose them through a\nlearner-facing result. `LessonAsset` is the sole owner join for lesson files;\ndo not add asset-id fields to lesson subclasses.\n\nLearner objects require exact tenant ownership and close generated surfaces.\n`LearnerService` owns actor/resource authorization and transactional planning and\nstart-progress; see [learner contract](agents/learner-service.md). Guardian\nrelationships require a host decision about their type and effective terms.\nNever expose direct collection writes as learner handlers, reset progress on a\nretry, or treat an unscored nullable decimal as zero.\n\nSubmission capture, guardian grading and private PDF packet splitting use\n`SubmissionService`; see [submission contract](agents/submission-service.md).\nKeep asset metadata on the same transaction and compensate only newly planned\nfiles after rollback; never expose source URIs or accept learner grade patches.\n\nValidation: `pnpm --filter @happyvertical/smrt-education test`,\n`test:postgres`, `typecheck`, and `build`.\n\nPhysical workbook capture, immutable assessment/feedback history and descriptive\nevidence use [WorkbookService](agents/workbook-service.md). Keep provisional\nsharing separate from guardian Grade authority. Photo-first receipt/context\ncapture uses [WorkbookPhotoService](agents/photo-intake.md); covers/references\nnever create learning evidence, and blank exercises need explicit work intent.\n\nSource import: [host boundary and transaction contract](agents/source-import.md).\n`SourceImportService` requires host opt-in, matching active actor/tenant and\nexplicit licensing authorization; never add a system/global write bypass.\n",
+  "agentDoc": "# smrt-education\n\nCatalog objects are optional-tenant scoped and have no generated REST, CLI, MCP,\nor AI surface. Applications use `CatalogService`, supplying their actor-bound\nauthorization decision and the trusted `TenantCollection.withTenantCatalogReadScope`\nadapter from smrt-users. Catalog authorization receives the exact shared collection\nexecutor; live session/permission checks must use that executor. That read scope may widen only an allowlisted catalog\ncollection's `list` to self, ancestors, and globals; it never authorizes a get,\nwrite, raw query, sibling, or descendant read.\n\n`personal-use-copy` courses and all `answer-key` lesson assets are private\nfamily material. Do not publish them, promote them, or expose them through a\nlearner-facing result. `LessonAsset` is the sole owner join for lesson files;\ndo not add asset-id fields to lesson subclasses.\n\nLearner objects require exact tenant ownership and close generated surfaces.\n`LearnerService` owns actor/resource authorization and transactional planning and\nstart-progress; see [learner contract](agents/learner-service.md). Guardian\nrelationships require a host decision about their type and effective terms.\nNever expose direct collection writes as learner handlers, reset progress on a\nretry, or treat an unscored nullable decimal as zero.\n\nSubmission capture, guardian grading and private PDF packet splitting use\n`SubmissionService`; see [submission contract](agents/submission-service.md).\nKeep asset metadata on the same transaction and compensate only newly planned\nfiles after rollback; never expose source URIs or accept learner grade patches.\n\nValidation: `pnpm --filter @happyvertical/smrt-education test`,\n`test:postgres`, `typecheck`, and `build`.\n\nPhysical workbook capture, immutable assessment/feedback history and descriptive\nevidence use [WorkbookService](agents/workbook-service.md). Keep provisional\nsharing separate from guardian Grade authority. Photo-first receipt/context\ncapture uses [WorkbookPhotoService](agents/photo-intake.md); covers/references\nnever create learning evidence, and blank exercises need explicit work intent.\n\nSource import: [host boundary and transaction contract](agents/source-import.md).\n`SourceImportService` requires host opt-in, matching active actor/tenant and\nexplicit licensing authorization; never add a system/global write bypass.\n\nFamily-owned unassigned originals and audited learner adoption use\n[FamilyIntakeService](agents/family-intake.md). Keep family source scope immutable;\nassignment alone never creates learning history or grants learner inbox access.\n",
   "moduleDocs": [
     {
       "path": "agents/learner-service.md",
@@ -5918,6 +6427,11 @@
       "path": "agents/source-import.md",
       "module": "source-import",
       "content": "# Source import integration\n\n`SourceImportService` is a server-side host boundary, with no generated REST,\nCLI, MCP or AI operation. Recipes remain metadata only. Provision a closed\n`CourseSource` in the owning tenant, then construct the service with the root\nSQL database and an actor-bound `SourceImportAuthorizer`. Enable tenancy and\ncall within `withTenant({ tenantId, userId })`; the request must match both.\nMissing context, a different actor/tenant and super-admin bypass fail closed.\n\nRegister Easy Peasy only after the host operator accepts its terms, using\n`registerEasyPeasy({ termsAccepted: true, fetchPage })`. Do not derive that\nboolean from an HTTP request. `fetchPage(url, { redirect: 'error' })` must reject\nredirects, bound time/size and return `{ html, url }`. It fetches the page only,\nnever a PDF. The service checks the approved HTTPS URL before fetching, checks\nthe response URL, limits HTML to 2 million characters, then parses the complete\npage before any write. There is no automatic registration or network access. Structural h1–h6 headings delimit day content, including trailing Resources\nsections; ordinary non-lesson bold instructions do not. Supported\nheading blocks are h1–h6 or a lesson marker as the first bold run in a\nparagraph/list item.\nRecognizable markers outside that layout, including multiple markers in one\nparagraph, fail closed rather than silently assigning a PDF to the wrong day.\n\nThe authorizer must verify the authenticated actor's management grant and the\nprovisioned tenant's family/group classification. Tenant has no built-in kind;\nneither hierarchy position nor client input establishes a family. Authorization\nis required before fetch and again inside the transaction; callbacks must be\nread-only decisions, since a rolled-back contention retry can call them again.\n\n`sharing` is a ceiling: private permits private-family import only; group and\nglobal permit private-family or group import. Group imports additionally require\nnonblank host-recorded `config.licenseEvidence` and an explicit host grant that\nvalidates that permission. Global/null destinations are unsupported and rejected;\nthere is no global/system bypass. Widening a source never promotes existing\nimports. Private imports are draft `personal-use-copy` courses and retain the\ncatalog's immutable owner/license and no-publication protection. A host may\ncreate a new licensed group source and import there after receiving permission.\n\nUse a stable `courseRef` independent of source URLs. Identities derive from the\nowning tenant, source row ID, course reference and lesson day; retain the source\nrow when updating policy. Changes to titles/page/PDF URLs update in place.\nMissing days are retained, not deleted, so enrollment, progress, submission and\nasset foreign keys remain valid. A changed lesson kind fails the whole import\nrather than replacing a row. Only title and pointer fields are refreshed; body,\nanswer keys, learner state and manually authored settings are never replaced.\nThe packet URL is returned as a source link and is not downloaded or mirrored.\n\nAll source policy rechecks and catalog mutations use collections bound to the\nsame SQL transaction. Embedded writes use the public write queue; PostgreSQL\nserializes an import identity with a transaction-scoped advisory lock. Only\nrolled-back busy/serialization/deadlock errors retry (at most three retries),\nwithout repeating fetch. Connection-invalidated and other failures propagate.\nDo not wrap the service in a caller transaction if the caller expects a durable\ncommit before returning; any outer transaction remains the caller's boundary.\n\nSQLite and PostgreSQL integration tests exercise real transactions and rollback.\nFull catalog children remain unavailable on DuckDB due to core's existing\nON UPDATE CASCADE/self-referential schema limitations documented in\n[catalog-service.md](catalog-service.md); no alternate schema is substituted.\nTests use synthetic local HTML and an injected fetch callback, never the network.\n\nGoogle Drive discovery defaults every record to `teacher`. A trusted host may\nmake only an exact reviewed file ID visible by passing `studentSafeFileIds`;\nfolder IDs and descendant membership never grant visibility. A teacher-marked\nfolder or name still wins over that allowlist. File shortcuts are excluded: a\nshortcut does not prove the target remains under a reviewed root or retains the\ntarget's teacher-path classification. Resync after changing the allowlist: the\ndurable sync upsert rewrites existing visibility rather than retaining a\nprevious learner classification.\n\nGeneric “Printable” and “Printables” labels identify lesson PDFs; course packets\nrequire explicit packet/whole-course/complete-course wording. Only actual href\nattributes supply pointers; data-href metadata does not.\n"
+    },
+    {
+      "path": "agents/family-intake.md",
+      "module": "family-intake",
+      "content": "# Family intake\n\n`FamilyIntakeService` retains guardian-only originals before a learner is known.\nThe host supplies a trusted actor/tenant and a current family authorizer; each\nread, original download, assignment and adoption revalidates this authority on\nthe service's exact executor. Learners cannot browse the family inbox. Generated\nCRUD, CLI, MCP and AI surfaces remain closed.\n\nRetain the whole document with its source identity, delivery key, immutable hash\nand original private assets. Source delivery retries must preserve identical\ncontent and provenance. Email and scanner adapters are separate host configuration;\nthis service does not configure or select them. Trusted candidate DTOs and their\nquoted evidence are advisory. A guardian's active learner preference, visible\nmarks, uncertain names or a first-page guess never establish ownership. Mixed\nlearner PDFs stay unresolved until an explicit whole-document assignment is safe.\n\nAssignment records an immutable guardian decision with a revision and request\nkey. It does not create learner work. Adoption freezes that assignment and borrows\nthe exact original assets through learner photo ownership joins; it never rewrites\nsource confidentiality or creates grades. The existing photo resolution and\ncompleted-work capture preconditions still apply. Existing derived capture copies\nare permitted. Once adopted, a receipt cannot silently change learners; recovery\nrequires a separate explicit policy. An unadopted attribution can be corrected by\nanother audited decision with the current revision.\n\nFamily ownership retains originals beyond generic receipt expiry. Adoption does\nnot transfer or delete that ownership. Cleanup and rollback must preserve shared\nretained bytes and compensate only newly created files. Every access checks the\noriginal hash before adoption or download.\n\nValidation uses shared family workflows on real SQLite and isolated PostgreSQL;\nno AI providers, scanner/email services or containers are required.\n\nImport `FamilyIntakeService`, `receiveFamilyIntake` and\n`retainFamilyIntakeReceipt` from `@happyvertical/smrt-education/ingestion`.\nThe bridge uses the fixed `familyIntakeScopeId(tenantId)` namespace and public\n`getReceiptSource` to retain authoritative delivery identity. This namespace is\nnever an authorization grant. The host's `IngestionService.authorize` callback\nmust call the same current family authorizer on every operation, including direct\n`getEvidence`, `readEvidence` and `getReceiptSource` calls. For example, await\n`family.authorizeFamilyIntake({ tenantId: scope.tenantId, actorUserId: scope.actorId })`\nthen return true; propagate denial. Actor equality or tenant membership alone is\ninsufficient. This protects raw envelopes and rejected/unretained originals as\nwell as adopted receipts. Adoption permits only normal authorized learner work\nreads; it never grants the learner generic family ingestion access. A receive that\nsucceeds before education retention fails is repaired by retrying the same\nreceipt, never by inventing another delivery identity.\n\nDeploy manifest migrations for all three FamilyIntake models and the nullable\n`WorkbookPhotoIntake.familyIntakeId` FK before use. There is no runtime DDL.\nAdoption commits its immutable audit and exact photo/original joins atomically;\nthe family asset remains the sole original owner. Existing derived submission\ncopies use normal capture compensation. The exact adoption audit is required\nwhen validating borrowing joins, reads and immutable family-scope analysis.\n`countFamilyIntakes` counts unadopted receipts across the full inbox, while\n`listFamilyIntakes` pages the complete receipt history.\n\nAfter adoption, use the returned `photoIntakeId` with ordinary photo\nresolution/capture methods. Family-scope photo analysis checks the exact adopted\nitem/learner binding; learner-scoped uploads retain their existing strict scope.\nThe existing submission/assessment ingestion handlers still revalidate the\ncaptured learner/attempt. Temporary ingestion expiry does not prevent manual\nresolution/capture from retained education originals; re-analysis of an expired\nreceipt needs a separately authorized retained-input orchestration.\n\nThis initial contract assigns a whole receipt/document. It does not split a\nmixed-child PDF, automatically infer a child or configure a source adapter.\nFuture range adoption must preserve original hashes and page provenance; the\nretained immutable originals remain available for such an explicit workflow.\n\nSource-tree retention includes image/PDF attachments beneath metadata envelopes.\nA supported-media descendant of another supported original (for example a PDF's\npage thumbnail) stays in the evidence graph but is not duplicated as learner\nwork. Photo identification and captured-work analysis preservation use this same\noriginal-selection convention, so retained attachment hashes remain authoritative\nafter adoption and retries. The immutable graph retains only IDs, parent IDs, media types and hashes;\nit does not copy email bodies, arbitrary headers or credentials into public\nsource metadata. A source image such as an email logo is not automatically\nclassified as completed work. Whole-document attribution/classification remains\nan explicit guardian decision; ambiguous mixed contents need resolution.\n\nCustom source adapters must follow this supported convention: metadata parents\ncontain independent original attachments; descendants of supported media are\nrenditions of that media. Extraction outputs already live separately from source\nevidence. An adapter that uses media-child relationships for independently\nauthored attachments is unsupported by this bridge until its role is explicitly\nestablished; do not claim complete attachment fidelity for that shape or infer\nroles from first-page content. Full immutable evidence lineage is retained even\nwhen a rendition is excluded from capture pages.\n\nThe bridge rejects an entire receipt containing an unsupported independent\noriginal, including a mixed PDF/TIFF bundle, before family retention. Generic\nsource originals remain available for recovery; no partial family receipt or\nadoption is created. Hosts must acknowledge successful family import only after\nfamily retention succeeds and surface failed source imports. Known JSON\nmetadata wrappers and media descendants under the supported rendition convention\nare not independent originals.\n"
     }
   ],
   "recipes": [