@choiceapps/communityservices-sdk 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 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/coordinated-entry-event.d.mts

@@ -0,0 +1,78 @@
+import type {Answers, EncodingOptions, PicklistSelector, WellSkyClient} from '../dist/esm/index.js';
+import type {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']>;
+}): 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}) {
+    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, 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.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);
     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, 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. */