@choiceapps/communityservices-sdk 0.1.0

package/browser/case-plans.d.mts

@@ -0,0 +1,20 @@
+import type {Page} from 'playwright-core';
+import type {WellSkyClient} from '../dist/esm/index.js';
+import type {UiMutationStore} from './index.mjs';
+export interface CasePlanUi {
+ readonly connection?:import("./connection.mjs").UiConnection;confirmEmpty(input:{kind:'note'|'goal';clientId:number}):Promise<boolean>;}
+export interface NoteValues {note_date:string;note:string;}
+export interface GoalValues {providerId:number;dateGoalsSet:string;classification:string;type:string;overallStatus:string;goalDescription:string;targetDate?:string|null;outcome?:string;outcomeDate?:string|null;projectFollowupDate?:string|null;followupMade?:boolean;followupUser?:string;percentComplete?:string;caseManager?:string;}
+export interface ActionValues {providerId:number;dateSet:string;actionStep:string;status:string;targetDate?:string|null;outcome?:string;outcomeDate?:string|null;followupOutcome?:string;}
+export interface CasePlanResult {key:string;recordId:number;kind:'note'|'goal'|'action';outcome:'verified'|'already-present';values:Record<string,string|number|boolean|null>;}
+export interface RecordInput<T> {key:string;clientId:number;values:T;}
+export interface CasePlans {
+ createClientNote(input:RecordInput<NoteValues>):Promise<CasePlanResult>;
+ updateClientNote(input:RecordInput<Partial<NoteValues>>&{recordId:number}):Promise<CasePlanResult>;
+ createGoal(input:RecordInput<GoalValues>):Promise<CasePlanResult>;
+ updateGoal(input:RecordInput<Partial<GoalValues>>&{recordId:number}):Promise<CasePlanResult>;
+ createActionStep(input:RecordInput<ActionValues>&{goalId:number}):Promise<CasePlanResult>;
+ updateActionStep(input:RecordInput<Partial<ActionValues>>&{goalId:number;recordId:number}):Promise<CasePlanResult>;
+}
+export function createCasePlans(options:{api:WellSkyClient;ui:CasePlanUi;store:UiMutationStore}):CasePlans;
+export function createCasePlanUi(options:{page:Page}):CasePlanUi;

package/browser/case-plans.mjs

