@choiceapps/communityservices-sdk 0.1.0

package/browser/program-discovery.mjs

@@ -0,0 +1,80 @@
+import {pageConnection} from './connection.mjs';
+import {decodeMappedResponse} from './gwt-mapped.mjs';
+import {withPageLock} from './page-lock.mjs';
+
+const positiveId=value=>{if(!Number.isSafeInteger(value)||value<1)throw Error('Positive provider ID required');return value;};
+
+/** Read-only catalog adapter. Requires Provider Admin / Assessment Admin access.
+ * Use a dedicated page: navigation leaves any currently displayed editor. No Save is clicked.
+ * Available/assigned assessments and default enrollment instruments are different settings. */
+export function createProgramDiscovery({page}) {
+ const connection=pageConnection(page),base=connection.moduleBaseUrl;
+  let wire;
+  const guard=()=>{const u=new URL(page.url());if(u.origin+u.pathname!==base+'index.html')throw Error('Configured application page required');};
+  const ready=async()=>{
+    await page.waitForFunction(()=>!document.body.innerText.includes('Processing...')&&!document.body.innerText.includes('Loading...'),null,{timeout:30000});
+    guard();if(await page.locator('[id="formfield-password"]:visible').count())throw Error('Session expired');
+  };
+  const initialize=async()=>{
+    guard();if(await page.locator('[role=dialog]:visible').count())throw Error('Close dialogs before catalog discovery');
+    let pending;
+    const listener=request=>{
+      if(request.url()===base+'service/MetaQueryService'&&request.postData()?.includes('|getMappedResults|')){
+        const policy=request.postData().split('|')[4];
+        pending=request.allHeaders().then(h=>{wire={policy,headers:Object.fromEntries(['content-type','x-gwt-module-base','x-gwt-permutation'].map(k=>[k,h[k]]))};});
+      }
+    };
+    wire=undefined;page.on('request',listener);
+    try{
+      await page.goto(base+'index.html#adminAssessments');await ready();
+      await page.getByRole('button',{name:'Search',exact:true}).click();await ready();await pending;
+      if(!wire?.policy||Object.values(wire.headers).some(v=>!v))throw Error('Assessment catalog permission or session unavailable');
+    }finally{page.off('request',listener);}
+  };
+  const mapped=async query=>{
+    guard();if(!wire)throw Error('Catalog session unavailable');
+    const rows=[],ids=new Set();let total;
+    for(let offset=0;offset<10000;offset+=100){
+      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 100,${offset}`];
+      const body=['7','0',strings.length,...strings,1,2,3,4,5,5,6,7,7,8,9,0,0,100,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('Assessment catalog read failed');
+      const result=decodeMappedResponse(r.body);
+      if(total!==undefined&&total!==result.total)throw Error('Assessment catalog changed during pagination');
+      total=result.total;
+      if(total>10000||result.rows.length>100||result.rows.length!==Math.min(100,total-offset))throw Error('Assessment catalog exceeds 10000 rows or is incomplete');
+      for(const row of result.rows){
+        if(!Number.isSafeInteger(row.assessmentId)||row.assessmentId<1||ids.has(row.assessmentId)||typeof row.name!=='string'||!row.name.trim()||typeof row.code!=='string'||!row.code.trim())throw Error('Invalid or duplicate assessment catalog row');
+        ids.add(row.assessmentId);rows.push(row);
+      }
+      if(rows.length===total)return rows;
+    }
+    throw Error('Assessment catalog pagination incomplete');
+  };
+  const listAssessments=()=>withPageLock(page,async()=>{
+    await initialize();
+    const assessments=await mapped("SELECT a.assessmentId AS assessmentId, a.name AS name, a.code AS code FROM DaAssessment AS a WHERE a.active = true AND a.hidden = false AND a.published = true AND a.assessmentTypeId = 1 AND a.code <> 'CLIENTDEMOGRAPHICS' AND a.code <> 'CLIENTMERGECOMPARISON' ORDER BY a.name ASC, a.assessmentId ASC");
+    return {source:'admin-catalog',retrievedAt:new Date().toISOString(),assessments};
+  });
+  const getProviderAssessments=({providerId})=>withPageLock(page,async()=>{
+    positiveId(providerId);await initialize();
+    const rows=await mapped(`SELECT a.assessment.assessmentId AS assessmentId, a.assessment.name AS name, a.assessment.code AS code, a.visible AS visible FROM DaAssessmentProvider AS a WHERE a.providerId = ${providerId} AND a.assessment.hidden = false AND a.assessment.active = true AND a.assessment.published = true ORDER BY a.assessment.name ASC, a.assessment.assessmentId ASC`);
+    const assessments=rows.map(({visible,...row})=>{if(typeof visible!=='boolean')throw Error('Invalid assessment visibility');return {...row,assignedToAssessmentTab:visible};});
+    await page.goto(base+`index.html#loadProvider;providerId=${providerId};subview=moduleSettings`);await ready();
+    await page.getByRole('tab',{name:'Display Settings',exact:true}).click();await ready();
+    await page.getByRole('tab',{name:'Assessment Display Settings',exact:true}).click();await ready();
+    if(!(await page.locator('body').innerText()).includes(`(${providerId}) `))throw Error('Provider identity unavailable');
+    const display=await page.locator('[id^="selectAssessment-"]').evaluateAll(elements=>elements.filter(e=>e.getBoundingClientRect().width>0).map(e=>{
+      const row=e.closest('tr');if(!row||row.cells.length<4)throw Error('Unexpected assessment display controls');
+      return {location:e.id.slice('selectAssessment-'.length),label:row.cells[0].innerText.trim(),name:row.cells[1].innerText.trim(),allowMultiple:row.querySelector('input[type=checkbox]')?.checked??null};
+    }));
+    if(display.length!==38||new Set(display.map(r=>r.location)).size!==38)throw Error('Assessment display settings incomplete or changed');
+    const defaults=display.map(({name,...row})=>{
+      const matches=name?assessments.filter(a=>a.name===name):[];
+      // A duplicate name must not resolve to an arbitrary instrument code.
+      return {...row,assessmentName:name||null,resolution:!name?'unset':matches.length===1?'resolved':'unresolved',assessment:matches.length===1?matches[0]:null};
+    });
+    return {source:'provider-display-settings',providerId,retrievedAt:new Date().toISOString(),assessments,defaults};
+  });
+  return {connection,listAssessments,getProviderAssessments};
+}

