@choiceapps/communityservices-sdk 0.1.0

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

@@ -0,0 +1,44 @@
+import type {Answers, AnswerValue, WellSkyClient} from '../dist/esm/index.js';
+import type {UiMutationStore} from './index.mjs';
+/** Exact virtual fields from the target program's client-scoped metadata. No guessed codes. */
+export interface CurrentLivingSituationFields {
+    parentField: string;
+    startDate: string;
+    endDate: string;
+    informationDate: string;
+    livingSituation: string;
+    verifiedBy?: string;
+}
+export interface CurrentLivingSituationInput {
+    /** Unique upstream contact event within this client. Preserve it and the journal on retries. */
+    key: string;
+    clientId: number;
+    enrollmentId: number;
+    assessmentCode: string;
+    /** Contact date as a timezone-qualified whole-second instant, in the program's calendar. */
+    informationDate: string;
+    livingSituation: AnswerValue;
+    /** Open by default. Recording another contact does not close the previous contact row. */
+    endDate?: null | '';
+    /** Optional. A recording program may be supplied using the field's verified text or lookup representation. */
+    verifiedBy?: AnswerValue;
+    /** Only actual additional platform questions. Cannot override the mapped fields. */
+    additionalAnswers?: Answers;
+}
+export interface CurrentLivingSituationResult {
+    key: string; clientId: number; enrollmentId: number; recordsetId: number;
+    startDate: string; endDate: null; informationDate: string;
+    outcome: 'verified' | 'already-present' | 'reconciled';
+}
+export interface CurrentLivingSituationRecorder {
+    record(input: CurrentLivingSituationInput): Promise<CurrentLivingSituationResult>;
+}
+export class CurrentLivingSituationConflictError extends Error {
+    readonly code: 'CURRENT_LIVING_SITUATION_CONFLICT';
+    readonly reason: string;
+    constructor(reason: string);
+}
+/** REST orchestration. No browser launch, credential loading, or automatic interim. */
+export function createCurrentLivingSituationRecorder(options: {
+    api: WellSkyClient; store: UiMutationStore; fields: CurrentLivingSituationFields;
+}): CurrentLivingSituationRecorder;

package/browser/current-living-situation.mjs

@@ -0,0 +1,161 @@
+import {apiScope} from './connection.mjs';
+import {encodeAnswers, toItems, semanticHash} from '../dist/esm/index.js';
+
+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; }
+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);
+    }
+    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');
+    const reserved = Object.values(fields);
+    if (Object.keys(input.additionalAnswers).some(field => reserved.includes(field))) fail('reserved-field-override');
+    const answers = {...input.additionalAnswers, [fields.startDate]: {value: entryDate}, [fields.endDate]: {value: ''}, [fields.informationDate]: {value: input.informationDate}, [fields.livingSituation]: input.livingSituation};
+    if (input.verifiedBy !== undefined) {
+        const question = index.get(fields.verifiedBy);
+        if (!question || !['textbox', 'textarea', 'lookup'].includes(question.questionType)) fail('verified-by-representation-unsupported');
+        if (['textbox', 'textarea'].includes(question.questionType) && (!('value' in input.verifiedBy) || typeof input.verifiedBy.value !== 'string' || !input.verifiedBy.value.trim())) fail('verified-by-text-required');
+        answers[fields.verifiedBy] = input.verifiedBy;
+    }
+    const encoded = encodeAnswers(parent.children, answers, {endpoint: 'mobile'});
+    if (!encoded.some(q => q.virt_field_name === fields.livingSituation && q.answer_value)) fail('living-situation-required');
+    for (const q of index.values()) {
+        if (q.mandatory === true && !encoded.some(answer => answer.virt_field_name === q.fieldName && answer.answer_value !== '')) fail(`platform-required-field:${q.fieldName}`);
+    }
+    // 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});
+            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');
+        });
+    }};
+}

package/browser/date-of-birth-ui.mjs