@@ -0,0 +1,89 @@
+import {apiScope} from './connection.mjs';
+import {createHash} from 'node:crypto';
+import {toItems} from '../dist/esm/index.js';
+const digest=v=>createHash('sha256').update(JSON.stringify(v,(_,x)=>x&&typeof x==='object'&&!Array.isArray(x)?Object.fromEntries(Object.entries(x).sort(([a],[b])=>a.localeCompare(b))):x)).digest('hex');
+const id=n=>{if(!Number.isSafeInteger(n)||n<1)throw Error('Positive record ID required');return n;};
+const configs={
+ note:{id:'client_note_id',client:'client_id',active:'active',fields:['note_date','note'],required:['note_date','note'],dates:['note_date']},
+ goal:{id:'goalId',client:'clientId',active:'isActive',fields:['providerId','dateGoalsSet','classification','type','targetDate','overallStatus','outcome','outcomeDate','projectFollowupDate','followupMade','followupUser','percentComplete','caseManager','goalDescription'],required:['providerId','dateGoalsSet','classification','type','overallStatus','goalDescription'],dates:['dateGoalsSet','targetDate','outcomeDate','projectFollowupDate']},
+ action:{id:'goalActionStepId',client:'clientId',active:'isActive',fields:['providerId','dateSet','actionStep','targetDate','status','outcome','outcomeDate','followupOutcome'],required:['providerId','dateSet','actionStep','status'],dates:['dateSet','targetDate','outcomeDate']},
+};
+const instant=s=>{if(typeof s!=='string'||!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.000)?(?:Z|[+-]\d{2}:\d{2})$/.test(s)||!Number.isFinite(Date.parse(s))||new Date(s.slice(0,19)+'Z').toISOString().slice(0,19)!==s.slice(0,19))throw Error('Valid timezone-qualified record date required');return new Date(s).toISOString();};
+const serverDate=s=>instant(/(?:Z|[+-]\d\d:\d\d)$/.test(s)?s:s+'Z');
+const normalize=(kind,row)=>{
+ const c=configs[kind],values={};
+ for(const k of c.fields){const value=row[kind==='action'&&k==='actionStep'?'actionstep':k];values[k]=c.dates.includes(k)?value?serverDate(value):null:k==='followupMade'?value??false:k==='providerId'?value:value??'';}
+ return values;
+};
+const matches=(values,expected)=>Object.entries(expected).every(([k,v])=>values[k]===v);
+/** Journaled single-client notes, goals and action steps. Each write is read back field by field.
+ * Goal response household arrays are intentionally ignored. This is not a household mutation. */
+export function createCasePlans({api,store,ui}){
+ const tenantScope=apiScope(api, ui);
+ if(!store?.withLock||!ui?.confirmEmpty)throw Error('REST API, durable store and case-plan UI reader required');
+ const goal=async(clientId,goalId)=>{const rows=toItems(await api.goals.get({path:{goalId}}));if(rows.length!==1||rows[0].goalId!==goalId||rows[0].clientId!==clientId||rows[0].isActive!==true)throw Error('Goal ownership or active state mismatch');return rows[0];};
+ const list=async(kind,clientId,goalId,initial)=>{
+  if(kind==='action'){const g=await goal(clientId,goalId);if(!Array.isArray(g.actionSteps))throw Error('Action steps unavailable');return g.actionSteps;}
+  const rows=[];let count;
+  for(let startPage=1;startPage<=100;startPage++){
+   let r;const query={perPage:100,startPage,total_count:true};
+   try{r=kind==='note'?await api.clientNotes.list({query:{...query,query:`client_id eq ${clientId}`}}):await api.goals.listForClient({path:{clientId},query});}
+   catch(e){if(initial&&startPage===1&&e.status===404&&await ui.confirmEmpty({kind,clientId}))return [];throw e;}
+   if(!Number.isSafeInteger(r?.count)||r.count<0||!Array.isArray(r.values)||count!==undefined&&count!==r.count)throw Error('Record list count unavailable or changed');count=r.count;rows.push(...r.values);
+   if(rows.length===count)return rows;if(!r.values.length||rows.length>count)throw Error('Incomplete record list');
+  }throw Error('Record list exceeds safety limit');
+ };
+ const run=async(kind,mode,input)=>{
+  const c=configs[kind];if(!input||Object.keys(input).some(k=>!['key','clientId','goalId','recordId','values'].includes(k))||typeof input.key!=='string'||!input.key.trim()||input.key.length>500)throw Error('Stable case-plan source key and supported fields required');
+  const clientId=id(input.clientId);if(kind==='action')id(input.goalId);else if(input.goalId!==undefined)throw Error('goalId only belongs to action steps');
+  if(mode==='update')id(input.recordId);else if(input.recordId!==undefined)throw Error('Create cannot specify recordId');
+  const values=structuredClone(input.values);if(!values||Array.isArray(values)||!Object.keys(values).length||Object.keys(values).some(k=>!c.fields.includes(k)))throw Error('Unsupported case-plan values');
+  if(c.required.some(k=>(mode==='create'||k in values)&&(values[k]===undefined||values[k]===null||values[k]==='')))throw Error('Required case-plan values missing');
+  for(const [k,v]of Object.entries(values)){
+   if(c.dates.includes(k))values[k]=v===null?null:instant(v);
+   else if(k==='providerId')id(v);else if(k==='followupMade'){if(typeof v!=='boolean')throw Error('followupMade must be boolean');}
+   else if(typeof v!=='string'||v.length>100000||v.includes('\0'))throw Error('Invalid case-plan text');
+  }
+  if(kind==='goal'&&'percentComplete' in values&&values.percentComplete!==''&&!/^[1-9]0%$/.test(values.percentComplete))throw Error('Percent complete must be a UI label from 10% through 90%, or empty');
+  const intent={kind,mode,clientId,goalId:input.goalId,recordId:input.recordId,values};const keyHash=digest(input.key),intentHash=digest(intent),scope=JSON.stringify([tenantScope,'case-plans',clientId]);
+  return store.withLock(scope,async()=>{
+   const entries=await store.read(scope);if(!Array.isArray(entries)||entries.some(e=>e.version!==1||!['planned','attempted','verified'].includes(e.stage)))throw Error('Invalid case-plan journal');
+   let e=entries.find(v=>v.keyHash===keyHash);if(entries.filter(v=>v.keyHash===keyHash).length>1||e&&e.intentHash!==intentHash)throw Error('Case-plan key conflicts with earlier intent');
+   if(entries.some(v=>v.keyHash!==keyHash&&v.stage!=='verified'))throw Error('Another case-plan write is unresolved');
+   const persist=async stage=>{e={...e,version:1,keyHash,intentHash,kind,goalId:input.goalId,stage};const i=entries.findIndex(v=>v.keyHash===keyHash);if(i<0)entries.push(e);else entries[i]=e;await store.write(scope,structuredClone(entries));};
+   const readAll=async initial=>{
+    const rows=await list(kind,clientId,input.goalId,initial),ids=new Set();
+    for(const r of rows){id(r[c.id]);if(ids.has(r[c.id])||r[c.client]!==clientId||kind==='action'&&r.goalId!==input.goalId)throw Error('Record list ownership or duplicate ID mismatch');ids.add(r[c.id]);}
+    return rows.filter(r=>r[c.active]===true);
+   };
+   let rows=await readAll(!e),current;
+   if(e?.recordId||mode==='update')current=rows.find(r=>r[c.id]===(e?.recordId??input.recordId));
+   else {const found=rows.filter(r=>matches(normalize(kind,r),values));if(found.length>1)throw Error('Duplicate matching records require review');current=found[0];}
+   if(e?.stage==='verified'){
+    const latest=entries.filter(v=>v.kind===kind&&v.recordId===e.recordId&&v.stage==='verified').at(-1);
+    if(!current||!matches(normalize(kind,current),latest.target))throw Error('Record changed since verification; refusing replay');return {key:input.key,recordId:e.recordId,kind,outcome:'already-present',values:normalize(kind,current)};
+   }
+   if(!e){
+    if(mode==='update'&&!current)throw Error('Active record required for update');
+    const baseline=current?normalize(kind,current):null;e={baseline,recordId:current?.[c.id],target:mode==='update'?{...baseline,...values}:values};await persist('planned');
+   }
+   if(!current||!matches(normalize(kind,current),e.target)){
+    if(e.stage!=='planned')throw Error('Record write unresolved; refusing another mutation');
+    if(mode==='update'&&(!current||!matches(normalize(kind,current),e.baseline)))throw Error('Record changed before update');
+    const body=mode==='update'?e.target:values;
+    const clients=toItems(await api.clients.get({path:{clientId}}));if(clients.length!==1||clients[0].clientId!==clientId||clients[0].isActive!==true)throw Error('Active client required');
+    await persist('attempted');let failure;
+    try{
+     if(kind==='note'){if(mode==='create')await api.clientNotes.create({body:{client_id:clientId,...body}});else await api.clientNotes.update({query:{clientNoteId:input.recordId},body});}
+     if(kind==='goal'){if(mode==='create')await api.goals.create({body:{clientId,...body}});else await api.goals.update({path:{goalId:input.recordId},body:{clientId,...body}});}
+     if(kind==='action'){if(mode==='create')await api.goals.createAction({path:{goalId:input.goalId},body:{clientId,...body}});else await api.goals.updateAction({path:{goalActionStepId:input.recordId},body});}
+    }catch(error){failure=error;}
+    rows=await readAll(false);
+    const found=rows.filter(r=>(mode==='create'||r[c.id]===input.recordId)&&matches(normalize(kind,r),e.target));
+    if(found.length!==1)throw failure??Error('Record not uniquely verified; journal blocks replay');current=found[0];
+   }
+   e.recordId=current[c.id];e.target=normalize(kind,current);await persist('verified');return {key:input.key,recordId:e.recordId,kind,outcome:'verified',values:e.target};
+  });
+ };
+ return {createClientNote:i=>run('note','create',i),updateClientNote:i=>run('note','update',i),createGoal:i=>run('goal','create',i),updateGoal:i=>run('goal','update',i),createActionStep:i=>run('action','create',i),updateActionStep:i=>run('action','update',i)};
+}

package/browser/client-creation.d.mts

