@choiceapps/communityservices-sdk 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.7.0 - 2026-11-10
+
+- Add `createReadBackWriteLabelResolver` for exact observed lookup labels, including HUD suffixes. Unobserved options remain unresolved; no suffix is inferred from metadata.
+- Expose `groupId` and `grouped` on GWT enrollment catalog rows and details without per-row reads.
+- Add `discoverHouseholdEnrollment` and adoption from a head's client/enrollment IDs, requiring a unique verified household membership match.
+- Add `registerEntryRows` to bind existing recordsets to adopted entry keys for in-place corrections.
+- Add stable workflow error codes and per-operation `committed` markers, preserving uncertain prior writes and original causes.
+- Add `writeMobileAnswersChecked` and enrollment-workflow scalar collision preflight for questions shared across instruments.
+- Document missing diagnostics in 0.5.0 journals, the unsupported yes/no clear route, and integrator-reported 0.6.0 acceptance separately from local tests.
+
 ## 0.6.0 - 2026-11-10
 
 - Reject yes/no fields in `correctEntry.clear` before any correction write or new journal entry. Correct synthetic fixtures that incorrectly accepted blank yes/no values. Setting `No` remains supported.

package/browser/enrollment-workflow.d.mts

@@ -107,6 +107,19 @@ export interface AdoptHouseholdEnrollmentInput {
  /** Complete linked cohort, including already exited participants. IDs are explicit, not inferred. */
  members:Array<{clientId:number;enrollmentId:number}>;
 }