package/browser/recovery-diagnostics.mjs

@@ -0,0 +1,9 @@
+/** Serializable diagnostics only. Never copies response bodies, headers, tokens or request data. */
+export function recoveryDiagnostics(error,depth=0){
+ const result={name:typeof error?.name==='string'?error.name:'Error'};
+ for(const key of ['code','kind','stage','recoveryStage','operation','requestId','correlationId'])if(typeof error?.[key]==='string')result[key]=error[key];
+ for(const key of ['status','retryAfterMs'])if(Number.isFinite(error?.[key]))result[key]=error[key];
+ if(typeof error?.reauthenticated==='boolean')result.reauthenticated=error.reauthenticated;
+ if(depth<2&&error?.cause&&error.cause!==error)result.cause=recoveryDiagnostics(error.cause,depth+1);
+ return result;
+}

package/browser/service-recording.d.mts

@@ -0,0 +1,45 @@
+import type {Page} from 'playwright-core';
+import type {WellSkyClient,ServiceAddViewModel} from '../dist/esm/index.js';
+import type {UiMutationStore} from './index.mjs';
+import type {SsvfInformation} from './ssvf-rules.mjs';
+export interface ServiceUiContext {clientId:number;serviceId:number;providerId:number;serviceNote?:string;}
+export interface FundingSourceOption {fundId:number;fundCycleId:number;name:string;description:string|null;remainingBalance:number|null;submissionDeadline:string|null;}
+export interface FundingAllocation {fundId:number;fundCycleId:number;name:string;amount:number;}
+export interface ServiceUiDetails {financialAssistancePeriod?:{start:string;end:string}|null;fundingSources:FundingAllocation[];ssvfInformation?:SsvfInformation;}
+export interface ServiceUiSnapshot {
+ /** Visible SSVF controls, verified separately from REST readback. */
+ ssvfInformation?:Record<string,string|number>;
+ needStatus:string|null;needOutcome:string|null;serviceStart:string|null;serviceEnd:string|null;
+ financialAssistancePeriod:{start:string|null;end:string|null};timezone:string;
+ fundingSources:(FundingAllocation&{allocationId:number})[];
+}
+export interface ServiceUi {
+ readonly connection?:import("./connection.mjs").UiConnection;
+ assertReady():Promise<void>;
+ inspect(context:ServiceUiContext):Promise<ServiceUiSnapshot>;
+ matches(snapshot:ServiceUiSnapshot,expected:ServiceUiDetails):boolean;
+ complete(context:ServiceUiContext,expected:ServiceUiDetails,beforeSave:()=>Promise<void>):Promise<ServiceUiSnapshot>;
+ /** Read-only context supplies the current UI query/policy. Overrides filter choices before creating a service. */
+ listFundingSources(input:{context:ServiceUiContext;providerId?:number;serviceCodeId?:number}):Promise<FundingSourceOption[]>;
+}
+export interface ServiceRecordInput {
+ /** Stable source row identifier, never a batch position or randomly regenerated retry key. */
+ key:string;
+ body:Omit<Pick<ServiceAddViewModel,'clientId'|'serviceProvider'|'serviceCode'|'serviceStartDate'|'serviceEndDate'|'serviceNote'|'serviceCosts'>,'serviceEndDate'>&{
+  serviceEndDate:string;needStatus?:'Closed';
+  ssvfInformation?:SsvfInformation;
+ };
+ /** Required when ssvfFinancialAssistanceType is supplied; rejected otherwise. */
+ financialAssistancePeriod?:{start:string;end:string};
+ fundingSources?:FundingAllocation[];
+}
+export interface ServiceRecordResult {key:string;outcome:'verified'|'already-present';serviceId:number;needId:number;ui:ServiceUiSnapshot;}
+export interface RecoveryDiagnostic {name:string;code?:string;kind?:string;stage?:string;recoveryStage?:string;operation?:string;requestId?:string;correlationId?:string;status?:number;retryAfterMs?:number;reauthenticated?:boolean;cause?:RecoveryDiagnostic;}
+export type ServiceBulkResult = {index:number;key:string;outcome:'fulfilled';value:ServiceRecordResult}|{index:number;key:string;outcome:'rejected';message:string;error:RecoveryDiagnostic}|{index:number;key:string;outcome:'skipped'};
+export interface ServiceRecorder {
+ record(input:ServiceRecordInput):Promise<ServiceRecordResult>;
+ /** Sequential UI saves; stops at first failed row. Retry with the same keys/store to reconcile. */
+ recordBulk(inputs:ServiceRecordInput[],options?:{signal?:AbortSignal;onResult?:(result:ServiceBulkResult)=>void|Promise<void>}):Promise<{results:ServiceBulkResult[];callbackFailed:boolean}>;
+}
+export function createServiceRecorder(options:{api:WellSkyClient;ui:ServiceUi;store:UiMutationStore}):ServiceRecorder;
+export function createServiceUi(options:{page:Page}):ServiceUi;

package/browser/service-recording.mjs

