sos-data-utils-ts

Blocking local-first release order

Feature branches may merge and push to main with their changelog while a larger cumulative release is still being assembled; do not bump or publish one package per branch, and do not call that integration state release-ready. When the grouped functionality is ready, run the complete cumulative local matrix, apply the release versions on a release branch, merge and push that release to main, and verify local main equals origin/main. Only then publish the exact pushed commits bottom-up. Consumers install exact registry versions, run their required artifact gates, commit lockfiles, and merge/push to main. Never publish from an unmerged or unpushed commit. Never commit file:, Git, workspace or vendored dependencies.

Coordinated beta/MVP compatibility points use the immutable manifest and tag contract in docs/MVP_SNAPSHOT_RELEASES.md. Repository-safe fixtures and value-free privacy validation are exported from sos-data-utils-ts/repository-privacy.

Product-neutral contracts shared outward from SOS channel infrastructure into human-health and animal products. It may reuse product-neutral canonical vocabulary from gdc-common-utils-ts, but has no dependency on GW CORE or any uhc-* or vet-* package.

The complete package boundary and dependency diagram is maintained in docs/SDK_LAYERING.md. sos-data-utils-ts is always the visible data-contract layer below the runtime-neutral sos-sdk-core-ts; Vet and UHC also depend on this package directly when they import or expose its types.

The first contract defines capability-based BFF route roots. Public products use /api/assistant/*; /api/internal/* is reserved for authenticated service-to-service adapters. Product-name prefixes such as /api/unid, /api/uhc, /api/vetchain and /api/petchain are not public API surfaces.

Sector behavior remains in its owner:

• sos-*: reusable channel, BFF and emergency primitives;
• uhc-*: human-health extensions;
• vet-*: animal/veterinary extensions;
• the terminology service: international terminology and regional catalogs.

Emergency data contracts are defined once in this package. They include the shared evidence vocabulary, flat Group and ServiceRequest claims, and stable card-to-Place/vehicle associations. SDKs consume these types and deterministic builders. Shared runtime-neutral authorization and orchestration belong to sos-sdk-core-ts; gateway calls and product workflows remain outside this data package.

The shared Task authoring schema uses canonical flat FHIR-like claims from gdc-common-utils-ts. Task.status and Task.intent are mandatory; display, correlation and output claims remain optional so the same contract supports human work items and machine-created asynchronous jobs.

Subject-card index resolution uses one product-neutral 27-digit preimage:

speciesId7 + first20DigitsOfValidatedCardNumber21

The final printed Damm digit is validation only and is excluded. Animal products provide the animal's NCBI Taxonomy identifier separately from the printed card. Human-health products use Homo sapiens (9606, projected as 0009606) implicitly and never display or request species. Only the lowercase SHA3-256 digest of the 27 ASCII digits may cross the blockchain boundary; it locates the active index provider and grants no data access.

The organization-verification contract resolves policy by business sector and ISO country. The governed CA/US profiles are:

• animal-care: immutable form/PDF, existing marketplace organization, outbound OTP to its official telephone or the technical controller telephone supplied in the application, confirmation by web or telephone, and marketplace primary-location evidence;
• health-care: immutable form/PDF, existing marketplace organization, authenticated representative/controller email, and a numeric code delivered to the legal postal address and confirmed only in the authenticated portal. The organization remains inactive until that code is confirmed against the exact form-PDF hash.

After organization activation, a professional invitation records both employee email and employee phone. Its initial OTP channel is employee email; this proves only invitation reachability and remains separate from licence and DCR.

Both use Organization/_transaction. Order/_batch is used only when a new host Offer exists; the later licence/DCR activation code is a different secret. Ungoverned sector/country combinations fail closed.

Canonical production operator hosts are host-vet.connecthealth.info, host-uhc.connecthealth.info and host-sos.connecthealth.info. Product aliases are not host identities or DID domains.

Verify

npm ci
npm run check