@@ -0,0 +1,16 @@
+import type {WellSkyClient} from '../dist/esm/index.js';
+import type {UiMutationStore} from './index.mjs';
+export type VeteranStatus='Yes (HUD)'|'No (HUD)'|"Client doesn't know (HUD)"|'Client prefers not to answer (HUD)'|'Data not collected (HUD)';
+export interface ClientCreationInput {
+ sourceId:string;
+ body:{firstName:string;lastName:string;dateEffective:string;middleName?:string;suffix?:string;search_alias?:string;nameDataQuality?:string;socSecNo?:string;ssnDataQuality?:string;veteranStatus?:VeteranStatus};
+ /** Explicitly create a distinct person despite flagged candidates. Never merges. */allowDistinctClient?:boolean;
+}
+export interface ClientCreationResult {sourceId:string;clientId:number;outcome:'verified'|'already-present';}
+export interface ClientCreator {
+ create(input:ClientCreationInput):Promise<ClientCreationResult>;
+ /** Operator must verify this ID belongs to the attempted create before calling. No server write. */
+ resolveCreated(input:ClientCreationInput&{clientId:number}):Promise<ClientCreationResult>;
+ lookup(sourceId:string):Promise<{clientId:number|null;stage:'attempted'|'created'|'verified'}|null>;
+}
+export function createClientCreator(options:{api:WellSkyClient;store:UiMutationStore}):ClientCreator;

package/browser/client-creation.mjs

@@ -0,0 +1,60 @@
+import {apiScope} from './connection.mjs';
+import {createHash} from 'node:crypto';
+import {toItems} from '../dist/esm/index.js';
+const digest=v=>createHash('sha256').update(JSON.stringify(v,(_,x)=>x&&typeof x==='object'&&!Array.isArray(x)?Object.fromEntries(Object.entries(x).sort(([a],[b])=>a.localeCompare(b))):x)).digest('hex');
+const fields=['firstName','middleName','lastName','suffix','search_alias','nameDataQuality','socSecNo','ssnDataQuality','veteranStatus','dateEffective'];
+const veteranStatuses=['Yes (HUD)','No (HUD)',"Client doesn't know (HUD)",'Client prefers not to answer (HUD)','Data not collected (HUD)'];
+const id=n=>{if(!Number.isSafeInteger(n)||n<1)throw Error('Positive client ID required');return n;};
+const error=(code,message,details={})=>Object.assign(Error(message),{code,...details});
+function prepareClientCreation(input){
+ if(!input||Object.keys(input).some(k=>!['sourceId','body','allowDistinctClient'].includes(k))||typeof input.sourceId!=='string'||!input.sourceId.trim()||input.sourceId.length>500)throw Error('Stable source ID required');
+ const body=structuredClone(input.body);if(!body||Object.keys(body).some(k=>!fields.includes(k))||!body.firstName?.trim()||!body.lastName?.trim())throw Error('Supported identity fields and names required; use DOB/profile helpers for assessment fields');
+ if('veteranStatus' in body&&!veteranStatuses.includes(body.veteranStatus))throw error('INVALID_VETERAN_STATUS',`Veteran status must be omitted or one of: ${veteranStatuses.join('; ')}`);
+ for(const [k,v]of Object.entries(body))if(typeof v!=='string'||/[\r\n\0]/.test(v)||v.length>255)throw Error('Invalid client identity field');
+ if(body.socSecNo!==undefined&&!/^\d{9}$/.test(body.socSecNo))throw Error('SSN must contain nine digits');
+ if(!/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.000)?(?:Z|[+-]\d\d:\d\d)$/.test(body.dateEffective??'')||!Number.isFinite(Date.parse(body.dateEffective))||new Date(body.dateEffective.slice(0,19)+'Z').toISOString().slice(0,19)!==body.dateEffective.slice(0,19))throw Error('Explicit valid creation effective date required');
+ body.dateEffective=new Date(body.dateEffective).toISOString();if(input.allowDistinctClient!==undefined&&typeof input.allowDistinctClient!=='boolean')throw Error('allowDistinctClient must be boolean');
+ return {body,sourceHash:digest(input.sourceId),intentHash:digest({body,allowDistinctClient:input.allowDistinctClient??false})};
+}
+/** Source IDs map to server-returned IDs. Names/SSNs only flag candidates and never select a client.
+ * A missing creation receipt requires explicit resolveCreated after operator verification. */
+export function createClientCreator({api,store}){
+ const tenantScope=apiScope(api);
+ if(!store?.withLock)throw Error('REST API and durable store required');
+ const scope=JSON.stringify([tenantScope,'client-creation']);
+ const read=async clientId=>{const rows=toItems(await api.clients.get({path:{clientId:id(clientId)}}));if(rows.length!==1||rows[0].clientId!==clientId||rows[0].isActive!==true)throw Error('Active client readback required');return rows[0];};
+ const verify=(client,body)=>{for(const [k,v]of Object.entries(body))if(k!=='dateEffective'&&client[k]!==v)throw error('CLIENT_CREATION_DRIFT','Client field does not match creation intent',{field:k});};
+ const candidates=async body=>{
+  const quote=s=>"'"+s.replaceAll("'","''")+"'";const filter=`(first_name eq ${quote(body.firstName)} and last_name eq ${quote(body.lastName)})`+(body.socSecNo?` or soc_sec_no eq ${quote(body.socSecNo)}`:'');
+  let result;try{result=await api.clients.list({query:{query:filter,total_count:true,perPage:100,startPage:1}});}catch(e){if(e.status===404)return [];throw e;}
+  if(!Number.isSafeInteger(result?.count)||!Array.isArray(result.values)||result.count!==result.values.length||result.count>100)throw Error('Candidate list incomplete; review before creating');
+  const ids=result.values.map(c=>id(c.clientId));if(new Set(ids).size!==ids.length)throw Error('Duplicate candidate IDs');return ids;
+ };
+ const run=async(input,resolution)=>{
+  const p=prepareClientCreation(input);
+  return store.withLock(scope,async()=>{
+   const entries=await store.read(scope);if(!Array.isArray(entries)||entries.some(e=>e.version!==1||!['attempted','created','verified'].includes(e.stage)))throw Error('Invalid client mapping journal');
+   let entry=entries.find(e=>e.sourceHash===p.sourceHash);if(entries.filter(e=>e.sourceHash===p.sourceHash).length>1||entry&&entry.intentHash!==p.intentHash)throw error('SOURCE_ID_CONFLICT','Source ID was already used with different client details');
+   const persist=async stage=>{entry={...entry,version:1,sourceHash:p.sourceHash,intentHash:p.intentHash,stage};const i=entries.findIndex(e=>e.sourceHash===p.sourceHash);if(i<0)entries.push(entry);else entries[i]=entry;await store.write(scope,structuredClone(entries));};
+   const previous=entry?.stage;
+   if(resolution!==undefined){
+    id(resolution);if(!entry||entry.stage!=='attempted'||entry.clientId)throw error('RESOLUTION_NOT_REQUIRED','Only a creation attempt without a receipt can be explicitly resolved');
+    if(entries.some(e=>e.clientId===resolution))throw error('CLIENT_ALREADY_MAPPED','Client ID already belongs to another source');
+    verify(await read(resolution),p.body);entry.clientId=resolution;await persist('created');
+   }
+   if(entry&&!entry.clientId)throw error('CLIENT_CREATE_UNCERTAIN','No client receipt was saved; verify the server result and explicitly resolveCreated. Do not resend creation',{stage:entry.stage});
+   if(!entry){
+    const found=await candidates(p.body);if(found.length&&!input.allowDistinctClient)throw error('POSSIBLE_DUPLICATE','Potential existing clients require review; no automatic matching or merging',{candidateClientIds:found});
+    await persist('attempted');let response;
+    try{response=await api.clients.create({body:p.body});}catch(cause){throw error('CLIENT_CREATE_UNCERTAIN','Creation receipt unavailable; explicit resolution required',{stage:'attempted',cause});}
+    const rows=toItems(response);if(rows.length!==1||!Number.isSafeInteger(rows[0].clientId)||rows[0].clientId<1)throw error('CLIENT_CREATE_UNCERTAIN','Creation returned no unambiguous client ID',{stage:'attempted'});
+    if(entries.some(e=>e.sourceHash!==p.sourceHash&&e.clientId===rows[0].clientId))throw error('CLIENT_ALREADY_MAPPED','Server returned an ID mapped to another source');
+    entry.clientId=rows[0].clientId;await persist('created');
+   }
+   const client=await read(entry.clientId);verify(client,p.body);await persist('verified');return {clientId:entry.clientId,sourceId:input.sourceId,outcome:previous==='verified'?'already-present':'verified'};
+  });
+ };
+ return {create:input=>run(input),resolveCreated:({clientId,...input})=>run(input,id(clientId)),lookup:async sourceId=>{
+  if(typeof sourceId!=='string'||!sourceId.trim())throw Error('Source ID required');return store.withLock(scope,async()=>{const entries=await store.read(scope),matches=entries.filter(e=>e.sourceHash===digest(sourceId));if(matches.length>1)throw Error('Duplicate source mappings');const e=matches[0];return e?{clientId:e.clientId??null,stage:e.stage}:null;});
+ }};
+}

