vet-sdk-core-ts 0.4.39 → 0.4.41

package/README.md

@@ -7,13 +7,15 @@ An animal is the first member of its own Individual Organization, so
 human that creates it is `Organization.owner`, the controller by default;
 `RESPRSN` must never be copied into the animal member.
 
-Name, birth date, exact NCBI species and optional breed are animal
-demographics. Breed remains separate descriptive text. Controller-authored
+Usual name, birth date, exact NCBI species and optional breed are animal
+demographics. The usual name may be supplied by the controller or generated as
+a pronounceable species ordinal such as `Dog 1`; it is not identity evidence.
+Breed remains separate descriptive text. Controller-authored
 demographics remain editable until a veterinarian attests them; attestation
 does not rewrite the original author, and later correction creates a new
 veterinarian-authored version.
 
-Use `buildVetChainAnimalDraftClaims(...)` while the name, exact NCBI species or
+Use `buildVetChainAnimalDraftClaims(...)` while the generated/supplied usual name, exact NCBI species or
 public Card is missing. Only a draft for which
 `readVetChainAnimalOnboardingReadiness(...)` returns `ready: true` may be
 activated and issued a Card. See
@@ -228,6 +230,16 @@ The catalogue is a governed starter set, not a closed biological universe.
 Callers may retain another verified positive non-human NCBI Taxonomy identifier.
 This matters because animal keeping varies by jurisdiction and taxonomy evolves.
 
+Species-language resolution is channel-neutral. Voice, WhatsApp, portal chat
+and portal speech call `resolveVetChainSpeciesAlias` with the same localized
+lexicon. It performs exact normalized matching only. If that fast path misses,
+a server adapter implements `VetChainSpeciesTerminologyResolver` and sends text
+plus locale to the authenticated terminology service. The service returns a
+closed NCBI candidate set, which must pass
+`validateVetChainSpeciesTerminologyCandidates`; a model such as Gemma may rank
+that set but cannot add codes. `selectVetChainSpeciesTerminologyCandidate`
+accepts only a code actually returned for user review and confirmation.
+
 Current cards are issued with `issueVetChainAnimalCard`: five jurisdiction
 digits plus `animalNumericId15 + checkDigit1`, and the matching
 `did:web:{host}:card:vetchain:{jurisdiction5}:{animal16}`. Species is separate
@@ -238,10 +250,16 @@ being repeated in the 21 printed digits.
 import {
   VetChainDomesticAnimalSpecies,
   findVetChainSpeciesByTaxonomyId,
+  resolveVetChainSpeciesAlias,
 } from "vet-sdk-core-ts/species";
 
 VetChainDomesticAnimalSpecies.DomesticFerret.ncbiTaxonomyId; // "9669"
 findVetChainSpeciesByTaxonomyId("9685")?.key; // "Cat"