+export interface HouseholdEnrollmentDiscoveryInput {headClientId:number;headEnrollmentId:number;}
+export interface HouseholdEnrollmentDiscoveryResult extends HouseholdEnrollmentDiscoveryInput {
+ householdId:number;householdSource:'verified-membership';providerId:number;type:string;
+ members:Array<{clientId:number;enrollmentId:number}>;
+}
+export interface AdoptHouseholdEnrollmentFromHeadInput extends HouseholdEnrollmentDiscoveryInput {key:string;}
+export interface RegisterEntryRowsInput {
+ key:string;enrollmentKey:string;clientId:number;
+ rows:Array<{key:string;parentField:string;recordsetId:number}>;
+}
+export interface RegisterEntryRowsResult {
+ key:string;enrollmentKey:string;clientId:number;enrollmentId:number;outcome:'verified'|'already-present';recordsetIds:Record<string,number>;
+}
 export interface EnrollmentWorkflowResult {
   key:string;
   outcome:'verified'|'already-present';
@@ -146,12 +159,16 @@ export interface EnrollmentWorkflow {
   exitEnrollment(input:ExitEnrollmentInput):Promise<ExitEnrollmentResult>;
   /** Patch an open entry at its original timestamp, before any review or exit. */
   correctEntry(input:EntryCorrectionInput):Promise<EntryCorrectionResult>;
+  /** Bind explicit existing row IDs to stable keys without writing HMIS records. */
+  registerEntryRows(input:RegisterEntryRowsInput):Promise<RegisterEntryRowsResult>;
+  /** Resolve a unique current household satisfying full-cohort membership/head/date checks. */
+  discoverHouseholdEnrollment(input:HouseholdEnrollmentDiscoveryInput):Promise<HouseholdEnrollmentDiscoveryResult>;
   /** Verify unchanged state and independently confirmed rejection; keeps the attempt history. */
   resolveEntryCorrection(input:ResolveEntryCorrectionInput):Promise<ResolveEntryCorrectionResult>;
   /** Verify an existing standalone entry and journal it without an HMIS write. */
   adoptEnrollment(input:AdoptEnrollmentInput):Promise<EnrollmentWorkflowResult>;
   /** Verify all existing linked entries, original head and dates; no HMIS writes. */
-  adoptHouseholdEnrollment(input:AdoptHouseholdEnrollmentInput):Promise<HouseholdEnrollmentResult>;
+  adoptHouseholdEnrollment(input:AdoptHouseholdEnrollmentInput|AdoptHouseholdEnrollmentFromHeadInput):Promise<HouseholdEnrollmentResult>;
   /** Reads the local journal only. A verified journal is not fresh server verification. */
   getStatus(input:{clientId:number;key:string}):Promise<EnrollmentWorkflowStatus|null>;
   createHouseholdEnrollment(input:HouseholdEnrollmentInput):Promise<HouseholdEnrollmentResult>;
@@ -242,12 +259,17 @@ export interface EnrollmentWorkflowOptions {
 }
 export class EnrollmentWorkflowError extends Error {
   readonly reason:string;
-  readonly code?:string;
+  readonly code:string;
+  readonly committed:false|'unknown';
+  readonly operation?:string;
+  /** Resolution-call failure does not establish the original correction's outcome. */
+  readonly originalCommitted?:'unknown';
+  readonly reauthenticated?:boolean;
   readonly fields?:string[];
   readonly status?:number;
   /** Failed durable stage, when known. The original write error is available as cause in memory. */
   readonly step?:string;
-  constructor(reason:string,options?:ErrorOptions&{step?:string;code?:string;fields?:string[];status?:number});
+  constructor(reason:string,options?:ErrorOptions&{step?:string;code?:string;fields?:string[];status?:number;committed?:false|'unknown'});
 }
 /** An unavailable list is never evidence that no enrollment exists. */
 export class EnrollmentReadError extends EnrollmentWorkflowError {

package/browser/enrollment-workflow.mjs

@@ -2,6 +2,9 @@ import {apiScope} from './connection.mjs';
 import {validateBirthDate} from './date-of-birth.mjs';
 import {expectedExitDetails} from './exit-details.mjs';
 import {createEntryCorrector,correctionFailureDetails} from './entry-correction.mjs';
+import {createEntryRowRegistrar} from './entry-row-registration.mjs';
+import {createHouseholdEnrollmentDiscovery} from './household-enrollment-discovery.mjs';
+import {workflowErrorCode} from './workflow-error-codes.mjs';
 import {createHash} from 'node:crypto';
 import {readProgramCatalog,encodeAnswers,encodeNewSubassessmentRow,toItems,parseRestInstant} from '../dist/esm/index.js';
 
@@ -10,12 +13,13 @@ const positive=v=>Number.isSafeInteger(v)&&v>0;
 const entryExitTypes=['HUD','Basic','Standard','RHY','VA','Basic Center Program Entry/Exit','PATH','Quick Call','Transitional Living Program Entry/Exit'];
 const canonical=v=>JSON.stringify(v,(_,x)=>object(x)?Object.fromEntries(Object.keys(x).sort().map(k=>[k,x[k]])):x);
 const hash=v=>createHash('sha256').update(canonical(v)).digest('hex');
-const fail=message=>{throw new EnrollmentWorkflowError(message);};
+const fail=(message,options)=>{throw new EnrollmentWorkflowError(message,{committed:false,...options});};
 export class EnrollmentWorkflowError extends Error {
  constructor(reason,options){
   super(`Enrollment workflow: ${reason}`,options);this.name='EnrollmentWorkflowError';this.reason=reason;
   if(options?.step!==undefined)this.step=options.step;
-  if(options?.code!==undefined)this.code=options.code;
+  this.code=options?.code??workflowErrorCode(reason);
+  this.committed=options?.committed??'unknown';
   if(options?.fields!==undefined)this.fields=[...options.fields];
   const status=options?.status??options?.cause?.status;
   if(Number.isInteger(status)&&status>=100&&status<=599)this.status=status;
@@ -68,7 +72,7 @@ function compile(definition,input,{yesNoWrites,writeLabel}={}){
  const covered=new Set([...Object.keys(answers),...Object.keys(excluded),...carry,...compiledRows.map(r=>r.parentField),...compiledEnds.map(r=>r.parentField)]);
  for(const q of definition.questions){
   if(['blank','label'].includes(q.questionType))continue;
-  if(!covered.has(q.fieldName))fail(`uncovered assessment field ${q.fieldName}`);
+  if(!covered.has(q.fieldName))fail(`uncovered assessment field ${q.fieldName}`,{code:'ASSESSMENT_FIELD_UNCOVERED',fields:[q.fieldName??String(q.questionId)]});
   if((q.fieldName in excluded||carry.includes(q.fieldName))&&(q.fieldName in answers||compiledRows.some(r=>r.parentField===q.fieldName)||compiledEnds.some(r=>r.parentField===q.fieldName)))fail('conflicting field coverage');
   if(q.fieldName in excluded&&carry.includes(q.fieldName))fail('conflicting field coverage');
  }
@@ -81,12 +85,12 @@ function compile(definition,input,{yesNoWrites,writeLabel}={}){
  if(yesNo.length)for(const q of definition.questions){
   if(!q.mandatory||['blank','label','sub_assessment'].includes(q.questionType)||yesNo.some(y=>y.virt_field_name===q.fieldName))continue;
   // Only mandatory lookups were verified live; this also keeps DOB inside its own helper.
-  if(q.questionType!=='lookup')fail(`standard yes/no writes support mandatory lookups only; ${q.fieldName} is ${q.questionType}`);
+  if(q.questionType!=='lookup')fail(`standard yes/no writes support mandatory lookups only; ${q.fieldName} is ${q.questionType}`,{code:'UNSUPPORTED_MANDATORY_FIELD_TYPE',fields:[q.fieldName??String(q.questionId)]});
   const base={question_id:q.questionId,question_type:q.questionType,virt_field_name:q.fieldName};
   if(q.fieldName in answers){
    const [label]=encodeAnswers(definition.questions,{[q.fieldName]:answers[q.fieldName]},{endpoint:'standalone',writeLabel});
    const [stored]=encodeAnswers(definition.questions,{[q.fieldName]:answers[q.fieldName]},{endpoint:'mobile'});
-   if(!label||!stored)fail(`mandatory answer ${q.fieldName} has no standard encoding`);
+   if(!label||!stored)fail(`mandatory answer ${q.fieldName} has no standard encoding`,{code:'ANSWER_ENCODING_UNAVAILABLE',fields:[q.fieldName??String(q.questionId)]});
    mandatory.push({...base,answer_value:label.answer_value,expected:stored.answer_value});
   }else if(q.fieldName in excluded)mandatory.push({...base,answer_value:'',expected:''});
   else if(carry.includes(q.fieldName))mandatory.push({...base,carry:true});
@@ -111,7 +115,18 @@ async function enrollments(api,clientId,{enrollmentSession,writeAttempted=false}
 /** Explicit orchestration for an existing client. All writers must share the durable store.
  * No automatic retries of uncertain REST writes. This is not a cross-system transaction. */
 export function createEnrollmentWorkflow({api,discovery,helpers,store,enrollmentSession,exitUi,memberEntryDatePort,birthDates,assessmentLocations={},yesNoWrites='mobile',writeLabel}){
- const tenantScope=apiScope(api, discovery, helpers, enrollmentSession, exitUi);
+ let tenantScope;try{tenantScope=apiScope(api, discovery, helpers, enrollmentSession, exitUi, writeLabel);}catch(cause){throw new EnrollmentWorkflowError(cause instanceof Error?cause.message:'invalid workflow configuration',{code:'WORKFLOW_CONFIGURATION_INVALID',committed:false,cause});}
+ const execute=async(operation,action)=>{
+  const state={attempted:false};
+  try{return await action(state);}catch(cause){
+   const error=cause instanceof EnrollmentWorkflowError?cause:new EnrollmentWorkflowError(cause instanceof Error?cause.message:'upstream workflow operation failed',{code:cause?.code==='SESSION_INTERRUPTED'?'SESSION_INTERRUPTED':cause?.kind==='validation'?'WORKFLOW_VALIDATION_FAILED':'WORKFLOW_UPSTREAM_FAILURE',...(Array.isArray(cause?.fields)&&cause.fields.every(f=>typeof f==='string')?{fields:cause.fields}:{}),cause});
+   if(cause?.code==='SESSION_INTERRUPTED')error.reauthenticated=cause.reauthenticated;
+   error.operation=operation;
+   error.committed=state.attempted||cause instanceof EnrollmentReadError&&cause.committed==='unknown'||cause?.code==='ENTRY_CORRECTION_UNCERTAIN'?'unknown':false;
+   if(operation==='resolveEntryCorrection')error.originalCommitted='unknown';
+   throw error;
+  }
+ };
  if(typeof discovery?.getProviderAssessments!=='function'||typeof helpers?.createInterimUpdate!=='function'||!store)fail('REST API, discovery, enrollment helpers and durable store required');
  if(!['mobile','standard'].includes(yesNoWrites)||yesNoWrites==='standard'&&(typeof writeLabel!=='function'||typeof api.assessments?.create!=='function'))fail('yesNoWrites must be mobile, or standard with writeLabel and assessments.create');
  if(!object(assessmentLocations))fail('assessment locations must be a map by Entry/Exit type');
@@ -123,7 +138,7 @@ export function createEnrollmentWorkflow({api,discovery,helpers,store,enrollment
  const locationsByType={HUD:{entry:'showHudEntry',interim:'showHudInterim',exit:'showHudExit'},VA:{entry:'showVaEntry',interim:'showVaInterim',exit:'showVaExit'},...structuredClone(assessmentLocations)};
  const discover=async(input,includeExit=false)=>{
   fields(input,['clientId','providerId','type','entryDate']);if(!positive(input.clientId)||!positive(input.providerId)||!entryExitTypes.includes(input.type))fail('client, provider and supported Entry/Exit type required');const at=date(input.entryDate);
-  const locations=locationsByType[input.type];if(!locations||includeExit&&!locations.exit)fail(`assessment locations required for ${input.type}${includeExit?' including exit':''}`);
+  const locations=locationsByType[input.type];if(!locations||includeExit&&!locations.exit)fail(`assessment locations required for ${input.type}${includeExit?' including exit':''}`,{code:'ASSESSMENT_LOCATIONS_REQUIRED'});
   const client=toItems(await api.clients.get({path:{clientId:input.clientId}}));if(client.length!==1||client[0].clientId!==input.clientId||client[0].isActive===false)fail('active client required');
   const catalog=await readProgramCatalog(api);const providers=catalog.providers.filter(p=>p.providerId===input.providerId);if(providers.length!==1)fail('active operational program required');
   const configuration=await discovery.getProviderAssessments({providerId:input.providerId});if(configuration.providerId!==input.providerId)fail('provider discovery mismatch');
@@ -139,7 +154,10 @@ export function createEnrollmentWorkflow({api,discovery,helpers,store,enrollment
  const scope=clientId=>JSON.stringify([tenantScope,'enrollment-workflow',clientId]);
  const reservationScope=clientId=>JSON.stringify([tenantScope,'household-workflow-reservation',clientId]);
  const {correctEntry,resolveEntryCorrection}=createEntryCorrector({api,store,enrollmentSession,writeLabel,discover,scope,reservationScope,makeError:(reason,options)=>new EnrollmentWorkflowError(reason,options)});
+ const registerEntryRows=createEntryRowRegistrar({api,store,enrollmentSession,discover,scope,reservationScope,makeError:(reason,options)=>new EnrollmentWorkflowError(reason,options)});
+ const discoverHouseholdEnrollment=createHouseholdEnrollmentDiscovery({api,enrollmentSession,makeError:(reason,options)=>new EnrollmentWorkflowError(reason,options)});
  const run=async(kind,raw,internal={})=>{
+  const operation=internal.operation??{attempted:false};
   const standaloneExit=kind==='exit'&&internal.standaloneExit===true;
   fields(raw,kind==='entry'?['key','clientId','providerId','type','entryDate','assessment']:['key','enrollmentKey','clientId',kind==='exit'?'exitDate':'reviewDate','assessment',...(standaloneExit?['destination','reasonForLeaving','destinationDetails','reasonForLeavingOther']:[])]);
   const input=structuredClone(raw);key(input.key);if(!positive(input.clientId))fail('client ID required');
@@ -153,7 +171,9 @@ export function createEnrollmentWorkflow({api,discovery,helpers,store,enrollment
   return locked(scope(input.clientId),async()=>{
    const reservations=await store.withLock(reservationScope(input.clientId),()=>store.read(reservationScope(input.clientId)));
    if(!Array.isArray(reservations)||reservations.some(r=>r.stage!=='verified'&&r.owner!==internal.owner))fail('unfinished household workflow must be reconciled first');
+   const inheritedAttempt=operation.attempted;operation.attempted=true;
    const records=await store.read(scope(input.clientId));if(!Array.isArray(records)||records.some(r=>!object(r)||r.version!==1||!object(r.steps)))fail('invalid workflow journal');
+   operation.attempted=inheritedAttempt||records.some(r=>r.key===input.key&&Object.keys(r.steps).length>0);
    if(records.some(r=>r.stage!=='verified'&&!(r.kind==='correction'&&r.stage==='rejected')&&r.key!==input.key))fail('another unfinished workflow must be reconciled first');
    const matches=records.filter(r=>r.key===input.key);if(matches.length>1)fail('duplicate journal keys');let record=matches[0];
    const intentHash=hash({kind,input,...(internal.owner?{household:internal.owner}:{})});if(record&&record.intentHash!==intentHash)fail('key conflicts with previous intent');
@@ -226,6 +246,17 @@ export function createEnrollmentWorkflow({api,discovery,helpers,store,enrollment
    // that instant; one second later returns them. Only the yes/no step needs this.
    const readSaved=async()=>questions(await api.assessments.get({path:{clientId:input.clientId,assessmentCode:code},query:{dateEffective:new Date(Date.parse(at)+1000).toISOString()}}));
    const initial=await read();
+   if(!record&&plan.scalar.length){
+    const saved=await readSaved();
+    const existing=plan.scalar.map(q=>({q,row:saved.find(r=>r.virt_field_name===q.virt_field_name)}));
+    const complete=existing.every(({q,row})=>row&&sameAnswer(q,row.answer_value)&&restDate(row.date_effective)===restDate(at));
+    if(!complete){
+     const unavailable=existing.filter(({q,row})=>!row||row.question_type!==q.question_type||row.date_effective!=null&&(!Number.isFinite(restDate(row.date_effective))||restDate(row.date_effective)>restDate(at))||row.date_effective==null&&row.answer_value!=null&&row.answer_value!=='').map(({q})=>q.virt_field_name);
+     if(unavailable.length)fail('mobile scalar preflight unavailable',{code:'MOBILE_PREFLIGHT_UNAVAILABLE',fields:unavailable});
+     const collisions=existing.filter(({row})=>restDate(row.date_effective)===restDate(at)).map(({q})=>q.virt_field_name);
+     if(collisions.length)fail('mobile scalar answer already exists at the effective date',{code:'MOBILE_ANSWER_EXISTS',fields:collisions});
+    }
+   }
    if(expectedHead===input.clientId&&headQuestion)checkHeadAnswer(proposedHead?.answer_value??initial.find(q=>q.virt_field_name==='HUD_RELATIONTOHOH')?.answer_value);
    for(const field of plan.carry.filter(field=>field!=='SVPPROFDOB')){if(kind==='entry'&&record?.correctedScalars?.[field])continue;const q=initial.find(q=>q.virt_field_name===field);if(!q||(q.question_type==='sub_assessment'?!q.sub_assessment_answer_list?.length:!q.answer_value))fail('carry-forward field is empty');}
    // Resend mandatory answers with the standard yes/no write. A blank write must not hide a recorded value.
@@ -236,11 +267,11 @@ export function createEnrollmentWorkflow({api,discovery,helpers,store,enrollment
     if(m.carry){
      const question=definition.questions.find(q=>q.fieldName===m.virt_field_name),options=question.options.filter(o=>String(o.id)===String(recorded));
      const label=options.length===1?writeLabel(question,options[0]):undefined;
-     if(!label)fail(`carried mandatory answer ${m.virt_field_name} has no verified write label`);
+     if(!label)fail(`carried mandatory answer ${m.virt_field_name} has no verified write label`,{code:'LOOKUP_WRITE_LABEL_UNAVAILABLE',fields:[m.virt_field_name]});
      if(m.virt_field_name==='HUD_RELATIONTOHOH')checkHeadAnswer(recorded);
      return {question_id:m.question_id,question_type:m.question_type,virt_field_name:m.virt_field_name,answer_value:label,expected:String(recorded)};
     }
-    if(m.expected===''&&recorded!==null&&recorded!==undefined&&recorded!=='')fail(`not-applicable mandatory field ${m.virt_field_name} has a recorded value; answer it explicitly`);
+    if(m.expected===''&&recorded!==null&&recorded!==undefined&&recorded!=='')fail(`not-applicable mandatory field ${m.virt_field_name} has a recorded value; answer it explicitly`,{code:'MANDATORY_CLEAR_CONFLICT',fields:[m.virt_field_name]});
     return m;
    });
    // Validate closure targets before creating enrollment/review or submitting any answers.
@@ -274,6 +305,7 @@ export function createEnrollmentWorkflow({api,discovery,helpers,store,enrollment
     if(previous)throw new EnrollmentWorkflowError(previous.state==='verified'?'verified step changed':'uncertain write requires reconciliation',{step:name});
     record.steps[name]={state:'attempted'};await persist();
     let writeError;
+    operation.attempted=true;
     try{await submit(result);}catch(error){writeError=error;}
     // A write response alone never establishes success or absence. Preserve its
     // diagnostic cause in memory while reconciliation remains authoritative.
@@ -299,6 +331,7 @@ export function createEnrollmentWorkflow({api,discovery,helpers,store,enrollment
    else {const found=await findEnrollment();if(!found.found)fail('saved enrollment missing');record.enrollmentId=entry.enrollmentId;}
    await persist();
    if(kind==='interim'){
+    if(!internal.readReview)operation.attempted=true;
     // The GWT helper has its own journal and authoritative reads; it owns uncertain-write reconciliation.
     const review=internal.readReview?await internal.readReview({clientId:input.clientId,enrollmentId:record.enrollmentId}):await helpers.createInterimUpdate({clientId:input.clientId,enrollmentId:record.enrollmentId,clientIds:[input.clientId],reviewDate:at});
     const matches=review.snapshot.reviews.filter(r=>r.type==='Update'&&restDate(r.reviewDate)===restDate(at)&&r.clientIds.includes(input.clientId));if(matches.length!==1||record.reviewId&&record.reviewId!==matches[0].reviewId)fail('interim did not verify');record.reviewId=matches[0].reviewId;await persist();
@@ -361,7 +394,7 @@ export function createEnrollmentWorkflow({api,discovery,helpers,store,enrollment
      const known=record.steps.birthDate.value;
      result=await birthDates.verify({...dobContext,dateOfBirth:known.dateOfBirth,effectiveDate:known.effectiveDate,allowLater:true});
     }else if(plan.dateOfBirth!==undefined){
-     result=await birthDates.update({...dobContext,key:'enrollment-dob:'+hash({key:input.key,kind,clientId:input.clientId}),dateOfBirth:plan.dateOfBirth,effectiveDate:at,...(kind==='entry'?{entry:{enrollmentId:record.enrollmentId,assessmentName:discovered.entry.assessment.name}}:{})});
+     operation.attempted=true;result=await birthDates.update({...dobContext,key:'enrollment-dob:'+hash({key:input.key,kind,clientId:input.clientId}),dateOfBirth:plan.dateOfBirth,effectiveDate:at,...(kind==='entry'?{entry:{enrollmentId:record.enrollmentId,assessmentName:discovered.entry.assessment.name}}:{})});
     }else result=await birthDates.verify({...dobContext,dateOfBirth:carriedBirthDate.dateOfBirth,effectiveDate:carriedBirthDate.effectiveDate,allowLater:true});
     record.steps.birthDate={state:'verified',value:{clientId:input.clientId,dateOfBirth:result.dateOfBirth,effectiveDate:result.effectiveDate}};await persist();
    }
@@ -373,6 +406,11 @@ export function createEnrollmentWorkflow({api,discovery,helpers,store,enrollment
  const memberKey=(key,clientId)=>'household:'+hash({key,clientId});
  const withClients=(ids,work,index=0)=>index===ids.length?work():store.withLock(scope(ids[index]),()=>withClients(ids,work,index+1));
  const adopt=async(household,raw)=>{
+  if(household&&raw&&Object.hasOwn(raw,'headEnrollmentId')){
+   fields(raw,['key','headClientId','headEnrollmentId']);key(raw.key);
+   const found=await discoverHouseholdEnrollment({headClientId:raw.headClientId,headEnrollmentId:raw.headEnrollmentId});
+   raw={key:raw.key,headClientId:found.headClientId,householdId:found.householdId,members:found.members};
+  }
   fields(raw,household?['key','householdId','headClientId','members']:['key','clientId','enrollmentId']);
   const input=structuredClone(raw);key(input.key);
   if(typeof enrollmentSession?.readEnrollment!=='function')fail('authoritative enrollment session required for adoption');
@@ -448,7 +486,7 @@ export function createEnrollmentWorkflow({api,discovery,helpers,store,enrollment
    });
   });
  };
- const householdRun=async(kind,raw)=>{
+ const householdRun=async(kind,raw,operation={attempted:false})=>{
   if(typeof enrollmentSession?.readEnrollment!=='function'||typeof helpers.addHouseholdMembers!=='function'||typeof api.households?.get!=='function')fail('household API and authoritative enrollment session required');
   fields(raw,kind==='addition'?['key','enrollmentKey','headClientId','entryDate','members']:kind==='entry'?['key','householdId','headClientId','providerId','type','entryDate','members']:['key','enrollmentKey','headClientId',kind==='exit'?'exitDate':'reviewDate','members',...(kind==='exit'?['destination','reasonForLeaving','destinationDetails','reasonForLeavingOther']:[])]);
   const input=structuredClone(raw);key(input.key);
@@ -463,8 +501,10 @@ export function createEnrollmentWorkflow({api,discovery,helpers,store,enrollment
   else{key(input.enrollmentKey);if(kind==='addition')input.entryDate=date(input.entryDate);else if(kind==='exit')input.exitDate=date(input.exitDate);else input.reviewDate=date(input.reviewDate);}
   // Read the cohort under its journal lock, then acquire all client locks in order.
   // Recheck under both locks so concurrent membership growth cannot escape protection.
+  operation.attempted=true;
   const prior=await store.withLock(householdScope(input.headClientId),()=>store.read(householdScope(input.headClientId)));
   if(!Array.isArray(prior))fail('invalid household journal');
+  operation.attempted=prior.some(r=>r.key===input.key);
   const lockedIds=[...new Set([input.headClientId,...ids,...prior.flatMap(r=>r.clientIds??[])])].sort((a,b)=>a-b);
   return withClients(lockedIds,()=>store.withLock(householdScope(input.headClientId),async()=>{
    const records=await store.read(householdScope(input.headClientId));
@@ -532,7 +572,7 @@ export function createEnrollmentWorkflow({api,discovery,helpers,store,enrollment
    const toMember=m=>['entry','addition'].includes(kind)?{key:memberKey(input.key,m.clientId),clientId:m.clientId,providerId:context.providerId,type:context.type,entryDate:context.entryDate,assessment:m.assessment}:{key:memberKey(input.key,m.clientId),enrollmentKey:memberKey(catalog[m.clientId].entryKey,m.clientId),clientId:m.clientId,...(kind==='exit'?{exitDate:input.exitDate}:{reviewDate:input.reviewDate}),assessment:m.assessment};
    // Validate every member before any record mutation. The same client locks cover
    // preflight and execution, including overlaps with the single-client workflow.
-   const preflight=[];for(const member of input.members)preflight.push(await run(kind==='addition'?'entry':kind,toMember(member),{locked:true,owner,headClientId:input.headClientId,preflight:true,...(kind==='addition'?{pinSchema:true}:{})}));
+   const preflight=[];for(const member of input.members)preflight.push(await run(kind==='addition'?'entry':kind,toMember(member),{locked:true,owner,operation,headClientId:input.headClientId,preflight:true,...(kind==='addition'?{pinSchema:true}:{})}));
    if(kind==='addition'&&record?.entrySchemas&&canonical(record.entrySchemas)!==canonical(preflight))fail('additional member assessment configuration changed');
    if(kind==='exit'&&record?.exitSchemas&&canonical(record.exitSchemas)!==canonical(preflight))fail('exit assessment configuration changed');
    const wasVerified=record?.stage==='verified';
@@ -580,14 +620,14 @@ export function createEnrollmentWorkflow({api,discovery,helpers,store,enrollment
      const existing=await enrollments(api,clientId,{enrollmentSession,writeAttempted:await writeAttempted()});if(existing.some(e=>e.enrollmentProvider===context.providerId&&e.type===context.type&&e.isActive&&e.projectExitDate==null&&restDate(e.projectStartDate)===restDate(context.entryDate)))fail('member already has an independent matching enrollment');
     }
     const head=input.members.find(m=>m.clientId===input.headClientId);
-    const result=await run('entry',toMember(head),{locked:true,owner,headClientId:input.headClientId,findEnrollment:findMember(head.clientId)});record.members[head.clientId]=result;await persist();
+    const result=await run('entry',toMember(head),{locked:true,owner,operation,headClientId:input.headClientId,findEnrollment:findMember(head.clientId)});record.members[head.clientId]=result;await persist();
     // Reject unexpected members before the attachment helper is allowed to write.
     await readTarget({clientId:head.clientId,enrollmentId:result.enrollmentId},{partial:!record.attached});
     record.attachmentAttempted=true;await persist();
-    const attached=await helpers.addHouseholdMembers({clientId:head.clientId,enrollmentId:result.enrollmentId,memberClientIds:ids.filter(id=>id!==head.clientId)});
+    operation.attempted=true;const attached=await helpers.addHouseholdMembers({clientId:head.clientId,enrollmentId:result.enrollmentId,memberClientIds:ids.filter(id=>id!==head.clientId)});
     const snapshot=validateSnapshot(attached.snapshot,{clientId:head.clientId,enrollmentId:result.enrollmentId});
     for(const m of snapshot.members)record.members[m.clientId]??={clientId:m.clientId,enrollmentId:m.enrollmentId};record.attached=true;await persist();
-    for(const member of input.members.filter(m=>m.clientId!==head.clientId)){record.members[member.clientId]=await run('entry',toMember(member),{locked:true,owner,headClientId:input.headClientId,findEnrollment:findMember(member.clientId)});await persist();}
+    for(const member of input.members.filter(m=>m.clientId!==head.clientId)){record.members[member.clientId]=await run('entry',toMember(member),{locked:true,owner,operation,headClientId:input.headClientId,findEnrollment:findMember(member.clientId)});await persist();}
    }else if(kind==='addition'){
     if(!record.anchor){
      for(const clientId of Object.keys(catalog).map(Number).sort((a,b)=>a-b)){
@@ -601,7 +641,7 @@ export function createEnrollmentWorkflow({api,discovery,helpers,store,enrollment
      const existing=await enrollments(api,clientId,{enrollmentSession,writeAttempted:await writeAttempted()});if(existing.some(e=>e.enrollmentProvider===context.providerId&&e.type===context.type&&e.isActive&&e.projectExitDate==null))fail('additional member already has an independent enrollment');
     }
     record.attachmentAttempted=true;await persist();
-    const attached=await helpers.addHouseholdMembers({...record.anchor,memberClientIds:ids});
+    operation.attempted=true;const attached=await helpers.addHouseholdMembers({...record.anchor,memberClientIds:ids});
     validateSnapshot(attached.snapshot,record.anchor);
     for(const clientId of ids){const found=attached.snapshot.members.find(m=>m.clientId===clientId);if(record.members[clientId]?.enrollmentId&&record.members[clientId].enrollmentId!==found.enrollmentId)fail('added enrollment identity changed');record.members[clientId]??={clientId,enrollmentId:found.enrollmentId};}
     record.attached=true;await persist();await preserve();
@@ -619,13 +659,13 @@ export function createEnrollmentWorkflow({api,discovery,helpers,store,enrollment
       const change={...target,providerId:context.providerId,type:context.type,entryDate:input.entryDate,cohort};
       await memberEntryDatePort.validateMemberEntryDate(change);
       record.entryDates[clientId]='attempted';record.entryDateInputs[clientId]=change;await persist();
-      try{await memberEntryDatePort.saveMemberEntryDate(change);}catch{/* Resolve only through readback; never replay the date update. */}
+      operation.attempted=true;try{await memberEntryDatePort.saveMemberEntryDate(change);}catch{/* Resolve only through readback; never replay the date update. */}
      }
      if(record.entryDates[clientId]==='attempted'&&record.entryDateInputs[clientId])await memberEntryDatePort.validateMemberEntryDate(record.entryDateInputs[clientId]);
      const fresh=await readTarget(target);if(!wasVerified&&fresh.exits?.filter(e=>e.clientId===clientId&&e.enrollmentId===target.enrollmentId&&e.projectExitDate===null).length!==1)fail('new member must remain enrolled');
      await preserve();record.entryDates[clientId]='verified';await persist();
     }
-    for(const member of input.members){record.members[member.clientId]=await run('entry',toMember(member),{locked:true,owner,headClientId:input.headClientId,findEnrollment:findMember(member.clientId)});await persist();}
+    for(const member of input.members){record.members[member.clientId]=await run('entry',toMember(member),{locked:true,owner,operation,headClientId:input.headClientId,findEnrollment:findMember(member.clientId)});await persist();}
    }else if(kind==='interim'){
     // Verify all linked enrollments before making the single household review call.
     const existingReviews=[];
@@ -640,7 +680,7 @@ export function createEnrollmentWorkflow({api,discovery,helpers,store,enrollment
     if(existingReviews.some(Boolean)&&existingReviews.some(r=>!r))fail('partial household review requires reconciliation');
     if(existingReviews[0]&&new Set(existingReviews.map(r=>r.reviewId)).size!==ids.length)fail('duplicate household review IDs');
     const target={clientId:ids[0],enrollmentId:catalog[ids[0]].enrollmentId};
-    const review=await helpers.createInterimUpdate({...target,clientIds:ids,reviewDate:input.reviewDate});validateSnapshot(review.snapshot,target);
+    operation.attempted=true;const review=await helpers.createInterimUpdate({...target,clientIds:ids,reviewDate:input.reviewDate});validateSnapshot(review.snapshot,target);
     const readReview=async target=>{
      const snapshot=await readTarget(target),reviews=snapshot.reviews.filter(r=>r.type==='Update'&&restDate(r.reviewDate)===restDate(input.reviewDate));
      if(reviews.length!==1||!positive(reviews[0].reviewId)||canonical([...reviews[0].clientIds].sort((a,b)=>a-b))!==canonical(ids))fail('household review membership mismatch');
@@ -650,7 +690,7 @@ export function createEnrollmentWorkflow({api,discovery,helpers,store,enrollment
     // Pin every member's distinct review ID before writing any member's answers.
     for(const clientId of ids){const enrollmentId=catalog[clientId].enrollmentId,{snapshot}=await readReview({clientId,enrollmentId});record.members[clientId]??={clientId,enrollmentId};record.members[clientId].reviewId=snapshot.reviews.find(r=>r.type==='Update'&&restDate(r.reviewDate)===restDate(input.reviewDate)).reviewId;await persist();}
     if(new Set(ids.map(id=>record.members[id].reviewId)).size!==ids.length)fail('duplicate household review IDs');
-    for(const member of input.members){record.members[member.clientId]=await run('interim',toMember(member),{locked:true,owner,headClientId:input.headClientId,findEnrollment:findMember(member.clientId),readReview});await persist();}
+    for(const member of input.members){record.members[member.clientId]=await run('interim',toMember(member),{locked:true,owner,operation,headClientId:input.headClientId,findEnrollment:findMember(member.clientId),readReview});await persist();}
    }else if(kind==='exit'){
     const target={clientId:ids[0],enrollmentId:catalog[ids[0]].enrollmentId};
     const normalizeLabel=value=>typeof value==='string'?value.replace(/\s*\(HUD\)\s*$/,'').trim():value;
@@ -681,7 +721,7 @@ export function createEnrollmentWorkflow({api,discovery,helpers,store,enrollment
      const exitInput={...target,clientIds:ids,exitDate:input.exitDate,destination:input.destination,reasonForLeaving:input.reasonForLeaving,...(input.destinationDetails?{destinationDetails:input.destinationDetails}:{}),...(input.reasonForLeavingOther?{reasonForLeavingOther:input.reasonForLeavingOther}:{})};
      await exitUi.validateExit(exitInput);
      record.exitStep='attempted';await persist();
-     try{await exitUi.saveExit(exitInput);}catch{/* Only authoritative readback establishes success. Never replay an uncertain save. */}
+     operation.attempted=true;try{await exitUi.saveExit(exitInput);}catch{/* Only authoritative readback establishes success. Never replay an uncertain save. */}
      observed=await inspect();if(!observed.found)fail('uncertain household exit requires reconciliation');
     }
     await validateHeadCoverage();await preserve();
@@ -689,7 +729,7 @@ export function createEnrollmentWorkflow({api,discovery,helpers,store,enrollment
     const readExit=async target=>{
      const result=await inspect();if(!result.found)fail('verified exit missing');return result.exits.find(e=>e.clientId===target.clientId&&e.enrollmentId===target.enrollmentId);
     };
-    for(const member of input.members){record.members[member.clientId]=await run('exit',toMember(member),{locked:true,owner,headClientId:input.headClientId,findEnrollment:findMember(member.clientId),readExit});await persist();}
+    for(const member of input.members){record.members[member.clientId]=await run('exit',toMember(member),{locked:true,owner,operation,headClientId:input.headClientId,findEnrollment:findMember(member.clientId),readExit});await persist();}
    }
    if(kind==='exit'||kind==='addition')await preserve();
    await validateHeadCoverage();
@@ -698,13 +738,16 @@ export function createEnrollmentWorkflow({api,discovery,helpers,store,enrollment
   }));
  };
  return {
-  correctEntry,
-  resolveEntryCorrection,
-  adoptEnrollment:input=>adopt(false,input),adoptHouseholdEnrollment:input=>adopt(true,input),
-  addHouseholdMembers:input=>householdRun('addition',input),
-  createHouseholdEnrollment:input=>householdRun('entry',input),createHouseholdInterim:input=>householdRun('interim',input),exitHousehold:input=>householdRun('exit',input),
-  discoverExit:input=>discover(input,true),
+  correctEntry:input=>execute('correctEntry',operation=>correctEntry(input,operation)),
+  registerEntryRows:input=>execute('registerEntryRows',()=>registerEntryRows(input)),
+  discoverHouseholdEnrollment:input=>execute('discoverHouseholdEnrollment',()=>discoverHouseholdEnrollment(input)),
+  resolveEntryCorrection:input=>execute('resolveEntryCorrection',()=>resolveEntryCorrection(input)),
+  adoptEnrollment:input=>execute('adoptEnrollment',()=>adopt(false,input)),adoptHouseholdEnrollment:input=>execute('adoptHouseholdEnrollment',()=>adopt(true,input)),
+  addHouseholdMembers:input=>execute('addHouseholdMembers',operation=>householdRun('addition',input,operation)),
+  createHouseholdEnrollment:input=>execute('createHouseholdEnrollment',operation=>householdRun('entry',input,operation)),createHouseholdInterim:input=>execute('createHouseholdInterim',operation=>householdRun('interim',input,operation)),exitHousehold:input=>execute('exitHousehold',operation=>householdRun('exit',input,operation)),
+  discoverExit:input=>execute('discoverExit',()=>discover(input,true)),
   async getHouseholdStatus(input){
+   return execute('getHouseholdStatus',async()=>{
    fields(input,['headClientId','key']);if(!positive(input.headClientId))fail('head client ID required');key(input.key);
    return store.withLock(householdScope(input.headClientId),async()=>{
     const records=await store.read(householdScope(input.headClientId));if(!Array.isArray(records))fail('invalid household journal');
@@ -712,9 +755,11 @@ export function createEnrollmentWorkflow({api,discovery,helpers,store,enrollment
     if(record.version!==1||!object(record.members))fail('invalid household journal');
     return {key:record.key,kind:record.kind,stage:record.stage,householdId:record.context.householdId,headClientId:input.headClientId,members:record.clientIds.map(clientId=>({clientId,key:memberKey(input.key,clientId),...structuredClone(record.members[clientId]??{})}))};
    });
+   });
   },
-  discover,createEnrollment:input=>run('entry',input),createInterim:input=>run('interim',input),exitEnrollment:input=>run('exit',input,{standaloneExit:true}),
+  discover:input=>execute('discover',()=>discover(input)),createEnrollment:input=>execute('createEnrollment',operation=>run('entry',input,{operation})),createInterim:input=>execute('createInterim',operation=>run('interim',input,{operation})),exitEnrollment:input=>execute('exitEnrollment',operation=>run('exit',input,{standaloneExit:true,operation})),
   async getStatus(input){
+   return execute('getStatus',async()=>{
    fields(input,['clientId','key']);if(!positive(input.clientId))fail('client ID required');key(input.key);
    return store.withLock(scope(input.clientId),async()=>{
     const records=await store.read(scope(input.clientId));if(!Array.isArray(records))fail('invalid workflow journal');
@@ -722,6 +767,7 @@ export function createEnrollmentWorkflow({api,discovery,helpers,store,enrollment
     if(r.version!==1||!object(r.steps))fail('invalid workflow journal');
     return {key:r.key,kind:r.kind,stage:r.stage,assessmentCode:r.assessmentCode,...(r.enrollmentId?{enrollmentId:r.enrollmentId}:{}),...(r.reviewId?{reviewId:r.reviewId}:{}),...(r.projectExitDate?{projectExitDate:r.projectExitDate,exitSubgroupId:r.exitSubgroupId}:{}),...(r.resolution?{resolution:structuredClone(r.resolution)}:{}),recordsetIds:structuredClone(r.rows),steps:Object.entries(r.steps).map(([name,step])=>({name,state:step.state,...(step.failure?{failure:correctionFailureDetails(step.failure)}:{})}))};
    });
+   });
   },
  };
 }

package/browser/entry-correction.mjs

@@ -50,7 +50,7 @@ export function createEntryCorrector({api,store,enrollmentSession,writeLabel,dis
   if(rows.some(q=>!object(q)||typeof q.virt_field_name!=='string')||new Set(rows.map(q=>q.virt_field_name)).size!==rows.length)fail('ambiguous correction assessment read');
   return rows;
  };
- const run=async(mode,raw)=>{
+ const run=async(mode,raw,operation={attempted:false})=>{
   const resolving=mode==='resolve';
   fields(raw,resolving?['key','enrollmentKey','clientId','evidenceReference','confirmNotApplied']:['key','enrollmentKey','clientId','answers','clear','subassessments']);
   const {confirmNotApplied,...serializable}=raw;
@@ -61,8 +61,10 @@ export function createEntryCorrector({api,store,enrollmentSession,writeLabel,dis
   return store.withLock(scope(input.clientId),async()=>{
    const reservations=await store.withLock(reservationScope(input.clientId),()=>store.read(reservationScope(input.clientId)));
    if(!Array.isArray(reservations)||reservations.some(r=>r.stage!=='verified'))fail('unfinished household workflow must be reconciled first');
+   if(!resolving)operation.attempted=true;
    const records=await store.read(scope(input.clientId));
    if(!Array.isArray(records)||records.some(r=>!object(r)||r.version!==1||!object(r.steps)))fail('invalid workflow journal');
+   if(!resolving)operation.attempted=records.some(r=>r.key===input.key&&Object.keys(r.steps).length>0);
    if(records.some(r=>r.stage!=='verified'&&!(r.kind==='correction'&&r.stage==='rejected')&&r.key!==input.key))fail('another unfinished workflow must be reconciled first');
    const entries=records.filter(r=>r.kind==='entry'&&r.key===input.enrollmentKey&&r.stage==='verified');
    if(entries.length!==1)fail('verified enrollment workflow required');const entry=entries[0];
@@ -162,7 +164,7 @@ export function createEntryCorrector({api,store,enrollmentSession,writeLabel,dis
     for(const patch of input.subassessments??[]){
      fields(patch,['key','parentField','answers','clear']);key(patch.key);
      const id=entry.rows[patch.key],parent=definition.questions.find(q=>q.fieldName===patch.parentField&&q.questionType==='sub_assessment');
-     if(!positive(id)||ids.has(id)||!parent||!observed.rows[parent.fieldName]?.[id])fail('correction requires an existing entry row key and matching parent');ids.add(id);
+     if(!positive(id)||ids.has(id)||!parent||!observed.rows[parent.fieldName]?.[id]||entry.rowParents?.[patch.key]&&entry.rowParents[patch.key]!==patch.parentField)fail('correction requires an existing entry row key and matching parent');ids.add(id);
      const cells=encode(parent.children,patch.answers??{},patch.clear??[],'mobile');if(!cells.length)fail('empty row correction');
      rowPlans.push({id,parentField:parent.fieldName,questionId:parent.questionId,cells});
     }
@@ -184,7 +186,7 @@ export function createEntryCorrector({api,store,enrollmentSession,writeLabel,dis
     if(record.steps[name])throw uncertain();
     if(!await inspect(null))fail('entry changed since correction preflight');
     await verifyEnrollment();record.steps[name]={state:'attempted'};await persist();let cause;
-    try{await submit();}catch(e){
+    operation.attempted=true;try{await submit();}catch(e){
      cause=e;const failure=correctionFailureDetails(e);
      if(Object.keys(failure).length){record.steps[name].failure=failure;await persist();}
     }
@@ -201,5 +203,5 @@ export function createEntryCorrector({api,store,enrollmentSession,writeLabel,dis
    record.stage='verified';await persist();return result('verified');
   });
  };
- return {correctEntry:raw=>run('correct',raw),resolveEntryCorrection:raw=>run('resolve',raw)};
+ return {correctEntry:(raw,operation)=>run('correct',raw,operation),resolveEntryCorrection:raw=>run('resolve',raw)};
 }

package/browser/entry-row-registration.mjs

@@ -0,0 +1,63 @@
+import {createHash} from 'node:crypto';
+import {parseRestInstant,toItems} from '../dist/esm/index.js';
+
+const object=v=>v!==null&&typeof v==='object'&&!Array.isArray(v);
+const canonical=v=>JSON.stringify(v,(_,x)=>object(x)?Object.fromEntries(Object.keys(x).sort().map(k=>[k,x[k]])):x);
+const hash=v=>createHash('sha256').update(canonical(v)).digest('hex');
+const positive=v=>Number.isSafeInteger(v)&&v>0;
+
+/** Registers caller-selected existing identities locally; never writes an assessment. */
+export function createEntryRowRegistrar({api,store,enrollmentSession,discover,scope,reservationScope,makeError}){
+ const fail=(code,reason)=>{throw makeError(reason,{code,committed:false});};
+ const key=v=>typeof v==='string'&&!!v.trim()&&v.length<=200;
+ return async raw=>{
+  if(!object(raw)||Object.keys(raw).some(k=>!['key','enrollmentKey','clientId','rows'].includes(k))||!key(raw.key)||!key(raw.enrollmentKey)||!positive(raw.clientId)||!Array.isArray(raw.rows)||!raw.rows.length)fail('ROW_REGISTRATION_INPUT_INVALID','valid registration key, entry key, client and explicit rows required');
+  if(typeof enrollmentSession?.readEnrollment!=='function')fail('ROW_REGISTRATION_READER_REQUIRED','authoritative enrollment reader required');
+  const input=structuredClone(raw);input.rows.sort((a,b)=>String(a?.key).localeCompare(String(b?.key)));
+  const keys=new Set(),ids=new Set();
+  for(const row of input.rows){
+   if(!object(row)||Object.keys(row).some(k=>!['key','parentField','recordsetId'].includes(k))||!key(row.key)||!key(row.parentField)||!positive(row.recordsetId)||keys.has(row.key)||ids.has(row.recordsetId))fail('ROW_REGISTRATION_INPUT_INVALID','unique row keys, parents and positive recordset IDs required');
+   keys.add(row.key);ids.add(row.recordsetId);
+  }
+  return store.withLock(scope(input.clientId),async()=>{
+   const reservations=await store.withLock(reservationScope(input.clientId),()=>store.read(reservationScope(input.clientId)));
+   if(!Array.isArray(reservations)||reservations.some(r=>r.stage!=='verified'))fail('WORKFLOW_PENDING','unfinished household workflow must be reconciled first');
+   const records=await store.read(scope(input.clientId));
+   if(!Array.isArray(records)||records.some(r=>r.version!==1||!object(r.steps)))fail('WORKFLOW_JOURNAL_INVALID','invalid workflow journal');
+   if(records.some(r=>r.stage!=='verified'&&!(r.kind==='correction'&&r.stage==='rejected')))fail('WORKFLOW_PENDING','unfinished workflow must be reconciled first');
+   const entries=records.filter(r=>r.key===input.enrollmentKey&&r.kind==='entry'&&r.stage==='verified');
+   if(entries.length!==1)fail('ROW_REGISTRATION_ENTRY_REQUIRED','verified enrollment workflow required');const entry=entries[0];
+   const prior=Object.hasOwn(entry.rowRegistrations??{},input.key)?entry.rowRegistrations[input.key]:undefined,intentHash=hash(input);
+   if(prior&&prior.intentHash!==intentHash)fail('ROW_REGISTRATION_INTENT_CONFLICT','registration key conflicts with previous intent');
+   const target={clientId:input.clientId,enrollmentId:entry.enrollmentId},at=entry.context.entryDate;
+   const verifyEnrollment=async()=>{
+    const s=await enrollmentSession.readEnrollment(target);
+    if(s?.source!=='gwt-rpc'||s.tenant!==api.tenant||s.clientId!==target.clientId||s.enrollmentId!==target.enrollmentId||s.providerId!==entry.context.providerId||s.enrollmentType!==entry.context.type||parseRestInstant(s.projectStartDate)!==parseRestInstant(at))fail('ROW_REGISTRATION_CONTEXT_MISMATCH','enrollment identity changed during row registration');
+   };
+   await verifyEnrollment();
+   const discovered=await discover({...entry.context}),definition=discovered.entry.definition;
+   const schemaHash=hash({providerId:discovered.provider.providerId,entry:{assessment:discovered.entry.assessment,questions:definition.questions},interim:{assessment:discovered.interim.assessment,questions:discovered.interim.definition.questions}});
+   if(schemaHash!==entry.schemaHash)fail('WORKFLOW_SCHEMA_CHANGED','program assessment configuration changed');
+   const rowMap=entry.rows??{},parents=entry.rowParents??{};
+   for(const row of input.rows){
+    if(!definition.questions.some(q=>q.fieldName===row.parentField&&q.questionType==='sub_assessment'))fail('ROW_REGISTRATION_PARENT_INVALID','subassessment parent not in entry definition');
+    if(Object.hasOwn(rowMap,row.key)&&(rowMap[row.key]!==row.recordsetId||!Object.hasOwn(parents,row.key))||Object.entries(rowMap).some(([key,id])=>key!==row.key&&id===row.recordsetId)||Object.hasOwn(parents,row.key)&&parents[row.key]!==row.parentField)fail('ROW_REGISTRATION_BINDING_CONFLICT','row key or recordset is already bound differently');
+   }
+   const verifyRows=async effectiveDate=>{
+    const response=toItems(await api.assessments.get({path:{clientId:input.clientId,assessmentCode:entry.assessmentCode},query:{dateEffective:effectiveDate}}));
+    for(const row of input.rows){
+     const parent=response.filter(p=>p?.virt_field_name===row.parentField&&p.question_type==='sub_assessment');
+     if(parent.length!==1||!Array.isArray(parent[0].sub_assessment_answer_list))fail('ROW_REGISTRATION_READ_UNAVAILABLE','complete row registration read required');
+     const matches=parent[0].sub_assessment_answer_list.filter(r=>r?.recordset_id===row.recordsetId);
+     if(matches.length!==1||!Array.isArray(matches[0].sub_assessment_list))fail('ROW_REGISTRATION_ROW_MISSING','selected row is missing or ambiguous at the entry date or current read');
+    }
+   };
+   await verifyRows(at);await verifyRows(new Date(Math.max(Date.now(),parseRestInstant(at)+1000)).toISOString());await verifyEnrollment();
+   entry.rows=Object.fromEntries([...Object.entries(rowMap),...input.rows.map(r=>[r.key,r.recordsetId])]);
+   entry.rowParents=Object.fromEntries([...Object.entries(parents),...input.rows.map(r=>[r.key,r.parentField])]);
+   entry.rowRegistrations=Object.fromEntries([...Object.entries(entry.rowRegistrations??{}),[input.key,{intentHash,rows:input.rows}]]);
+   await store.write(scope(input.clientId),structuredClone(records));
+   return {key:input.key,enrollmentKey:input.enrollmentKey,clientId:input.clientId,enrollmentId:entry.enrollmentId,outcome:prior?'already-present':'verified',recordsetIds:structuredClone(entry.rows)};
+  });
+ };
+}

package/browser/household-enrollment-discovery.mjs

@@ -0,0 +1,49 @@
+import {parseRestInstant,toItems} from '../dist/esm/index.js';
+
+const positive=v=>Number.isSafeInteger(v)&&v>0;
+const pairs=members=>JSON.stringify(members.map(({clientId,enrollmentId})=>({clientId,enrollmentId})).sort((a,b)=>a.clientId-b.clientId));
+
+/** Resolves only a unique current household satisfying the adoption membership contract. */
+export function createHouseholdEnrollmentDiscovery({api,enrollmentSession,makeError}){
+ const fail=(code,reason)=>{throw makeError(reason,{code,committed:false});};
+ return async input=>{
+  if(!input||Object.keys(input).some(k=>!['headClientId','headEnrollmentId'].includes(k))||!positive(input.headClientId)||!positive(input.headEnrollmentId))fail('HOUSEHOLD_DISCOVERY_INPUT_INVALID','head client and enrollment IDs required');
+  if(typeof enrollmentSession?.readEnrollment!=='function'||typeof api.households?.listForClient!=='function'||typeof api.households?.get!=='function')fail('HOUSEHOLD_DISCOVERY_READERS_REQUIRED','GWT detail and complete household readers required');
+  const target={clientId:input.headClientId,enrollmentId:input.headEnrollmentId};
+  const anchor=await enrollmentSession.readEnrollment(target);
+  const valid=(s,t)=>s?.source==='gwt-rpc'&&s.tenant===api.tenant&&s.clientId===t.clientId&&s.enrollmentId===t.enrollmentId&&positive(s.providerId)&&typeof s.enrollmentType==='string'&&Number.isFinite(parseRestInstant(s.projectStartDate));
+  if(!valid(anchor,target)||!Array.isArray(anchor.members)||!anchor.members.length||anchor.members.some(m=>!positive(m?.clientId)||!positive(m?.enrollmentId))||new Set(anchor.members.map(m=>m.clientId)).size!==anchor.members.length||new Set(anchor.members.map(m=>m.enrollmentId)).size!==anchor.members.length||!anchor.members.some(m=>m.clientId===target.clientId&&m.enrollmentId===target.enrollmentId))fail('HOUSEHOLD_DISCOVERY_DETAIL_INVALID','complete linked enrollment cohort required');
+  if(anchor.members.length===1&&anchor.grouped!==true)fail('ENROLLMENT_NOT_GROUPED','standalone enrollment uses adoptEnrollment');
+  if(anchor.grouped===false&&anchor.members.length>1)fail('HOUSEHOLD_DISCOVERY_DETAIL_INVALID','group flag conflicts with linked cohort');
+  const members=anchor.members.map(({clientId,enrollmentId})=>({clientId,enrollmentId})).sort((a,b)=>a.clientId-b.clientId),starts=new Map();
+  for(const member of members){
+   const s=member.clientId===target.clientId?anchor:await enrollmentSession.readEnrollment(member);
+   if(!valid(s,member)||s.providerId!==anchor.providerId||s.enrollmentType!==anchor.enrollmentType||!Array.isArray(s.members)||pairs(s.members)!==pairs(members))fail('HOUSEHOLD_DISCOVERY_COHORT_CHANGED','linked enrollment cohort changed during discovery');
+   starts.set(member.clientId,parseRestInstant(s.projectStartDate));
+  }
+  const candidates=[],seen=new Set();let total;
+  for(let startPage=1;startPage<=100;startPage++){
+   const result=await api.households.listForClient({path:{clientId:input.headClientId},query:{perPage:100,startPage,total_count:true}});
+   if(!Number.isSafeInteger(result?.count)||result.count<0||!Array.isArray(result.values)||total!==undefined&&total!==result.count)fail('HOUSEHOLD_DISCOVERY_LIST_INCOMPLETE','household list count unavailable or changed');total=result.count;
+   for(const h of result.values){
+    if(!positive(h?.householdId)||seen.has(h.householdId)||!Array.isArray(h.clients)||h.clients.some(m=>!positive(m?.clientId))||new Set(h.clients.map(m=>m.clientId)).size!==h.clients.length||!h.clients.some(m=>m.clientId===input.headClientId))fail('HOUSEHOLD_DISCOVERY_LIST_INCOMPLETE','invalid household list');
+    seen.add(h.householdId);candidates.push(h);
+   }
+   if(seen.size===total)break;
+   if(seen.size>total||!result.values.length||startPage===100)fail('HOUSEHOLD_DISCOVERY_LIST_INCOMPLETE','incomplete household list');
+  }
+  const matches=h=>{
+   if(h.isActive!==true||!Array.isArray(h.clients))return false;
+   const heads=h.clients.filter(m=>m.headofhouseholdStatus&&m.isActive!==false&&!m.dateLeft);
+   return heads.length===1&&heads[0].clientId===input.headClientId&&members.every(m=>{
+    const found=h.clients.filter(c=>c.clientId===m.clientId);
+    return found.length===1&&found[0].isActive!==false&&!found[0].dateLeft&&Number.isFinite(parseRestInstant(found[0].dateJoined))&&parseRestInstant(found[0].dateJoined)<=starts.get(m.clientId);
+   });
+  };
+  const found=candidates.filter(matches);
+  if(found.length!==1)fail(found.length?'HOUSEHOLD_DISCOVERY_AMBIGUOUS':'HOUSEHOLD_DISCOVERY_NOT_FOUND','a unique current household matching the full cohort, head and dates is required');
+  const fresh=toItems(await api.households.get({path:{householdId:found[0].householdId}}));
+  if(fresh.length!==1||fresh[0].householdId!==found[0].householdId||!matches(fresh[0]))fail('HOUSEHOLD_DISCOVERY_COHORT_CHANGED','household membership changed during discovery');
+  return {headClientId:input.headClientId,headEnrollmentId:input.headEnrollmentId,householdId:fresh[0].householdId,householdSource:'verified-membership',providerId:anchor.providerId,type:anchor.enrollmentType,members};
+ };
+}

package/browser/index.d.mts

@@ -17,10 +17,12 @@ export class LoginError extends Error {
 }
 export interface UiSession {readonly connection:UiConnection;browser: Browser;context: BrowserContext;page: Page;passwordRecovery:'restored-original'|'not-needed';ensureAuthenticated():Promise<void>;reauthenticate():Promise<void>;close():Promise<void>;}
 export interface PlaywrightGwtOptions {page:Page;tenant:string;moduleBaseUrl:string;}
-export interface PlaywrightEnrollmentSnapshot extends GwtEnrollmentSnapshot {providerId:number;enrollmentType:string;exits:readonly GwtEnrollmentExit[];}
+export interface PlaywrightEnrollmentSnapshot extends GwtEnrollmentSnapshot {providerId:number;enrollmentType:string;exits:readonly GwtEnrollmentExit[];groupId?:number|string|null;grouped?:boolean;}
 export interface EnrollmentListRow {
  enrollmentId:number;clientId:number;enrollmentProvider:number;type:string;
  projectStartDate:string;projectExitDate:string|null;isActive:boolean;
+ /** An enrollment group pointer, not a household identifier or member count. */
+ groupId:number|string|null;grouped:boolean;
 }
 export interface EnrollmentListSnapshot {
  source:'gwt-rpc';tenant:string;clientId:number;count:number;values:EnrollmentListRow[];