package/browser/client-profile-ui.mjs

@@ -0,0 +1,59 @@
+import {pageConnection} from './connection.mjs';
+import {withPageLock} from './page-lock.mjs';
+
+const nameLabels={firstName:'Client First Name',middleName:'Client Middle Name',lastName:'Client Last Name',suffix:'Client Suffix'};
+const rowLabels={search_alias:'Alias',socSecNo:'Social Security',nameDataQuality:'Name Data Quality',ssnDataQuality:'SSN Data Quality',veteranStatus:'U.S. Military Veteran?',sex:'Sex'};
+const id=n=>{if(!Number.isSafeInteger(n)||n<=0)throw Error('Positive client ID required');};
+
+/** Fresh Client Record forms; Sex is saved by the UI's current GWT serializer. */
+export function createClientProfileUi({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 dialog=()=>page.getByRole('dialog',{name:'Client Record',exact:true});
+ const row=label=>dialog().getByText(label,{exact:true}).locator('xpath=ancestor::tr[.//input or .//select][1]');
+ const cancel=async()=>{if(await dialog().isVisible()){await dialog().getByRole('button',{name:'Cancel',exact:true}).click();await dialog().waitFor({state:'hidden'});}};
+ const open=async clientId=>{
+  id(clientId);if(new URL(page.url()).origin+new URL(page.url()).pathname!==base+'index.html')throw Error('Configured application page required');await ready();
+  if(await page.locator('[role=dialog]:visible').count())throw Error('Close dialogs before profile workflow');
+  // Leaving the client discards the cached model without reloading the authenticated app.
+  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:'Client Profile',exact:true}).click();await ready();
+  await page.getByTitle('Edit Client Record',{exact:true}).click();await dialog().waitFor();await ready();
+  await page.waitForFunction(()=>[...document.querySelectorAll('[role="dialog"] select')].length===4&&[...document.querySelectorAll('[role="dialog"] select')].every(e=>e.options.length>1),null,{timeout:30000});
+ };
+ const read=async()=>{
+  const values={},choices={};
+  for(const [key,label] of Object.entries(nameLabels))values[key]=await dialog().getByLabel(label,{exact:true}).inputValue();
+  for(const [key,label] of Object.entries(rowLabels)){
+   const field=row(label).locator(key==='search_alias'||key==='socSecNo'?'input':'select');
+   if(key==='socSecNo'){
+    const parts=await field.evaluateAll(es=>es.map(e=>({value:e.value,maxLength:e.maxLength})));
+    if(JSON.stringify(parts.map(p=>p.maxLength))!=='[3,2,4]')throw Error('SSN widget changed');values[key]=parts.map(p=>p.value).join('');
+   }else{
+    if(await field.count()!==1)throw Error('Profile field is ambiguous');const value=await field.inputValue();values[key]=value==='-Select-'?'':value;
+    if(key!=='search_alias')choices[key]=(await field.locator('option').allTextContents()).filter(v=>v!=='-Select-');
+   }
+  }
+  return {values,choices};
+ };
+ const inspect=clientId=>withPageLock(page,async()=>{await open(clientId);try{return await read();}finally{await cancel();}});
+ const updateSex=({clientId,sex,expected,beforeSave})=>withPageLock(page,async()=>{
+  await open(clientId);let attempted=false,verified=false;
+  try{
+   const current=await read();
+   if(!current.choices.sex.includes(sex))throw Error('Sex option unavailable');
+   for(const [key,value] of Object.entries(expected))if(key!=='sex'&&current.values[key]!==value)throw Error('Client Record changed before Sex save');
+   if(current.values.sex===sex)return current;
+   await row('Sex').locator('select').selectOption({label:sex});
+   await beforeSave();attempted=true;
+   await dialog().getByRole('button',{name:'Save',exact:true}).click();await dialog().waitFor({state:'hidden'});await ready();
+   await open(clientId);const result=await read();if(result.values.sex!==sex)throw Error('Sex did not persist');verified=true;return result;
+  }finally{if(!attempted||verified)await cancel();}
+ });
+ return {connection,inspect,updateSex};
+}

