@choiceapps/communityservices-sdk 0.1.0

package/docs/durable-records.md

@@ -0,0 +1,156 @@
+# Create clients, households, and case plans safely
+
+[Documentation index](README.md) · [Typed integration example](../examples/durable-records.mts) · [Recovery](troubleshooting.md)
+
+These helpers require a V3 `WellSkyClient` configured for the target tenant. The browser adapters require a dedicated authenticated page. All snippets below are integration fragments: your application supplies the IDs, source keys, dates, and values. No example logs in or writes on import.
+
+## Set up the helpers
+
+```js
+import {
+	createFileGwtMutationStore, createClientCreator,
+	createHouseholds, createHouseholdUi,
+	createCasePlans, createCasePlanUi,
+} from '@choiceapps/communityservices-sdk/browser';
+
+const store = createFileGwtMutationStore(journalDirectory);
+const clients = createClientCreator({api, store});
+const households = createHouseholds({
+	api, store, ui: createHouseholdUi({page: session.page}),
+});
+const casePlans = createCasePlans({
+	api, store, ui: createCasePlanUi({page: session.page}),
+});
+```
+
+Use the same private journal directory on every retry and process restart. The file store coordinates one host. Multiple hosts need a shared durable locking implementation. These operations are not atomic across entities, and external writers do not use the SDK's lock.
+
+## Map a source person to a client
+
+```js
+const original = {
+	sourceId: sourcePersonId,
+	body: {firstName, lastName, dateEffective: effectiveInstant},
+};
+const created = await clients.create(original);
+const mapping = await clients.lookup(sourcePersonId);
+```
+
+`create` records the server-returned client ID and verifies the supported identity fields. An identical source-ID retry returns that ID without another create. A changed creation intent under the same source raises `SOURCE_ID_CONFLICT`. To edit a person later, use the [profile helpers](profiles.md), not a revised creation request. After a legitimate profile edit, `lookup` retrieves the mapping; replaying the old create can reject the changed fields.
+
+Name and SSN candidate matches raise `POSSIBLE_DUPLICATE` with `candidateClientIds`. They never select, link, or merge a person automatically. After reviewing those candidates, an application can explicitly create a distinct person with `allowDistinctClient: true`. Retain that flag with the original intent on retries. The helper does not perform demographic deduplication or fuzzy matching.
+
+If the create response is lost before an ID is durably saved, `CLIENT_CREATE_UNCERTAIN` blocks another create. Verify the server's creation receipt or the target record independently. Only then call:
+
+```js
+const recovered = await clients.resolveCreated({
+	...original, clientId: verifiedCreatedClientId,
+});
+```
+
+This records an explicitly verified mapping and performs no server write. It does not find the client for you. Never obtain the ID by automatically choosing a name or DOB match. An ID already mapped to another source is rejected.
+
+Supported creation fields are names, suffix, alias, name quality, SSN and its quality, veteran status, and the explicit effective instant. Use the [DOB helper](profiles.md#birth-dates) for calendar birth dates and the profile/assessment helpers for other fields. Unsupported fields are rejected. The exact input and result contracts are in [client-creation.d.mts](../browser/client-creation.d.mts).
+
+For `veteranStatus`, omit the field or supply exactly `Yes (HUD)`, `No (HUD)`, `Client doesn't know (HUD)`, `Client prefers not to answer (HUD)`, or `Data not collected (HUD)`. Other values, including `Yes`, `No`, and an empty string, raise `INVALID_VETERAN_STATUS` before API access or journal reservation. The helper does not translate aliases. An invalid label accepted by REST can later break service reads or return an error after a service has already been created. This validation does not repair older client records or journals. Review those records and retain the original journal rather than changing a saved creation intent to bypass a conflict. Profile updates validate veteran status against the current UI choices.
+
+## Create and manage a household
+
+```js
+const createdHousehold = await households.create({
+	key: sourceHouseholdId,
+	headClientId,
+	householdType,
+	members: [
+		{clientId: headClientId, relationship: 'Self', dateJoined: joinedAt},
+		{clientId: memberClientId, relationship: memberRelationship, dateJoined: joinedAt},
+	],
+});
+const householdId = createdHousehold.household.householdId;
+```
+
+`getHouseholdOptions()` returns the verified sandbox labels and their verification date. It is a dated snapshot, not a live configuration query. Use one head with relationship `Self`, unique member IDs, and timezone-qualified join dates. The head's join date must cover every member's membership. Existing invalid head state is a data error and blocks mutation.
+
+Add a child or another person with their own later join date:
+
+```js
+await households.addMembers({
+	key: sourceMembershipId, householdId, headClientId, householdType,
+	members: [{clientId: childClientId, relationship: 'Daughter', dateJoined: childJoinedAt}],
+});
+await households.updateRelationships({
+	key: sourceRelationshipChangeId, householdId, headClientId,
+	members: [{clientId: memberClientId, relationship: 'Significant other'}],
+});
+await households.endMembers({
+	key: sourceDepartureId, householdId, headClientId,
+	clientIds: [memberClientId], dateEnded: memberLeftAt,
+});
+```
+
+The helper preserves unrelated members, previous join dates, and ended records. Existing membership cannot be silently replaced or rejoined. The head cannot leave an active household, be demoted, or be replaced through these methods. Household closure and retroactive head corrections need separate workflows.
+
+Household membership is separate from program enrollment. After creating the household, pass its ID to the [household enrollment workflow](enrollments.md). A later child must first belong to the household, then be attached to the program with their own entry date and assessment. Ending household membership does not exit a program. Program exits continue to use the enrollment head-coverage guards.
+
+Creation and changes reconcile exact saved state after uncertain responses. Completed retries also recognize subsequent verified changes in the same journal. External drift and unresolved attempts block writes. See [households.d.mts](../browser/households.d.mts) for all methods.
+
+## Create and update Client Notes, goals, and action steps
+
+```js
+const note = await casePlans.createClientNote({
+	key: sourceClientNoteId, clientId,
+	values: {note_date: noteInstant, note: clientNoteText},
+});
+const goal = await casePlans.createGoal({
+	key: sourceGoalId, clientId,
+	values: {
+		providerId, dateGoalsSet: goalInstant, classification: 'Case Plan',
+		type: 'Develop a Case Plan', overallStatus: 'In Progress',
+		goalDescription,
+	},
+});
+const action = await casePlans.createActionStep({
+	key: sourceActionId, clientId, goalId: goal.recordId,
+	values: {providerId, dateSet: actionInstant, actionStep, status: 'In Progress'},
+});
+```
+
+Choose classification, type, and status values from the actual tenant form. The strings above are verified sandbox examples, not universal options. Each operation checks ownership and verifies its supported fields after saving. A sequence can stop partway through. Reuse every original key when resuming; the [typed example](../examples/durable-records.mts) gives each component its own stable suffix.
+
+Use a new source key for an intentional update:
+
+```js
+await casePlans.updateClientNote({
+	key: sourceNoteRevisionId, clientId, recordId: note.recordId,
+	values: {note: revisedText},
+});
+await casePlans.updateGoal({
+	key: sourceGoalRevisionId, clientId, recordId: goal.recordId,
+	values: {goalDescription: revisedDescription, percentComplete: '50%'},
+});
+await casePlans.updateActionStep({
+	key: sourceActionRevisionId, clientId, goalId: goal.recordId,
+	recordId: action.recordId, values: {actionStep: revisedAction},
+});
+```
+
+Update requests preserve the helper's supported unmodified fields. Unreadable follow-up fields are not exposed as writable helper fields. Percent complete uses UI labels `10%` through `90%`, or an empty string; numeric string `50` is invalid. Consult [case-plans.d.mts](../browser/case-plans.d.mts) for field coverage. Initial empty REST results need fresh UI confirmation. Failed or incomplete reads never authorize a repeat write.
+
+Client Notes differ from goal case notes. The latter use the Goal's **Add Case Note** button or the Notes-column paper icon. Never use the unrelated `households` array observed in REST goal responses to select note participants.
+
+## Give goal case notes a source key
+
+```js
+await session.workflows.createCaseNote({
+	key: sourceGoalNoteId, clientId, goalId, providerId,
+	noteDate: localCalendarDate, note: goalNoteText,
+});
+```
+
+A keyed retry must retain the same client, goal, provider, calendar date, and text. Changed intent raises `CASE_NOTE_SOURCE_CONFLICT` before browser access. The journal also verifies the saved note ID. The key is optional only for compatibility: unkeyed calls retain text/date/provider matching. Identical existing notes can be reconciled; a new source key is not a command to force a duplicate. Notes are single-client operations.
+
+## Return service diagnostics to the application
+
+Rejected `recordBulk` rows include `message` and structured `error` metadata. Fields include `code`, `kind`, `stage`, `status`, `reauthenticated`, and bounded causes when available. These are optional because some failures are ordinary JavaScript errors. The [typed example](../examples/durable-records.mts) retains them and returns an application action without replaying any write.
+
+For `SESSION_INTERRUPTED`, check `reauthenticated`. Resume with the same row keys and journal only after authentication is ready. Other failures need saved-state review. Keep fulfilled and skipped rows in the application's report. A successful REST create may still need UI completion and Closed/Fully Met need verification. See [services](services.md) and [recovery](troubleshooting.md).

package/docs/enrollments.md

@@ -0,0 +1,217 @@
+# Discover programs and manage enrollments
+
+[Documentation index](README.md) · [Agent guide](../AGENTS.md)
+
+The snippets are integration fragments. Your application supplies existing client and household IDs, stable source keys, and assessment plans. Use the [durable client and household helpers](durable-records.md) before enrolling new people. Client identity decisions and household membership remain separate from program participation.
+
+## Programs, assessments and form definitions
+
+```js
+import {readProgramCatalog, flattenQuestions} from '@choiceapps/communityservices-sdk';
+import {createProgramDiscovery} from '@choiceapps/communityservices-sdk/browser';
+const catalog = await readProgramCatalog(api); // Counted REST pages, active/operational by default.
+const discovery = createProgramDiscovery({page: session.page});
+const configuration = await discovery.getProviderAssessments({providerId});
+const entry = configuration.defaults.find(d => d.location === 'showVaEntry');
+if (entry?.resolution !== 'resolved') throw new Error('Entry assessment not resolved');
+const definition = await api.assessments.getDefinition({
+  clientId:metadataClientId, assessmentCode:entry.assessment.code,
+});
+const questions = flattenQuestions(definition.questions); // Includes subassessment children.
+const picklists = await api.picklists.list({clientId:metadataClientId, assessmentCode:entry.assessment.code});
+```
+
+Provider lists include agencies and parent organizations as well as programs. Listing a provider does not establish permission to enroll or provide services. Swagger lacks provider-to-assessment assignments, so the browser adapter reads Provider Admin display settings and the published catalog. It distinguishes assessment-tab assignment from entry/interim/exit defaults and leaves ambiguous names unresolved. `listAssessments()` returns the published top-level catalog. Browser discovery requires administrative read access and shares the page lock with the other helpers.
+
+REST form metadata includes question paths, mandatory flags, current option IDs/codes/names, and nested subassessment definitions without recorded client answers. It requires a permitted client context and does not reproduce every UI conditional rule or historical picklist version. See [program discovery findings](capabilities.md) and [example](../examples/program-discovery.ts).
+
+## Enrollment workflow from program discovery
+
+`createEnrollmentWorkflow` composes the provider catalog, current program assessment defaults, question/picklist metadata, REST enrollment and answer writes, and the durable GWT interim helper. It accepts an **existing client ID** and supports HUD and VA program defaults. It does not create clients or infer program eligibility, answers, conditional applicability, or which verification types a program requires.
+
+```ts
+import {
+  openEnrollmentSession, createProgramDiscovery,
+  createEnrollmentWorkflow, createFileGwtMutationStore,
+  createDateOfBirth, createDateOfBirthUi,
+} from '@choiceapps/communityservices-sdk/browser';
+
+const store = createFileGwtMutationStore('/private/application/hmis-journal');
+const session = await openEnrollmentSession({ chromium, store });
+try {
+  const workflow = createEnrollmentWorkflow({
+    api, // WellSkyClient with the deployment's explicitly measured mobile date correction.
+    discovery: createProgramDiscovery({ page: session.page }),
+    helpers: session.helpers,
+    store,
+    birthDates: createDateOfBirth({
+      api, store, ui: createDateOfBirthUi({page: session.page}),
+    }),
+  });
+  const context = { clientId, providerId, type: 'HUD' as const, entryDate };
+  const catalog = await workflow.discover(context);
+  // Render catalog.entry.definition and catalog.interim.definition in the application.
+  const entry = await workflow.createEnrollment({
+    ...context, key: `${sourceEnrollmentId}:entry`, assessment: entryPlan,
+  });
+  const interim = await workflow.createInterim({
+    key: `${sourceEnrollmentId}:review:${sourceReviewId}`,
+    enrollmentKey: `${sourceEnrollmentId}:entry`, clientId, reviewDate,
+    assessment: interimPlan,
+  });
+} finally {
+  await session.close();
+}
+```
+
+An assessment plan has these fields:
+
+- `answers`: field names mapped to the SDK's `{value}`, `{option: {code|name}}`, or supported `{options}` selectors.
+- `subassessments`: new rows with a stable `key`, `parentField`, and child `answers`. Results return `recordsetIds` keyed by those row keys. Equivalent duplicate rows are rejected, including reordered answer properties, equivalent dates and monetary representations.
+- `endDates`: explicit `parentField`, `recordsetId`, `startDateField`, `endDateField`, and `endDate`. Interims and exits can close rows; entry plans cannot. The end must be on or after the stored start and enrollment, and strictly before that interim or exit timestamp. Closure readback verifies retained fields as well as the end date. A different existing end date is a conflict.
+- `carryForward`: fields or subassessment groups that already have values at this effective date. Unchanged verification groups should be carried forward instead of recreated.
+- `notApplicable`: field names mapped to nonempty explanations. Every editable top-level question must have exactly one applicable coverage choice; multiple new rows and closures in the same group are allowed. Display labels and blanks need no answers. Child fields omitted from a new row are encoded as empty; the application must decide which child questions apply.
+
+A replacement-income interim closes the original row using `entry.recordsetIds['earned-income']`, adds one new earned-income row with a new stable key and review-date start, and writes the new overall income answer and amount. The other groups carry forward. Supply timezone-qualified whole-second timestamps; body dates are never shifted. Scalar verification checks both the saved value and its effective timestamp. It uses the assessment API, not the known-defective complete-enrollment entry arrays.
+
+DOB plans use `answers: {SVPPROFDOB: {value: '1984-02-29'}}`, a strict `YYYY-MM-DD` calendar date. Supply the `birthDates` adapter above whenever a plan answers or carries forward DOB. The workflow removes DOB from the ordinary mobile answer batch and runs the dedicated helper after other assessment writes. It preserves the enrollment/effective timestamp, verifies the client API and fresh UI, and returns `result.birthDate`. Household operations apply this to every selected member, including children joining later at their own entry date. All member DOBs are preflighted before enrollment creation or attachment.
+
+For an unknown or declined DOB, answer `SVPPROFDOBTYPE` with its discovered option code and provide a `notApplicable.SVPPROFDOB` explanation. Do not submit a DOB value or carry forward an absent date. This preserves missing DOBs for each household member and does not require the calendar-date writer. See [quality-only DOB plans](profiles.md#unknown-or-declined-birth-date).
+
+When an actual DOB exists and the discovered interim or exit instrument includes DOB, use `carryForward: ['SVPPROFDOB', ...otherUnchangedFields]` if DOB has not changed. If the instrument does not include DOB, leave it out of that plan. This reads the client API and UI even when the mobile answer value is blank, and creates no new DOB history row. Completed workflow retries verify the saved DOB without restoring earlier assessment values. An explicit new DOB at a later effective timestamp uses the helper; correction at an existing timestamp is supported only with matching entry context. Earlier historical corrections stop before writes. Migrate older workflow DOB timestamps to calendar dates explicitly; the workflow rejects timestamp-shaped DOB input.
+
+All cooperating writers must retain the same durable store and keys. The workflow pins program/assessment metadata, rejects changed intent or schema under an existing key, checks complete counted enrollment lists, and records each attempt before sending. It adopts a unique existing enrollment with the same client/provider/type/start and exact existing subassessment rows rather than duplicating them. Multiple matches fail. A lost response is reconciled by readback; an empty, partial or failed read does not authorize resending. Another unfinished workflow for the client blocks subsequent workflow keys until it is reconciled. Existing GWT helpers keep their separate durable review journal.
+
+`await workflow.getStatus({clientId, key})` reads local progress and attempted/verified stages without making network requests. Its status describes the journal, not fresh server state. Retry the same intent to reconcile; do not delete the journal or change keys to bypass an uncertain write. The process is not a transaction: saved enrollment/review records remain when a later stage fails. Locks coordinate this integration on one host; unrelated users or integrations can still race it. These single-client methods populate one person's assessment per call; use the household methods below to coordinate linked enrollments and reviews.
+
+See the [packaged enrollment example](../examples/enrollment-workflow.mts) for a typed application-owned plan builder. The optional browser export requires a dedicated authenticated application page with the administrative read access needed for program assessment discovery.
+
+[Live workflow acceptance](capabilities.md) covers a new synthetic client, exact entry/interim UI values, all verification table pages, and repeated calls with zero REST writes or GWT creations. [DOB workflow acceptance](capabilities.md) covers a leap-day DOB, distinct household member DOBs, a later-entry newborn, and repeated entry/interim operations after later assessment changes.
+
+## Household enrollment and interim assessments
+
+The same workflow exposes `createHouseholdEnrollment` and `createHouseholdInterim`. Supply `enrollmentSession: session.enrollmentSession` when constructing it. Initial household enrollment requires an existing household and at least two existing clients, including its head. Later interims and exits accept a nonempty subset of enrolled members. Establish household membership separately before enrollment.
+
+```ts
+const workflow = createEnrollmentWorkflow({
+  api, discovery: createProgramDiscovery({page: session.page}),
+  helpers: session.helpers, enrollmentSession: session.enrollmentSession, store,
+  birthDates: createDateOfBirth({api, store, ui: createDateOfBirthUi({page: session.page})}),
+});
+const entry = await workflow.createHouseholdEnrollment({
+  key: sourceEnrollmentId, householdId, headClientId,
+  providerId, type: 'HUD', entryDate,
+  members: [
+    {clientId: headClientId, assessment: headEntryPlan},
+    {clientId: memberClientId, assessment: memberEntryPlan},
+  ],
+});
+const interim = await workflow.createHouseholdInterim({
+  key: sourceReviewId, enrollmentKey: sourceEnrollmentId,
+  headClientId, reviewDate,
+  members: [
+    {clientId: headClientId, assessment: headInterimPlan},
+    {clientId: memberClientId, assessment: memberInterimPlan},
+  ],
+});
+```
+
+Each member receives their own assessment plan, enrollment ID, interim ID and verification recordset IDs in `result.members`. Use that member's returned IDs when closing and replacing verification rows. Interims accept a nonempty subset of currently enrolled members, including later entrants. The selected set is fixed under that interim key. Array order may change on retries; membership, dates and answers may not change under an existing key. The application still determines applicability, including child-specific questions and verification types.
+
+All member plans are validated before record creation. The workflow creates the head's entry through REST, attaches members using the existing GWT helper, then populates their assessments individually. One household interim operation creates the linked reviews, followed by each person's assessment writes. Fresh browser reads verify every member's provider, type, entry date, enrollment identity and review membership. These reads avoid the sandbox server's broken grouped enrollment REST projection. Existing independent member enrollments or same-date reviews cause a conflict instead of being silently merged.
+
+Client locks coordinate overlapping household and single-client operations. Durable household reservations block unrelated work after partial completion. A failed attachment, review or answer batch must be reconciled with the same keys and journal; no uncertain mutation is automatically resent. `getHouseholdStatus({headClientId,key})` reports local member progress and generated member keys, which can be passed to `getStatus({clientId,key})`. This is a resumable sequence, not an atomic transaction. The file store fails closed on a concurrent writer or leftover crash lock; inspect and reconcile such a lock before removing it.
+
+See the typed [household example](../examples/household-enrollment-workflow.mts) and [live household verification](capabilities.md). The integration uses the configured tenant and uses an isolated authenticated page.
+
+## Household exits
+
+Add `exitUi: createHouseholdExitUi({page: session.page})` to the workflow options. `discoverExit` returns the provider's entry, interim and exit definitions; use the exit definition to build each person's plan.
+
+```ts
+const exit = await workflow.exitHousehold({
+  key: sourceExitId, enrollmentKey: sourceEnrollmentId,
+  headClientId, exitDate,
+  destination: 'Rental by client, no ongoing housing subsidy',
+  reasonForLeaving: 'Completed program',
+  members: [
+    {clientId: headClientId, assessment: headExitPlan},
+    {clientId: memberClientId, assessment: memberExitPlan},
+  ],
+});
+```
+
+This requires a verified household entry in the same durable workflow store. Supply only the members exiting on this date, including a single member if needed; the household head need not be selected. Use separate stable keys for exits on different dates. Every exit plan is validated before saving. The browser submits one shared exit, then authoritative GWT reads verify every member's exit date, destination, reason and exact linked exit group before individual assessment writes. The returned members include `projectExitDate`, `exitSubgroupId` and any new verification `recordsetIds`. Exit dates cannot precede entry or an existing interim.
+
+Use `endDates` only for verification records that changed, with replacement rows in `subassessments`; use `carryForward` for unchanged groups. Ending enrollment does not automatically end all verification records. Stored dates are never shifted. Discovery and completeness checks do not decide individual eligibility or which verification types apply.
+
+Reusing the same key and unchanged plans reconciles against fresh reads without repeating writes, including after a lost save response. A partial household exit, unexpected linked member, conflicting exit metadata, schema drift, or an uncertain uncommitted save fails closed. Do not change keys or delete journals to bypass these checks. This remains a non-atomic sequence and does not prevent unrelated integrations or users from editing concurrently.
+
+The supplied Swagger has no exit mutation. The optional UI port exposes `listOptions({clientId,enrollmentId})` for available destination, reason and `rentalSubsidyTypes` choices. It opens the form and cancels without saving. Conditional exit details are shared by the selected members:
+
+```ts
+// Rental destination with an ongoing subsidy:
+const subsidyDetails = {
+  destination: 'Rental by client, with ongoing housing subsidy',
+  destinationDetails: {
+    kind: 'rental-subsidy' as const,
+    rentalSubsidyType: 'RRH or equivalent subsidy',
+  },
+  reasonForLeaving: 'Completed program',
+};
+// Separate explanations for the destination and reason:
+const otherDetails = {
+  destination: 'Other',
+  destinationDetails: {kind: 'other' as const, explanation: 'Application-provided destination explanation'},
+  reasonForLeaving: 'Other',
+  reasonForLeavingOther: 'Application-provided reason explanation',
+};
+// Spread the chosen details into exitHousehold alongside the key, date and member plans.
+```
+
+Subsidy types must match a currently available choice. Other explanations must contain 1 to 100 characters without leading/trailing whitespace or control characters. Missing, irrelevant or contradictory details fail before saving. The UI port fills each explanation beside its own labeled field and verifies the selected subsidy. `readExitDetails` reopens a saved member exit and reads its persisted details without saving. The workflow compares these details for every member on initial readback and retries; changed explanations or subsidy types conflict instead of being silently overwritten. Custom UI ports must implement `readExitDetails` to support conditional details. An unexpected legacy `Subsidy` form is still rejected because its storage contract has not been verified. Use the port through the journaled workflow, not as an independently idempotent writer. See the [typed exit example](../examples/household-exit-workflow.mts) and [live conditional-exit verification](capabilities.md).
+
+## Later household members and staggered exits
+
+`exitHousehold` and `createHouseholdInterim` accept selected members, including members added later. Continue supplying the original household `enrollmentKey` and `headClientId`. Each member retains their own enrollment ID and entry date. Exit subgroups are checked against the selected IDs; unselected enrollment dates, exits, conditional exit details and reviews are compared before and after a pending exit.
+
+Head of household is fixed for the enrollment. A proposed or detected head change is a red flag, including after the original head exits. Using another member as the UI/RPC target never promotes that member, and a later entrant cannot become the enrollment head. When the discovered assessment includes `HUD_RELATIONTOHOH`, household workflow plans reject answers that promote another member, demote the original head, or clear the relationship. Interim and exit preflight also reject conflicting stored relationships in that assessment. These checks do not govern independent raw API writes.
+
+An enrollment without a head of household is invalid data even when WellSky accepts it. Household helpers throw `EnrollmentWorkflowError` with an explicit `invalid enrollment data` reason when the designated head is absent or other members would remain enrolled beyond the head's exit. Preflight checks both existing records and the requested change before reserving or writing the operation, and readback checks the saved group. A head-only exit is allowed only after every other member has an exit at or before that date. A later child cannot join a group whose head has exited. Existing orphaned groups, including retries against them, require explicit reconciliation; the helper does not promote a replacement or silently repair dates. Closed groups with valid historical head coverage can still be retried without duplicate writes.
+
+Selecting every enrolled member in one `exitHousehold` call saves their exit metadata through one UI-generated `updateEntryExitWithHouseholdMembers` GWT request. Per-member assessment writes follow through REST, so the complete workflow is not atomic. [Live required-head acceptance](capabilities.md) verifies blocked head-first exits, separate member exits, head-last and all-member exits, unchanged retries, and persisted UI forms on new synthetic clients.
+
+When the discovered instrument exposes the head relationship question, the designated head must have a valid Self answer in the plan or at the assessment's effective date. Marking the question not applicable cannot substitute for a missing relationship. Standalone enrollment helpers treat the sole client as head. These guards cannot enforce constraints on writes made directly through WellSky or the raw REST/GWT APIs.
+
+A head correction must be a separate, explicit retroactive correction, and the replacement must have the same first entry date as the original head. This workflow does not implement that correction or silently change its journal identity. An actual change of head during participation generally requires exiting all enrollments and creating a fresh enrollment with the new head. A fresh entry may establish relationships different from prior assessment history.
+
+For a newborn or a child moving in later, establish the child in the existing household first, with the correct relationship and joined date. Then add a separate immutable operation:
+
+```ts
+const workflow = createEnrollmentWorkflow({
+  api, discovery, helpers: session.helpers, store,
+  birthDates: createDateOfBirth({api, store, ui: createDateOfBirthUi({page: session.page})}),
+  enrollmentSession: session.enrollmentSession,
+  exitUi: createHouseholdExitUi({page: session.page}),
+  memberEntryDatePort: createMemberEntryDatePort({
+    api, enrollmentSession: session.enrollmentSession,
+  }),
+});
+const child = await workflow.addHouseholdMembers({
+  key: sourceChildEntryId, enrollmentKey: sourceEnrollmentId, headClientId,
+  entryDate: childEntryDate,
+  members: [{clientId: childClientId, assessment: childEntryPlan}],
+});
+```
+
+The later date must follow the original household entry, and an existing member must still be enrolled. The child must have joined the household on or before their own entry date. New client and household-member creation remain separate operations. The application supplies age-appropriate answers and explicit applicability reasons; the SDK does not infer them.
+
+The workflow discovers and pins the new member's assessments, attaches the member through a fresh GWT request, then uses a date-only REST update for their enrollment. It verifies all linked enrollment dates and exits through GWT before populating answers and verification rows at the child's own entry date. Existing assessment dates are never rewritten. These stages are not atomic: a failure may leave a linked child awaiting the correct date or assessment completion. Keep the same journal and key to reconcile; an uncertain date update is never blindly resent.
+
+Retries can verify an earlier entry, addition or exit after later household changes without creating duplicates. All cooperating writers must share the durable store. External changes to enrollment identity, selected exit membership, or pending-operation preserved state cause a conflict. The UI adapter scopes checkbox selection to the active dialog because the additional-members popup can overlay another visible household tree.
+
+See the [typed lifecycle example](../examples/household-lifecycle-workflow.mts) and [sandbox verification](capabilities.md).
+
+## Current Living Situation contacts
+
+For street outreach and night-by-night shelter meaningful contacts, use the [Current Living Situation recorder](current-living-situation.md). Start always comes from program entry, information date comes from the contact, and end may be empty. Generic `subassessments` plans do not infer these event rules and can adopt an existing semantically matching row. They are not a distinct-contact recorder. Do not use the income replacement example to close or replace CLS contact history.

package/docs/files-and-notes.md

@@ -0,0 +1,39 @@
+# Upload files and record notes
+
+[Documentation index](README.md) · [Agent guide](../AGENTS.md)
+
+The snippets assume `session` from [browser session setup](browser-session.md), plus application-owned client, goal, and provider IDs.
+
+## Attachments and goal case notes
+
+After an attachment is adopted or created, retries require its saved attachment ID as well as matching bytes and metadata. A missing attachment or an identical replacement under a different ID is a conflict. Inspect the original record and journal; do not discard the journal to upload another copy.
+
+Conflicts raise the exported `AttachmentConflictError` with code `ATTACHMENT_CONFLICT` and a `reason`: `intent-changed`, `duplicate-name`, `identity-changed`, `content-changed`, or `unresolved`. Managed sessions preserve this error without probing or reauthenticating, so an unrelated expired session cannot turn a confirmed conflict into `SESSION_INTERRUPTED`. The next operation still checks authentication normally. Failed reads and uncertain new upload responses remain subject to session recovery and journal reconciliation.
+
+`session.workflows` provides browser-authenticated reads and writes:
+
+```js
+const uploaded = await session.workflows.uploadAttachment({
+  clientId,
+  location: { kind: 'goal', goalId }, // Or {kind:'profile'} / {kind:'case-plans'}.
+  file: { name: 'synthetic.txt', mimeType: 'text/plain', buffer: new TextEncoder().encode('Synthetic test') },
+  description: 'Synthetic test attachment',
+});
+const files = await session.workflows.listAttachments(clientId);
+const bytes = await session.workflows.downloadAttachment({
+  clientId, attachmentId: uploaded.attachment.attachmentId,
+});
+const note = await session.workflows.createCaseNote({
+  key: sourceGoalNoteId, clientId, goalId, providerId,
+  noteDate: '2026-10-21', note: 'Synthetic progress note',
+});
+const notes = await session.workflows.listCaseNotes({clientId, goalId});
+```
+
+Uploads are limited to 10,000,000 bytes and verified by downloading and hashing the stored bytes. Repeating the same client/location/name/content/description returns the existing attachment. Reusing the name with different content or description is a conflict. Supply a stable source key for case notes. Reusing it with changed intent raises `CASE_NOTE_SOURCE_CONFLICT`; saved note identity is also checked. Unkeyed legacy calls match the goal, client, provider, exact text, and browser-local calendar date. The helper verifies the provider shown by the goal's note form and saves only for the requested client. It does not switch providers or create notes for multiple household members. Existing identical notes are returned; partial or uncertain attempts are never automatically repeated. These helpers use the same durable store and do not change file visibility settings.
+
+The UI uses authenticated multipart `uploadAttachment` and `downloadAttachment`, while REST uses `fileAttachments.createForClient`/`getForClient` with credentials in the body in addition to the REST token. REST entity labels are `Client Profile`, `Case Plans`, and `Goal`; the UI uses `SpClient`, `CasePlans`, and `SpGoal`. In the tested tenant both REST attachment calls returned a credential/token mismatch even with the token account's credentials. Browser upload/readback succeeded at all three locations. Profile lists include attachments from other locations and paginate at five rows. No anonymous-access or other-provider visibility claim was tested.
+
+Further authentication testing reproduced the failure with native JSON and multipart requests outside the SDK. Ordinary client reads succeeded with the same fresh token. `SetAuthKey` issued a user-ID claim containing literal single quotes, which may affect attachment identity comparisons, but the server's root cause is unconfirmed. Alternate documented authentication routes did not yield a working attachment token. No password transformation or token modification is applied by the SDK.
+
+Use [journaled case-plan helpers](durable-records.md#create-and-update-client-notes-goals-and-action-steps) for Client Notes, goals, and action steps. Raw REST create/update/read methods are also available but do not provide durable retry protection. Include `clientId` when updating a goal; the tested server rejected an update without it despite the optional Swagger field. Goal case notes use the paper icon in the Notes column or Add Case Note inside the goal; they are distinct from Client Notes. The REST goal response did not expose these case notes. Observed goal responses also included unrelated `households` rows while the goal had no household association; do not use that nested array to choose clients for a write.

package/docs/getting-started.md

@@ -0,0 +1,56 @@
+# Read a synthetic client without an HMIS account
+
+[Documentation index](README.md) · [Using the SDK](using-the-sdk.md)
+
+This example reads one synthetic client through the SDK's real validation and transport code. The fake transport cannot send requests to WellSky.
+
+## Install the package
+
+Use Node 22 or newer, then install from the default npm registry:
+
+```sh
+npm install @choiceapps/communityservices-sdk
+```
+
+If you are in the SDK source checkout, run `npm ci` and `npm run build` in `packages/wellsky-sdk` instead. This builds the package's self-referenced imports.
+
+## Run the read
+
+Save the following as `quickstart.mjs` in your application directory:
+
+<!-- checked-example: examples/quickstart.mjs -->
+```js
+import assert from 'node:assert/strict';
+import {createFakeWellSkyClient} from '@choiceapps/communityservices-sdk/testing';
+import {toItems} from '@choiceapps/communityservices-sdk';
+
+const client = createFakeWellSkyClient();
+client.fake.set('GET /clients/{clientId}', {
+	kind: 'reply', body: [{clientId: 123, firstName: 'Synthetic'}],
+});
+const people = toItems(await client.clients.get({path: {clientId: 123}}));
+assert.equal(people.length, 1);
+assert.equal(people[0].clientId, 123);
+assert.equal(client.fake.calls.length, 1);
+console.log('Read synthetic client 123; no network requests.');
+```
+
+Run it:
+
+```sh
+node quickstart.mjs
+```
+
+Expected output:
+
+```text
+Read synthetic client 123; no network requests.
+```
+
+The same file ships as [examples/quickstart.mjs](../examples/quickstart.mjs). From the SDK checkout, run `node examples/quickstart.mjs` after the build.
+
+## Connect your application
+
+For a real read, construct a `WellSkyClient` with your tenant and credentials from your server's secret store. Follow [Configure a client](rest-client.md#configure-a-client). Replace the synthetic ID with an authorized client ID from your application.
+
+For mutations, first choose a verified workflow from the [capability table](capabilities.md). Preserve its journal and stable keys. Do not convert this example into a retry loop around a raw write.

package/docs/independent-needs.md

@@ -0,0 +1,77 @@
+# Independent needs and service types
+
+`createNeedRecorder` records a need without a service or referral. This supports workflows such as a Point in Time count's need for emergency shelter. The supplied V2/V3 Swagger documents reads of needs, but no independent-need create operation or service taxonomy catalog. These helpers therefore use the authenticated UI and counted GWT reads in the configured tenant.
+
+```ts
+import {
+  createNeedUi, createNeedRecorder,
+} from '@choiceapps/communityservices-sdk/browser';
+
+const ui = createNeedUi({page: session.page});
+const catalog = await ui.listServiceTypes({clientId});
+const quicklist = await ui.listServiceQuicklist({clientId, providerId});
+// Let the application choose from quicklist.types or catalog.types.
+const chosen = catalog.types.find(t => t.serviceCodeId === selectedServiceCodeId);
+if (!chosen) throw new Error('Select an available service type');
+const needs = createNeedRecorder({ui, store});
+await needs.record({
+  key: sourceEventId, clientId, providerId,
+  serviceCodeId: chosen.serviceCodeId,
+  needDate: observedAt, // timezone-qualified instant, whole seconds
+  status: selectedStatus, outcome: selectedOutcome,
+  note: 'Synthetic PIT emergency shelter need',
+});
+```
+
+Custom adapters must supply an explicit `tenant` to `createNeedRecorder`; the packaged UI adapter supplies its bound connection automatically.
+
+The application supplies the provider, source event ID, date, and status/outcome. Choose labels from `quicklist.needOptions`. Independent needs do not default to Closed/Fully Met. A `Not Met` outcome can include `reasonUnmet`; `amount` optionally records a nonnegative financial amount with up to two decimal places. No household members are silently included.
+
+## REST route investigation
+
+Authenticated sandbox probes on October 24, 2026 found no standalone need-create route among eight candidates in either API V2 or V3. Live Swagger matched the pinned specifications.
+
+| POST route tested | V2 and V3 result |
+| --- | --- |
+| `/needs`, `/needs/create`, `/needs/add` | 405 Method Not Allowed; `Allow: GET` |
+| `/need/create`, `/services/needs/create`, `/needs/household/create` | 404 Not Found |
+| `/needs/create/0`, `/needs/household/create/0` | 404 Not Found |
+
+Probes used malformed JSON with no valid client IDs or write data. As a control, documented `POST /services/create` reached JSON validation and returned 400. `GET /needs/create` returned a validation error identifying `create` as an invalid `clientId`, confirming that this path matches `/needs/{clientId}` rather than a create action. No probe reached a valid write.
+
+These results rule out the tested routes, not every possible undocumented URL. The SDK continues to use the verified UI/GWT `saveNeeds` operation for independent creation. `/services/needs/household/update/{serviceId}` is an update associated with an existing service, not an independent create operation.
+
+## Discover types for both needs and services
+
+`listServiceTypes({clientId})` returns the **tenant-wide** catalog:
+
+- `codeSets`: configured code-set IDs and names, including AIRS Taxonomy when configured.
+- `types`: active assignable terms, each with `serviceCodeId`, taxonomy `code`, `description`, `codeSetId`, and `parentServiceCodeId`.
+
+`listServiceQuicklist({clientId, providerId})` separately returns the selected program/provider's `types` and `needOptions` (status, outcome, and unmet-reason picklists). It reads only that quicklist's terms, without fetching the full catalog. Service types are configured at the tenant level, not per user or program; quicklists are configured per program/provider. Both methods require an authenticated session. `clientId` supplies browser navigation context, not a catalog filter.
+
+The catalog follows the UI's exclusion of target-population Y codes and Modality/Delivery Format facets. It reads ordered, counted pages and rejects inconsistent counts, duplicate IDs, or catalogs above 50,000 terms. The provider quicklist is a convenience subset, not the full lookup. A parent ID can refer to an unassignable hierarchy node omitted from this selection list. Preserve the source code-set identity; do not assume every deployment uses AIRS or the same numeric IDs.
+
+Pass `chosen.serviceCodeId` to independent needs; pass `chosen.code` as `body.serviceCode` to the [service recorder](services.md). These choices describe service types, not eligibility, SSVF conditional fields, funding availability, or authorization to use a provider. Use the service recorder's separate SSVF and funding contracts for those fields. The SDK does not bundle the licensed taxonomy or publish tenant catalogs.
+
+## Cache the catalog in your application
+
+Cache `listServiceTypes` results **once per instance/tenant**, instead of fetching the full catalog for every form, user, program, or transaction. The sandbox catalog contained 2,835 assignable terms when verified; its count and contents can change. Serve the cached list to your type selector and reuse the selected ID/code for subsequent transactions. The write helper opens its own fresh form and checks that the selected code is still active and assignable; it does not enumerate the entire catalog before every save.
+
+Cache `listServiceQuicklist` separately by **instance/tenant and provider/program ID**. When the application switches programs, fetch or reuse that program's small quicklist and combine it with the existing tenant catalog. Do not invalidate the tenant catalog just because the program or user changes. The application still controls which users may access its cached data.
+
+Use a configurable TTL appropriate to how often your organization changes configuration, such as one hour as an application starting point, and offer an explicit refresh. Invalidate the tenant catalog when service-type/code-set configuration changes, and invalidate the affected program's quicklist when its configuration changes. If a selected code is no longer accepted, refresh and have the application resolve the choice; do not substitute another code automatically. Coalesce concurrent refreshes so several forms do not fetch the same catalog repeatedly. Keep cached tenant/licensed taxonomy data within your application's authorized scope.
+
+This is an application cache recommendation, not a built-in SDK cache or a promise that an old selection remains valid. Do **not** cache need-record reads used for duplicate detection, journal reconciliation, or post-save verification. Those reads must remain fresh.
+
+## Retry and verification contract
+
+Keep a persistent [mutation store](browser-session.md) and the same source key across restarts. A hash marker is appended to the need note. Source keys are scoped across clients, so reusing a key for another client or changed input is rejected before any browser operation.
+
+The adapter opens a fresh Add Need form, journals immediately before its single Save & Exit click, and performs counted reads of active needs and service/referral links. It verifies the client, provider, code ID, exact stored instant, note, amount, status, outcome, unmet reason, and absence of associated service records. Stored dates are not shifted.
+
+An identical retry verifies the original ID without another save. A lost response can reconcile if the marker and fields identify one saved record. Missing records after an attempted save, duplicate markers, replaced IDs, edited fields, or subsequently attached services produce `NeedConflictError` (`code: NEED_CONFLICT`). Inspect its `reason`; do not regenerate the key to bypass it. A failed read never proves absence. There is no server-side idempotency key and no protection against unrelated external writers copying the marker.
+
+Use a dedicated managed page. Close any unfinished form or dialog before reconciling an interrupted save. Reauthentication never replays the save. `ui.list({clientId})` provides counted stored readback; the REST SDK's `needs.getComplete` remains available for a second read. The REST representation may omit the financial amount.
+
+See the shipped [independent-needs example](../examples/independent-needs.mts) for discovery, PIT recording, and using the same selected type with a service.