@@ -0,0 +1,68 @@
+import {pageConnection} from './connection.mjs';
+import {withPageLock} from './page-lock.mjs';
+import {validateBirthDate} from './date-of-birth.mjs';
+
+/** UI verification plus correction of DOB at an existing enrollment's entry date. */
+export function createDateOfBirthUi({page}){
+ const connection=pageConnection(page),base=connection.moduleBaseUrl;
+ const ready=()=>page.waitForFunction(()=>!document.body.innerText.includes('Processing...')&&!document.body.innerText.includes('Loading...'),null,{timeout:30000});
+ const control=id=>page.locator(`[id="${id}"]:visible`);
+ const navigate=async clientId=>{
+  if(!Number.isSafeInteger(clientId)||clientId<1||new URL(page.url()).origin+new URL(page.url()).pathname!==base+'index.html')throw Error('Client and configured application page required');
+  await ready();if(await page.locator('[role=dialog]:visible').count())throw Error('Close dialogs before DOB operation');
+  if(/Client - \(\d+\)/.test(await page.locator('body').innerText())){
+   await page.getByRole('tab',{name:'Client Information',exact:true}).click();await page.getByRole('tab',{name:'Summary',exact:true}).click();await ready();
+   await page.getByRole('button',{name:'Exit',exact:true}).click();await page.waitForURL(u=>u.hash==='#clientPointClientMain');await ready();
+  }
+  await page.goto(base+'index.html#loadClient;clientId='+clientId);
+  await page.waitForFunction(clientId=>document.body.innerText.includes(`Client - (${clientId})`)&&!document.body.innerText.includes('Processing...')&&!document.body.innerText.includes('Loading...'),clientId,{timeout:30000});
+  await page.getByRole('tab',{name:'Summary',exact:true}).click();await ready();
+ };
+ const validateRestDate=async dateOfBirth=>{
+  validateBirthDate(dateOfBirth);
+  const rendered=await page.evaluate(value=>{const d=new Date(value+'T07:00:00Z');return [d.getFullYear(),String(d.getMonth()+1).padStart(2,'0'),String(d.getDate()).padStart(2,'0')].join('-');},dateOfBirth);
+  if(rendered!==dateOfBirth)throw Error('Browser timezone cannot display the REST DOB encoding on the intended date');
+ };
+ const read=clientId=>withPageLock(page,async()=>{
+  await navigate(clientId);
+  const text=await page.getByText('Date of Birth',{exact:true}).evaluate(e=>e.closest('td').nextElementSibling.innerText.trim());
+  if(!text)return null;
+  const m=/^(\d{2})\/(\d{2})\/(\d{4})(?: \(Age \d+\))?$/.exec(text);
+  if(!m)throw Error('Unexpected Summary DOB format');return validateBirthDate(`${m[3]}-${m[1]}-${m[2]}`);
+ });
+ const correctAtEntry=input=>withPageLock(page,async()=>{
+  const {clientId,entry,dateOfBirth,effectiveDate,expectedDateOfBirth,beforeSave}=input;
+  validateBirthDate(dateOfBirth);
+  if(!entry||!Number.isSafeInteger(entry.enrollmentId)||entry.enrollmentId<1||typeof entry.assessmentName!=='string'||!entry.assessmentName.trim()||typeof beforeSave!=='function')throw Error('DOB entry context and journal callback required');
+  await navigate(clientId);await page.getByRole('tab',{name:'Entry / Exit',exact:true}).click();await ready();
+  await control(`ClientEntryExitTab.editEntry-imageLink_${entry.enrollmentId}`).click();
+  await control('EntryDataPopup.cancel-button').waitFor();await ready();
+  const heading=await page.locator('[role=dialog]:visible').innerText();
+  if(!heading.includes(`Edit Project Start Data - (${clientId})`))throw Error('Entry client mismatch');
+  const parts={};for(const part of ['Month','Day','Year','Hour','Minute','Second','AM/PM'])parts[part]=await page.getByLabel('Project Start Date '+part,{exact:true}).inputValue();
+  const sameInstant=await page.evaluate(({parts,effectiveDate})=>{
+   const date=new Date(effectiveDate),hour=date.getHours();
+   return Number(parts.Year)===date.getFullYear()&&Number(parts.Month)===date.getMonth()+1&&Number(parts.Day)===date.getDate()&&Number(parts.Hour)===(hour%12||12)&&Number(parts.Minute)===date.getMinutes()&&Number(parts.Second)===date.getSeconds()&&parts['AM/PM']===(hour<12?'AM':'PM');
+  },{parts,effectiveDate});
+  if(!sameInstant){await control('EntryDataPopup.cancel-button').click();throw Error('DOB correction requires the exact existing entry effective date');}
+  await control('EntryDataPopup.saveAndContinue-button').click();await control('EntryDataPopup.cancel-button').waitFor({state:'hidden'});await ready();
+  const dialog=page.getByRole('dialog',{name:'Entry/Exit Data',exact:true});
+  await dialog.getByRole('button',{name:entry.assessmentName,exact:true}).click();
+  const month=page.getByLabel('Date of Birth Month',{exact:true}),day=page.getByLabel('Date of Birth Day',{exact:true}),year=page.getByLabel('Date of Birth Year',{exact:true});
+  await month.waitFor();await ready();
+  if(!new RegExp(`check_circle\\s*\\(${clientId}\\)`).test(await dialog.innerText()))throw Error('Selected assessment client mismatch');
+  const current=validateBirthDate(`${await year.inputValue()}-${(await month.inputValue()).padStart(2,'0')}-${(await day.inputValue()).padStart(2,'0')}`);
+  if(current!==expectedDateOfBirth)throw Error('DOB changed before UI correction');
+  const controls=()=>dialog.locator('input,select,textarea').evaluateAll(es=>es.filter(e=>e.getClientRects().length&&!/^Date of Birth (Month|Day|Year)$/.test(e.getAttribute('aria-label')||'')).map(e=>({id:e.id,label:e.getAttribute('aria-label'),value:e.value,checked:e.checked,selected:e.tagName==='SELECT'?[...e.selectedOptions].map(o=>o.value):null})));
+  const before=JSON.stringify(await controls());
+  // Blur each component and wait for GWT's dependent refresh before editing the next.
+  for(const [field,value] of [[day,'01'],[year,dateOfBirth.slice(0,4)],[month,dateOfBirth.slice(5,7)],[day,dateOfBirth.slice(8,10)]]){await field.fill(value);await field.press('Tab');await ready();}
+  const edited=`${await year.inputValue()}-${(await month.inputValue()).padStart(2,'0')}-${(await day.inputValue()).padStart(2,'0')}`;
+  if(edited!==dateOfBirth)throw Error('DOB widget did not retain the requested calendar date');
+  if(JSON.stringify(await controls())!==before)throw Error('Other assessment controls changed');
+  await beforeSave();await dialog.getByRole('button',{name:'Save',exact:true}).click();await ready();
+  if(await page.getByRole('dialog',{name:'Validation Warning',exact:true}).isVisible())throw Error('Assessment validation blocked DOB save; complete required answers before reconciling');
+  await control('EntryExitAssessment.btnExit-button').click();await dialog.waitFor({state:'hidden'});await ready();
+ });
+ return {connection,read,correctAtEntry,validateRestDate};
+}