package/browser/client-profile.d.mts

@@ -0,0 +1,24 @@
+import type {Page} from 'playwright-core';
+import type {WellSkyClient} from '../dist/esm/index.js';
+import type {UiMutationStore} from './index.mjs';
+export type ClientSex='Male'|'Female'|"Client doesn't know"|'Client prefers not to answer'|'Data not collected';
+/** Fields in Client Profile > Client Record. DOB, legacy Gender and race are separate. */
+export interface ClientRecordValues {
+ firstName:string;middleName:string;lastName:string;suffix:string;search_alias:string;
+ socSecNo:string;nameDataQuality:string;ssnDataQuality:string;veteranStatus:string;sex:ClientSex|'';
+}
+export interface ClientProfileSnapshot {values:ClientRecordValues;choices:Record<'nameDataQuality'|'ssnDataQuality'|'veteranStatus'|'sex',string[]>;}
+export interface ClientProfileUi {
+ readonly connection?:import("./connection.mjs").UiConnection;
+ inspect(clientId:number):Promise<ClientProfileSnapshot>;
+ updateSex(input:{clientId:number;sex:ClientSex;expected:ClientRecordValues;beforeSave:()=>Promise<void>}):Promise<ClientProfileSnapshot>;
+}
+export type ClientProfileChanges=Partial<Omit<ClientRecordValues,'sex'>>&{sex?:ClientSex};
+export interface ClientProfileUpdate {clientId:number;key:string;changes:ClientProfileChanges;/** Required for REST changes; Sex uses current UI audit context. */dateEffective?:string;}
+export interface ClientProfile {
+ read(clientId:number):Promise<ClientProfileSnapshot&{clientId:number}>;
+ /** Same key/input/journal reconciles uncertain writes. Never automatically replays an update. */
+ update(input:ClientProfileUpdate):Promise<{clientId:number;key:string;outcome:'verified'|'already-present';values:ClientRecordValues}>;
+}
+export function createClientProfile(options:{api:WellSkyClient;ui:ClientProfileUi;store:UiMutationStore}):ClientProfile;
+export function createClientProfileUi(options:{page:Page}):ClientProfileUi;

package/browser/client-profile.mjs

@@ -0,0 +1,94 @@
+import {apiScope} from './connection.mjs';
+import {createHash} from 'node:crypto';
+import {toItems} from '../dist/esm/index.js';
+
+const restKeys=['firstName','middleName','lastName','suffix','search_alias','socSecNo','nameDataQuality','ssnDataQuality','veteranStatus'];
+const limits={firstName:30,middleName:30,lastName:30,suffix:10,search_alias:255};
+const protectedKeys=['svpprofdob','svpprofdobtype','svpprofgender','hud_raceethnicity','hud_raceethnicitydetail','phone','email'];
+const digest=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 same=(a,b)=>Object.entries(b).every(([k,v])=>a[k]===v);
+const id=n=>{if(!Number.isSafeInteger(n)||n<=0)throw Error('Positive client ID required');};
+const instant=s=>typeof s==='string'&&/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.000)?(?:Z|[+-]\d{2}:\d{2})$/.test(s)&&Number.isFinite(Date.parse(s))&&new Date(s.slice(0,19)+'Z').toISOString().slice(0,19)===s.slice(0,19);
+
+/** Client Record section only. REST preserves the complete record; Sex uses the UI.
+ * Durable hashes prevent replay of uncertain writes without retaining SSNs in the journal. */
+export function createClientProfile({api,ui,store}) {
+ const tenantScope=apiScope(api, ui);
+ if(!ui?.inspect||!ui?.updateSex||!store)throw Error('REST client, profile UI and durable store required');
+ const readRest=async clientId=>{
+  const rows=toItems(await api.clients.get({path:{clientId}}));
+  if(rows.length!==1||rows[0].clientId!==clientId||rows[0].isActive===false)throw Error('Active client readback unavailable');return rows[0];
+ };
+ const read=async clientId=>{
+  id(clientId);const snapshot=await ui.inspect(clientId),rest=await readRest(clientId);
+  if(!same(snapshot.values,pick(rest,restKeys)))throw Error('Client Record REST and UI disagree');
+  return {clientId,...snapshot};
+ };
+ const update=async input=>{
+  if(!input||Object.keys(input).some(k=>!['key','clientId','changes','dateEffective'].includes(k)))throw Error('Unknown profile update field');
+  const {key,clientId,dateEffective}=input;id(clientId);
+  if(typeof key!=='string'||!key.trim()||key.length>200)throw Error('Stable profile update key required');
+  const changes=structuredClone(input.changes);
+  if(!changes||typeof changes!=='object'||Array.isArray(changes)||!Object.keys(changes).length)throw Error('Profile changes required');
+  for(const [field,value] of Object.entries(changes)){
+   if(![...restKeys,'sex'].includes(field))throw Error(`Unsupported Client Record field: ${field}`);
+   if(typeof value!=='string'||/[\r\n\0]/.test(value))throw Error(`Invalid Client Record field: ${field}`);
+   if(limits[field]!==undefined&&value.length>limits[field])throw Error(`${field} exceeds ${limits[field]} characters`);
+   if(field==='socSecNo'&&value!==''&&!/^\d{9}$/.test(value))throw Error('SSN must be nine digits or an empty string');
+  }
+  const restChanges=Object.fromEntries(Object.entries(changes).filter(([k])=>k!=='sex'));
+  if(Object.keys(restChanges).length&&!instant(dateEffective))throw Error('Timezone-qualified dateEffective required for REST profile changes');
+  if(dateEffective!==undefined&&!instant(dateEffective))throw Error('Invalid dateEffective');
+  const keyHash=digest(key),intentHash=digest({clientId,changes,dateEffective});
+  return store.withLock(JSON.stringify([tenantScope,'client-profile',clientId]),async()=>{
+   const scope=JSON.stringify([tenantScope,'client-profile',clientId]),entries=await store.read(scope);
+   if(!Array.isArray(entries))throw Error('Invalid profile journal');
+   let entry=entries.find(e=>e.keyHash===keyHash);
+   if(entries.filter(e=>e.keyHash===keyHash).length>1||entry&&entry.intentHash!==intentHash)throw Error('Profile key conflicts with an earlier intent');
+   if(entries.some(e=>e.keyHash!==keyHash&&e.stage!=='verified'))throw Error('Another profile update is unresolved');
+   if(entry&&(!['planned','rest-attempted','rest-verified','ui-attempted','verified'].includes(entry.stage)||entry.version!==1))throw Error('Invalid profile journal stage');
+   const wasVerified=entry?.stage==='verified';
+   const persist=async stage=>{
+    entry={...entry,version:1,keyHash,intentHash,stage};
+    const i=entries.findIndex(e=>e.keyHash===keyHash);if(i<0)entries.push(entry);else entries[i]=entry;
+    await store.write(scope,structuredClone(entries));
+   };
+   let snapshot=await ui.inspect(clientId),rest=await readRest(clientId);
+   for(const [field,options] of Object.entries(snapshot.choices))if(field in changes&&!options.includes(changes[field]))throw Error(`Unavailable Client Record choice: ${field}`);
+   const core=pick(rest,restKeys);
+   if(!same(snapshot.values,core))throw Error('Client Record REST and UI disagree');
+   if(!entry){
+    const target={...core,...restChanges};
+    entry={restExpectedHash:digest(target),protectedHash:digest(pick(rest,protectedKeys)),uiExpectedHash:digest({...target,sex:changes.sex??snapshot.values.sex})};
+    await persist('planned');
+   }
+   const protectedMatch=()=>digest(pick(rest,protectedKeys))===entry.protectedHash;
+   if(!protectedMatch())throw Error('Unrequested profile fields changed; reconcile before continuing');
+   let restMatches=digest(pick(rest,restKeys))===entry.restExpectedHash;
+   if(!restMatches){
+    if(entry.stage!=='planned')throw Error('REST profile update unresolved or changed; refusing another write');
+    // WellSky clears SSN when omitted, even during a middle-name-only update.
+    const body={...pick(rest,restKeys),...restChanges,dateEffective};
+    if(digest(pick(body,restKeys))!==entry.restExpectedHash)throw Error('Client Record changed before REST update');
+    await persist('rest-attempted');
+    let error;try{await api.clients.update({path:{client_id:clientId},body});}catch(e){error=e;}
+    rest=await readRest(clientId);
+    restMatches=digest(pick(rest,restKeys))===entry.restExpectedHash;
+    if(!restMatches||!protectedMatch())throw error??Error('REST profile readback mismatch; journal blocks another write');
+    snapshot=await ui.inspect(clientId);
+    if(!same(snapshot.values,pick(rest,restKeys)))throw Error('Client Record UI did not reflect the REST update');
+   }
+   if(entry.stage==='planned'||entry.stage==='rest-attempted')await persist('rest-verified');
+   if(digest(snapshot.values)!==entry.uiExpectedHash){
+    if(entry.stage==='ui-attempted'||wasVerified)throw Error('Client Record UI save unresolved or changed; refusing another save');
+    if(changes.sex===undefined)throw Error('Unrequested Sex value changed');
+    snapshot=await ui.updateSex({clientId,sex:changes.sex,expected:snapshot.values,beforeSave:()=>persist('ui-attempted')});
+   }
+   rest=await readRest(clientId);
+   if(digest(snapshot.values)!==entry.uiExpectedHash||digest(pick(rest,restKeys))!==entry.restExpectedHash||!protectedMatch())throw Error('Profile verification mismatch; journal blocks replay');
+   await persist('verified');return {clientId,key,outcome:wasVerified?'already-present':'verified',values:snapshot.values};
+  });
+ };
+ return {read,update};
+}