+resolveVetChainSpeciesAlias({
+  text: "Dog.",
+  locale: "en-CA",
+  lexicon: [{ ncbiTaxonomyId: "9615", acceptedTexts: ["dog", "it is a dog"] }],
+})?.ncbiTaxonomyId; // "9615"
 ```
 
 ## Digital-twin search

package/dist/animal-onboarding.d.ts

@@ -1,3 +1,50 @@
+/**
+ * Channel-neutral form contract for animal demographics.
+ *
+ * Voice, chat and portal navigation may render this schema differently, but
+ * they must not redefine required fields or post-activation mutability.
+ */
+export declare const VETCHAIN_ANIMAL_DEMOGRAPHICS_SCHEMA: Readonly<{
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "https://vetchain.org/schemas/animal-demographics/v1";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: Readonly<{
+        usualName: Readonly<{
+            type: "string";
+            maxLength: 200;
+            'x-vetchain-claim': "org.schema.Organization.alternateName";
+            'x-vetchain-auto-generated': true;
+            'x-vetchain-mutable-until-attested': true;
+        }>;
+        birthDate: Readonly<{
+            type: "string";
+            pattern: "^\\d{4}(?:-(?:0[1-9]|1[0-2])(?:-(?:0[1-9]|[12]\\d|3[01]))?)?$";
+            'x-vetchain-claim': "org.schema.Organization.member.birthDate";
+            'x-vetchain-mutable-until-attested': true;
+        }>;
+        species: Readonly<{
+            type: "string";
+            pattern: "^[1-9]\\d*$";
+            not: Readonly<{
+                const: "9606";
+            }>;
+            'x-vetchain-claim': "org.schema.Organization.member.additionalType";
+            'x-vetchain-immutable-after-activation': true;
+        }>;
+    }>;
+    readonly required: readonly string[];
+}>;
+/**
+ * Returns the controller-supplied usual name or a stable, pronounceable
+ * English fallback such as `Dog 1`. The ordinal is allocated durably by the
+ * owning BFF; this pure helper never counts records or exposes a private UUID.
+ */
+export declare function resolveVetChainAnimalUsualName(input: Readonly<{
+    usualName?: string;
+    ncbiTaxonomyId: string;
+    ordinal: number;
+}>): string;
 /** Canonical member relationship for the animal SELF subject. */
 export declare const VetChainAnimalMemberRoles: Readonly<{
     readonly Self: "ONESELF";

package/dist/animal-onboarding.js

@@ -1,6 +1,55 @@
 import { parseVetChainAnimalCardDid } from 'vet-data-utils-ts';
 import { buildAnimalIdentifier16, buildSpeciesId7 } from './animal-identity.js';
 import { normalizeVetChainNcbiTaxonomyId } from './card-issuance.js';
+import { findVetChainSpeciesByTaxonomyId } from './species.js';
+/**
+ * Channel-neutral form contract for animal demographics.
+ *
+ * Voice, chat and portal navigation may render this schema differently, but
+ * they must not redefine required fields or post-activation mutability.
+ */
+export const VETCHAIN_ANIMAL_DEMOGRAPHICS_SCHEMA = Object.freeze({
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: 'https://vetchain.org/schemas/animal-demographics/v1',
+    type: 'object',
+    additionalProperties: false,
+    properties: Object.freeze({
+        usualName: Object.freeze({
+            type: 'string', maxLength: 200,
+            'x-vetchain-claim': 'org.schema.Organization.alternateName',
+            'x-vetchain-auto-generated': true,
+            'x-vetchain-mutable-until-attested': true,
+        }),
+        birthDate: Object.freeze({
+            type: 'string', pattern: '^\\d{4}(?:-(?:0[1-9]|1[0-2])(?:-(?:0[1-9]|[12]\\d|3[01]))?)?$',
+            'x-vetchain-claim': 'org.schema.Organization.member.birthDate',
+            'x-vetchain-mutable-until-attested': true,
+        }),
+        species: Object.freeze({
+            type: 'string', pattern: '^[1-9]\\d*$', not: Object.freeze({ const: '9606' }),
+            'x-vetchain-claim': 'org.schema.Organization.member.additionalType',
+            'x-vetchain-immutable-after-activation': true,
+        }),
+    }),
+    required: Object.freeze(['species']),
+});
+/**
+ * Returns the controller-supplied usual name or a stable, pronounceable
+ * English fallback such as `Dog 1`. The ordinal is allocated durably by the
+ * owning BFF; this pure helper never counts records or exposes a private UUID.
+ */
+export function resolveVetChainAnimalUsualName(input) {
+    const supplied = String(input.usualName || '').trim();
+    if (supplied)
+        return supplied;
+    if (!Number.isSafeInteger(input.ordinal) || input.ordinal < 1) {
+        throw new TypeError('vet_animal_usual_name_ordinal_invalid');
+    }
+    const taxonomy = normalizeVetChainNcbiTaxonomyId(input.ncbiTaxonomyId);
+    const species = findVetChainSpeciesByTaxonomyId(taxonomy);
+    const label = species ? humanizeSpeciesKey(species.key) : 'Animal';
+    return `${label} ${input.ordinal}`;
+}
 /** Canonical member relationship for the animal SELF subject. */
 export const VetChainAnimalMemberRoles = Object.freeze({ Self: 'ONESELF' });
 /** Canonical schema.org claim names for the VetChain animal registration. */
@@ -136,3 +185,6 @@ function required(value, error) {
         throw new TypeError(error);
     return normalized;
 }
+function humanizeSpeciesKey(value) {
+    return value.replace(/([a-z0-9])([A-Z])/g, '$1 $2').trim();
+}

package/dist/species.d.ts

@@ -9,6 +9,27 @@ export type VetChainSpeciesDefinition = Readonly<{
     scientificName: string;
     group: VetChainAnimalGroup;
 }>;
+export declare const VETCHAIN_NCBI_TAXONOMY_CODE_SYSTEM: "https://www.ncbi.nlm.nih.gov/Taxonomy";
+/** Localized exact texts supplied by a VetChain product, independently of its channel adapter. */
+export type VetChainSpeciesLexiconEntry = Readonly<{
+    ncbiTaxonomyId: NcbiTaxonomyId;
+    acceptedTexts: readonly string[];
+}>;
+/** One reviewable result returned by the authenticated terminology service. */
+export type VetChainSpeciesTerminologyCandidate = Readonly<{
+    codeSystem: typeof VETCHAIN_NCBI_TAXONOMY_CODE_SYSTEM;
+    codeValue: NcbiTaxonomyId;
+    display: string;
+    score?: number;
+}>;
+/** Channel-neutral boundary implemented by a server-side VetChain terminology adapter. */
+export interface VetChainSpeciesTerminologyResolver {
+    search(input: Readonly<{
+        text: string;
+        locale: string;
+        maxCandidates: number;
+    }>): Promise<readonly VetChainSpeciesTerminologyCandidate[]>;
+}
 /**
  * Governed starter catalogue for domesticated and commonly kept animals.
  *
@@ -482,3 +503,27 @@ export declare const VetChainDomesticAnimalSpeciesList: readonly Readonly<{
 export declare function findVetChainSpeciesByTaxonomyId(value: string): VetChainSpeciesDefinition | undefined;
 /** The current printed card layout can embed only NCBI Taxonomy IDs of at most five digits. */
 export declare function isVetChainSpeciesCode5Compatible(value: string): boolean;
+/** Normalizes human text consistently before an exact localized alias lookup. */
+export declare function normalizeVetChainSpeciesText(value: string, locale?: string): string;
+/**
+ * Resolves only an exact normalized text configured by the product locale.
+ *
+ * Voice, WhatsApp, portal chat and portal speech must call this same helper.
+ * Unmatched free text belongs at the terminology boundary, not in an LLM-only
+ * inference path.
+ */
+export declare function resolveVetChainSpeciesAlias(input: Readonly<{
+    text: string;
+    locale: string;
+    lexicon: readonly VetChainSpeciesLexiconEntry[];
+}>): Readonly<{
+    ncbiTaxonomyId: NcbiTaxonomyId;
+    matchedText: string;
+}> | undefined;
+/** Validates the closed candidate set before it can be presented or ranked. */
+export declare function validateVetChainSpeciesTerminologyCandidates(values: readonly VetChainSpeciesTerminologyCandidate[]): readonly VetChainSpeciesTerminologyCandidate[];
+/**
+ * Selects only a code in the terminology service's reviewed candidate set.
+ * A Gemma/ranking service may reorder this set but cannot add a code.
+ */
+export declare function selectVetChainSpeciesTerminologyCandidate(candidates: readonly VetChainSpeciesTerminologyCandidate[], selectedCodeValue: string): VetChainSpeciesTerminologyCandidate;

package/dist/species.js

@@ -1,4 +1,5 @@
 // Copyright 2026 Connecting Solution & Applications Ltd under the Apache License, Version 2.0.
+export const VETCHAIN_NCBI_TAXONOMY_CODE_SYSTEM = "https://www.ncbi.nlm.nih.gov/Taxonomy";
 function species(key, ncbiTaxonomyId, scientificName, group) {
     if (!/^[1-9]\d*$/.test(ncbiTaxonomyId) || ncbiTaxonomyId === "9606") {
         throw new TypeError("A species requires a positive, non-human NCBI Taxonomy identifier.");
@@ -74,3 +75,71 @@ export function findVetChainSpeciesByTaxonomyId(value) {
 export function isVetChainSpeciesCode5Compatible(value) {
     return /^[1-9]\d{0,4}$/.test(value) && value !== "9606";
 }
+/** Normalizes human text consistently before an exact localized alias lookup. */
+export function normalizeVetChainSpeciesText(value, locale = "en") {
+    const normalizedLocale = String(locale || "en").trim() || "en";
+    return String(value || "")
+        .normalize("NFD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .toLocaleLowerCase(normalizedLocale)
+        .replace(/[^\p{L}\p{N}\s]/gu, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/**
+ * Resolves only an exact normalized text configured by the product locale.
+ *
+ * Voice, WhatsApp, portal chat and portal speech must call this same helper.
+ * Unmatched free text belongs at the terminology boundary, not in an LLM-only
+ * inference path.
+ */
+export function resolveVetChainSpeciesAlias(input) {
+    const normalizedInput = normalizeVetChainSpeciesText(input.text, input.locale);
+    if (!normalizedInput)
+        return undefined;
+    for (const entry of input.lexicon) {
+        assertNonHumanTaxonomyId(entry.ncbiTaxonomyId);
+        if (entry.acceptedTexts.some((text) => normalizeVetChainSpeciesText(text, input.locale) === normalizedInput)) {
+            return Object.freeze({ ncbiTaxonomyId: entry.ncbiTaxonomyId, matchedText: normalizedInput });
+        }
+    }
+    return undefined;
+}
+/** Validates the closed candidate set before it can be presented or ranked. */
+export function validateVetChainSpeciesTerminologyCandidates(values) {
+    if (!Array.isArray(values) || values.length === 0 || values.length > 20) {
+        throw new TypeError("Species terminology must return between one and twenty candidates.");
+    }
+    const seen = new Set();
+    return Object.freeze(values.map((candidate) => {
+        if (candidate.codeSystem !== VETCHAIN_NCBI_TAXONOMY_CODE_SYSTEM) {
+            throw new TypeError("Species terminology candidates must use the canonical NCBI Taxonomy code system.");
+        }
+        assertNonHumanTaxonomyId(candidate.codeValue);
+        if (!candidate.display.trim())
+            throw new TypeError("A species terminology candidate requires a display label.");
+        if (seen.has(candidate.codeValue))
+            throw new TypeError("Species terminology candidates must be unique.");
+        if (candidate.score !== undefined && (!Number.isFinite(candidate.score) || candidate.score < 0 || candidate.score > 1)) {
+            throw new TypeError("A species terminology candidate score must be between zero and one.");
+        }
+        seen.add(candidate.codeValue);
+        return Object.freeze({ ...candidate, display: candidate.display.trim() });
+    }));
+}
+/**
+ * Selects only a code in the terminology service's reviewed candidate set.
+ * A Gemma/ranking service may reorder this set but cannot add a code.
+ */
+export function selectVetChainSpeciesTerminologyCandidate(candidates, selectedCodeValue) {
+    const validated = validateVetChainSpeciesTerminologyCandidates(candidates);
+    const selected = validated.find((candidate) => candidate.codeValue === selectedCodeValue.trim());
+    if (!selected)
+        throw new TypeError("The selected species was not returned by the terminology service.");
+    return selected;
+}
+function assertNonHumanTaxonomyId(value) {
+    if (!/^[1-9]\d*$/.test(value) || value === "9606") {
+        throw new TypeError("A species requires a positive, non-human NCBI Taxonomy identifier.");
+    }
+}

package/docs/101-ANIMAL-INDIVIDUAL-ONBOARDING.md

@@ -40,7 +40,8 @@ readVetChainAnimalOnboardingReadiness(draft)
 // { ready: false, missing: ['alternateName', 'species', 'card'] }
 ```
 
-The BFF later rebuilds the same subject draft with its name and exact NCBI
+The BFF later rebuilds the same subject draft with its supplied usual name or a
+durably numbered species fallback such as `Dog 1`, plus its exact NCBI
 taxonomy, issues the public Card, and resubmits it under the same private
 `subjectId`. GW VET alone performs the `pending -> active` transition. A draft
 does not need a clinical `Composition`; the active clinical index is a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vet-sdk-core-ts",
-  "version": "0.4.39",
+  "version": "0.4.41",
   "description": "Browser-safe VetChain core contracts and governed animal species identifiers",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",