@choiceapps/communityservices-sdk 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.3.0 - 2026-11-03
+
+- Compare journaled attachment and case-note intents, and shelter stay identities, by canonical hash instead of key-order-sensitive JSON, so an identical retry no longer conflicts when a store such as Postgres `jsonb` reorders keys. Existing journals remain valid.
+- Add an optional `enrollmentSession` reader to `createCurrentLivingSituationRecorder` and `createCoordinatedEntryEventRecorder`. It reads the enrollment through GWT, so clients in household enrollments, whose REST enrollment reads fail with `42703`, can be recorded. Journal hashes match the REST path.
+- Export `parseRestInstant`, which parses REST read timestamps such as `2026-11-20 10:00:00-07` the same way on every engine and host timezone, treating a missing offset as UTC. `Date.parse` can return NaN for that form and reads a missing offset as local time.
+- Document that a mobile batch which returned HTTP 400 once saved one of its answers. The batch itself did not fail again in sandbox retests, including enrolled single-adult and household clients; the cause is unknown and the workflow is unchanged.
+
+## 0.2.0 - 2026-11-02
+
+- Add opt-in private HTTP error-body capture and retain the original write failure as the cause of an uncertain enrollment stage. Failed writes still require reconciliation and are never replayed automatically.
+- Add `yesNoWrites: 'standard'` with a `writeLabel` resolver to `createEnrollmentWorkflow`. Yes/no answers then leave the mobile batch and are written through `assessments.create` with every mandatory answer, in a separate `yesno` stage. The default `mobile` mode is unchanged, and an unfinished journal never switches modes.
+- Verify the `yesno` stage with a generic read one second after the effective instant, because a read at the instant omits yes/no answers. Standard mode supports mandatory lookups only.
+- Read subassessment rows in the enrollment workflow at the later of now and the record's date, and in the Current Living Situation and Coordinated Entry Event recorders one second after that, so yes/no answers saved at the event instant read back. Undated generic reads omitted rows dated after the server's current time, which left a live interim's new rows unverified.
+- Add `createCoordinatedEntryEventRecorder`, which records one journaled Coordinated Entry Event row per event key through the standard assessment endpoint, keeping provider locations and yes/no results. It checks each event's follow-up answers: placement referrals require a location, and other follow-up answers are refused where they do not apply. `recordResult` adds a referral result later by updating only the result cells of the recorded row.
+- The Current Living Situation and Coordinated Entry Event recorders share one internal row journal and reconciliation module. Current Living Situation behavior, error reasons and journal hashes are unchanged.
+- `subassessments.setEndDate` sends only the end-date cell instead of the whole row, so rows with provider questions, such as Coordinated Entry Events, can be end-dated, and other answers are left untouched. It finds an end-date question that the row has never answered from the parent's question list.
+- `encodeNewSubassessmentRow` omits an unanswered provider child for mobile rows instead of rejecting the row. Answered provider children are still refused.
+- Document the November 2, 2026 yes/no findings: mobile writes store yes/no answers empty and only insert rows, and standard writes need every mandatory answer.
+
 ## 0.1.1 - 2026-11-02
 
 - Accept Basic, Standard, RHY, Basic Center Program Entry/Exit, PATH, Quick Call, and Transitional Living Program Entry/Exit in enrollment workflows alongside HUD and VA. Added per-type assessment display location mappings, with current provider discovery and existing journal verification.

package/browser/client-workflows.mjs

@@ -3,9 +3,12 @@ import {createHash} from 'node:crypto';
 import {decodeMappedResponse} from './gwt-mapped.mjs';
 import {withPageLock} from './page-lock.mjs';
 import {AttachmentConflictError} from './attachment-conflict.mjs';
+import {semanticHash} from '../dist/esm/index.js';
 const id=n=>{if(!Number.isSafeInteger(n)||n<=0)throw Error('Positive integer ID required');return n;};
 const hash=b=>createHash('sha256').update(b).digest('hex');
 const maxBytes=10_000_000;
+// Key-order independent: stores such as Postgres jsonb do not preserve insertion order.
+const sameIntent=async(a,b)=>await semanticHash(a)===await semanticHash(b);
 
 /** Browser-authenticated attachment access where the REST account cannot upload/read files.
  * Own this page exclusively. The store must persist before resolving and survive restarts. */
