@choiceapps/communityservices-sdk 0.8.0 → 0.8.1

package/API.md

@@ -84,3 +84,248 @@ Both versions have the methods below. Import from `@choiceapps/communityservices
 | `tenants.update` | PUT | `/tenants/UpdateTenantRecord` |  |
 | `tenants.updateByCode` | PUT | `/tenants/UpdateTenantRecord/{tenant_code}` |  |
 | `tenants.delete` | DELETE | `/tenants/DeleteTenantRecord` |  |
+
+## Enrollment workflow errors
+
+This SDK-owned code inventory is generated from the workflow guards and stable reason map. These codes are separate from the REST Swagger operations above. Classify errors by `code`, never by message text. Existing codes remain stable when wording changes; later releases may add codes. Application-supplied constructor codes are outside this inventory.
+
+`EnrollmentWorkflowError.operation` identifies the SDK operation. `committed: false` means that operation has not attempted a WellSky record write; it does not promise that no local journal exists or that another operation wrote nothing. `committed: "unknown"` preserves an attempted or unreadable prior outcome. Never choose a new key solely from an HTTP status or unchanged read.
+
+A preflight refusal after enrollment creation can identify `step: "scalars"` while the enrollment is already saved. Keep the same key and reconcile the existing journal. A failed `resolveEntryCorrection` can have `committed: false` for resolution itself and `originalCommitted: "unknown"` for the original correction. See [recovery guidance](docs/troubleshooting.md#workflow-error-codes).
+
+| Code | Reason or meaning |
+| --- | --- |
+| `ACTIVE_CLIENT_REQUIRED` | active client required |
+| `ACTIVE_HOUSEHOLD_REQUIRED` | active household required |
+| `ACTIVE_HOUSEHOLD_REQUIRED_FOR_ADOPTION` | active household required for adoption |
+| `ACTIVE_OPERATIONAL_PROGRAM_REQUIRED` | active operational program required |
+| `ADDED_ENROLLMENT_IDENTITY_CHANGED` | added enrollment identity changed |
+| `ADDITION_REQUIRES_NEW_HOUSEHOLD_MEMBERS` | addition requires new household members |
+| `ADDITIONAL_MEMBER_ALREADY_HAS_AN_INDEPENDENT_ENROLLMENT` | additional member already has an independent enrollment |
+| `ADDITIONAL_MEMBER_ASSESSMENT_CONFIGURATION_CHANGED` | additional member assessment configuration changed |
+| `ADDITIONAL_MEMBER_ENTRY_MUST_FOLLOW_ORIGINAL_ENTRY` | additional member entry must follow original entry |
+| `ADOPTED_ENROLLMENT_IDENTITY_OR_CONFIGURATION_CHANGED` | adopted enrollment identity or configuration changed |
+| `ADOPTION_COMPLETE_COHORT_REQUIRED` | adoption requires the complete linked enrollment cohort |
+| `ADOPTION_ENROLLMENT_CONTEXT_MISMATCH` | adoption enrollment context mismatch |
+| `ADOPTION_EXIT_PRECEDES_ENTRY` | adoption exit precedes entry |
+| `ADOPTION_HOUSEHOLD_HEAD_MISMATCH` | adoption household head mismatch |
+| `ADOPTION_HOUSEHOLD_MEMBERSHIP_MISMATCH` | adoption household membership mismatch |
+| `ADOPTION_HOUSEHOLD_REQUIRED` | linked household enrollment requires adoptHouseholdEnrollment |
+| `ADOPTION_KEY_CONFLICTS_WITH_PREVIOUS_INTENT` | adoption key conflicts with previous intent |
+| `ADOPTION_REQUIRES_THE_ORIGINAL_ENROLLMENT_HEAD_RELATIONSHIP` | adoption requires the original enrollment head relationship |
+| `AMBIGUOUS_ASSESSMENT_READ` | ambiguous assessment read |
+| `AMBIGUOUS_CLOSURE_SNAPSHOT` | ambiguous closure snapshot |
+| `AMBIGUOUS_CORRECTION_ASSESSMENT_READ` | ambiguous correction assessment read |
+| `AMBIGUOUS_CORRECTION_ROW` | ambiguous correction row |
+| `AMBIGUOUS_CORRECTION_ROW_CELL` | ambiguous correction row cell |
+| `AMBIGUOUS_HOUSEHOLD_MEMBERSHIP` | ambiguous household membership |
+| `ANOTHER_UNFINISHED_HOUSEHOLD_WORKFLOW_MUST_BE_RECONCILED_FIRST` | another unfinished household workflow must be reconciled first |
+| `ANOTHER_UNFINISHED_WORKFLOW_MUST_BE_RECONCILED_FIRST` | another unfinished workflow must be reconciled first |
+| `ANSWER_ENCODING_UNAVAILABLE` | answer encoding unavailable |
+| `ASSESSMENT_FIELD_UNCOVERED` | assessment field uncovered |
+| `ASSESSMENT_LOCATIONS_MUST_BE_A_MAP_BY_ENTRY_EXIT_TYPE` | assessment locations must be a map by Entry/Exit type |
+| `ASSESSMENT_LOCATIONS_REQUIRED` | assessment locations required |
+| `ASSESSMENT_METADATA_INCOMPLETE` | assessment metadata incomplete |
+| `ASSESSMENT_PLAN_REQUIRED` | assessment plan required |
+| `ATTEMPTED_CORRECTION_REQUIRED_FOR_RESOLUTION` | attempted correction required for resolution |
+| `AUTHORITATIVE_ADOPTION_EXIT_DATE_REQUIRED` | authoritative adoption exit date required |
+| `AUTHORITATIVE_ENROLLMENT_SESSION_REQUIRED_FOR_ADOPTION` | authoritative enrollment session required for adoption |
+| `AUTHORITATIVE_EXIT_DETAILS_READER_REQUIRED` | authoritative exit details reader required |
+| `AUTHORITATIVE_EXIT_READ_REQUIRED` | authoritative exit read required |
+| `AUTHORITATIVE_HEAD_OF_HOUSEHOLD_EXIT_DATES_REQUIRED` | authoritative head of household exit dates required |
+| `AUTHORITATIVE_INDIVIDUAL_EXIT_READ_REQUIRED` | authoritative individual exit read required |
+| `CARRY_FORWARD_BIRTH_DATE_CHANGED_SINCE_ENROLLMENT` | carry-forward birth date changed since enrollment |
+| `CARRY_FORWARD_BIRTH_DATE_IS_EMPTY_OR_FOLLOWS_ASSESSMENT_DATE` | carry-forward birth date is empty or follows assessment date |
+| `CARRY_FORWARD_FIELD_IS_EMPTY` | carry-forward field is empty |
+| `CLIENT_ID_REQUIRED` | client ID required |
+| `CLIENT_PROVIDER_AND_SUPPORTED_ENTRY_EXIT_TYPE_REQUIRED` | client, provider and supported Entry/Exit type required |
+| `CONFLICTING_FIELD_COVERAGE` | conflicting field coverage |
+| `CORRECTION_ANSWER_COULD_NOT_BE_ENCODED` | correction answer could not be encoded |
+| `CORRECTION_KEY_CONFLICTS_WITH_PREVIOUS_INTENT` | correction key conflicts with previous intent |
+| `CORRECTION_LOOKUP_COULD_NOT_BE_RESOLVED` | correction lookup could not be resolved |
+| `CORRECTION_REQUIRES_AN_EXISTING_ENTRY_ROW_KEY_AND_MATCHING_PARENT` | correction requires an existing entry row key and matching parent |
+| `CORRECTION_ROW_METADATA_INCOMPLETE` | correction row metadata incomplete |
+| `CORRECTION_SCALAR_READ_MISSING` | correction scalar read missing |
+| `CORRECTION_STATE_CHANGED_DURING_RESOLUTION` | correction state changed during resolution |
+| `CORRECTION_STATE_DIFFERS_FROM_ITS_PRE_WRITE_SNAPSHOT_NON_APPLICATION_CANNOT_BE_RESOLVED` | correction state differs from its pre-write snapshot; non-application cannot be resolved |
+| `CORRECTION_SUBASSESSMENT_READ_MISSING` | correction subassessment read missing |
+| `CORRECTION_WAS_RESOLVED_AS_NOT_APPLIED_USE_A_NEW_KEY_FOR_A_CORRECTED_INTENT` | correction was resolved as not applied; use a new key for a corrected intent |
+| `DESTINATION_AND_REASON_FOR_LEAVING_REQUIRED` | destination and reason for leaving required |
+| `DOB_AND_HOUSEHOLD_HEAD_CORRECTIONS_REQUIRE_THEIR_DEDICATED_WORKFLOWS` | DOB and household head corrections require their dedicated workflows |
+| `DOB_HELPER_REQUIRED_FOR_BIRTH_DATE_ANSWERS_AND_CARRY_FORWARD` | DOB helper required for birth-date answers and carry-forward |
+| `DOB_QUESTION_TYPE_CHANGED` | DOB question type changed |
+| `DUPLICATE_ADOPTION_TARGETS` | duplicate adoption targets |
+| `DUPLICATE_CORRECTION_JOURNAL_KEYS` | duplicate correction journal keys |
+| `DUPLICATE_HOUSEHOLD_JOURNAL_KEYS` | duplicate household journal keys |
+| `DUPLICATE_HOUSEHOLD_MEMBER_ENROLLMENT` | duplicate household member enrollment |
+| `DUPLICATE_HOUSEHOLD_REVIEW_IDS` | duplicate household review IDs |
+| `DUPLICATE_JOURNAL_KEYS` | duplicate journal keys |
+| `DUPLICATE_MATCHING_ENROLLMENTS` | duplicate matching enrollments |
+| `DUPLICATE_MATCHING_SUBASSESSMENT_ROWS` | duplicate matching subassessment rows |
+| `DUPLICATE_SEMANTIC_SUBASSESSMENT_ROWS` | duplicate semantic subassessment rows |
+| `DUPLICATE_SUBASSESSMENT_KEY` | duplicate subassessment key |
+| `EMPTY_ENTRY_CORRECTION` | empty entry correction |
+| `EMPTY_ROW_CORRECTION` | empty row correction |
+| `END_DATE_PRECEDES_RECORD_START` | end date precedes record start |
+| `END_DATE_TARGET_INTERVAL_MISSING` | end-date target interval missing |
+| `END_DATE_TARGET_MISSING` | end-date target missing |
+| `ENROLLMENT_ALREADY_JOURNALED_USE_ITS_EXISTING_ENTRY_KEY` | enrollment already journaled; use its existing entry key |
+| `ENROLLMENT_COUNT_UNAVAILABLE_OR_CHANGED` | enrollment count unavailable or changed |
+| `ENROLLMENT_LIST_CONTEXT_MISMATCH` | enrollment list context mismatch |
+| `ENROLLMENT_LIST_EXCEEDS_LIMIT` | enrollment list exceeds limit |
+| `ENROLLMENT_NOT_GROUPED` | standalone enrollment uses adoptEnrollment |
+| `ENROLLMENT_READ_FAILED` | enrollment read failed |
+| `ENTRY_AND_INTERIM_ASSESSMENT_LOCATIONS_REQUIRED_EXIT_LOCATION_MUST_BE_NONEMPTY_WHEN_SUPPLIED` | entry and interim assessment locations required; exit location must be nonempty when supplied |
+| `ENTRY_CHANGED_SINCE_CORRECTION_PREFLIGHT` | entry changed since correction preflight |
+| `ENTRY_CORRECTION_DID_NOT_VERIFY` | entry correction did not verify |
+| `ENTRY_CORRECTION_ENROLLMENT_CONTEXT_MISMATCH` | entry correction enrollment context mismatch |
+| `ENTRY_CORRECTION_MUST_PRECEDE_INTERIM_OR_EXIT_WORKFLOWS` | entry correction must precede interim or exit workflows |
+| `ENTRY_CORRECTION_REJECTED` | correction was resolved as not applied; use a new key for a corrected intent<br>entry correction rejected |
+| `ENTRY_CORRECTION_REQUIRES_AN_OPEN_ENROLLMENT_WITHOUT_REVIEWS` | entry correction requires an open enrollment without reviews |
+| `ENTRY_CORRECTION_UNCERTAIN` | entry correction uncertain<br>uncertain entry correction requires reconciliation |
+| `EXISTING_EXIT_CONFLICTS_WITH_REQUESTED_EXIT` | existing exit conflicts with requested exit |
+| `EXISTING_HOUSEHOLD_REVIEW_CONFLICT` | existing household review conflict |
+| `EXIT_ASSESSMENT_CONFIGURATION_CHANGED` | exit assessment configuration changed |
+| `EXIT_IDENTITY_CHANGED` | exit identity changed |
+| `EXIT_IDENTITY_MISSING` | exit identity missing |
+| `EXIT_PRECEDES_AN_EXISTING_REVIEW` | exit precedes an existing review |
+| `EXIT_SUBGROUP_IDENTITY_CHANGED` | exit subgroup identity changed |
+| `EXIT_SUBGROUP_MEMBERSHIP_MISMATCH` | exit subgroup membership mismatch |
+| `EXIT_UI_AND_AUTHORITATIVE_ENROLLMENT_SESSION_REQUIRED` | exit UI and authoritative enrollment session required |
+| `EXIT_UI_DESTINATION_AND_REASON_FOR_LEAVING_REQUIRED` | exit UI, destination and reason for leaving required |
+| `EXPLICIT_ENROLLMENT_TARGETS_REQUIRED` | explicit enrollment targets required |
+| `HEAD_AND_HOUSEHOLD_MEMBERS_REQUIRED` | head and household members required |
+| `HEAD_CLIENT_ID_REQUIRED` | head client ID required |
+| `HEAD_OF_HOUSEHOLD_ASSESSMENT_OPTION_UNRESOLVED` | head of household assessment option unresolved |
+| `HEAD_OF_HOUSEHOLD_CHANGE_IS_A_RED_FLAG_USE_A_SEPARATE_RETROACTIVE_CORRECTION_FOR_A_MEMBER_WITH` | head of household change is a red flag; use a separate retroactive correction for a member with the same first entry date, or exit all enrollments and create a fresh enrollment |
+| `HOUSEHOLD_API_AND_AUTHORITATIVE_ENROLLMENT_SESSION_REQUIRED` | household API and authoritative enrollment session required |
+| `HOUSEHOLD_DISCOVERY_AMBIGUOUS` | a unique current household matching the full cohort, head and dates is required |
+| `HOUSEHOLD_DISCOVERY_COHORT_CHANGED` | household membership changed during discovery<br>linked enrollment cohort changed during discovery |
+| `HOUSEHOLD_DISCOVERY_DETAIL_INVALID` | complete linked enrollment cohort required<br>group flag conflicts with linked cohort |
+| `HOUSEHOLD_DISCOVERY_INPUT_INVALID` | head client and enrollment IDs required |
+| `HOUSEHOLD_DISCOVERY_LIST_INCOMPLETE` | household list count unavailable or changed<br>incomplete household list<br>invalid household list |
+| `HOUSEHOLD_DISCOVERY_NOT_FOUND` | a unique current household matching the full cohort, head and dates is required |
+| `HOUSEHOLD_DISCOVERY_READERS_REQUIRED` | GWT detail and complete household readers required |
+| `HOUSEHOLD_ENROLLMENT_CONTEXT_MISMATCH` | household enrollment context mismatch |
+| `HOUSEHOLD_ENROLLMENT_IDENTITY_CHANGED` | household enrollment identity changed |
+| `HOUSEHOLD_ENROLLMENT_MEMBERS_CHANGED` | household enrollment members changed |
+| `HOUSEHOLD_EXITS_ARE_NOT_LINKED` | household exits are not linked |
+| `HOUSEHOLD_HEAD_MISMATCH_HEAD_CHANGES_ARE_A_RED_FLAG_AND_REQUIRE_SEPARATE_RETROACTIVE` | household head mismatch; head changes are a red flag and require separate retroactive correction or a fresh enrollment |
+| `HOUSEHOLD_KEY_CONFLICTS_WITH_PREVIOUS_INTENT` | household key conflicts with previous intent |
+| `HOUSEHOLD_MEMBERS_UNAVAILABLE` | household members unavailable |
+| `HOUSEHOLD_MEMBERSHIP_CHANGED_WHILE_ACQUIRING_LOCKS_RETRY` | household membership changed while acquiring locks; retry |
+| `HOUSEHOLD_ORIGINAL_HEAD_AND_COMPLETE_ENROLLMENT_COHORT_REQUIRED` | household, original head and complete enrollment cohort required |
+| `HOUSEHOLD_PROGRAM_AND_SUPPORTED_ENTRY_EXIT_TYPE_REQUIRED` | household, program and supported Entry/Exit type required |
+| `HOUSEHOLD_REVIEW_IDENTITY_CHANGED` | household review identity changed |
+| `HOUSEHOLD_REVIEW_MEMBERSHIP_MISMATCH` | household review membership mismatch |
+| `HOUSEHOLD_REVIEWS_UNAVAILABLE` | household reviews unavailable |
+| `INCOMPLETE_ENROLLMENT_LIST` | incomplete enrollment list |
+| `INCOMPLETE_EXISTING_EXIT_METADATA` | incomplete existing exit metadata |
+| `INDEPENDENT_CONFIRMATION_REQUIRED` | independent non-application confirmation required |
+| `INDIVIDUAL_ENROLLMENT_CONTEXT_MISMATCH` | individual enrollment context mismatch |
+| `INDIVIDUAL_EXIT_MEMBERSHIP_MISMATCH` | individual exit membership mismatch |
+| `INTERIM_DID_NOT_VERIFY` | interim did not verify |
+| `INVALID_ASSESSMENT_PLAN` | invalid assessment plan |
+| `INVALID_CORRECTION_CLIENT_OR_ROWS` | invalid correction client or rows |
+| `INVALID_CORRECTION_DATE` | invalid correction date |
+| `INVALID_CORRECTION_EFFECTIVE_DATE` | invalid correction effective date |
+| `INVALID_ENROLLMENT_DATA_ADOPTED_MEMBERS_REQUIRE_MATCHING_PROGRAM_AND_HEAD_COVERAGE` | invalid enrollment data: adopted members require matching program and head coverage |
+| `INVALID_ENROLLMENT_DATA_ENROLLMENT_HAS_NO_HEAD_OF_HOUSEHOLD` | invalid enrollment data: enrollment has no head of household |
+| `INVALID_ENROLLMENT_DATA_HEAD_OF_HOUSEHOLD_RELATIONSHIP_IS_MISSING_OR_CLEARED` | invalid enrollment data: head of household relationship is missing or cleared |
+| `INVALID_ENROLLMENT_DATA_HOUSEHOLD_HAS_NO_ACTIVE_HEAD_OF_HOUSEHOLD` | invalid enrollment data: household has no active head of household |
+| `INVALID_ENROLLMENT_DATA_MEMBER_ENROLLMENT_WOULD_EXIST_WITHOUT_AN_ENROLLED_HEAD_OF_HOUSEHOLD` | invalid enrollment data: member enrollment would exist without an enrolled head of household; the original head must remain enrolled through every member exit; reconcile the data or exit all members and create a fresh enrollment |
+| `INVALID_ENROLLMENT_LIST` | invalid enrollment list |
+| `INVALID_HOUSEHOLD_ENROLLMENT_MEMBERS` | invalid household enrollment members |
+| `INVALID_HOUSEHOLD_JOURNAL` | invalid household journal |
+| `INVALID_OR_CONFLICTING_CORRECTION_ANSWERS_AND_CLEARS` | invalid or conflicting correction answers and clears |
+| `INVALID_OR_DUPLICATE_END_DATE_TARGET` | invalid or duplicate end-date target |
+| `INVALID_OR_REUSED_SUBASSESSMENT_ID` | invalid or reused subassessment ID |
+| `INVALID_STORED_CORRECTION_DATE` | invalid stored correction date |
+| `INVALID_STORED_CORRECTION_NUMBER` | invalid stored correction number |
+| `INVALID_SUBASSESSMENT_PLAN` | invalid subassessment plan |
+| `INVALID_WORKFLOW_JOURNAL` | invalid workflow journal |
+| `KEY_CONFLICTS_WITH_PREVIOUS_INTENT` | key conflicts with previous intent |
+| `LINKED_HOUSEHOLD_ENROLLMENT_REQUIRES_EXITHOUSEHOLD` | linked household enrollment requires exitHousehold |
+| `LOOKUP_WRITE_LABEL_UNAVAILABLE` | lookup write label unavailable |
+| `MANDATORY_CLEAR_CONFLICT` | mandatory clear conflict |
+| `MANDATORY_CORRECTION_FIELD_COULD_NOT_BE_ENCODED` | mandatory correction field could not be encoded |
+| `MANDATORY_CORRECTION_FIELD_REQUIRES_AN_EXPLICIT_ANSWER_OR_CLEAR` | mandatory correction field requires an explicit answer or clear |
+| `MANDATORY_CORRECTION_LOOKUP_LABEL_UNAVAILABLE` | mandatory correction lookup label unavailable |
+| `MATCHING_CORRECTION_JOURNAL_REQUIRED` | matching correction journal required |
+| `MEMBER_ALREADY_HAS_AN_INDEPENDENT_MATCHING_ENROLLMENT` | member already has an independent matching enrollment |
+| `MEMBER_CLIENT_AND_ASSESSMENT_REQUIRED` | member client and assessment required |
+| `MEMBER_ENROLLMENT_HAS_NOT_BEEN_ATTACHED` | member enrollment has not been attached |
+| `MEMBER_ENTRY_DATE_PORT_REQUIRED` | member entry date port required |
+| `MEMBER_EXIT_IDENTITY_MISSING` | member exit identity missing |
+| `MEMBER_IS_NOT_ACTIVE_IN_HOUSEHOLD_AT_ENTRY` | member is not active in household at entry |
+| `MOBILE_ANSWER_EXISTS` | mobile answer exists<br>mobile scalar answer already exists at the effective date |
+| `MOBILE_PREFLIGHT_UNAVAILABLE` | mobile preflight unavailable<br>mobile scalar preflight unavailable |
+| `MULTIPLE_END_DATE_OVERRIDES` | multiple end-date overrides |
+| `NEW_MEMBER_MUST_REMAIN_ENROLLED` | new member must remain enrolled |
+| `NOT_APPLICABLE_EXPLANATION_REQUIRED` | not-applicable explanation required |
+| `OPEN_HOUSEHOLD_ENROLLMENT_REQUIRED_TO_ADD_A_MEMBER` | open household enrollment required to add a member |
+| `PARTIAL_EXISTING_HOUSEHOLD_EXIT_REQUIRES_RECONCILIATION` | partial existing household exit requires reconciliation |
+| `PARTIAL_HOUSEHOLD_REVIEW_REQUIRES_RECONCILIATION` | partial household review requires reconciliation |
+| `PICKLIST_CATALOG_CONTEXT_MISMATCH` | picklist catalog client mismatch<br>picklist catalog context mismatch |
+| `PROGRAM_AND_SUPPORTED_ENTRY_EXIT_TYPE_REQUIRED` | program and supported Entry/Exit type required |
+| `PROGRAM_ASSESSMENT_CONFIGURATION_CHANGED` | program assessment configuration changed |
+| `PROGRAM_ASSESSMENT_DEFAULT_UNRESOLVED` | program assessment default unresolved |
+| `PROVIDER_DISCOVERY_MISMATCH` | provider discovery mismatch |
+| `RECORD_ALREADY_HAS_A_DIFFERENT_END_DATE` | record already has a different end date |
+| `RESOLUTION_EVIDENCE_REFERENCE_CHANGED` | resolution evidence reference changed |
+| `REST_API_DISCOVERY_ENROLLMENT_HELPERS_AND_DURABLE_STORE_REQUIRED` | REST API, discovery, enrollment helpers and durable store required |
+| `REVIEW_FOLLOWS_PROJECT_EXIT` | review follows project exit |
+| `REVIEW_PRECEDES_ENTRY` | review precedes entry |
+| `ROW_CLOSURE_MUST_FALL_BETWEEN_ENTRY_AND_ASSESSMENT` | row closure must fall between entry and assessment |
+| `ROW_REGISTRATION_BINDING_CONFLICT` | row key or recordset is already bound differently |
+| `ROW_REGISTRATION_CONTEXT_MISMATCH` | enrollment identity changed during row registration |
+| `ROW_REGISTRATION_ENTRY_REQUIRED` | verified enrollment workflow required |
+| `ROW_REGISTRATION_INPUT_INVALID` | unique row keys, parents and positive recordset IDs required<br>valid registration key, entry key, client and explicit rows required |
+| `ROW_REGISTRATION_INTENT_CONFLICT` | registration key conflicts with previous intent |
+| `ROW_REGISTRATION_PARENT_INVALID` | subassessment parent not in entry definition |
+| `ROW_REGISTRATION_READ_UNAVAILABLE` | complete row registration read required |
+| `ROW_REGISTRATION_READER_REQUIRED` | authoritative enrollment reader required |
+| `ROW_REGISTRATION_ROW_MISSING` | selected row is missing or ambiguous at the entry date or current read |
+| `SAVED_ENROLLMENT_MISSING` | saved enrollment missing |
+| `SAVED_ENROLLMENT_MISSING_OR_CHANGED` | saved enrollment missing or changed |
+| `SESSION_INTERRUPTED` | session interrupted<br>upstream workflow operation failed |
+| `STABLE_CORRECTION_KEY_REQUIRED` | stable correction key required |
+| `STABLE_KEY_REQUIRED` | stable key required |
+| `STANDARD_ASSESSMENT_WRITES_AND_AUTHORITATIVE_ENROLLMENT_READER_REQUIRED_FOR_CORRECTIONS` | standard assessment writes and authoritative enrollment reader required for corrections |
+| `STORED_EXIT_DETAILS_CONFLICT_WITH_REQUESTED_EXIT` | stored exit details conflict with requested exit |
+| `SUBASSESSMENT_READ_MISSING` | subassessment read missing |
+| `TIMEZONE_QUALIFIED_WHOLE_SECOND_DATE_REQUIRED` | timezone-qualified whole-second date required |
+| `UNCERTAIN_ENTRY_CORRECTION_REQUIRES_RECONCILIATION` | uncertain entry correction requires reconciliation |
+| `UNCERTAIN_HOUSEHOLD_EXIT_REQUIRES_RECONCILIATION` | uncertain household exit requires reconciliation |
+| `UNCERTAIN_MEMBER_ENTRY_DATE_REQUIRES_RECONCILIATION` | uncertain member entry date requires reconciliation |
+| `UNCERTAIN_WRITE_REQUIRES_RECONCILIATION` | uncertain write requires reconciliation |
+| `UNFINISHED_HOUSEHOLD_WORKFLOW_MUST_BE_RECONCILED_FIRST` | unfinished household workflow must be reconciled first |
+| `UNIQUE_MEMBERS_INCLUDING_HEAD_REQUIRED` | unique members including head required |
+| `UNKNOWN_CARRY_FORWARD_FIELD` | unknown carry-forward field |
+| `UNKNOWN_OR_INVALID_CORRECTION_FIELDS` | unknown or invalid correction fields |
+| `UNKNOWN_OR_INVALID_INPUT_FIELDS` | unknown or invalid input fields |
+| `UNSELECTED_HOUSEHOLD_MEMBER_CHANGED` | unselected household member changed |
+| `UNSELECTED_MEMBER_EXIT_IDENTITY_MISSING` | unselected member exit identity missing |
+| `UNSUPPORTED_CORRECTION_FIELD_TYPE` | unsupported correction field type |
+| `UNSUPPORTED_ENTRY_EXIT_TYPE_IN_ASSESSMENT_LOCATIONS` | unsupported Entry/Exit type in assessment locations |
+| `UNSUPPORTED_MANDATORY_CORRECTION_FIELD` | unsupported mandatory correction field |
+| `UNSUPPORTED_MANDATORY_FIELD_TYPE` | unsupported mandatory field type |
+| `UNSUPPORTED_YES_NO_CLEAR` | unsupported yes no clear<br>yes/no answers cannot be cleared |
+| `VERIFIED_CORRECTION_CANNOT_BE_REJECTED` | verified correction cannot be rejected |
+| `VERIFIED_ENROLLMENT_WORKFLOW_REQUIRED` | verified enrollment workflow required |
+| `VERIFIED_ENTRY_CORRECTION_CHANGED` | verified entry correction changed |
+| `VERIFIED_EXIT_MISSING` | verified exit missing |
+| `VERIFIED_HOUSEHOLD_ENTRY_REQUIRED` | verified household entry required |
+| `VERIFIED_HOUSEHOLD_ENTRY_WITH_IDENTICAL_MEMBERS_REQUIRED_UNKNOWN_SELECTED_MEMBER` | verified household entry with identical members required; unknown selected member |
+| `VERIFIED_ROW_CORRECTION_CHANGED` | verified row correction changed |
+| `VERIFIED_STEP_CHANGED` | verified step changed |
+| `WORKFLOW_CONFIGURATION_INVALID` | invalid workflow configuration<br>workflow configuration invalid |
+| `WORKFLOW_FAILED` | Unclassified workflow failure; inspect cause and commit markers. |
+| `WORKFLOW_JOURNAL_INVALID` | invalid workflow journal |
+| `WORKFLOW_PENDING` | unfinished household workflow must be reconciled first<br>unfinished workflow must be reconciled first |
+| `WORKFLOW_SCHEMA_CHANGED` | program assessment configuration changed |
+| `WORKFLOW_UPSTREAM_FAILURE` | upstream workflow operation failed<br>workflow upstream failure |
+| `WORKFLOW_VALIDATION_FAILED` | upstream workflow operation failed<br>workflow validation failed |
+| `YES_NO_ANSWERS_CANNOT_BE_CLEARED` | yes/no answers cannot be cleared |
+| `YES_NO_WRITE_MODE_CHANGED_SINCE_THIS_WORKFLOW_STARTED` | yes/no write mode changed since this workflow started |
+| `YESNOWRITES_MUST_BE_MOBILE_OR_STANDARD_WITH_WRITELABEL_AND_ASSESSMENTS_CREATE` | yesNoWrites must be mobile, or standard with writeLabel and assessments.create |

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.8.1 - 2026-11-11
+
+- Recheck mobile scalar collisions immediately before the first scalar-stage attempt, including answers that appeared after enrollment or review creation. Refuse known collisions and unavailable evidence without sending the batch or marking that stage attempted; preserve earlier lifecycle writes and prior-attempt reconciliation.
+- Give complete-cohort adoption, standalone adoption of grouped entries, and changed verified steps specific stable codes instead of `WORKFLOW_FAILED`.
+- Generate the complete enrollment workflow error-code reference in `API.md`; fail generation for new constant refusal reasons without codes, including conditional branches.
+- Clarify that household discovery verifies current membership, not the original historical association, and explicit IDs do not bypass active-membership validation.
+- Record the additional reported adoption/interim/correction acceptance from GitLab issues #5–#7, and distinguish the issue #2 report from the successful follow-up batch controls. The upstream partial-commit cause remains unresolved; no score-specific batch splitting is introduced.
+
 ## 0.8.0 - 2026-11-11
 
 - Resolve full lookup write labels without existing answers using `enrollmentSession.readPicklistOptions` and `createCatalogWriteLabelResolver`.

package/browser/enrollment-workflow.mjs

@@ -251,20 +251,20 @@ export function createEnrollmentWorkflow({api,discovery,helpers,store,enrollment
    // assessment's own rows. Read at the later of now and the assessment instant.
    const readCurrent=async()=>questions(await api.assessments.get({path:{clientId:input.clientId,assessmentCode:code},query:{dateEffective:new Date(Math.max(Date.now(),Date.parse(at))).toISOString().slice(0,19)+'Z'}}));
    // A generic read at exactly the effective instant returns null for yes/no answers saved at
-   // that instant; one second later returns them. Only the yes/no step needs this.
+   // that instant; one second later returns them. Scalar preflight and verification use this.
    const readSaved=async()=>questions(await api.assessments.get({path:{clientId:input.clientId,assessmentCode:code},query:{dateEffective:new Date(Date.parse(at)+1000).toISOString()}}));
-   const initial=await read();
-   if(!record&&plan.scalar.length){
-    const saved=await readSaved();
+   const assertScalarInsertable=saved=>{
     const existing=plan.scalar.map(q=>({q,row:saved.find(r=>r.virt_field_name===q.virt_field_name)}));
-    const complete=existing.every(({q,row})=>row&&sameAnswer(q,row.answer_value)&&restDate(row.date_effective)===restDate(at));
+    const complete=existing.every(({q,row})=>row&&row.question_type===q.question_type&&sameAnswer(q,row.answer_value)&&restDate(row.date_effective)===restDate(at));
     if(!complete){
      const unavailable=existing.filter(({q,row})=>!row||row.question_type!==q.question_type||row.date_effective!=null&&(!Number.isFinite(restDate(row.date_effective))||restDate(row.date_effective)>restDate(at))||row.date_effective==null&&row.answer_value!=null&&row.answer_value!=='').map(({q})=>q.virt_field_name);
-     if(unavailable.length)fail('mobile scalar preflight unavailable',{code:'MOBILE_PREFLIGHT_UNAVAILABLE',fields:unavailable});
+     if(unavailable.length)fail('mobile scalar preflight unavailable',{code:'MOBILE_PREFLIGHT_UNAVAILABLE',step:'scalars',fields:unavailable});
      const collisions=existing.filter(({row})=>restDate(row.date_effective)===restDate(at)).map(({q})=>q.virt_field_name);
-     if(collisions.length)fail('mobile scalar answer already exists at the effective date',{code:'MOBILE_ANSWER_EXISTS',fields:collisions});
+     if(collisions.length)fail('mobile scalar answer already exists at the effective date',{code:'MOBILE_ANSWER_EXISTS',step:'scalars',fields:collisions});
     }
-   }
+   };
+   const initial=await read();
+   if(!record&&plan.scalar.length)assertScalarInsertable(await readSaved());
    if(expectedHead===input.clientId&&headQuestion)checkHeadAnswer(proposedHead?.answer_value??initial.find(q=>q.virt_field_name==='HUD_RELATIONTOHOH')?.answer_value);
    for(const field of plan.carry.filter(field=>field!=='SVPPROFDOB')){if(kind==='entry'&&record?.correctedScalars?.[field])continue;const q=initial.find(q=>q.virt_field_name===field);if(!q||(q.question_type==='sub_assessment'?!q.sub_assessment_answer_list?.length:!q.answer_value))fail('carry-forward field is empty');}
    // Resend mandatory answers with the standard yes/no write. A blank write must not hide a recorded value.
@@ -370,7 +370,13 @@ export function createEnrollmentWorkflow({api,discovery,helpers,store,enrollment
     },()=>api.subassessments.setEndDate({clientId:input.clientId,assessmentCode:code,effectiveDate:at,parentField:end.parentField,recordsetId:end.recordsetId,endDateField:end.endDateField,endDate:end.endDate}));
    }
    if(plan.scalar.length)await step('scalars',async()=>{
-    const source=kind==='entry'&&record.correctedScalars?await readSaved():await read();return {found:plan.scalar.every(original=>{const q=kind==='entry'?record.correctedScalars?.[original.virt_field_name]??original:original,r=source.find(r=>r.virt_field_name===q.virt_field_name);return r&&sameAnswer(q,r.answer_value)&&(q.answer_value===''||restDate(r.date_effective)===restDate(at));}),value:plan.scalar.map(q=>q.virt_field_name)};
+    const source=await readSaved();
+    const found=plan.scalar.every(original=>{const q=kind==='entry'?record.correctedScalars?.[original.virt_field_name]??original:original,r=source.find(r=>r.virt_field_name===q.virt_field_name);return r&&r.question_type===q.question_type&&sameAnswer(q,r.answer_value)&&(q.answer_value===''||restDate(r.date_effective)===restDate(at));});
+    // Enrollment/review creation or another writer can populate shared questions after
+    // initial preflight. Refuse a known collision before journaling this first attempt.
+    // Prior attempts remain reconciliation-only, even when only part of a batch saved.
+    if(!found&&!record.steps.scalars)assertScalarInsertable(source);
+    return {found,value:plan.scalar.map(q=>q.virt_field_name)};
    },()=>api.assessmentsMobile.addAnswer({path:{clientId:input.clientId,assessmentCode:code},query:{dateEffective:at},body:plan.scalar}));
    // Standard writes update existing dated rows and change only the answers sent.
    if(plan.yesNo.length){const body=[...plan.yesNo,...mandatory.map(({expected,...q})=>q)],expected=[...plan.yesNo,...mandatory.map(({expected,...q})=>({...q,answer_value:expected}))];

package/browser/workflow-error-codes.mjs

@@ -1,5 +1,8 @@
 // Stable public codes. Keep code values when changing their associated messages.
 const codes = new Map([
+ ["adoption requires the complete linked enrollment cohort", "ADOPTION_COMPLETE_COHORT_REQUIRED"],
+ ["linked household enrollment requires adoptHouseholdEnrollment", "ADOPTION_HOUSEHOLD_REQUIRED"],
+ ["verified step changed", "VERIFIED_STEP_CHANGED"],
  ["DOB and household head corrections require their dedicated workflows", "DOB_AND_HOUSEHOLD_HEAD_CORRECTIONS_REQUIRE_THEIR_DEDICATED_WORKFLOWS"],
  ["DOB helper required for birth-date answers and carry-forward", "DOB_HELPER_REQUIRED_FOR_BIRTH_DATE_ANSWERS_AND_CARRY_FORWARD"],
  ["DOB question type changed", "DOB_QUESTION_TYPE_CHANGED"],

package/docs/assessments.md

@@ -73,7 +73,7 @@ Reproduced on November 2, 2026 in a sandbox tenant with synthetic clients:
 
 - **Mobile `AddAssessmentAnswer` does not store yes/no values.** Requests with `"Yes"`, `"1"`/`"0"`, and `"true"`/`"false"` returned success and created a row at the intended effective date, but its value read back empty through both the generic and mobile reads. An integrator's 30-answer entry batch showed the same result.
 - **Mobile writes are insert-only per question and effective date.** A second mobile write to any question that already has a row at that date returned HTTP 400 `An error occurred while saving the entity changes`. This affected yes/no and integer questions alike, so a mobile retry cannot repair an empty yes/no row.
-- **A failed mobile batch can still save part of its answers.** On November 2, 2026, an integrator's 15-answer batch returned HTTP 400 a few seconds after the client's household enrollment and entry answers were created. Afterwards one of the 15 answers was stored and the others were empty. Its error body was not captured, and the client's rows just before the send were not read. Later sends of the batch failed with the insert-only error above because that row existed. On November 3, the same byte-identical batch returned 200 and read back completely on fresh synthetic clients with no enrollment, an enrolled single adult, and an enrolled household head; batches with and without the score total question, and in either order, also succeeded. The cause is unknown; a race with enrollment creation is possible but unproven. Treat a failed mobile write as uncertain and reconcile it from a read, as the enrollment workflow does; never resend it.
+- **A failed mobile batch can still save part of its answers.** An integrator's November 2, 2026 report describes a 15-answer batch returning HTTP 400 with only the score total saved. GitLab issue #2 reports a captured entity-save error and no prior rows; separate retained notes describe a send shortly after household enrollment and do not retain a before-write snapshot. These accounts do not establish the same pre-write state. Later sends of the batch failed with the insert-only error above because that row existed. On November 3, the same byte-identical batch returned 200 and read back completely on fresh synthetic clients with no enrollment, an enrolled single adult, and an enrolled household head; batches with and without the score total question, and in either order, also succeeded. The cause is unknown; a race with enrollment creation is possible but unproven. Treat a failed mobile write as uncertain and reconcile it from a read, as the enrollment workflow does; never resend it.
 - **Standard `assessments.create` stores `"Yes"`/`"No"`.** It rejects `"true"`/`"false"`. It updates existing rows at the same effective date, including empty yes/no rows created by mobile writes, and changed only the answers it was sent in a full before/after comparison.
 - **Every standard write must include every mandatory answer**, even one already recorded at that date; otherwise it returns `All mandatory answers are not provided`. A conditionally mandatory lookup that does not apply can be sent as `""`; it is stored empty at that date.
 - **Generic reads omit yes/no answers at exactly their effective instant.** `assessments.get` with `dateEffective` equal to the saved instant returns `null` for those yes/no answers while other types read normally. One second later returns the saved value. The standard create response has the same omission. Mobile reads return the value, but they have no date filter and show only the latest row, so a later record hides the date being checked.
@@ -101,7 +101,9 @@ await writeMobileAnswersChecked(api, {
 
 `MobileAnswerPreflightError` has a stable `code`, affected `fields`, and `committed: false`. A collision uses `MOBILE_ANSWER_EXISTS`; unavailable evidence uses `MOBILE_PREFLIGHT_UNAVAILABLE`. The helper checks scalars, including questions shared across instruments, but does not detect duplicate subassessment rows. It makes one write after a successful preflight and does not retry or journal it. An error from that write retains its original type and possible uncertain outcome. Reads and writes are not atomic against other users. Pass the original instant; the SDK transport applies any configured mobile date correction.
 
-New enrollment workflow plans also check scalar collisions before creating an enrollment or sending a mobile batch. Existing pending journal operations retain their reconciliation behavior.
+Enrollment workflow plans check scalar collisions before creating an enrollment and again immediately before the first scalar batch. An answer can appear during enrollment/review creation or from another writer after the earlier read. If the complete requested scalar state already matches, the workflow verifies it without another insert. If only some rows occupy the instant, or their values conflict, it refuses before marking the scalar stage attempted. Unavailable evidence also blocks that first attempt.
+
+If an earlier enrollment, review or exit stage was already attempted, this refusal still has `committed: 'unknown'` for the overall operation and `step: 'scalars'`. Keep the existing key and journal; the enrollment may already exist. Reconcile the stored answers before resuming. Previously attempted scalar stages retain their normal uncertain-write reconciliation and are never resent or split automatically. No read-before-write check eliminates changes after the last read.
 
 ## Race and ethnicity combinations
 

package/docs/capabilities.md

@@ -96,7 +96,7 @@ The integrator reports these training-tenant results on November 10 and 11, 2026
 - Three pending 0.5.0 corrections were refused without confirmation and resolved as `rejected` with confirmation.
 - Earlier 0.5.0 runs verified individual/household adoption followed by exit, household re-enrollment after exit, and path corrections in both directions for individuals and households, with no-write same-key repeats.
 
-The integrator has not tested household adoption followed by `createHouseholdInterim`, scalar correction on an adopted enrollment, or a new correction key after resolution. Synthetic tests do not replace that acceptance.
+Further integrator reports in GitLab issues #5, #6 and #7 confirm three additional 0.6.0 paths on November 11: household adoption followed by `createHouseholdInterim` (a session interruption reauthenticated, and a same-key retry verified without a duplicate review); scalar-only correction on an adopted enrollment (same-key retry wrote nothing); and a new correction key after the original correction was resolved as not applied. These are reported live results, not an independent SDK-team rerun. Row corrections on adopted entries require the later `registerEntryRows` API.
 
 The 0.7.0 label resolver, group flags, household discovery, row registration, error codes and mobile collision preflight have local regression coverage, not new live tenant acceptance. In 0.7.0, full write labels remained unresolved for unobserved options; the 0.8.0 catalog reader below removes that limitation when UI catalog access is available. Household discovery refuses ambiguous current-membership matches. Yes/no blanking remains unsupported; no alternative route has been verified.
 

package/docs/enrollments.md

@@ -280,7 +280,7 @@ const adopted = await workflow.adoptHouseholdEnrollment({
 });
 ```
 