package/browser/date-of-birth.d.mts

@@ -0,0 +1,28 @@
+import type {Page} from 'playwright-core';
+import type {WellSkyClient} from '../dist/esm/index.js';
+import type {UiMutationStore} from './index.mjs';
+export interface BirthDateEntry {enrollmentId:number;assessmentName:string;}
+export interface BirthDateUpdate {
+ clientId:number;key:string;assessmentCode:string;
+ /** Strict calendar date, not a timestamp. */dateOfBirth:string;
+ /** Explicit instant. Never moved to avoid an existing-answer conflict. */effectiveDate:string;
+ /** Required to correct a DOB at the same effective timestamp as this enrollment's entry. */entry?:BirthDateEntry;
+}
+export interface DateOfBirthUi {
+ readonly connection?:import("./connection.mjs").UiConnection;
+ validateRestDate(dateOfBirth:string):Promise<void>;
+ read(clientId:number):Promise<string|null>;
+ correctAtEntry(input:BirthDateUpdate&{expectedDateOfBirth:string|null;beforeSave:()=>Promise<void>}):Promise<void>;
+}
+export interface BirthDateSnapshot {clientId:number;dateOfBirth:string|null;effectiveDate:string|null;}
+export interface DateOfBirth {
+ read(input:{clientId:number;assessmentCode:string}):Promise<BirthDateSnapshot>;
+ /** Read-only preflight; allowEntryCorrection reserves no write and creates no enrollment. */
+ validate(input:{clientId:number;assessmentCode:string;dateOfBirth:string;effectiveDate:string;allowEntryCorrection?:boolean}):Promise<BirthDateSnapshot>;
+ /** allowLater permits the same calendar value at a newer effective timestamp. */
+ verify(input:{clientId:number;assessmentCode:string;dateOfBirth:string;effectiveDate:string;allowLater?:boolean}):Promise<BirthDateSnapshot&{dateOfBirth:string;effectiveDate:string}>;
+ update(input:BirthDateUpdate):Promise<{clientId:number;dateOfBirth:string;effectiveDate:string;method:'rest'|'ui';outcome:'verified'|'already-present'}>;
+}
+export function validateBirthDate(value:unknown):string;
+export function createDateOfBirth(options:{api:WellSkyClient;ui:DateOfBirthUi;store:UiMutationStore}):DateOfBirth;
+export function createDateOfBirthUi(options:{page:Page}):DateOfBirthUi;

