# Change Log (AI/Human Curated) ## Entry Template ``` date: YYYY-MM-DD author: scope: type: change rationale: impact: status: completed|rolled-back|partial Summary: Validation: Follow-ups: ``` --- ### CL-001: TASK22211 endpoint search-document contract consistency slice date: 2026-03-23 author: Cline scope: `pages/api/endpoint/{getsearchdocumenthistory_api,getsearchdocumenthistorypaged_api,getsearchdocumentdetails_api,getsearchdocumentdetailspaged_api,getsearchdocumentTypes_api}.js`, `tests/phase21/endpoint-handler-contract.test.cjs` type: change rationale: Continue the endpoint contract-consistency stream by normalizing a coherent search-document handler cluster that still used raw error passthrough and noisy legacy logging patterns. impact: Improved negative-path consistency and safer error contract handling in search-document endpoints while preserving success payload behavior. status: completed Summary: - Branch created from `SIPS-Development`: `TASK22211-endpoint-search-document-contract-consistency`. - Standardized five search-document handlers to `respondError`/`respondSuccess` usage. - Added explicit required-input guards: - `DOCUMENT_ID_REQUIRED` for history/historypaged - `INCIDENT_ID_REQUIRED` for details/detailspaged/types - `ORDER_BY_REQUIRED`, `FIELD_SORT_REQUIRED`, `SHOW_NUMBER_OF_RECORDS_REQUIRED` for details-paged query requirements - Removed noisy direct logging in paged/details code paths. - Preserved success contract patterns (pass-through or transformed payloads where already established). - Expanded phase21 endpoint tests with missing-input, catch-path, and success parity assertions for this cluster. Validation: - `node tests/phase21/api-contract-slice1.test.cjs` -> pass - helper: 4/4 - file-handler: 11/11 - email-handler: 12/12 - endpoint-handler: 53/53 - `npm run lint` -> warnings only (pre-existing `react-hooks/exhaustive-deps` warnings; no new lint errors) Follow-ups: - Continue the next endpoint cluster using the same pattern (bounded slice + phase21 test expansion). - Keep response success payloads contract-stable and avoid broad relay/auth refactors in this stream. ### CL-002: TASK22211 endpoint token handler contract consistency slice date: 2026-03-23 author: Cline scope: `pages/api/endpoint/getToken.js`, `tests/phase21/endpoint-handler-contract.test.cjs` type: change rationale: Close out remaining non-standard endpoint contract handling by normalizing the legacy token endpoint to shared API response helpers and explicit error coding. impact: Improved endpoint error consistency and test coverage for token acquisition failures while preserving successful token payload passthrough. status: completed Summary: - Refactored `getToken.js` to use `respondSuccess` and `respondError` from `pages/api/middleware/apiResponse`. - Removed legacy raw `res.status(...).json(...)`/bare status assignment pattern and dead logging artifacts. - Added explicit catch-path contract: `TOKEN_FETCH_FAILED` with 400 status. - Added endpoint phase21 tests for: - success token payload passthrough - catch-path error contract assertion Validation: - `node tests/phase21/api-contract-slice1.test.cjs` -> pass - helper: 4/4 - file-handler: 11/11 - email-handler: 12/12 - endpoint-handler: 147/147 - `npm run lint` -> warnings only (pre-existing `react-hooks/exhaustive-deps` warnings; no new lint errors) Follow-ups: - Remaining outlier API handler for this consistency stream is `pages/api/file/generateappealpdfcopy.js` (not yet on shared response helpers). ### CL-003: TASK22211 endpoint contract-hardening stream backfill (all known slices) date: 2026-03-23 author: Cline scope: `pages/api/endpoint/*_api.js`, `pages/api/endpoint/getToken.js`, `tests/phase21/endpoint-handler-contract.test.cjs` type: change rationale: Backfill memory-bank traceability so the complete known TASK22211 contract-consistency stream is documented in one place now that memory-bank is being versioned. impact: Improves governance/auditability of API contract hardening, makes rollout and rollback analysis easier, and records exactly which endpoint clusters were normalized. status: completed Summary: - Backfilled all known TASK22211 slices currently on branch (in commit order): - `b57f3de` search-document endpoint contracts + phase21 coverage - `9af541a` my-portal retrieval endpoint contracts - `b880364` basic search endpoint contracts - `a106dea` DNS basic search endpoint contracts - `b5a3a62` portal module + LPA case endpoint contracts - `4601d7c` case detail endpoint contracts - `2959c7d` delete/watched-case endpoint contracts - `b59f13a` metadata + linked-case endpoint contracts - `bcf03a6` form + publication endpoint contracts - `e0e91c8` DNS + representation endpoint contracts - `98e159d` case creation + media endpoint contracts - `88e4586` advanced-search-paged endpoint contract - `cb69bbe` case update + CRM task endpoint contracts - `722ef98` hash + metadata endpoint contracts - `134f99c` address-search endpoint contract - `8b6ed73` new-appeal appeal-types endpoint contract - `eec59e8` token endpoint contract handling - Across the stream, handlers were standardized toward `respondSuccess`/`respondError`, required-input guards, and explicit negative-path error codes while preserving success payload compatibility. - Phase21 endpoint contract suite was expanded incrementally alongside each slice. Validation: - Stream validation baseline (latest known run): - `node tests/phase21/api-contract-slice1.test.cjs` -> pass (endpoint-handler 147/147) - `npm run lint` -> warnings only (pre-existing `react-hooks/exhaustive-deps`; no new lint errors) Follow-ups: - Continue with remaining non-standard API outlier(s), notably `pages/api/file/generateappealpdfcopy.js`. - Keep future slices logged in this file at commit-time now that memory-bank is versioned. --- ### CL-004: TASK22224 file + static endpoint contract hardening bundle (phase21) date: 2026-03-23 author: Cline scope: `pages/api/file/{downloadblob,generateappealpdfcopy}.js`, `pages/api/endpoint/{getsipsmedia_api,getappealtypesfornewappeal_api}.js`, `tests/phase21/{file-handler-contract,endpoint-handler-contract}.test.cjs` type: change rationale: Deliver the agreed larger bounded slice for remaining non-standard file/static handlers, improving negative-path consistency while preserving current success payload behavior. impact: Standardized error envelopes/codes for download and generated PDF copy flows, method guard parity for static endpoints, and expanded phase21 contract coverage for both file and endpoint handlers. status: completed Summary: - `downloadblob.js`: - added explicit catch-path response via `respondError` with `DOWNLOAD_BLOB_FAILED` - kept success behavior intact (attachment header + raw file body) - removed dead internal helper (`streamToBuffer`) and tightened local declarations - `generateappealpdfcopy.js`: - removed unused imports/noisy console warnings - standardized required-input and negative-path contracts: - `INCIDENT_ID_REQUIRED` (400) - `CASE_NOT_FOUND` (404) - `FORM_COLLECTION_NOT_FOUND` (400) - `APPEAL_PDF_COPY_GENERATION_FAILED` (400) - preserved success output contract (PDF content headers + buffer body) - `getsipsmedia_api.js` and `getappealtypesfornewappeal_api.js`: - added method guard for non-GET requests using `METHOD_NOT_ALLOWED` (405) - preserved existing GET success payloads - Expanded phase21 tests: - `file-handler-contract.test.cjs`: added coverage for download failure + full generated PDF copy contract/negative paths - `endpoint-handler-contract.test.cjs`: added method guard tests for both static endpoints Validation: - `node tests/phase21/api-contract-slice1.test.cjs` -> pass - helper: 4/4 - file-handler: 17/17 - email-handler: 12/12 - endpoint-handler: 149/149 - `npm run lint` -> warnings only (pre-existing `react-hooks/exhaustive-deps`; no new lint errors) Follow-ups: - If desired, next slice can target remaining file-route parity candidates outside this bundle, but this closes the planned TASK22224 scope. --- ### CL-005: TASK22224 downloadblob hotfix closure (path normalization + hash compatibility) date: 2026-03-23 author: Cline scope: `pages/api/file/downloadblob.js` type: change rationale: Close post-merge runtime regressions reported on live links where download URLs alternated between filename-only/full-path blob names and mixed encoded/raw hash input variants. impact: Restored reliable blob downloads without relaxing hash security guarantees (still HMAC validated), and preserved existing caller compatibility across legacy/new URL encodings. status: completed Summary: - Hotfix 1 (`f09f3b7`): normalized blob path resolution - accepts both forms of `blobname` input: - filename only (legacy) - full prefixed path (already includes `casefolderID/...`) - prevents double-prefix lookup failures - sets attachment filename from final path segment only - Hotfix 2 (`bd3bf68`): hash compatibility validation - validates against a bounded set of canonical query-path variants (raw/encoded combinations for `casefolderID` and `blobname`) - fixes `INVALID_HASH` false negatives for legitimate caller-generated links - keeps strict HMAC requirement in place (no unauthenticated bypass) Validation: - `node tests/phase21/file-handler-contract.test.cjs` -> pass (17/17) - `node tests/phase21/api-contract-slice1.test.cjs` -> pass - helper: 4/4 - file-handler: 17/17 - email-handler: 12/12 - endpoint-handler: 149/149 - User confirmation: "downloadblob now works" Follow-ups: - Next recommended slice on this branch: complete file-route guard parity for `deleteblob.js`, `deleteblobcase.js`, and `deleteblobrep.js` by aligning hash validation canonicalization and explicit `respondError` contracts (`MISSING_REQUIRED_QUERY`, `INVALID_HASH`, operation-specific `*_FAILED`). - Extend `tests/phase21/file-handler-contract.test.cjs` for the above routes with mixed encoded/raw hash cases to lock compatibility. --- ### CL-006: TASK22224 file delete-route guard parity slice date: 2026-03-23 author: Cline scope: `pages/api/file/{deleteblob,deleteblobcase,deleteblobrep}.js`, `tests/phase21/file-handler-contract.test.cjs` type: change rationale: Execute the next planned slice to align hash/canonicalization behavior and negative-path contracts across high-risk file delete routes, matching the compatibility posture established for `downloadblob`. impact: Reduces false `INVALID_HASH` failures for legitimate encoded/raw caller variants while preserving strict hash enforcement and improving resilience via explicit catch-path contracts. status: completed Summary: - `deleteblob.js` - added bounded hash candidate validation for encoded/raw combinations of `casefolderID` and `blobname` - normalized delete path handling for both filename-only and already-prefixed blob paths - added explicit catch-path contract: `DELETE_BLOB_FAILED` - `deleteblobcase.js` - added hash candidate validation for raw/encoded `casefolderID` - added explicit catch-path contract: `DELETE_BLOB_CASE_FAILED` - `deleteblobrep.js` - added hash candidate validation for encoded/raw `casefolderID` + `repfile` - added explicit catch-path contract: `DELETE_BLOB_REP_FAILED` - Phase21 tests expanded (`file-handler-contract.test.cjs`): - encoded hash-variant acceptance cases for all three delete routes - explicit dependency-failure contract assertions for all three delete routes Validation: - `node tests/phase21/file-handler-contract.test.cjs` -> pass (23/23) - `node tests/phase21/api-contract-slice1.test.cjs` -> pass - helper: 4/4 - file-handler: 23/23 - email-handler: 12/12 - endpoint-handler: 149/149 Follow-ups: - Optional next slice: apply same bounded hash-canonicalization parity to remaining high-sensitivity file routes where mixed encoded/raw callers may exist (`getbloblist`, `getprogressobjblob`) and add regression cases to phase21. --- ### CL-007: TASK22224 getrepsblob stability hotfix after delete representation flow date: 2026-03-23 author: Cline scope: `actions/azurestorage.js` (`getRepsBlobs`), `tests/phase21/file-handler-contract.test.cjs` type: change rationale: Resolve reported runtime 400 (`GET_REPS_BLOB_FAILED`) after delete representation actions, caused by stale soft-deleted blob tag hits during representation blob enumeration. impact: Prevents transient/stale Azure tag index entries from breaking representation retrieval, improving reliability of post-delete refresh without relaxing route security contracts. status: completed Summary: - Hardened `getRepsBlobs(containerName)` in `actions/azurestorage.js`: - fixed async misuse (`blobClient.getProperties().contentLength` without await) - added existence/property guard with explicit `await blobClient.getProperties()` - skips 404s (soft-deleted/stale tag index results) instead of throwing - preserves behavior for non-404 failures (rethrow for proper error visibility) - kept existing `_rep.json`/`undefined` name filtering intact - Added phase21 contract coverage for `getrepsblob` route: - success payload contract test - dependency failure contract test (`GET_REPS_BLOB_FAILED`) Validation: - `node tests/phase21/file-handler-contract.test.cjs` -> pass (25/25) - `node tests/phase21/api-contract-slice1.test.cjs` -> pass - helper: 4/4 - file-handler: 25/25 - email-handler: 12/12 - endpoint-handler: 149/149 Follow-ups: - Optional: add the same stale-tag existence guard pattern to any remaining Azure tag-list readers that still consume `findBlobsByTags` results without property existence verification.