@@ -0,0 +1,148 @@
+import {apiScope} from './connection.mjs';
+import {createHash} from 'node:crypto';
+import {recoveryDiagnostics} from './recovery-diagnostics.mjs';
+import {toItems} from '../dist/esm/index.js';
+import {validateSsvfInformation} from './ssvf-rules.mjs';
+
+const digest=value=>createHash('sha256').update(value).digest('hex');
+const canonical=value=>JSON.stringify(value,(_,v)=>v&&typeof v==='object'&&!Array.isArray(v)?Object.fromEntries(Object.keys(v).sort().map(k=>[k,v[k]])):v);
+const positive=n=>Number.isSafeInteger(n)&&n>0&&n<=2147483647;
+const object=v=>v!==null&&typeof v==='object'&&!Array.isArray(v);
+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);
+const timestamp=s=>Date.parse(/(?:Z|[+-]\d\d:\d\d)$/.test(s)?s:s+'Z');
+const one=response=>{const items=toItems(response);if(items.length!==1)throw Error('Expected exactly one record');return items[0];};
+const money=n=>typeof n==='number'&&Number.isFinite(n)&&n>=0&&n<=1e9&&Math.abs(n*100-Math.round(n*100))<1e-6;
+
+function prepare(input) {
+  if(!input||typeof input.key!=='string'||!input.key.trim()||input.key.length>200)throw Error('Stable service row key required');
+  if(Object.keys(input).some(k=>!['key','body','financialAssistancePeriod','fundingSources'].includes(k)))throw Error('Unknown service row field');
+  const body=structuredClone(input.body);
+  if(!object(body)||!positive(body.clientId)||!positive(body.serviceProvider)||typeof body.serviceCode!=='string'||!body.serviceCode.trim()||!instant(body.serviceStartDate)||!instant(body.serviceEndDate)||timestamp(body.serviceEndDate)<timestamp(body.serviceStartDate))throw Error('Client, provider, code and ordered timezone-qualified service dates required');
+  for(const field of ['serviceCosts','ssvfInformation'])if(body[field]!==undefined&&!object(body[field]))throw Error('Service details must be objects');
+  if(body.needStatus!==undefined&&body.needStatus!=='Closed')throw Error('Service recorder requires Closed needs');
+  if(Object.keys(body).some(k=>!['clientId','serviceProvider','serviceCode','serviceStartDate','serviceEndDate','serviceNote','needStatus','ssvfInformation','serviceCosts'].includes(k)))throw Error('Unsupported service recorder field');
+  if(body.serviceNote!==undefined&&(typeof body.serviceNote!=='string'||body.serviceNote.length>10000||body.serviceNote.includes('[sdk-service:')))throw Error('Invalid service note');
+  if(body.serviceCosts&&Object.entries(body.serviceCosts).some(([k,v])=>!['number_of_units','unit_type','total_cost_of_units'].includes(k)||(k==='unit_type'?typeof v!=='string':!money(v))))throw Error('Invalid service costs');
+  const period=structuredClone(input.financialAssistancePeriod??null);
+  if(period!==null&&!object(period))throw Error('Assistance period must be an object');
+  if(period&&(!body.ssvfInformation||!instant(period.start)||!instant(period.end)||timestamp(period.end)<timestamp(period.start)||Object.keys(period).some(k=>!['start','end'].includes(k))))throw Error('Invalid SSVF assistance period');
+  validateSsvfInformation(body.ssvfInformation,period);
+  const fundingSources=structuredClone(input.fundingSources??[]);
+  if(!Array.isArray(fundingSources)||fundingSources.length>20||fundingSources.some(f=>!f||!positive(f.fundId)||!positive(f.fundCycleId)||typeof f.name!=='string'||!f.name.trim()||!money(f.amount)||f.amount===0||Object.keys(f).some(k=>!['fundId','fundCycleId','name','amount'].includes(k)))||new Set(fundingSources.map(f=>f.fundCycleId)).size!==fundingSources.length||new Set(fundingSources.map(f=>f.name)).size!==fundingSources.length)throw Error('Invalid or duplicate funding sources');
+  body.needStatus='Closed';
+  const intentHash=digest(canonical({body,period,fundingSources}));
+  const keyHash=digest(input.key),marker=`[sdk-service:${keyHash}]`;
+  body.serviceNote=[body.serviceNote,marker].filter(Boolean).join('\n');
+  return {key:input.key,keyHash,intentHash,body,period,fundingSources,marker};
+}
+
+function verifyService(service,body) {
+  for(const field of ['clientId','serviceProvider','serviceCode','serviceNote'])if(service[field]!==body[field])throw Error('Stored service differs from requested row');
+  for(const field of ['serviceStartDate','serviceEndDate'])if(timestamp(service[field])!==timestamp(body[field]))throw Error('Stored service date differs');
+  for(const field of ['ssvfInformation','serviceCosts'])for(const [key,value]of Object.entries(body[field]??{}))if(service[field]?.[key]!==value)throw Error('Stored service details differ');
+  if(!positive(service.needId)||!positive(service.serviceId)||service.isActive===false)throw Error('Service has no active associated need');
+}
+
+async function serviceList(api,clientId,allowInitial404) {
+  const rows=[],ids=new Set();let count;
+  for(let page=1;page<=100;page++){
+    let result;try{result=await api.services.listForClient({path:{clientId},query:{perPage:100,startPage:page,total_count:true}});}catch(error){if(page===1&&allowInitial404&&error.status===404)return [];throw error;}
+    if(!Number.isSafeInteger(result?.count)||result.count<0||!Array.isArray(result.values)||count!==undefined&&count!==result.count)throw Error('Service list count unavailable or changed');
+    count=result.count;
+    for(const row of result.values){if(!positive(row.serviceId)||row.clientId!==clientId||ids.has(row.serviceId))throw Error('Invalid or duplicate service list record');ids.add(row.serviceId);rows.push(row);}
+    if(rows.length===count)return rows;
+    if(rows.length>count||!result.values.length)throw Error('Incomplete service list');
+  }
+  throw Error('Service list exceeds 100 pages');
+}
+
+/** Tenant-configured orchestration. REST creates once, UI fills contract gaps, both read back.
+ * Keep the same durable store and stable row keys across restarts and reordered batches.
+ * An uncertain write is reconciled, never automatically repeated. */
+export function createServiceRecorder({api,ui,store}) {
+ const tenantScope=apiScope(api, ui);
+  if(!ui||!store)throw Error('REST client, service UI adapter and durable store required');
+  const recordPrepared=async input=>{
+    const {body,keyHash,intentHash,marker,period,fundingSources}=input;
+    const scope=JSON.stringify([tenantScope,'service-recording',body.clientId]);
+    let failedStage='journal-lock';
+    try{return await store.withLock(scope,async()=>{
+      failedStage='journal-read';const entries=await store.read(scope);
+      if(!Array.isArray(entries))throw Error('Invalid service journal');
+      let entry=entries.find(e=>e.keyHash===keyHash);
+      if(entries.filter(e=>e.keyHash===keyHash).length>1||entry&&entry.intentHash!==intentHash)throw Error('Service key conflicts with earlier intent');
+      const persist=async stage=>{entry={...entry,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,entries);};
+      let service;
+      failedStage='session-preflight';await ui.assertReady();failedStage='rest-read';
+      if(entry?.serviceId){service=one(await api.services.getComplete({path:{serviceId:entry.serviceId}}));}
+      else {
+        const matches=[];
+        // Paginate fully before deciding that an earlier create is absent.
+        for(const item of await serviceList(api,body.clientId,!entry)){
+          if(item.serviceProvider!==body.serviceProvider||item.serviceCode!==body.serviceCode)continue;
+          const detail=one(await api.services.getComplete({path:{serviceId:item.serviceId}}));
+          if(detail.serviceId!==item.serviceId)throw Error('Service readback identity mismatch');
+          if(detail.serviceNote?.split('\n').includes(marker))matches.push(detail);
+        }
+        if(matches.length>1)throw Error('Duplicate service markers require review');
+        service=matches[0];
+        if(!service){
+          if(entry)throw Error('Unresolved REST create; refusing another create');
+          await persist('rest-attempted');
+          failedStage='rest-create';let createError;
+          try{service=one(await api.services.create({body}));}catch(error){createError=error;}
+          failedStage='rest-reconcile';
+          if(!service){
+            try{for(const item of await serviceList(api,body.clientId,false)){
+              if(item.serviceProvider!==body.serviceProvider||item.serviceCode!==body.serviceCode)continue;
+              const detail=one(await api.services.getComplete({path:{serviceId:item.serviceId}}));
+              if(detail.serviceId!==item.serviceId)throw Error('Service readback identity mismatch');
+              if(detail.serviceNote?.split('\n').includes(marker))matches.push(detail);
+            }
+            if(matches.length!==1)throw Error('REST create outcome uncertain; journal blocks repetition');
+            }catch(error){if(createError&&error!==createError&&!error.cause)error.cause=createError;throw error;}
+            service=matches[0];
+          }
+        }
+        verifyService(service,body);entry={...entry,serviceId:service.serviceId,needId:service.needId};await persist('rest-verified');
+      }
+      verifyService(service,body);
+      if(service.serviceId!==entry.serviceId||entry.needId!==undefined&&service.needId!==entry.needId)throw Error('Saved service or need identity changed');
+      // Older journals did not retain need IDs. Pin the first verified read
+      // before UI work, then require that association on every later retry.
+      if(entry.needId===undefined){entry.needId=service.needId;await persist(entry.stage);}
+      const context={clientId:body.clientId,serviceId:service.serviceId,providerId:body.serviceProvider,serviceNote:body.serviceNote};
+      const expected={financialAssistancePeriod:period,fundingSources,ssvfInformation:body.ssvfInformation};
+      failedStage='ui-inspect';let snapshot=await ui.inspect(context);
+      const wasVerified=entry.stage==='verified';
+      if(!ui.matches(snapshot,expected)){
+        if(entry.stage==='ui-attempted'||wasVerified)throw Error('UI save unresolved or stored row changed; refusing automatic replay');
+        failedStage='ui-complete';snapshot=await ui.complete(context,expected,()=>persist('ui-attempted'));
+      }
+      failedStage='verification';if(!ui.matches(snapshot,expected))throw Error('UI details did not verify; journal blocks repetition');
+      service=one(await api.services.getComplete({path:{serviceId:service.serviceId}}));verifyService(service,body);
+      if(service.serviceId!==entry.serviceId||service.needId!==entry.needId)throw Error('Saved service or need identity changed');
+      const need=one(await api.needs.getComplete({path:{needId:service.needId}}));
+      if(need.needId!==entry.needId||need.isActive===false||need.clientId!==body.clientId||need.needProvider!==body.serviceProvider||need.statusInformation?.needStatus!=='Closed'||need.statusInformation?.needOutcome!=='Fully Met')throw Error('Associated need did not verify identity, active state and Closed / Fully Met');
+      failedStage='journal-verify';await persist('verified');
+      return {key:input.key,outcome:wasVerified?'already-present':'verified',serviceId:service.serviceId,needId:service.needId,ui:snapshot};
+    });}catch(error){if(error&&typeof error==='object'&&!error.stage)error.stage=failedStage;throw error;}
+  };
+  return {
+    record:async input=>recordPrepared(prepare(input)),
+    async recordBulk(inputs,{signal,onResult}={}) {
+      if(!Array.isArray(inputs)||inputs.length>10000)throw Error('At most 10,000 rows per batch');
+      // Validate every row before any write. A shared browser executes sequentially.
+      const keys=new Set(),prepared=inputs.map(input=>{const row=prepare(input),key=`${row.body.clientId}:${row.keyHash}`;if(keys.has(key))throw Error('Duplicate row keys in batch');keys.add(key);return row;});
+      const results=[];let stopped=false,callbackFailed=false;
+      for(const [index,row]of prepared.entries()){
+        let result;
+        if(signal?.aborted||stopped)result={index,key:row.key,outcome:'skipped'};
+        else try{result={index,key:row.key,outcome:'fulfilled',value:await recordPrepared(row)};}catch(error){result={index,key:row.key,outcome:'rejected',message:error.message,error:recoveryDiagnostics(error)};stopped=true;}
+        results.push(result);
+        if(onResult&&!callbackFailed)try{await onResult(result);}catch{stopped=true;callbackFailed=true;}
+      }
+      return {results,callbackFailed};
+    },
+  };
+}