package/browser/date-of-birth.mjs

@@ -0,0 +1,112 @@
+import {apiScope} from './connection.mjs';
+import {createHash} from 'node:crypto';
+import {toItems} from '../dist/esm/index.js';
+
+const coreKeys=['firstName','middleName','lastName','suffix','search_alias','socSecNo','nameDataQuality','ssnDataQuality','veteranStatus'];
+const protectedKeys=[...coreKeys,'svpprofdobtype','svpprofgender','hud_raceethnicity','hud_raceethnicitydetail','phone','email'];
+const hash=value=>createHash('sha256').update(JSON.stringify(value,(_,v)=>v&&typeof v==='object'&&!Array.isArray(v)?Object.fromEntries(Object.entries(v).sort(([a],[b])=>a.localeCompare(b))):v)).digest('hex');
+const pick=(value,keys)=>Object.fromEntries(keys.map(k=>[k,value[k]??'']));
+const fail=message=>{throw Error(`Date of birth: ${message}`);};
+export function validateBirthDate(value){
+ if(typeof value!=='string'||!/^\d{4}-\d{2}-\d{2}$/.test(value)||value<'0001-01-01'||!Number.isFinite(Date.parse(value+'T00:00:00Z'))||new Date(value+'T00:00:00Z').toISOString().slice(0,10)!==value)fail('valid YYYY-MM-DD calendar date required');
+ return value;
+}
+const instant=value=>{
+ if(typeof value!=='string'||!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.000)?(?:Z|[+-]\d{2}:\d{2})$/.test(value)||!Number.isFinite(Date.parse(value))||new Date(value.slice(0,19)+'Z').toISOString().slice(0,19)!==value.slice(0,19))fail('timezone-qualified whole-second effective date required');
+ return new Date(value).toISOString();
+};
+const storedDate=value=>value==null||value===''?null:validateBirthDate(value.replaceAll('/','-'));
+const answerDate=value=>{
+ if(typeof value!=='string'||!/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}-07$/.test(value))fail('unexpected DOB answer format or timezone');
+ return validateBirthDate(value.slice(0,10));
+};
+const effective=value=>{if(typeof value!=='string'||!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$/.test(value))fail('unexpected answer effective date');return instant(value+'Z');};
+
+/** Calendar-date writer. New effective timestamps use REST;
+ * collisions use the existing entry assessment UI without moving the timestamp. */
+export function createDateOfBirth({api,ui,store}){
+ const tenantScope=apiScope(api, ui);
+ if(!ui?.read||!ui?.correctAtEntry||!ui?.validateRestDate||!store?.withLock||!store?.read||!store?.write)fail('REST API, DOB UI and durable store required');
+ const read=async input=>{
+  const rows=toItems(await api.clients.get({path:{clientId:input.clientId}}));
+  if(rows.length!==1||rows[0].clientId!==input.clientId||rows[0].isActive===false)fail('active client readback unavailable');
+  const client=rows[0],answers=toItems(await api.assessmentsMobile.getAnswers({path:{clientId:input.clientId,assessmentCode:input.assessmentCode}}));
+  const dob=answers.filter(q=>q.virt_field_name==='SVPPROFDOB');
+  if(dob.length!==1||dob[0].question_type!=='date')fail('assessment must expose one DOB date question');
+  const row=dob[0],dateOfBirth=storedDate(client.svpprofdob),hasValue=row.answer_value!==null&&row.answer_value!==undefined&&row.answer_value!=='',hasAnswer=row.date_effective!==null&&row.date_effective!==undefined&&row.date_effective!=='';
+  // WellSky's mobile projection omits the value for UI-created date answers.
+  // Require matching current client + fresh UI values; use the answer only for its effective date.
+  if(hasValue&&(!hasAnswer||answerDate(row.answer_value)!==dateOfBirth)||!hasAnswer&&dateOfBirth!==null)fail('client and assessment DOB disagree');
+  const uiDate=await ui.read(input.clientId);
+  if(uiDate!==dateOfBirth)fail('client and UI DOB disagree');
+  // Values and effective dates of every other exposed answer must survive the write.
+  const protectedAnswers=answers.filter(q=>q.virt_field_name!=='SVPPROFDOB').map(q=>({field:q.virt_field_name,value:q.answer_value??null,text:q.answer_value_text??null,effective:q.date_effective??null,rows:q.sub_assessment_answer_list??null})).sort((a,b)=>String(a.field).localeCompare(String(b.field)));
+  return {client,dateOfBirth,effectiveDate:hasAnswer?effective(row.date_effective):null,protectedHash:hash({client:pick(client,protectedKeys),answers:protectedAnswers})};
+ };
+ const update=async raw=>{
+  if(!raw||Object.keys(raw).some(k=>!['clientId','key','assessmentCode','dateOfBirth','effectiveDate','entry'].includes(k)))fail('unknown update field');
+  if(!Number.isSafeInteger(raw.clientId)||raw.clientId<1||typeof raw.key!=='string'||!raw.key.trim()||raw.key.length>200||typeof raw.assessmentCode!=='string'||!/^[A-Za-z0-9_]+$/.test(raw.assessmentCode))fail('client, stable key and assessment code required');
+  const input={...structuredClone(raw),dateOfBirth:validateBirthDate(raw.dateOfBirth),effectiveDate:instant(raw.effectiveDate)};
+  if(input.dateOfBirth>input.effectiveDate.slice(0,10))fail('birth date follows effective date');
+  if(input.entry&&(!Number.isSafeInteger(input.entry.enrollmentId)||input.entry.enrollmentId<1||typeof input.entry.assessmentName!=='string'||!input.entry.assessmentName.trim()||Object.keys(input.entry).some(k=>!['enrollmentId','assessmentName'].includes(k))))fail('entry enrollment and assessment name required');
+  const scope=JSON.stringify([tenantScope,'client-profile',input.clientId]),keyHash=hash('dob:'+input.key),intentHash=hash(input);
+  return store.withLock(scope,async()=>{
+   const records=await store.read(scope);if(!Array.isArray(records))fail('invalid journal');
+   let record=records.find(r=>r.keyHash===keyHash);
+   if(records.filter(r=>r.keyHash===keyHash).length>1||record&&record.intentHash!==intentHash)fail('key conflicts with earlier intent');
+   if(records.some(r=>r.keyHash!==keyHash&&r.stage!=='verified'))fail('another profile update is unresolved');
+   if(record&&(record.version!==1||record.operation!=='dob'||!['planned','attempted','verified'].includes(record.stage)))fail('invalid journal stage');
+   const wasVerified=record?.stage==='verified';
+   const persist=async stage=>{record={...record,version:1,operation:'dob',keyHash,intentHash,stage};const index=records.findIndex(r=>r.keyHash===keyHash);if(index<0)records.push(record);else records[index]=record;await store.write(scope,structuredClone(records));};
+   let current=await read(input);
+   const matches=()=>current.dateOfBirth===input.dateOfBirth&&current.effectiveDate===input.effectiveDate;
+   if(!record){
+    if(current.effectiveDate&&Date.parse(input.effectiveDate)<Date.parse(current.effectiveDate))fail('historical correction before latest DOB requires a separate history workflow');
+    const method=current.effectiveDate===input.effectiveDate?'ui':'rest';
+    if(!matches()&&method==='rest')await ui.validateRestDate(input.dateOfBirth);
+    if(!matches()&&method==='ui'&&!input.entry)fail('effective timestamp already exists; provide its entry assessment context for UI correction');
+    record={method,protectedHash:current.protectedHash,beforeHash:hash({dob:current.dateOfBirth,effective:current.effectiveDate})};await persist('planned');
+   }
+   if(current.protectedHash!==record.protectedHash)fail('unrequested profile or assessment data changed');
+   if(!matches()){
+    if(record.stage!=='planned')fail('write unresolved or later value changed; refusing replay');
+    if(hash({dob:current.dateOfBirth,effective:current.effectiveDate})!==record.beforeHash)fail('DOB changed before write');
+    if(record.method==='rest'){
+     await ui.validateRestDate(input.dateOfBirth);
+     // The training server converts UTC to fixed -07 for DOB values, in winter and summer.
+     // Keep this workaround scoped to this helper; never shift enrollment/effective dates.
+     await persist('attempted');
+     let error;try{await api.clients.update({path:{client_id:input.clientId},body:{...pick(current.client,coreKeys),svpprofdob:input.dateOfBirth+'T07:00:00Z',dateEffective:input.effectiveDate}});}catch(e){error=e;}
+     current=await read(input);
+     if(!matches()||current.protectedHash!==record.protectedHash)throw error??Error('Date of birth: REST verification failed; journal blocks replay');
+    }else{
+     await ui.correctAtEntry({...input,expectedDateOfBirth:current.dateOfBirth,beforeSave:()=>persist('attempted')});
+     current=await read(input);
+    }
+   }
+   if(!matches()||current.protectedHash!==record.protectedHash)fail('verification failed; journal blocks replay');
+   await persist('verified');return {clientId:input.clientId,dateOfBirth:current.dateOfBirth,effectiveDate:current.effectiveDate,method:record.method,outcome:wasVerified?'already-present':'verified'};
+  });
+ };
+ const inspect=async input=>{
+  if(!input||Object.keys(input).some(k=>!['clientId','assessmentCode'].includes(k))||!Number.isSafeInteger(input.clientId)||input.clientId<1||typeof input.assessmentCode!=='string'||!/^[A-Za-z0-9_]+$/.test(input.assessmentCode))fail('client and assessment code required');
+  const current=await read(input);return {clientId:input.clientId,dateOfBirth:current.dateOfBirth,effectiveDate:current.effectiveDate};
+ };
+ const validate=async input=>{
+  if(!input||Object.keys(input).some(k=>!['clientId','assessmentCode','dateOfBirth','effectiveDate','allowEntryCorrection'].includes(k))||input.allowEntryCorrection!==undefined&&typeof input.allowEntryCorrection!=='boolean')fail('invalid DOB validation input');
+  const wanted=validateBirthDate(input.dateOfBirth),at=instant(input.effectiveDate);
+  if(wanted>at.slice(0,10))fail('birth date follows effective date');
+  const current=await inspect({clientId:input.clientId,assessmentCode:input.assessmentCode});
+  if(current.effectiveDate&&Date.parse(current.effectiveDate)>Date.parse(at))fail('historical correction before latest DOB requires a separate history workflow');
+  if(current.effectiveDate===at){if(current.dateOfBirth!==wanted&&!input.allowEntryCorrection)fail('existing effective timestamp requires matching entry context');}
+  else await ui.validateRestDate(wanted);
+  return current;
+ };
+ const verify=async input=>{
+  if(!input||Object.keys(input).some(k=>!['clientId','assessmentCode','dateOfBirth','effectiveDate','allowLater'].includes(k))||input.allowLater!==undefined&&typeof input.allowLater!=='boolean')fail('invalid DOB verification input');
+  const wanted=validateBirthDate(input.dateOfBirth),at=instant(input.effectiveDate),current=await inspect({clientId:input.clientId,assessmentCode:input.assessmentCode});
+  if(current.dateOfBirth!==wanted||current.effectiveDate===null||(input.allowLater?Date.parse(current.effectiveDate)<Date.parse(at):current.effectiveDate!==at))fail('saved birth date changed or effective timestamp does not match');
+  return current;
+ };
+ return {update,read:inspect,validate,verify};
+}