package/browser/client-workflows.mjs

@@ -0,0 +1,135 @@
+import {pageConnection} from './connection.mjs';
+import {createHash} from 'node:crypto';
+import {decodeMappedResponse} from './gwt-mapped.mjs';
+import {withPageLock} from './page-lock.mjs';
+import {AttachmentConflictError} from './attachment-conflict.mjs';
+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;
+
+/** 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. */
+export function createClientWorkflows({page,store}) {
+ const connection=pageConnection(page),base=connection.moduleBaseUrl;
+    const guard=()=>{const u=new URL(page.url());if(u.origin+u.pathname!==base+'index.html')throw Error('Configured application page required');};
+  const ready=()=>page.waitForFunction(()=>!document.body.innerText.includes('Processing...')&&!document.body.innerText.includes('Loading...'),null,{timeout:30000});
+  let wire;
+  const openClient=async clientId=>{
+    id(clientId);guard();
+    if(await page.locator('[role=dialog]:visible').count())throw Error('Close dialogs before client workflow');
+    wire=undefined;
+    let pendingHeaders;
+    const listener=request=>{
+      if(request.url()===base+'service/MetaQueryService'&&request.postData()?.includes('|getMappedResults|')){
+        const policy=request.postData().split('|')[4];pendingHeaders=request.allHeaders().then(h=>{wire={policy,headers:Object.fromEntries(['content-type','x-gwt-module-base','x-gwt-permutation'].map(k=>[k,h[k]]))};});
+      }
+    };
+    page.on('request',listener);
+    try{
+      if(new URL(page.url()).hash!==`#loadClient;clientId=${clientId}`)await page.goto(base+`index.html#loadClient;clientId=${clientId}`);
+      await page.getByRole('tab',{name:'Summary',exact:true}).click();await ready();await page.getByRole('tab',{name:'Client Profile',exact:true}).click();await ready();await pendingHeaders;
+      if(!wire||!new RegExp(`Client - \\(${clientId}\\)`).test(await page.locator('body').innerText())||await page.locator('[id="formfield-password"]:visible').count())throw Error('Client identity unavailable');
+    }finally{page.off('request',listener);}
+  };
+  const mapped=async query=>{
+    guard();if(!wire||!/^SELECT /.test(query)||/[|\\\r\n]/.test(query))throw Error('Invalid mapped read');
+    const strings=[base,wire.policy,'com.bowmansystems.sp5.core.client.services.GenericService','getMappedResults','java.lang.String/2004016611','java.util.HashMap/1797211028','I','Z',query+' LIMIT 1001,0'];
+    const body=['7','0',strings.length,...strings,1,2,3,4,5,5,6,7,7,8,9,0,0,1001,1,''].join('|');
+    const r=await page.evaluate(async({url,headers,body})=>{const r=await fetch(url,{method:'POST',headers,body,credentials:'same-origin',redirect:'error',signal:AbortSignal.timeout(30000)});return {status:r.status,body:await r.text()};},{url:base+'service/MetaQueryService',headers:wire.headers,body});
+    if(r.status!==200)throw Error('GWT read failed');const result=decodeMappedResponse(r.body);if(result.total!==result.rows.length||result.total>1000)throw Error('Incomplete client list');return result.rows;
+  };
+  const list=clientId=>mapped(`SELECT l.fileAttachmentId AS attachmentId, l.entityKeyId AS entityId, l.entityType.entityType AS entityType, l.entityType.entityName AS entityName, l.fileAttachment.fileName AS name, l.fileAttachment.extension AS extension, l.fileAttachment.description AS description FROM SpFileAttachmentLink AS l WHERE l.active = TRUE AND l.fileAttachment.active = TRUE AND l.clientId = ${id(clientId)}`);
+  const download=async attachmentId=>{
+    guard();const result=await page.evaluate(async({url,limit})=>{
+      const r=await fetch(url,{credentials:'same-origin',redirect:'error',signal:AbortSignal.timeout(30000)});
+      if(!r.ok||!r.body||Number(r.headers.get('content-length'))>limit)throw Error('Attachment download failed');
+      const reader=r.body.getReader(),chunks=[];let size=0;
+      try{for(;;){const {done,value}=await reader.read();if(done)break;size+=value.length;if(size>limit)throw Error('Attachment too large');chunks.push(value);}}finally{await reader.cancel();}
+      const bytes=new Uint8Array(size);let offset=0;for(const c of chunks){bytes.set(c,offset);offset+=c.length;}
+      let binary='';for(let i=0;i<bytes.length;i+=8192)binary+=String.fromCharCode(...bytes.subarray(i,i+8192));return btoa(binary);
+    },{url:base+`downloadAttachment?attachmentId=${id(attachmentId)}`,limit:maxBytes});
+    return Buffer.from(result,'base64');
+  };
+  const listAttachments=clientId=>withPageLock(page,async()=>{await openClient(clientId);return list(clientId);});
+  const downloadAttachment=({clientId,attachmentId})=>withPageLock(page,async()=>{
+    await openClient(clientId);if(!(await list(clientId)).some(a=>a.attachmentId===id(attachmentId)))throw Error('Attachment not linked to this client');return download(attachmentId);
+  });
+  const uploadAttachment=({clientId,location,file,description=''})=>withPageLock(page,async()=>{
+    id(clientId);if(!file||typeof file.name!=='string'||!file.name||/[\\/\r\n\0]/.test(file.name)||!(file.buffer instanceof Uint8Array)||!file.buffer.length||file.buffer.length>maxBytes||typeof description!=='string')throw Error('Invalid attachment or size exceeds 10,000,000 bytes');
+    const bytes=Buffer.from(file.buffer),checksum=hash(bytes),entityType={profile:'SpClient','case-plans':'CasePlans',goal:'SpGoal'}[location?.kind];
+    if(!entityType)throw Error('Unsupported attachment location');const entityId=location.kind==='goal'?id(location.goalId):null;
+    const intent={clientId,entityType,entityId,name:file.name,description,checksum};
+    const scope=JSON.stringify([base,'attachment',clientId,entityType,entityId,file.name]);
+    return store.withLock(scope,async()=>{
+      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');
+      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');
+        if(previous?.attachmentId&&matches[0]?.attachmentId!==previous.attachmentId)throw new AttachmentConflictError('identity-changed','Saved attachment identity changed or missing prior attachment; reconcile before retrying');
+        if(matches.length&&(matches[0].description!==description||hash(await download(matches[0].attachmentId))!==checksum))throw new AttachmentConflictError('content-changed','Existing attachment differs');return matches[0];
+      };
+      let found=await matching();if(found){await store.write(scope,[{intent,state:'verified',attachmentId:found.attachmentId}]);return {outcome:previous?'reconciled':'already-present',attachment:found,checksum};}
+      if(previous)throw new AttachmentConflictError('unresolved','Unresolved or missing prior attachment; refusing another upload');
+      await store.write(scope,[{intent,state:'attempted'}]);
+      let response;
+      try{response=await page.evaluate(async({url,clientId,entityType,entityId,name,mimeType,description,data})=>{
+        const form=new FormData();const bytes=Uint8Array.from(atob(data),c=>c.charCodeAt(0));form.set('uploadFormElement',new Blob([bytes],{type:mimeType}),name);form.set('descriptionFormElement',description);form.set('clientId',String(clientId));form.set('entityType',entityType);if(entityId!==null)form.set('entityKey',String(entityId));
+        const r=await fetch(url,{method:'POST',body:form,credentials:'same-origin',redirect:'error',signal:AbortSignal.timeout(30000)});return {status:r.status,body:await r.text()};
+      },{url:base+'/uploadAttachment',clientId,entityType,entityId,name:file.name,mimeType:file.mimeType??'application/octet-stream',description,data:bytes.toString('base64')});}catch{/* Never replay an uncertain upload. */}
+      found=await matching();if(!found)throw Error('Attachment outcome uncertain; journal blocks repeat upload');
+      await store.write(scope,[{intent,state:'verified',attachmentId:found.attachmentId}]);
+      return {outcome:response?.status===200&&response.body===`${found.attachmentId}:SUCCESS`?'written':'reconciled',attachment:found,checksum};
+    });
+  });
+  const notes=(clientId,goalId)=>mapped(`SELECT n.goalCasenoteId AS noteId, n.goalId AS goalId, n.clientId AS clientId, n.noteDate AS noteDate, n.note AS note, n.providerId AS providerId FROM SpGoalCasenote AS n WHERE n.active = TRUE AND n.clientId = ${id(clientId)} AND n.goalId = ${id(goalId)}`);
+  const listCaseNotes=({clientId,goalId})=>withPageLock(page,async()=>{await openClient(clientId);return notes(clientId,goalId);});
+  const createCaseNote=async({key,clientId,goalId,providerId,noteDate,note})=>{
+    id(clientId);id(goalId);id(providerId);
+    if(typeof note!=='string'||!note.trim()||note.length>100000||typeof noteDate!=='string'||!/^\d{4}-\d{2}-\d{2}$/.test(noteDate)||new Date(noteDate+'T12:00:00Z').toISOString().slice(0,10)!==noteDate)throw Error('Note and valid calendar date required');
+    if(key!==undefined&&(typeof key!=='string'||!key.trim()||key.length>500))throw Error('Stable case note source key required');
+    const intent={clientId,goalId,providerId,noteDate,checksum:hash(note)};
+    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'});
+      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');
+      const match=async()=>{
+        const current=await notes(clientId,goalId);
+        // Date-only UI controls use the browser's local calendar. Do not apply the REST mobile offset.
+        const dates=await page.evaluate(values=>values.map(value=>{const d=new Date(value);return [d.getFullYear(),String(d.getMonth()+1).padStart(2,'0'),String(d.getDate()).padStart(2,'0')].join('-');}),current.map(n=>n.noteDate));
+        const matches=current.filter((n,i)=>n.note===note&&dates[i]===noteDate&&n.providerId===providerId);
+        if(matches.length>1)throw Error('Duplicate case notes require review');
+        if(previous?.noteId&&matches[0]?.noteId!==previous.noteId)throw Error('Saved case note identity changed; reconcile before retrying');return matches[0];
+      };
+      let found=await match();if(found){await store.write(scope,[{intent,state:'verified',noteId:found.noteId}]);return {outcome:previous?'reconciled':'already-present',note:found};}
+      if(previous)throw Error('Unresolved or missing prior case note; refusing another write');
+      await page.getByRole('tab',{name:'Case Plans',exact:true}).click();await ready();
+      await page.locator(`[id="ClientCasePlansTab.editGoal-imageLink_${goalId}"]`).click();
+      const goal=page.getByRole('dialog',{name:'Goal',exact:true});await goal.waitFor();await ready();
+      if(!(await goal.innerText()).includes(`Goal - (${clientId})`))throw Error('Goal client mismatch');
+      await goal.getByRole('button',{name:'Add Case Note',exact:true}).click();
+      const dialog=page.getByRole('dialog',{name:'Case Note',exact:true});await dialog.waitFor();await ready();
+      const providerRow=await dialog.getByText('Provider',{exact:true}).locator('xpath=ancestor::tr[.//*[@role="button"]][1]').innerText();
+      if(!(await dialog.innerText()).includes(`Case Note - (${clientId})`)||!providerRow.includes(`(${providerId})`))throw Error('Case note provider/client mismatch');
+      const checkboxes=dialog.locator('[id^="HouseholdsCheckboxTree.householdCheckbox."] input');
+      for(let i=0;i<await checkboxes.count();i++){const box=checkboxes.nth(i);const member=await box.evaluate(e=>Number(e.parentElement.id.match(/\.client-(\d+)$/)?.[1]));if(await box.isEnabled())await box.setChecked(member===clientId);if(await box.isChecked()&&member!==clientId)throw Error('Unexpected case note recipient');}
+      const fields=dialog.locator('input.gwt-TextBox');if(await fields.count()!==3)throw Error('Unexpected case note date controls');
+      const [year,month,day]=noteDate.split('-');for(const [i,value]of [month,day,year].entries())await fields.nth(i).fill(value);
+      await dialog.locator('textarea').fill(note);
+      await store.write(scope,[{intent,state:'attempted'}]);
+      let acknowledged=false;
+      try{await page.locator('[id="CaseNotePopup.saveCasenote"]').click();await dialog.waitFor({state:'hidden'});await ready();acknowledged=true;}catch{/* Reconcile, never press Save again. */}
+      found=await match();if(!found)throw Error('Case note outcome uncertain; journal blocks repeat');
+      await store.write(scope,[{intent,state:'verified',noteId:found.noteId}]);
+      if(await dialog.isVisible())await page.locator('[id="CaseNotePopup.cancel"]').click();
+      await goal.getByRole('button',{name:'Exit',exact:true}).click();await ready();return {outcome:acknowledged?'written':'reconciled',note:found};
+      });
+    });
+  };
+  return {connection,listAttachments,downloadAttachment,uploadAttachment,listCaseNotes,createCaseNote};
+}