-Discovery reads the linked enrollment cohort through GWT and matches it against complete current household membership reads. It requires one household containing the cohort, the same head, and membership dates covering each entry. It verifies that household again before returning `householdSource: 'verified-membership'`. This is a verified membership match, not a native historical household pointer on the enrollment. Zero matches, multiple matches, incomplete reads or changed relationships fail without adopting. Historical households that no longer match require the existing explicit adoption inputs and their validation. No record is written to WellSky during discovery or adoption.
+Discovery reads the linked enrollment cohort through GWT and matches it against complete current household membership reads. It requires one household containing the cohort, the same head, and membership dates covering each entry. It verifies that household again before returning `householdSource: 'verified-membership'`. This is a verified membership match, not a native historical household pointer on the enrollment. Zero matches, multiple matches, incomplete reads or changed relationships fail without adopting. A unique current match does not prove the enrollment's original historical household association. If that original association is required, verify it independently; the SDK does not expose a native historical pointer. Explicit adoption inputs still require active household membership, the matching head and valid dates. Known historical IDs cannot bypass those guards, so inactive or changed historical households remain unsupported. No record is written to WellSky during discovery or adoption.
 
 ### Register existing entry rows
 

package/docs/troubleshooting.md

@@ -59,7 +59,7 @@ Enrollment workflow errors expose stable `code` values. Common actionable codes
 | `MOBILE_ANSWER_EXISTS` | A scalar row already occupies the requested mobile effective instant |
 | `MOBILE_PREFLIGHT_UNAVAILABLE` | The read cannot establish whether a scalar insert is safe |
 