package/browser/service-ui.mjs

@@ -0,0 +1,160 @@
+import {pageConnection} from './connection.mjs';
+import {decodeMappedResponse} from './gwt-mapped.mjs';
+import {withPageLock} from './page-lock.mjs';
+import {readSsvfInformation} from './ssvf-rules.mjs';
+const id=n=>{if(!Number.isSafeInteger(n)||n<=0)throw Error('Positive integer ID required');return n;};
+
+/** Fresh UI forms generate their own GWT payloads. No captured write payload is replayed. */
+export function createServiceUi({page}) {
+ const connection=pageConnection(page),base=connection.moduleBaseUrl;
+  const guard=()=>{if(new URL(page.url()).origin+new URL(page.url()).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});
+  const assertReady=async()=>{guard();await ready();if(await page.locator('[role=dialog]:visible').count()||await page.locator('[id="formfield-password"]:visible').count())throw Error('Authenticated application page with no open dialogs required');};
+  let readWire,groupId;
+  const exit=async()=>{if(await page.locator('[id="ServiceView.exit"]').isVisible()){await page.locator('[id="ServiceView.exit"]').click();await page.locator('[id="ServiceView.exit"]').waitFor({state:'hidden'});await ready();}};
+  const open=async context=>{
+    id(context.clientId);id(context.serviceId);id(context.providerId);guard();
+    if(await page.locator('[role=dialog]:visible').count())throw Error('Close dialogs before service workflow');
+    readWire=undefined;groupId=undefined;
+    await exit();
+    const visibleClient=(await page.locator('body').innerText()).match(/Client - \((\d+)\)/)?.[1];
+    if(visibleClient&&Number(visibleClient)!==context.clientId){
+      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(url=>url.hash==='#clientPointClientMain');await ready();
+    }
+    if(new URL(page.url()).hash!==`#loadClient;clientId=${context.clientId}`)await page.goto(base+`index.html#loadClient;clientId=${context.clientId}`);
+    await page.waitForFunction(clientId=>document.body.innerText.includes(`Client - (${clientId})`)&&!document.body.innerText.includes('Processing...'),context.clientId,{timeout:30000});
+    await page.getByRole('tab',{name:'Client Information',exact:true}).click();
+    await page.getByRole('tab',{name:'Summary',exact:true}).click();await ready();
+    if(!(await page.locator('body').innerText()).includes(`Client - (${context.clientId})`))throw Error('Wrong client page');
+    let target=page.locator(`[id="ClientSummaryTab.editService-imageLink_${context.serviceId}"]`);
+    if(!await target.count()){
+      await page.getByRole('tab',{name:'Service Transactions',exact:true}).click();await ready();
+      const previous=page.getByRole('button',{name:'View Previous Service Transactions',exact:true});if(await previous.isVisible())await previous.click();
+      await page.getByRole('tab',{name:'Services',exact:true}).click();await ready();
+      const dates=page.locator('select').filter({has:page.locator('option',{hasText:/^All Dates$/})});
+      await dates.selectOption({label:'All Dates'});await page.getByRole('button',{name:'Search',exact:true}).click();await ready();
+      target=page.locator(`[id="ServicesPanel.editService-imageLink_${context.serviceId}"]`);
+      for(let i=0;!await target.count()&&i<100;i++){
+        const next=page.getByRole('button',{name:'Next',exact:true});if(!await next.isVisible()||await next.getAttribute('aria-disabled')==='true')break;
+        const response=page.waitForResponse(r=>r.request().postData()?.includes('|getMappedResults|')&&r.request().postData()?.includes('SpNeedService'));
+        void response.catch(()=>{});
+        await next.click();await response;await ready();
+      }
+    }
+    const funding=page.waitForResponse(r=>r.url()===base+'service/FundManagerService'&&r.request().postData()?.includes('|getFundingSources|'));
+    const mapped=page.waitForResponse(r=>r.url()===base+'service/MetaQueryService'&&r.request().postData()?.includes('|getMappedResults|'));
+    const loaded=page.waitForResponse(r=>r.url()===base+'service/ServiceTransactionService'&&r.request().postData()?.includes('|getService|')&&r.request().postData()?.endsWith(`|${context.serviceId}|`));
+    // A failed click must not leave later timeout rejections unhandled.
+    const pending=Promise.all([funding,mapped,loaded]);void pending.catch(()=>{});
+    await target.click();const response=await loaded;if(response.status()!==200||!(await response.text()).startsWith('//OK'))throw Error('Service load failed');
+    await page.locator('[id="ServiceView.saveAndExit"]').waitFor();await ready();
+    await page.waitForFunction(({provider,note})=>document.body.innerText.includes(`(${provider})`)&&document.querySelector('[aria-label="Service Notes"]')&&(note===undefined||document.querySelector('[aria-label="Service Notes"]').value===note),{provider:context.providerId,note:context.serviceNote});
+    const [fundResponse,mapResponse]=await pending;
+    if(fundResponse.status()!==200||!(await fundResponse.text()).startsWith('//OK'))throw Error('Funding state unavailable');
+    groupId=id(Number(fundResponse.request().postData().split('|').at(-2)));
+    const request=mapResponse.request(),headers=await request.allHeaders();
+    readWire={policy:request.postData().split('|')[4],headers:Object.fromEntries(['content-type','x-gwt-module-base','x-gwt-permutation'].map(k=>[k,headers[k]]))};
+  };
+  const expandFunds=async()=>{const expand=page.getByTitle('Expand Apply Funds for Service Panel',{exact:true});if(await expand.isVisible())await expand.click();await page.locator('[id^="SpFundingSourcesPanel.addFundingSource-"]').waitFor();};
+  const read=async()=>{
+    await ready();
+    const values=await page.evaluate(()=>{
+      const field=label=>document.querySelector(`[aria-label="${label}"]`)?.value??null;
+      const date=prefix=>{
+        const year=field(prefix+' Year'),month=field(prefix+' Month'),day=field(prefix+' Day');if(!year&&!month&&!day)return null;
+        let hour=Number(field(prefix+' Hour'));if(field(prefix+' AM/PM')==='PM'&&hour!==12)hour+=12;if(field(prefix+' AM/PM')==='AM'&&hour===12)hour=0;
+        return new Date(Number(year),Number(month)-1,Number(day),hour,Number(field(prefix+' Minute')),Number(field(prefix+' Second'))).toISOString();
+      };
+      return {needStatus:field('Need Status'),needOutcome:field('Outcome of Need'),serviceStart:date('Start Date'),serviceEnd:date('End Date'),financialAssistancePeriod:{start:date('SSVF Financial Assistance Start Date'),end:date('SSVF Financial Assistance End Date')},timezone:Intl.DateTimeFormat().resolvedOptions().timeZone};
+    });
+    values.ssvfInformation=await readSsvfInformation(page);
+    await expandFunds();
+    values.fundingSources=await page.locator('[id^="SpFundingSourcesPanel.addFundingSource-"]').evaluate(button=>{
+      let panel=button.parentElement;while(panel&&!panel.innerText.includes('Client Co-Pay'))panel=panel.parentElement;
+      if(!panel)throw Error('Funding panel not found');const rows=[];
+      for(const link of panel.querySelectorAll('a')){
+        let row=link.closest('tr');while(row&&!row.querySelector('input.sp5-textbox'))row=row.parentElement.closest('tr');
+        if(!row)throw Error('Funding amount not found');const inputs=[...row.querySelectorAll('input.sp5-textbox')];
+        if(inputs.length!==1)throw Error('Ambiguous funding amount');rows.push({name:link.textContent,amount:Number(inputs[0].value.replace(/,/g,''))});
+      }
+      return rows;
+    });
+    const strings=[base,readWire.policy,'com.bowmansystems.sp5.core.client.services.GenericService','getMappedResults','java.lang.String/2004016611','java.util.HashMap/1797211028','I','Z',`SELECT f.needServiceGroupFundId AS allocationId, f.fundId AS fundId, f.fundCycleId AS fundCycleId, f.fund.name AS name, f.amount AS amount FROM SpNeedServiceGroupFund AS f WHERE f.needServiceGroupId = ${id(groupId)} AND f.active = true`];
+    const result=await page.evaluate(async w=>{const r=await fetch(w.url,{method:'POST',headers:w.headers,body:w.body,credentials:'same-origin',redirect:'error',signal:AbortSignal.timeout(30000)});return {status:r.status,body:await r.text()};},{url:base+'service/MetaQueryService',headers:readWire.headers,body:['7','0',9,...strings,1,2,3,4,5,5,6,7,7,8,9,0,0,1001,1,''].join('|')});
+    if(result.status!==200)throw Error('Stored funding read failed');const stored=decodeMappedResponse(result.body);
+    if(stored.total!==stored.rows.length||stored.total>1000||stored.rows.length!==values.fundingSources.length)throw Error('Funding UI and stored allocation counts differ');
+    for(const f of stored.rows){id(f.allocationId);id(f.fundId);id(f.fundCycleId);if(values.fundingSources.filter(s=>s.name===f.name&&s.amount===f.amount).length!==1)throw Error('Stored funding differs from UI');}
+    values.fundingSources=stored.rows;return values;
+  };
+  const matches=(snapshot,expected)=>snapshot.needStatus==='Closed'&&snapshot.needOutcome==='Fully Met'&&Object.entries(expected.ssvfInformation??{}).every(([key,value])=>snapshot.ssvfInformation?.[key]===value)&&(!expected.financialAssistancePeriod||['start','end'].every(k=>Date.parse(snapshot.financialAssistancePeriod[k])===Date.parse(expected.financialAssistancePeriod[k])))&&expected.fundingSources.length===snapshot.fundingSources.length&&expected.fundingSources.every(f=>snapshot.fundingSources.filter(s=>s.fundId===f.fundId&&s.fundCycleId===f.fundCycleId&&s.name===f.name&&s.amount===f.amount).length===1);
+  const searchFunds=async()=>{
+    await expandFunds();
+    const responsePromise=page.waitForResponse(r=>r.url()===base+'service/MetaQueryService'&&r.request().postData()?.includes('SELECT SpFundCycleBalanceView.name AS name'));
+    void responsePromise.catch(()=>{});
+    await page.locator('[id^="SpFundingSourcesPanel.addFundingSource-"]').click();
+    const response=await responsePromise;await ready();
+    if(response.status()!==200)throw Error('Funding lookup failed');
+    const request=response.request(),headers=await request.allHeaders();
+    return {body:request.postData(),headers:Object.fromEntries(['content-type','x-gwt-module-base','x-gwt-permutation'].map(k=>[k,headers[k]]))};
+  };
+  const fundOptions=async(wire,overrides={})=>{
+    const parts=wire.body.split('|');if(parts[0]!=='7'||parts[1]!=='0'||Number(parts[2])!==9||parts[6]!=='getMappedResults')throw Error('Funding lookup format changed');
+    let query=parts[11];
+    if(!query.startsWith('SELECT SpFundCycleBalanceView.name AS name')||!query.includes('SpFundCompatibleCode.compatibleCodeId')||!query.includes('SpFundEnforcement'))throw Error('Funding filter missing');
+    if(overrides.providerId!==undefined)query=query.replace(/\bproviderId = \d+/g,`providerId = ${id(overrides.providerId)}`);
+    if(overrides.serviceCodeId!==undefined)query=query.replace(/\bcompatibleCodeId = \d+/g,`compatibleCodeId = ${id(overrides.serviceCodeId)}`);
+    parts[11]=query.replace(/LIMIT \d+,\d+$/,'LIMIT 1001,0');
+    // v7 getMappedResults(String,HashMap,int,int,boolean), observed null map and zero offset.
+    if(parts.slice(12).join('|')!=='1|2|3|4|5|5|6|7|7|8|9|0|0|10|1|')throw Error('Funding query arguments changed');
+    parts[25]='1001';
+    const result=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:parts.join('|')});
+    if(result.status!==200)throw Error('Funding read failed');const decoded=decodeMappedResponse(result.body);
+    if(decoded.total!==decoded.rows.length||decoded.total>1000)throw Error('Incomplete funding list');
+    for(const row of decoded.rows){id(row.fundId);id(row.fundCycleId);if(typeof row.name!=='string'||!row.name)throw Error('Invalid funding source');}
+    return decoded.rows;
+  };
+  const listFundingSources=input=>withPageLock(page,async()=>{
+    await open(input.context);
+    try{const wire=await searchFunds();try{return await fundOptions(wire,input);}finally{await page.locator('[id="FundServicesSearchPopup.cancel"]').click();}}finally{await exit();}
+  });
+  const inspect=context=>withPageLock(page,async()=>{await open(context);try{return await read();}finally{await exit();}});
+  const fillDate=async(prefix,value)=>{
+    const parts=await page.evaluate(value=>{const d=new Date(value);const rebuilt=new Date(d.getFullYear(),d.getMonth(),d.getDate(),d.getHours(),d.getMinutes(),d.getSeconds());if(rebuilt.getTime()!==d.getTime())throw Error('Ambiguous local time');return {Month:String(d.getMonth()+1).padStart(2,'0'),Day:String(d.getDate()).padStart(2,'0'),Year:String(d.getFullYear()),Hour:String(d.getHours()%12||12),Minute:String(d.getMinutes()).padStart(2,'0'),Second:String(d.getSeconds()).padStart(2,'0'),'AM/PM':d.getHours()<12?'AM':'PM'};},value);
+    for(const [part,value]of Object.entries(parts)){const field=page.getByLabel(prefix+' '+part,{exact:true});if(['Month','Day','Year'].includes(part)){await field.fill(value);await field.press('Tab');}else await field.selectOption(value);}
+  };
+  const complete=(context,expected,beforeSave)=>withPageLock(page,async()=>{
+    await open(context);let attempted=false;
+    try{
+      const current=await read();if(matches(current,expected))return current;
+      if(current.fundingSources.length)throw Error('Existing funding differs; manual reconciliation required');
+      await page.getByLabel('Need Status',{exact:true}).selectOption({label:'Closed'});
+      await page.getByLabel('Outcome of Need',{exact:true}).selectOption({label:'Fully Met'});
+      if(expected.financialAssistancePeriod){await fillDate('SSVF Financial Assistance Start Date',expected.financialAssistancePeriod.start);await fillDate('SSVF Financial Assistance End Date',expected.financialAssistancePeriod.end);}
+      for(const fund of expected.fundingSources){
+        const wire=await searchFunds(),options=await fundOptions(wire);
+        const matches=options.filter(f=>f.fundId===fund.fundId&&f.fundCycleId===fund.fundCycleId&&f.name===fund.name);
+        if(matches.length!==1||options.filter(f=>f.name===fund.name).length!==1)throw Error('Funding source unavailable or ambiguous');
+        const dialog=page.getByRole('dialog',{name:'Add Funding Source',exact:true});
+        const search=dialog.locator('input[name="txtSearchBox"]');await search.fill('');await search.pressSequentially(fund.name);
+        const searched=page.waitForResponse(r=>r.url()===base+'service/MetaQueryService'&&r.request().postData()?.includes('SELECT SpFundCycleBalanceView.name AS name'));
+        void searched.catch(()=>{});
+        await page.locator('[id="FundServicesSearchView.searchButton"]').click();await searched;await ready();
+        // Reject ambiguous names/cycles above. Select only the row displaying this verified name.
+        const row=dialog.getByText(fund.name,{exact:true}).locator('xpath=ancestor::tr[@role="row"][1]');
+        await row.getByTitle('Select Fund',{exact:true}).click();await dialog.waitFor({state:'hidden'});await ready();
+        const amount=page.getByText(fund.name,{exact:true}).locator('xpath=ancestor::tr[.//input[contains(@class,"textbox")]][1]').locator('input.sp5-textbox');await amount.fill(fund.amount.toFixed(2));await amount.press('Tab');
+      }
+      await beforeSave();attempted=true;
+      await page.locator('[id="ServiceView.saveAndExit"]').click();
+      await page.locator('[id="ServiceView.saveAndExit"]').waitFor({state:'hidden'});await ready();
+      await open(context);const saved=await read();if(!matches(saved,expected))throw Error('Service UI readback mismatch');return saved;
+    }finally{
+      // Never dismiss an uncertain save/validation dialog or click Save again.
+      if(!await page.locator('[role=dialog]:visible').count())await exit();
+      else if(!attempted&&await page.locator('[id="FundServicesSearchPopup.cancel"]').isVisible()){await page.locator('[id="FundServicesSearchPopup.cancel"]').click();await exit();}
+    }
+  });
+  return {connection,assertReady:()=>withPageLock(page,assertReady),inspect,matches,complete,listFundingSources};
+}