package/browser/connection.d.mts

@@ -0,0 +1,4 @@
+export interface UiConnectionOptions {tenant:string;moduleBaseUrl?:string;}
+export interface UiConnection {readonly tenant:string;readonly moduleBaseUrl:string;readonly scope:string;}
+/** Resolve a tenant's application URL. Both live and training use this contract. */
+export function resolveUiConnection(options:UiConnectionOptions):UiConnection;

package/browser/connection.mjs

@@ -0,0 +1,41 @@
+const moduleSuffix = '/com.bowmansystems.sp5.core.ServicePoint/';
+const defaultOrigin = 'https://wscs.wellsky.com';
+const defaultApi = 'https://csclientapi.wellsky.com/client-api-prod';
+const pages = new WeakMap();
+
+export function validateTenant(tenant) {
+    if (typeof tenant !== 'string' || !/^[A-Za-z0-9_-]+$/.test(tenant)) throw new TypeError('A valid tenant is required');
+    return tenant;
+}
+
+/** The tenant selects the deployment; live and training use identical operations. */
+export function resolveUiConnection({tenant, moduleBaseUrl} = {}) {
+    validateTenant(tenant);
+    const url = new URL(moduleBaseUrl ?? `${defaultOrigin}/${tenant}${moduleSuffix}`);
+    if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash || url.pathname !== `/${tenant}${moduleSuffix}`) throw new TypeError('Module URL must match the configured tenant');
+    return Object.freeze({tenant, moduleBaseUrl: url.href, scope: url.origin === defaultOrigin ? tenant : JSON.stringify([url.origin, tenant])});
+}
+
+/** Pin a page once. A helper must never follow a later navigation into another tenant. */
+export function pageConnection(page) {
+    let connection = pages.get(page);
+    if (!connection) {
+        const url = new URL(page.url());
+        const match = url.pathname.match(/^\/([A-Za-z0-9_-]+)\/com\.bowmansystems\.sp5\.core\.ServicePoint\/index\.html$/);
+        if (!match) throw new TypeError('A Community Services application page is required');
+        connection = resolveUiConnection({tenant: match[1], moduleBaseUrl: url.origin + url.pathname.slice(0, -'index.html'.length)});
+        pages.set(page, connection);
+    }
+    return connection;
+}
+
+export function apiScope(api, ...adapters) {
+    const tenant = validateTenant(api?.tenant);
+    for (const adapter of adapters) {
+        const adapterTenant = adapter?.connection?.tenant ?? adapter?.tenant;
+        if (adapterTenant !== undefined && adapterTenant !== tenant) throw new TypeError('REST and UI tenants must match');
+    }
+    const base = (api.baseUrl ?? defaultApi).replace(/\/$/, '');
+    // Preserve existing journals on the default deployment, including uncertain writes.
+    return base === defaultApi ? tenant : JSON.stringify([base, tenant]);
+}