-The [workflow code table](../browser/workflow-error-codes.mjs) maps existing reasons to codes; new guards supply explicit codes. `committed: false` identifies a pre-write refusal for the named operation. `'unknown'` requires journal/readback reconciliation. Resolution errors separately retain `originalCommitted: 'unknown'` for the original correction. HTTP status and causes are exposed where captured; they are not proof of non-application.
+The complete [SDK-owned code inventory](../API.md#enrollment-workflow-errors) is generated from the guards and stable reason map. Generation rejects new constant refusal reasons that have no specific code, including conditional branches. `committed: false` identifies a pre-write refusal for the named operation. `'unknown'` requires journal/readback reconciliation. Resolution errors separately retain `originalCommitted: 'unknown'` for the original correction. HTTP status and causes are exposed where captured; they are not proof of non-application.
 
 Pending 0.5.0 corrections may have no saved `failure` kind or status. Keep your own original failure evidence for the confirmation callback. Do not repeat the write to recover missing diagnostics.
 

package/docs/vendor-issues/yes-no-answers.md

@@ -36,8 +36,16 @@ After a successful standard write, the generic assessment read with `dateEffecti
 
 ## A failed mobile batch saved one of its answers
 
-Observed by an integrator on November 2, 2026, with synthetic records. A 15-answer `AddAssessmentAnswer` batch (1 `date`, 13 `lookup`, 1 `int`) was sent a few seconds after the client's household enrollment and entry-assessment answers were created. It returned HTTP 400; the error body was not captured. Afterwards the `int` answer was stored at the correct effective date and the other 14 were empty. The client's rows for this assessment were not read just before the send, so the absence of prior rows is inferred from the integration's own writes. Resends failed as in [the existing-row case](#mobile-writes-fail-for-an-existing-row).
+GitLab issue #2 reports a November 2, 2026 synthetic-client test: a combined 15-answer batch (1 `date`, 13 `lookup`, 1 `int`) returned HTTP 400 with `An error occurred while saving the entity changes. See the inner exception for details.` Only the integer score answer was stored afterwards. The issue says no row existed beforehand, that the error body was captured, and that the non-score batch and score-only batch each succeeded separately.
 
-On November 3, the byte-identical batch returned 200 and read back completely on fresh synthetic clients without an enrollment, an enrolled single adult, and an enrolled household head. Splitting the batch, reordering it, or omitting the `int` answer made no difference. The failure has not been reproduced.
+Separate retained run notes describe a batch sent shortly after household enrollment and entry answers, without a retained before-write assessment snapshot or raw error body. These accounts differ in their stated evidence. The SDK team cannot establish that they describe identical attempts or independently confirm their pre-write state. An existing answer shared by two instruments is one possible collision source, not an established explanation of the reported failure.
 
-**Ask WellSky:** Can a mobile write that returns HTTP 400 commit part of its batch? Is a write to an assessment assigned to the provider affected by work the server does after enrollment creation?
+On November 3, the byte-identical batch returned 200 and read back completely on fresh synthetic clients without an enrollment, an enrolled single adult, and an enrolled household head. Splitting the batch, reordering it, or omitting the `int` answer made no difference in those successful controls. The original failure remains unreproduced in that follow-up. These controls do not disprove the original report or establish a score-specific serialization rule.
+
+## SDK guard for an observed collision after preflight
+
+A November 11 synthetic regression demonstrated a narrower SDK defect: enrollment creation populated a scalar after the initial preflight; the scalar-stage read observed that occupied instant, but the workflow still submitted the full mobile batch. SDK 0.8.1 now refuses that first scalar attempt before marking it attempted. This protects against an observed collision and unavailable evidence after an earlier lifecycle stage. It does not establish the cause of issue #2 or make mobile batches atomic.
+
+A separate synthetic partial-commit control returned HTTP 400 after saving only one answer. Its stage stayed pending, same-key retries sent nothing, and later row stages did not run. Preserve that uncertain-write behavior. Do not split, replay, change the effective date, or replace the key to work around an already-attempted batch.
+
+**Ask WellSky:** Can a mobile write that returns HTTP 400 commit part of its batch? Is a write to an assessment assigned to the provider affected by work the server does after enrollment creation? Which server-side diagnostic can identify the failing question and database constraint?

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@choiceapps/communityservices-sdk",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "SDK for WellSky Community Services (HMIS), formerly ServicePoint, Client API V2 and V3",
   "type": "module",
   "main": "./dist/cjs/index.js",