package/browser/session-authentication.mjs

@@ -0,0 +1,40 @@
+import {pageConnection} from './connection.mjs';
+import {randomUUID} from 'node:crypto';
+import {AttachmentConflictError} from './attachment-conflict.mjs';
+const sessions=new WeakMap();
+export class SessionInterruptedError extends Error {
+ constructor(reauthenticated){
+  super(reauthenticated?'Session reauthenticated after an interrupted operation. Retry with the same durable journal and operation key to reconcile; the operation was not replayed.':'Session reauthentication failed after an interrupted operation. Resolve authentication, then reconcile with the same durable journal and operation key.');
+  this.name='SessionInterruptedError';this.code='SESSION_INTERRUPTED';this.reauthenticated=reauthenticated;
+ }
+}
+export const sessionAuthentication=page=>sessions.get(page);
+export const sessionGeneration=page=>sessions.get(page)?.generation??'unmanaged';
+/** Internal hooks run only while the page lock is held. Never rerun a work callback. */
+export function attachAuthentication(page,reconnect,probe,connection=pageConnection(page)){
+ const target=new URL(connection.moduleBaseUrl);
+ let expired=false,blocked,closed=false,generation=randomUUID();
+ const response=r=>{const u=new URL(r.url());if(u.origin===target.origin&&u.pathname.startsWith('/'+connection.tenant+'/')&&r.status()===401)expired=true;};
+ page.on('response',response);
+ const state={
+  get generation(){return generation;},
+  async isExpired(){return expired||await page.locator('[id="formfield-password"]:visible').count()>0;},
+  async reauthenticate(){
+   if(closed)throw Error('Session closed');
+   // Invalidate all prepared payloads even if authentication subsequently fails.
+   generation=randomUUID();expired=true;
+   try{await reconnect();expired=false;blocked=undefined;}catch(error){blocked=error;throw error;}
+  },
+  async before(){if(closed)throw Error('Session closed');if(blocked)throw blocked;if(await state.isExpired())await state.reauthenticate();},
+  async afterFailure(error){
+   // Preserve confirmed conflicts even if the session expired independently.
+   // The next operation still performs normal authentication preflight.
+   if(error instanceof AttachmentConflictError)throw error;
+   if(!await state.isExpired()&&!await Promise.resolve().then(()=>probe?.()).catch(()=>false))throw error;
+   try{await state.reauthenticate();}catch{throw new SessionInterruptedError(false);}
+   throw new SessionInterruptedError(true);
+  },
+  close(){closed=true;page.off('response',response);},
+ };
+ sessions.set(page,state);return state;
+}