@@ -64,7 +67,7 @@ export function createClientWorkflows({page,store}) {
       await openClient(clientId);
       if(entityId&&!(await mapped(`SELECT g.goalId AS goalId FROM SpGoal AS g WHERE g.active = TRUE AND g.goalId = ${entityId} AND g.clientId = ${clientId}`)).length)throw Error('Goal does not belong to client');
       const records=await store.read(scope);if(!Array.isArray(records)||records.length>1)throw Error('Invalid upload journal');const previous=records[0];
-      if(previous&&JSON.stringify(previous.intent)!==JSON.stringify(intent))throw new AttachmentConflictError('intent-changed','Attachment intent conflicts with prior attempt');
+      if(previous&&!(await sameIntent(previous.intent,intent)))throw new AttachmentConflictError('intent-changed','Attachment intent conflicts with prior attempt');
       const matching=async()=>{
         const matches=(await list(clientId)).filter(a=>a.entityType===entityType&&(a.entityId??null)===entityId&&a.name===file.name);
         if(matches.length>1)throw new AttachmentConflictError('duplicate-name','Duplicate attachment names');
@@ -94,7 +97,7 @@ export function createClientWorkflows({page,store}) {
     const scope=JSON.stringify(key===undefined?[base,'case-note',clientId,goalId,providerId,noteDate,hash(note)]:[base,'case-note-source',hash(key)]);
     return store.withLock(scope,async()=>{
       const records=await store.read(scope);if(!Array.isArray(records)||records.length>1)throw Error('Invalid case note journal');const previous=records[0];
-      if(previous&&JSON.stringify(previous.intent)!==JSON.stringify(intent))throw Object.assign(Error('Case note source key conflicts with earlier intent'),{code:'CASE_NOTE_SOURCE_CONFLICT'});
+      if(previous&&!(await sameIntent(previous.intent,intent)))throw Object.assign(Error('Case note source key conflicts with earlier intent'),{code:'CASE_NOTE_SOURCE_CONFLICT'});
       return withPageLock(page,async()=>{
       await openClient(clientId);
       if(!(await mapped(`SELECT g.goalId AS goalId FROM SpGoal AS g WHERE g.active = TRUE AND g.goalId = ${goalId} AND g.clientId = ${clientId}`)).length)throw Error('Goal does not belong to client');

package/browser/coordinated-entry-event.d.mts

@@ -0,0 +1,81 @@
+import type {Answers, EncodingOptions, PicklistSelector, WellSkyClient} from '../dist/esm/index.js';
+import type {EnrollmentReader, UiMutationStore} from './index.mjs';
+/** Exact virtual fields from the target instrument's client-scoped metadata. No guessed codes. */
+export interface CoordinatedEntryEventFields {
+    parentField: string;
+    startDate: string;
+    endDate: string;
+    eventDate: string;
+    event: string;
+    /** yes_no: Problem Solving/Diversion result, client housed or re-housed in a safe alternative. */
+    housedSafely: string;
+    /** yes_no: post-placement/follow-up case management result, enrolled in aftercare. */
+    enrolledInAftercare: string;
+    /** provider: location of the crisis or permanent housing referral. */
+    location: string;
+    /** lookup: referral result. */
+    referralResult: string;
+    /** date: date of the referral result. */
+    resultDate: string;
+}
+export interface CoordinatedEntryEventInput {
+    /** Unique upstream event within this client. Preserve it and the journal on retries. */
+    key: string;
+    clientId: number;
+    enrollmentId: number;
+    /** An instrument containing the CE Event subassessment and no mandatory questions. */
+    assessmentCode: string;
+    /** Date of the event as a timezone-qualified whole-second instant. */
+    eventDate: string;
+    /** The Event option. Its code selects which follow-up answers are allowed or required. */
+    event: {option: PicklistSelector};
+    /** Optional; only for a Problem Solving/Diversion event. */
+    housedSafely?: boolean;
+    /** Optional; only for a post-placement/follow-up case management referral. */
+    enrolledInAftercare?: boolean;
+    /** Provider ID. Required for, and only allowed on, ES, TH, Joint TH-RRH, RRH, PSH and Other PH referrals. */
+    location?: number;
+    /** Only on those referrals, together with resultDate. Usually known after the referral. */
+    referralResult?: {option: PicklistSelector};
+    resultDate?: string;
+    /** Other actual platform questions in the row. Cannot override the mapped fields. */
+    additionalAnswers?: Answers;
+}
+export interface CoordinatedEntryEventResult {
+    key: string; clientId: number; enrollmentId: number; recordsetId: number;
+    startDate: string; endDate: null; eventDate: string;
+    outcome: 'verified' | 'already-present' | 'reconciled';
+}
+export interface CoordinatedEntryResultInput {
+    /** The event key used with record(). The event must already be verified. */
+    key: string;
+    clientId: number;
+    assessmentCode: string;
+    referralResult: {option: PicklistSelector};
+    /** Date of the result; not before the event date. */
+    resultDate: string;
+}
+export interface CoordinatedEntryResultReceipt {
+    key: string; clientId: number; recordsetId: number; resultDate: string;
+    outcome: 'verified' | 'already-present' | 'reconciled';
+}
+export interface CoordinatedEntryEventRecorder {
+    record(input: CoordinatedEntryEventInput): Promise<CoordinatedEntryEventResult>;
+    /** Adds a referral result and date to a recorded ES, TH, Joint TH-RRH, RRH, PSH or Other PH
+     * referral. Updates only those cells through the mobile endpoint; journaled and never resent. */
+    recordResult(input: CoordinatedEntryResultInput): Promise<CoordinatedEntryResultReceipt>;
+}
+export class CoordinatedEntryEventConflictError extends Error {
+    readonly code: 'COORDINATED_ENTRY_EVENT_CONFLICT';
+    readonly reason: string;
+    constructor(reason: string);
+}
+/** REST orchestration through the standard assessment endpoint. No browser launch or credential loading. */
+export function createCoordinatedEntryEventRecorder(options: {
+    api: WellSkyClient; store: UiMutationStore; fields: CoordinatedEntryEventFields;
+    /** Tenant-verified labels for lookup answers, including the Event. */
+    writeLabel: NonNullable<EncodingOptions['writeLabel']>;
+    /** Read the enrollment through this GWT reader instead of REST, which fails for grouped
+     * (household) enrollments. Use the reader `openEnrollmentSession` returns. */
+    enrollmentSession?: EnrollmentReader;
+}): CoordinatedEntryEventRecorder;

package/browser/coordinated-entry-event.mjs

@@ -0,0 +1,175 @@
+import {encodeAnswers, resolvePicklistOption, semanticHash} from '../dist/esm/index.js';
+import {createRowRecorder, rowHelpers, checkJournal, object, positive, nonempty} from './subassessment-row-recorder.mjs';
+
+const fail = reason => { throw new CoordinatedEntryEventConflictError(reason); };
+export class CoordinatedEntryEventConflictError extends Error {
+    constructor(reason) { super(`Coordinated Entry Event: ${reason}`); this.name = 'CoordinatedEntryEventConflictError'; this.code = 'COORDINATED_ENTRY_EVENT_CONFLICT'; this.reason = reason; }
+}
+const {instant, exactFields, valueOf, childIndex} = rowHelpers(fail);
+const roles = ['parentField', 'startDate', 'endDate', 'eventDate', 'event', 'housedSafely', 'enrolledInAftercare', 'location', 'referralResult', 'resultDate'];
+const roleTypes = {startDate: 'date', endDate: 'date', eventDate: 'date', event: 'lookup', housedSafely: 'yes_no', enrolledInAftercare: 'yes_no', location: 'provider', referralResult: 'lookup', resultDate: 'date'};
+// Follow-up answers each Event option allows, matching the form's dependency labels.
+// Placement referrals require a location; results usually arrive later and stay optional.
+const placement = {location: 'required', result: 'optional'};
+const EVENT_RULES = Object.freeze({
+    PREVASSIST: {}, PROBSOLV: {housedSafely: 'optional'}, CRISISNEEDS: {}, HOUSINGNEEDS: {},
+    POSTPLACEFOLLOWUP: {enrolledInAftercare: 'optional'}, STREETOUTREACH: {}, HOUSINGNAVIGATION: {}, NONCONT_INELIG: {}, NONCONT_NOAVAIL: {},
+    EMERGSHELTER: placement, TRANSITHOUSING: placement, JOINTTHRRH: placement, RRH: placement, PSH: placement, OTHERPH: placement,
+});
+const EVENT_PREFIX = 'COORDINATEDENTRYEVENT_EVENT_';
+
+function normalize(raw) {
+    exactFields(raw, ['key', 'clientId', 'enrollmentId', 'assessmentCode', 'eventDate', 'event', 'housedSafely', 'enrolledInAftercare', 'location', 'referralResult', 'resultDate', 'additionalAnswers']);
+    if (!nonempty(raw.key) || !positive(raw.clientId) || !positive(raw.enrollmentId) || !nonempty(raw.assessmentCode) || !object(raw.event) || raw.additionalAnswers !== undefined && !object(raw.additionalAnswers)) fail('invalid-input');
+    for (const flag of ['housedSafely', 'enrolledInAftercare']) if (raw[flag] !== undefined && typeof raw[flag] !== 'boolean') fail('invalid-input');
+    if (raw.location !== undefined && !positive(raw.location)) fail('location-provider-id-required');
+    if (raw.referralResult !== undefined && !(object(raw.referralResult) && object(raw.referralResult.option))) fail('referral-result-option-required');
+    if (raw.additionalAnswers !== undefined && Object.values(raw.additionalAnswers).some(answer => !object(answer))) fail('invalid-input');
+    return {key: raw.key, clientId: raw.clientId, enrollmentId: raw.enrollmentId, assessmentCode: raw.assessmentCode, eventDate: instant(raw.eventDate), event: structuredClone(raw.event),
+        ...Object.fromEntries(['housedSafely', 'enrolledInAftercare', 'location'].filter(k => raw[k] !== undefined).map(k => [k, raw[k]])),
+        ...(raw.referralResult !== undefined ? {referralResult: structuredClone(raw.referralResult)} : {}),
+        ...(raw.resultDate !== undefined ? {resultDate: instant(raw.resultDate)} : {}),
+        additionalAnswers: structuredClone(raw.additionalAnswers ?? {})};
+}
+function ruleFor(option) {
+    const rule = option?.code?.startsWith(EVENT_PREFIX) ? EVENT_RULES[option.code.slice(EVENT_PREFIX.length)] : undefined;
+    if (!rule) fail('unsupported-event');
+    return rule;
+}
+function eventRule(question, selector) {
+    if (!('option' in selector)) fail('event-option-required');
+    let option;
+    try { option = resolvePicklistOption(question, selector.option); } catch { fail('unsupported-event'); }
+    return ruleFor(option);
+}
+function mappedChildren(definition, fields, assessmentCode, tenant) {
+    const {parent, index} = childIndex(definition, assessmentCode, fields.parentField, tenant);
+    for (const [role, type] of Object.entries(roleTypes)) if (index.get(fields[role])?.questionType !== type) fail(`${role}-field-unavailable`);
+    return {parent, index};
+}
+function normalizeResult(raw) {
+    exactFields(raw, ['key', 'clientId', 'assessmentCode', 'referralResult', 'resultDate']);
+    if (!nonempty(raw.key) || !positive(raw.clientId) || !nonempty(raw.assessmentCode)) fail('invalid-input');
+    if (!(object(raw.referralResult) && object(raw.referralResult.option))) fail('referral-result-option-required');
+    return {key: raw.key, clientId: raw.clientId, assessmentCode: raw.assessmentCode, referralResult: structuredClone(raw.referralResult), resultDate: instant(raw.resultDate)};
+}
+function compile(definition, fields, input, entryDate, tenant, writeLabel) {
+    // The standard endpoint rejects any request that omits a mandatory answer. Resending
+    // other answers would create new dated rows for them, so such instruments are refused.
+    if (definition?.questions?.some?.(q => q.mandatory === true && !['label', 'blank'].includes(q.questionType))) fail('instrument-has-mandatory-questions');
+    const {parent, index} = mappedChildren(definition, fields, input.assessmentCode, tenant);
+    if (index.get(fields.endDate).mandatory === true) fail('platform-requires-end-date');
+    if (Object.keys(input.additionalAnswers).some(field => Object.values(fields).includes(field))) fail('reserved-field-override');
+    const rule = eventRule(index.get(fields.event), input.event);
+    for (const flag of ['housedSafely', 'enrolledInAftercare']) if (input[flag] !== undefined && !rule[flag]) fail(`${flag}-not-applicable`);
+    if (rule.location === 'required' && input.location === undefined) fail('location-required');
+    if (!rule.location && input.location !== undefined) fail('location-not-applicable');
+    const hasResult = input.referralResult !== undefined, hasResultDate = input.resultDate !== undefined;
+    if ((hasResult || hasResultDate) && !rule.result) fail('referral-result-not-applicable');
+    if (hasResult !== hasResultDate) fail('referral-result-and-date-required-together');
+    if (hasResultDate && input.resultDate < input.eventDate) fail('result-before-event');
+    const answers = {...input.additionalAnswers, [fields.startDate]: {value: entryDate}, [fields.eventDate]: {value: input.eventDate}, [fields.event]: input.event,
+        ...(input.housedSafely !== undefined ? {[fields.housedSafely]: {value: input.housedSafely}} : {}),
+        ...(input.enrolledInAftercare !== undefined ? {[fields.enrolledInAftercare]: {value: input.enrolledInAftercare}} : {}),
+        ...(input.location !== undefined ? {[fields.location]: {value: input.location}} : {}),
+        ...(hasResult ? {[fields.referralResult]: input.referralResult, [fields.resultDate]: {value: input.resultDate}} : {})};
+    for (const [field, answer] of Object.entries(input.additionalAnswers)) if (index.get(field)?.questionType === 'date' && object(answer) && 'value' in answer) answers[field] = {value: instant(answer.value)};
+    // Labels are sent; the same selectors encoded as option IDs are what reads return.
+    const sent = encodeAnswers(parent.children, answers, {endpoint: 'standalone', writeLabel});
+    const stored = encodeAnswers(parent.children, answers, {endpoint: 'standalone', writeLabel: (_q, option) => String(option.id)});
+    for (const q of index.values()) {
+        if (q.mandatory === true && !sent.some(answer => answer.virt_field_name === q.fieldName && answer.answer_value !== '')) fail(`platform-required-field:${q.fieldName}`);
+    }
+    return {parent, sent, stored};
+}
+
+/** One new CE Event recordset per event key, written through the standard assessment endpoint,
+ * which keeps provider and yes/no answers that mobile writes drop. Follow-up answers are
+ * checked against the selected Event. */
+export function createCoordinatedEntryEventRecorder({api, store, fields: mapping, writeLabel, enrollmentSession}) {
+    if (!store?.withLock || !store?.read || !store?.write || typeof api?.assessments?.create !== 'function') fail('api-and-store-required');
+    if (typeof writeLabel !== 'function') fail('write-label-required');
+    exactFields(mapping, roles);
+    const fields = structuredClone(mapping);
+    if (roles.some(role => !nonempty(fields[role])) || new Set(Object.values(fields)).size !== roles.length) fail('invalid-field-mapping');
+    const recorder = createRowRecorder({api, store, enrollmentSession, fail, kind: 'coordinated-entry-event', noun: 'event', dateKey: 'eventDate', parentField: fields.parentField, normalize,
+        compile(definition, input, enrollment) {
+            const {parent, sent, stored} = compile(definition, fields, input, enrollment.entryDate, api.tenant, writeLabel);
+            // Hash option IDs, not labels, so a relabelled option does not invalidate verified keys.
+            return {expected: stored, empty: [fields.endDate], intent: {fields, stored},
+                body: [{question_id: parent.questionId, question_type: 'sub_assessment', virt_field_name: fields.parentField, answer_value: '', subAssessmentQuestionAnswers: [{subAssessments: sent}]}]};
+        },
+        write: (input, body) => api.assessments.create({path: {clientId: input.clientId, assessmentCode: input.assessmentCode}, query: {dateEffective: input.eventDate}, body}),
+    });
+    /** Adds a referral result to an event this recorder verified. The standard endpoint only
+     * creates rows, so this sends just the result cells to the event's recordset through the
+     * mobile endpoint, which updates those cells and keeps the others, including the location. */
+    async function recordResult(raw) {
+        if (typeof api.assessmentsMobile?.addAnswer !== 'function') fail('api-and-store-required');
+        const input = normalizeResult(raw), scope = recorder.scopeOf(input.clientId);
+        return store.withLock(scope, async () => {
+            const entries = await store.read(scope);
+            checkJournal(entries, fail);
+            const entry = entries.find(e => e.key === input.key);
+            if (entry?.stage !== 'verified' || !positive(entry.recordsetId)) fail('event-not-verified');
+            if (entries.some(e => (e.stage === 'attempted' || e.update?.stage === 'attempted') && e.key !== input.key)) fail('unfinished-event');
+            const definition = await api.assessments.getDefinition({clientId: input.clientId, assessmentCode: input.assessmentCode, effectiveDate: input.resultDate, refresh: true});
+            const {parent, index} = mappedChildren(definition, fields, input.assessmentCode, api.tenant);
+            const cells = encodeAnswers(parent.children, {[fields.referralResult]: input.referralResult, [fields.resultDate]: {value: input.resultDate}}, {endpoint: 'mobile'});
+            const intentHash = await semanticHash({input, fields, cells});
+            if (entry.update && entry.update.intentHash !== intentHash) fail('result-intent-changed');
+            const read = () => recorder.readRows({clientId: input.clientId, assessmentCode: input.assessmentCode}, input.resultDate);
+            const result = outcome => ({key: input.key, clientId: input.clientId, recordsetId: entry.recordsetId, resultDate: input.resultDate, outcome});
+            const resultFields = [fields.referralResult, fields.resultDate];
+            const saved = row => cells.every(q => row.fields[q.virt_field_name]?.type === q.question_type && row.fields[q.virt_field_name]?.value === valueOf(q));
+            let rows = await read(), row = rows.find(row => row.id === entry.recordsetId);
+            if (!row) fail('verified-event-changed');
+            const eventOptions = index.get(fields.event).options, storedEvent = row.fields[fields.event]?.value, storedDate = row.fields[fields.eventDate]?.value;
+            if (!Array.isArray(eventOptions)) fail('event-picklist-unavailable');
+            const eventOption = eventOptions.find(o => String(o.id) === storedEvent);
+            if (!eventOption || typeof storedDate !== 'string') fail('verified-event-changed');
+            if (!ruleFor(eventOption).result) fail('referral-result-not-applicable');
+            // A result may follow the client's exit; only the event itself must fall within the enrollment.
+            if (input.resultDate < storedDate) fail('result-before-event');
+            // Only the result cells may change: earlier answers, other rows and the row count stay.
+            const reconcile = async () => {
+                const before = entry.update.before, target = before.find(r => r.id === entry.recordsetId);
+                if (rows.length !== before.length) fail('existing-event-changed');
+                for (const prior of before) {
+                    const after = rows.find(r => r.id === prior.id);
+                    if (!after) fail('existing-event-changed');
+                    if (prior.id !== entry.recordsetId && await semanticHash(after) !== await semanticHash(prior)) fail('existing-event-changed');
+                }
+                const after = rows.find(r => r.id === entry.recordsetId);
+                for (const [field, answer] of Object.entries(target.fields)) if (!resultFields.includes(field) && await semanticHash(after.fields[field]) !== await semanticHash(answer)) fail('verified-event-changed');
+                if (!saved(after)) fail('uncertain-result-save');
+            };
+            // Drift in the event's other answers is reported by record() under the same key.
+            if (entry.update?.stage === 'verified') { if (!saved(row)) fail('verified-result-changed'); return result('already-present'); }
+            if (entry.update?.stage === 'attempted') {
+                await reconcile();
+                entry.update = {stage: 'verified', intentHash};
+                await store.write(scope, structuredClone(entries));
+                return result('reconciled');
+            }
+            if (resultFields.some(field => (row.fields[field]?.value ?? null) !== null)) {
+                if (!saved(row)) fail('result-conflict');
+                entry.update = {stage: 'verified', intentHash};
+                await store.write(scope, structuredClone(entries));
+                return result('already-present');
+            }
+            entry.update = {stage: 'attempted', intentHash, before: rows};
+            await store.write(scope, structuredClone(entries));
+            let failed = false;
+            try {
+                await api.assessmentsMobile.addAnswer({path: {clientId: input.clientId, assessmentCode: input.assessmentCode}, query: {dateEffective: input.resultDate}, body: [{question_id: parent.questionId, question_type: 'sub_assessment', virt_field_name: fields.parentField, answer_value: '', subAssessmentQuestionAnswers: [{recordset_id: entry.recordsetId, isDeleted: false, subAssessments: cells}]}]});
+            } catch { failed = true; }
+            rows = await read();
+            await reconcile();
+            entry.update = {stage: 'verified', intentHash};
+            await store.write(scope, structuredClone(entries));
+            return result(failed ? 'reconciled' : 'verified');
+        });
+    }
+    return {record: recorder.record, recordResult};
+}

package/browser/current-living-situation.d.mts

@@ -1,5 +1,5 @@
 import type {Answers, AnswerValue, WellSkyClient} from '../dist/esm/index.js';
-import type {UiMutationStore} from './index.mjs';
+import type {EnrollmentReader, UiMutationStore} from './index.mjs';
 /** Exact virtual fields from the target program's client-scoped metadata. No guessed codes. */
 export interface CurrentLivingSituationFields {
     parentField: string;
@@ -41,4 +41,7 @@ export class CurrentLivingSituationConflictError extends Error {
 /** REST orchestration. No browser launch, credential loading, or automatic interim. */
 export function createCurrentLivingSituationRecorder(options: {
     api: WellSkyClient; store: UiMutationStore; fields: CurrentLivingSituationFields;
+    /** Read the enrollment through this GWT reader instead of REST, which fails for grouped
+     * (household) enrollments. Use the reader `openEnrollmentSession` returns. */
+    enrollmentSession?: EnrollmentReader;
 }): CurrentLivingSituationRecorder;

package/browser/current-living-situation.mjs

@@ -1,60 +1,19 @@
-import {apiScope} from './connection.mjs';
-import {encodeAnswers, toItems, semanticHash} from '../dist/esm/index.js';
+import {encodeAnswers} from '../dist/esm/index.js';
+import {createRowRecorder, rowHelpers, object, positive, nonempty} from './subassessment-row-recorder.mjs';
 
-const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
-const positive = value => Number.isSafeInteger(value) && value > 0;
 const fail = reason => { throw new CurrentLivingSituationConflictError(reason); };
 export class CurrentLivingSituationConflictError extends Error {
     constructor(reason) { super(`Current Living Situation: ${reason}`); this.name = 'CurrentLivingSituationConflictError'; this.code = 'CURRENT_LIVING_SITUATION_CONFLICT'; this.reason = reason; }
 }
-function instant(value, stored = false) {
-    if (typeof value !== 'string') fail('invalid-date');
-    // Enrollment/assessment reads emit UTC without a suffix.
-    const text = stored ? value.replace(' ', 'T').replace(/([+-]\d\d)$/, '$1:00') + (/(?:Z|[+-]\d\d(?::\d\d)?)$/.test(value) ? '' : 'Z') : value;
-    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.000)?(?:Z|[+-]\d{2}:\d{2})$/.test(text) || !Number.isFinite(Date.parse(text)) || new Date(text.slice(0, 19) + 'Z').toISOString().slice(0, 19) !== text.slice(0, 19)) fail('invalid-date');
-    return new Date(text).toISOString();
-}
-function exactFields(value, allowed) {
-    if (!object(value) || Object.keys(value).some(key => !allowed.includes(key))) fail('invalid-input');
-}
-function nonempty(value) { return typeof value === 'string' && value.trim().length > 0 && value.length <= 200; }
+const {instant, exactFields, childIndex} = rowHelpers(fail);
 function normalize(raw) {
     exactFields(raw, ['key', 'clientId', 'enrollmentId', 'assessmentCode', 'informationDate', 'livingSituation', 'endDate', 'verifiedBy', 'additionalAnswers']);
     if (!nonempty(raw.key) || !positive(raw.clientId) || !positive(raw.enrollmentId) || !nonempty(raw.assessmentCode) || !object(raw.livingSituation) || (raw.endDate !== undefined && raw.endDate !== null && raw.endDate !== '')) fail('invalid-input');
     if (raw.verifiedBy !== undefined && !object(raw.verifiedBy) || raw.additionalAnswers !== undefined && !object(raw.additionalAnswers)) fail('invalid-input');
     return {key: raw.key, clientId: raw.clientId, enrollmentId: raw.enrollmentId, assessmentCode: raw.assessmentCode, informationDate: instant(raw.informationDate), livingSituation: structuredClone(raw.livingSituation), endDate: '', ...(raw.verifiedBy !== undefined ? {verifiedBy: structuredClone(raw.verifiedBy)} : {}), additionalAnswers: structuredClone(raw.additionalAnswers ?? {})};
 }
-async function readEnrollment(api, input) {
-    const rows = [], ids = new Set(); let total;
-    for (let page = 1; page <= 100; page++) {
-        const response = await api.enrollments.listForClient({path: {clientId: input.clientId}, query: {perPage: 100, startPage: page, total_count: true}});
-        if (!Number.isSafeInteger(response?.count) || response.count < 0 || !Array.isArray(response.values) || total !== undefined && total !== response.count) fail('enrollment-count-unavailable');
-        total = response.count;
-        for (const row of response.values) {
-            if (!object(row) || !positive(row.enrollmentId) || row.clientId !== input.clientId || ids.has(row.enrollmentId)) fail('invalid-enrollment-read');
-            ids.add(row.enrollmentId); rows.push(row);
-        }
-        if (rows.length === total) {
-            const row = rows.find(row => row.enrollmentId === input.enrollmentId);
-            if (!row || row.isActive !== true || !positive(row.enrollmentProvider)) fail('enrollment-unavailable');
-            const entryDate = instant(row.projectStartDate, true);
-            if (input.informationDate < entryDate || row.projectExitDate && input.informationDate > instant(row.projectExitDate, true)) fail('contact-outside-enrollment');
-            return {entryDate, providerId: row.enrollmentProvider};
-        }
-        if (rows.length > total || !response.values.length) fail('incomplete-enrollment-read');
-    }
-    fail('enrollment-page-limit');
-}
 function compile(definition, fields, input, entryDate, tenant) {
-    if (definition?.tenant !== tenant || definition.assessmentCode !== input.assessmentCode || !Array.isArray(definition.questions)) fail('invalid-definition');
-    const parents = definition.questions.filter(q => q.fieldName === fields.parentField && q.questionType === 'sub_assessment');
-    if (parents.length !== 1 || !positive(parents[0].questionId) || !Array.isArray(parents[0].children)) fail('parent-unavailable');
-    const parent = parents[0], index = new Map();
-    for (const q of parent.children) {
-        if (['label', 'blank'].includes(q.questionType)) continue;
-        if (!nonempty(q.fieldName) || !positive(q.questionId) || index.has(q.fieldName)) fail('ambiguous-definition');
-        index.set(q.fieldName, q);
-    }
+    const {parent, index} = childIndex(definition, input.assessmentCode, fields.parentField, tenant);
     for (const role of ['startDate', 'endDate', 'informationDate']) if (index.get(fields[role])?.questionType !== 'date') fail('date-field-unavailable');
     if (index.get(fields.livingSituation)?.questionType !== 'lookup') fail('living-situation-picklist-unavailable');
     if (index.get(fields.endDate).mandatory === true) fail('platform-requires-end-date');
@@ -75,87 +34,19 @@ function compile(definition, fields, input, entryDate, tenant) {
     // Do not invent answers for omitted optional questions. Verify every answer sent.
     return {parent, encoded};
 }
-function valueOf(question) {
-    if (question.answer_value === null || question.answer_value === undefined || question.answer_value === '') return null;
-    if (question.question_type === 'date') return instant(question.answer_value, true);
-    if (typeof question.answer_value !== 'string') fail('invalid-answer-read');
-    return question.answer_value;
-}
-async function readRows(api, input, fields) {
-    const response = await api.assessments.get({path: {clientId: input.clientId, assessmentCode: input.assessmentCode}});
-    const questions = toItems(response);
-    if (!Array.isArray(questions) || object(response) && 'count' in response && response.count !== questions.length) fail('incomplete-assessment-read');
-    const parents = questions.filter(q => q?.virt_field_name === fields.parentField && q.question_type === 'sub_assessment');
-    if (parents.length !== 1 || !Array.isArray(parents[0].sub_assessment_answer_list)) fail('rows-unavailable');
-    const rows = parents[0].sub_assessment_answer_list, ids = new Set();
-    if (rows.length > 10000) fail('row-limit');
-    return rows.map(row => {
-        if (!positive(row.recordset_id) || ids.has(row.recordset_id) || !Array.isArray(row.sub_assessment_list)) fail('ambiguous-row-read');
-        ids.add(row.recordset_id);
-        const fields = {};
-        for (const q of row.sub_assessment_list) {
-            if (['label', 'blank'].includes(q.question_type)) continue;
-            if (!nonempty(q.virt_field_name) || Object.hasOwn(fields, q.virt_field_name) || typeof q.question_type !== 'string') fail('ambiguous-answer-read');
-            Object.defineProperty(fields, q.virt_field_name, {value: {type: q.question_type, value: valueOf(q)}, enumerable: true});
-        }
-        return {id: row.recordset_id, fields};
-    });
-}
-const matches = (row, encoded) => encoded.every(q => row.fields[q.virt_field_name]?.type === q.question_type && row.fields[q.virt_field_name]?.value === valueOf(q));
 
 /** One new recordset per contact key, even when two contacts have identical answers. */
-export function createCurrentLivingSituationRecorder({api, store, fields: mapping}) {
- const tenantScope=apiScope(api);
+export function createCurrentLivingSituationRecorder({api, store, fields: mapping, enrollmentSession}) {
     if (!store?.withLock || !store?.read || !store?.write) fail('api-and-store-required');
     exactFields(mapping, ['parentField', 'startDate', 'endDate', 'informationDate', 'livingSituation', 'verifiedBy']);
     const fields = structuredClone(Object.fromEntries(Object.entries(mapping).filter(([, value]) => value !== undefined)));
     if (['parentField', 'startDate', 'endDate', 'informationDate', 'livingSituation'].some(role => !nonempty(fields[role])) || fields.verifiedBy !== undefined && !nonempty(fields.verifiedBy) || new Set(Object.values(fields)).size !== Object.keys(fields).length) fail('invalid-field-mapping');
-    return {async record(raw) {
-        const input = normalize(raw), scope = JSON.stringify([tenantScope, 'current-living-situation', input.clientId]);
-        return store.withLock(scope, async () => {
-            const entries = await store.read(scope);
-            if (!Array.isArray(entries) || new Set(entries.map(e => e?.key)).size !== entries.length || entries.some(e => !object(e) || e.version !== 1 || !nonempty(e.key) || !['attempted', 'verified'].includes(e.stage) || typeof e.intentHash !== 'string' || !Array.isArray(e.baseline) || e.stage === 'verified' && !positive(e.recordsetId))) fail('invalid-journal');
-            let entry = entries.find(e => e.key === input.key);
-            if (entries.some(e => e.stage === 'attempted' && e.key !== input.key)) fail('unfinished-contact');
-            const enrollment = await readEnrollment(api, input);
-            const definition = await api.assessments.getDefinition({clientId: input.clientId, assessmentCode: input.assessmentCode, effectiveDate: input.informationDate, refresh: true});
+    return createRowRecorder({api, store, enrollmentSession, fail, kind: 'current-living-situation', noun: 'contact', dateKey: 'informationDate', parentField: fields.parentField, normalize,
+        compile(definition, input, enrollment) {
             const {parent, encoded} = compile(definition, fields, input, enrollment.entryDate, api.tenant);
-            const intentHash = await semanticHash({input, fields, enrollment, encoded});
-            if (entry && entry.intentHash !== intentHash) fail('intent-or-schema-changed');
-            let rows = await readRows(api, input, fields);
-            const result = (row, outcome) => ({key: input.key, clientId: input.clientId, enrollmentId: input.enrollmentId, recordsetId: row.id, startDate: enrollment.entryDate, endDate: null, informationDate: input.informationDate, outcome});
-            if (entry?.stage === 'verified') {
-                const row = rows.find(row => row.id === entry.recordsetId);
-                if (!row || !matches(row, encoded)) fail('verified-contact-changed');
-                return result(row, 'already-present');
-            }
-            const reconcile = async () => {
-                for (const before of entry.baseline) {
-                    const after = rows.find(row => row.id === before.id);
-                    if (!after || await semanticHash(after) !== await semanticHash(before)) fail('existing-contact-changed');
-                }
-                const added = rows.filter(row => !entry.baseline.some(before => before.id === row.id));
-                if (added.length !== 1 || !matches(added[0], encoded)) fail('uncertain-contact-save');
-                return added[0];
-            };
-            if (entry) {
-                const row = await reconcile();
-                entry.stage = 'verified'; entry.recordsetId = row.id;
-                await store.write(scope, structuredClone(entries));
-                return result(row, 'reconciled');
-            }
-            entry = {version: 1, key: input.key, intentHash, stage: 'attempted', baseline: rows};
-            entries.push(entry);
-            await store.write(scope, structuredClone(entries));
-            let failed = false;
-            try {
-                await api.assessmentsMobile.addAnswer({path: {clientId: input.clientId, assessmentCode: input.assessmentCode}, query: {dateEffective: input.informationDate}, body: [{question_id: parent.questionId, question_type: 'sub_assessment', virt_field_name: fields.parentField, answer_value: '', subAssessmentQuestionAnswers: [{recordset_id: 0, isDeleted: false, subAssessments: encoded}]}]});
-            } catch { failed = true; }
-            rows = await readRows(api, input, fields);
-            const row = await reconcile();
-            entry.stage = 'verified'; entry.recordsetId = row.id;
-            await store.write(scope, structuredClone(entries));
-            return result(row, failed ? 'reconciled' : 'verified');
-        });
-    }};
+            return {expected: encoded, empty: [], intent: {fields, encoded},
+                body: [{question_id: parent.questionId, question_type: 'sub_assessment', virt_field_name: fields.parentField, answer_value: '', subAssessmentQuestionAnswers: [{recordset_id: 0, isDeleted: false, subAssessments: encoded}]}]};
+        },
+        write: (input, body) => api.assessmentsMobile.addAnswer({path: {clientId: input.clientId, assessmentCode: input.assessmentCode}, query: {dateEffective: input.informationDate}, body}),
+    });
 }

package/browser/enrollment-workflow.d.mts

@@ -1,5 +1,5 @@
 import type {DateOfBirth} from './date-of-birth.mjs';
-import type {Answers, AssessmentDefinition, GwtEnrollmentHelpers, Provider, WellSkyClient} from '../dist/esm/index.js';
+import type {Answers, AssessmentDefinition, EncodingOptions, GwtEnrollmentHelpers, Provider, WellSkyClient} from '../dist/esm/index.js';
 import type {UiMutationStore,EnrollmentReader} from './index.mjs';
 import type {ProviderAssessmentItem, ProgramDiscovery} from './program-discovery.mjs';
 import type {HouseholdExitUi,HouseholdExitDetailInput} from './household-exit.mjs';
@@ -170,10 +170,18 @@ export interface EnrollmentWorkflowOptions {
   exitUi?:HouseholdExitUi;
   /** Required to set the later entry date for newly attached household members. */
   memberEntryDatePort?:MemberEntryDatePort;
+  /** Default `mobile` keeps yes/no answers in the mobile scalar batch, which can store them empty.
+   * `standard` writes them through `assessments.create` with every mandatory answer, after the mobile scalars;
+   * every mandatory question must be a lookup. An unfinished journal never reconciles in the other mode. */
+  yesNoWrites?:'mobile'|'standard';
+  /** Required for `yesNoWrites: 'standard'`: tenant-verified labels for mandatory lookup answers. */
+  writeLabel?:EncodingOptions['writeLabel'];
 }
 export class EnrollmentWorkflowError extends Error {
   readonly reason:string;
-  constructor(reason:string);
+  /** 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});
 }
 /** Tenant-configured. Retain stable keys and one durable store for all cooperating writers.
  * A partial or uncertain write requires reconciliation; no automatic write replay occurs. */