package/browser/enrollment-workflow.d.mts

@@ -0,0 +1,174 @@
+import type {DateOfBirth} from './date-of-birth.mjs';
+import type {Answers, AssessmentDefinition, 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';
+import type {MemberEntryDatePort} from './member-entry-date.mjs';
+
+export interface EnrollmentSubassessmentPlan {
+  /** Stable source row key, retained across retries. */
+  key:string;
+  parentField:string;
+  answers:Answers;
+}
+export interface EnrollmentEndDatePlan {
+  parentField:string;
+  recordsetId:number;
+  /** Used to reject an end date before the stored row's start. */
+  startDateField:string;
+  endDateField:string;
+  endDate:string;
+}
+/** Every editable top-level field needs an answer, subassessment operation,
+ * explicit applicability reason, or a nonempty value to carry forward.
+ * The application determines applicability and required verification types. */
+export interface EnrollmentAssessmentPlan {
+  /** SVPPROFDOB requires {value:'YYYY-MM-DD'} and the birthDates dependency. Other date answers remain timestamps. */
+  answers?:Answers;
+  subassessments?:EnrollmentSubassessmentPlan[];
+  endDates?:EnrollmentEndDatePlan[];
+  notApplicable?:Record<string,string>;
+  carryForward?:string[];
+}
+export interface EnrollmentDiscoveryInput {
+  clientId:number;
+  providerId:number;
+  type:'HUD'|'VA';
+  /** Timezone-qualified timestamp with whole-second precision. */
+  entryDate:string;
+}
+export interface EnrollmentWorkflowDiscovery {
+  provider:Provider;
+  entry:{assessment:ProviderAssessmentItem;definition:AssessmentDefinition};
+  interim:{assessment:ProviderAssessmentItem;definition:AssessmentDefinition};
+}
+export interface EnrollmentWorkflowInput extends EnrollmentDiscoveryInput {
+  key:string;
+  assessment:EnrollmentAssessmentPlan;
+}
+export interface InterimWorkflowInput {
+  key:string;
+  /** Key of a verified entry in the same durable store and client scope. */
+  enrollmentKey:string;
+  clientId:number;
+  reviewDate:string;
+  assessment:EnrollmentAssessmentPlan;
+}
+export interface EnrollmentWorkflowResult {
+  key:string;
+  outcome:'verified'|'already-present';
+  clientId:number;
+  enrollmentId:number;
+  assessmentCode:string;
+  /** The subassessment plan's stable row keys map to stored recordset IDs. */
+  recordsetIds:Record<string,number>;
+  effectiveDate:string;
+  /** Fresh client API and UI verification of the member's calendar DOB. */
+  birthDate?:{clientId:number;dateOfBirth:string;effectiveDate:string};
+}
+export interface InterimWorkflowResult extends EnrollmentWorkflowResult {reviewId:number;}
+export interface ExitWorkflowResult extends EnrollmentWorkflowResult {projectExitDate:string;exitSubgroupId:string;}
+export interface ExitWorkflowDiscovery extends EnrollmentWorkflowDiscovery {exit:{assessment:ProviderAssessmentItem;definition:AssessmentDefinition};}
+export interface EnrollmentWorkflowStatus {
+  key:string;
+  kind:'entry'|'interim'|'exit';
+  stage:'pending'|'verified';
+  assessmentCode:string;
+  enrollmentId?:number;
+  reviewId?:number;
+  projectExitDate?:string;
+  exitSubgroupId?:string;
+  recordsetIds:Record<string,number>;
+  steps:{name:string;state:'attempted'|'verified'}[];
+}
+export interface EnrollmentWorkflow {
+  discover(input:EnrollmentDiscoveryInput):Promise<EnrollmentWorkflowDiscovery>;
+  discoverExit(input:EnrollmentDiscoveryInput):Promise<ExitWorkflowDiscovery>;
+  createEnrollment(input:EnrollmentWorkflowInput):Promise<EnrollmentWorkflowResult>;
+  createInterim(input:InterimWorkflowInput):Promise<InterimWorkflowResult>;
+  /** 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>;
+  addHouseholdMembers(input:HouseholdMemberAdditionInput):Promise<HouseholdEnrollmentResult>;
+  createHouseholdInterim(input:HouseholdInterimInput):Promise<HouseholdInterimResult>;
+  exitHousehold(input:HouseholdExitInput):Promise<HouseholdExitResult>;
+  /** Local progress only. Member keys can be passed to getStatus for individual steps. */
+  getHouseholdStatus(input:{headClientId:number;key:string}):Promise<HouseholdWorkflowStatus|null>;
+}
+export interface HouseholdMemberPlan {clientId:number;assessment:EnrollmentAssessmentPlan;}
+export interface HouseholdEnrollmentInput extends Omit<EnrollmentDiscoveryInput,'clientId'> {
+  key:string;
+  /** Existing household with all selected clients already joined at entry. */
+  householdId:number;
+  headClientId:number;
+  /** At least two unique clients, including the head. Order is immaterial. */
+  members:HouseholdMemberPlan[];
+}
+export interface HouseholdMemberAdditionInput {
+  key:string;
+  /** Stable key of the original verified household enrollment. */
+  enrollmentKey:string;
+  headClientId:number;
+  /** Later than the original entry. Applies to the selected new clients only. */
+  entryDate:string;
+  /** At least one new client in the existing household, excluding the head. */
+  members:HouseholdMemberPlan[];
+}
+export interface HouseholdInterimInput {
+  key:string;
+  enrollmentKey:string;
+  headClientId:number;
+  reviewDate:string;
+  /** Nonempty selected subset of the enrolled cohort, including a singleton. The head may be excluded. */
+  members:HouseholdMemberPlan[];
+}
+export interface HouseholdExitInput extends HouseholdExitDetailInput {
+  key:string;
+  enrollmentKey:string;
+  headClientId:number;
+  exitDate:string;
+  /** Exact available labels from exitUi.listOptions. Shared only by selected members. */
+  destination:string;
+  reasonForLeaving:string;
+  /** Nonempty selected subset of the enrolled cohort, including a singleton. The head may be excluded.
+   * Assessment answers remain per person; unselected enrollments and exits are preserved. */
+  members:HouseholdMemberPlan[];
+}
+export interface HouseholdEnrollmentResult {
+  key:string;
+  outcome:'verified'|'already-present';
+  householdId:number;
+  headClientId:number;
+  members:EnrollmentWorkflowResult[];
+}
+export interface HouseholdInterimResult extends Omit<HouseholdEnrollmentResult,'members'> {members:InterimWorkflowResult[];}
+export interface HouseholdExitResult extends Omit<HouseholdEnrollmentResult,'members'> {members:ExitWorkflowResult[];}
+export interface HouseholdWorkflowStatus {
+  key:string;
+  kind:'entry'|'addition'|'interim'|'exit';
+  stage:'pending'|'verified';
+  householdId:number;
+  headClientId:number;
+  members:Array<{clientId:number;key:string}&Partial<Omit<InterimWorkflowResult&ExitWorkflowResult,'clientId'|'key'>>>;
+}
+export interface EnrollmentWorkflowOptions {
+  api:Pick<WellSkyClient,'tenant'|'clients'|'providers'|'enrollments'|'assessments'|'assessmentsMobile'|'subassessments'>&Partial<Pick<WellSkyClient,'households'>>;
+  discovery:Pick<ProgramDiscovery,'getProviderAssessments'>;
+  helpers:Pick<GwtEnrollmentHelpers,'createInterimUpdate'>&Partial<Pick<GwtEnrollmentHelpers,'addHouseholdMembers'>>;
+  store:UiMutationStore;
+  /** Required for SVPPROFDOB answers or carry-forward. Share this workflow's durable store. */
+  birthDates?:DateOfBirth;
+  /** Required, along with api.households and helpers.addHouseholdMembers, for household operations. */
+  enrollmentSession?:EnrollmentReader;
+  /** Required for exitHousehold; the workflow owns its durable write journal. */
+  exitUi?:HouseholdExitUi;
+  /** Required to set the later entry date for newly attached household members. */
+  memberEntryDatePort?:MemberEntryDatePort;
+}
+export class EnrollmentWorkflowError extends Error {
+  readonly reason:string;
+  constructor(reason: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. */
+export function createEnrollmentWorkflow(options:EnrollmentWorkflowOptions):EnrollmentWorkflow;