package/browser/shelter-inventory.d.mts

@@ -0,0 +1,103 @@
+import type { Page } from 'playwright-core';
+
+export interface ShelterInventoryFreshness {
+    /** Host UTC timestamps spanning the reads, not a server transaction timestamp. */
+    startedAt: string;
+    observedAt: string;
+    completedAt: string;
+    sourceUpdatedAt: null;
+    atomic: false;
+}
+export interface ShelterInventoryLimits {
+    maxPages: number;
+    maxUnitLists: number;
+    /** Named beds plus occupied overflow rows. The new-overflow action is excluded. */
+    maxBeds: number;
+}
+export interface ShelterInventoryReportedCounts {
+    totalBeds: number;
+    /** Includes held beds. Do not use this as the number of occupants. */
+    usedBeds: number;
+    availableBeds: number;
+    overflowOccupants: number;
+}
+export interface ShelterUnitList {
+    providerId: number;
+    unitListId: number;
+    name: string;
+    type: string;
+    reported: ShelterInventoryReportedCounts;
+}
+export interface ShelterInventoryOccupant {
+    clientId: number;
+    displayName: string;
+    /** UI text only. No timezone or exact check-in instant is inferred. */
+    dateInText: string | null;
+    groupId: number | null;
+    /** A scheduled checkout never makes the bed vacant in this snapshot. */
+    scheduledCheckout: { status: 'scheduled'; localDateTimeText: string } | { status: 'not-indicated' | 'unknown' };
+}
+interface ShelterInventoryBedIdentity {
+    /** JSON tuple of tenant, providerId, unitListId, unit, address, name.
+     * Stable across row ordering and occupancy changes, changes on renaming.
+     * Never pass this key as a server bed ID. Duplicate paths reject the read.
+     */
+    bedKey: string;
+    /** The visible inventory does not expose a server bed ID. */
+    bedId: null;
+    unit: string;
+    address: string;
+    name: string;
+}
+export type ShelterInventoryBed = ShelterInventoryBedIdentity & (
+    { status: 'occupied'; reason: null; occupant: ShelterInventoryOccupant } |
+    { status: 'vacant'; reason: null; occupant: null } |
+    { status: 'unavailable'; reason: 'held'; occupant: null } |
+    { status: 'unknown'; reason: 'unrecognized-row' | 'check-in-unavailable'; occupant: null }
+);
+export type ShelterVacancySnapshot = {
+    status: 'known'; vacantCount: number; vacantBedKeys: string[];
+} | {
+    status: 'unknown'; vacantCount: null; vacantBedKeys: []; reasons: ['unclassified-beds'];
+};
+interface ShelterInventoryObservation {
+    provider: { providerId: number; name: string };
+    source: 'ui';
+    freshness: ShelterInventoryFreshness;
+    limits: ShelterInventoryLimits;
+}
+export interface ShelterUnitListSnapshot extends ShelterInventoryObservation {
+    completeness: 'complete-visible-provider';
+    unitLists: ShelterUnitList[];
+}
+export interface ShelterInventorySnapshot extends ShelterInventoryObservation {
+    completeness: 'complete-visible-unit-list';
+    unitList: ShelterUnitList;
+    beds: ShelterInventoryBed[];
+    counts: { total: number; occupied: number; vacant: number; unavailable: number; unknown: number };
+    overflow: { occupants: ShelterInventoryOccupant[]; entryAvailable: boolean };
+    /** A snapshot, not a reservation or an admission/eligibility decision. */
+    availability: ShelterVacancySnapshot;
+}
+export interface ShelterInventory {
+ readonly connection?:import("./connection.mjs").UiConnection;
+    listUnitLists(input: { providerId: number }): Promise<ShelterUnitListSnapshot>;
+    getInventory(input: { providerId: number; unitListId: number }): Promise<ShelterInventorySnapshot>;
+}
+export function createShelterInventory(options: {
+    /** Dedicated authenticated application Page, shared with other SDK helpers through their page lock. */
+    page: Page;
+    /** Default and maximum 100 counted availability pages. */
+    maxPages?: number;
+    /** Default and maximum 1,000 visible unit lists. */
+    maxUnitLists?: number;
+    /** Default and maximum 10,000 bed/occupied-overflow rows. */
+    maxBeds?: number;
+    /** Per-wait timeout, default 30,000 ms, maximum 60,000 ms. */
+    timeoutMs?: number;
+}): ShelterInventory;
+export class ShelterInventoryError extends Error {
+    readonly code: 'SHELTER_INVENTORY_UNAVAILABLE';
+    readonly reason: string;
+    constructor(reason: string);
+}