@wemush/wols 0.1.0 → 1.2.0

package/dist/types/crypto/decrypt.d.ts

@@ -4,6 +4,12 @@
  * Provides AES-256-GCM decryption for encrypted specimens using Web Crypto API.
  * Supports both password-based (PBKDF2) and raw CryptoKey decryption.
  *
+ * ## Self-Describing Payloads
+ *
+ * Encrypted specimens from v1.2.0+ include `iterations` in the payload, enabling
+ * automatic key derivation without caller needing to know encryption parameters.
+ * For payloads without `iterations` (pre-1.2.0), the default of 100,000 is used.
+ *
  * @module crypto/decrypt
  */
 import type { Specimen, EncryptedSpecimen, DecryptionOptions, ParseResult } from '../types.js';

package/dist/types/crypto/decrypt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decrypt.d.ts","sourceRoot":"","sources":["../../../src/crypto/decrypt.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAqE/F;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,iBAAiB,EAC5B,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAqDhC"}
+{"version":3,"file":"decrypt.d.ts","sourceRoot":"","sources":["../../../src/crypto/decrypt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAwE/F;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,iBAAiB,EAC5B,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAwDhC"}

package/dist/types/crypto/encrypt.d.ts

@@ -4,6 +4,54 @@
  * Provides AES-256-GCM encryption for specimens using Web Crypto API.
  * Supports both password-based (PBKDF2) and raw CryptoKey encryption.
  *
+ * ## Security Model
+ *
+ * This module implements a **deterministic key derivation** model optimized for:
+ * - Cross-environment compatibility (browser + Node.js)
+ * - Offline decryption (no external key storage needed)
+ * - Self-describing payloads (iterations stored in output)
+ *
+ * ### Password vs CryptoKey
+ *
+ * | Input Type | Use Case | Security Level |
+ * |------------|----------|----------------|
+ * | `string` (password) | Simple sharing, QR codes | Good (depends on password strength) |
+ * | `CryptoKey` | Server-side, key management systems | Best (full control over key material) |
+ *
+ * ### Security Considerations
+ *
+ * 1. **Fixed Salt**: The PBKDF2 salt is fixed per crypto version. This is intentional
+ *    for deterministic cross-environment key derivation. Password strength is critical.
+ *
+ * 2. **Iteration Count**: Default 100,000 iterations. Can be increased via `iterations`
+ *    option for higher security (at cost of performance).
+ *
+ * 3. **Random IV**: Each encryption uses a cryptographically random 96-bit IV,
+ *    ensuring identical plaintexts produce different ciphertexts.
+ *
+ * 4. **Authenticated Encryption**: AES-256-GCM provides both confidentiality and
+ *    integrity - tampered ciphertext will fail decryption.
+ *
+ * ## Future Specification Updates (v1.2.1+)
+ *
+ * TODO(wols-spec): The following enhancements should be documented in the upstream
+ * WOLS specification (wemush/open-standard/SPECIFICATION.md) in a future release:
+ *
+ * 1. **EncryptedSpecimen schema**: Define the `cryptoVersion` and `iterations` fields
+ *    in the encrypted payload format section.
+ *
+ * 2. **Configurable iterations**: Document the `iterations` option in EncryptionOptions
+ *    with recommended ranges (100k-600k) and minimum floor (10k).
+ *
+ * 3. **Self-describing payloads**: Explain that v1.2.0+ payloads include derivation
+ *    parameters for forward-compatible decryption.
+ *
+ * 4. **Security guidance**: Add a security considerations section covering:
+ *    - Fixed salt tradeoffs (determinism vs uniqueness)
+ *    - Password strength requirements
+ *    - When to use CryptoKey vs password
+ *    - Optional random salt for high-security scenarios (future v2)
+ *
  * @module crypto/encrypt
  */
 import type { Specimen, EncryptedSpecimen, EncryptionOptions } from '../types.js';
@@ -18,10 +66,17 @@ import type { Specimen, EncryptedSpecimen, EncryptionOptions } from '../types.js
  * ```typescript
  * import { encryptSpecimen } from '@wemush/wols/crypto';
  *
+ * // Basic encryption with default iterations (100k)
  * const encrypted = await encryptSpecimen(specimen, {
  *   key: 'my-secret-password',
  * });
- * // Returns: { encrypted: true, payload: "...", iv: "...", algorithm: "AES-256-GCM" }
+ *
+ * // Higher security with custom iterations
+ * const secureEncrypted = await encryptSpecimen(specimen, {
+ *   key: 'my-secret-password',
+ *   iterations: 300_000,
+ * });
+ * // Returns: { encrypted: true, payload: "...", iv: "...", algorithm: "AES-256-GCM", cryptoVersion: "v1", iterations: 300000 }
  * ```
  */
 export declare function encryptSpecimen(specimen: Specimen, options: EncryptionOptions): Promise<EncryptedSpecimen>;

package/dist/types/crypto/encrypt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"encrypt.d.ts","sourceRoot":"","sources":["../../../src/crypto/encrypt.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAwElF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,iBAAiB,CAAC,CAgC5B;AA+CD;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAStE"}
+{"version":3,"file":"encrypt.d.ts","sourceRoot":"","sources":["../../../src/crypto/encrypt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAkHlF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,iBAAiB,CAAC,CAuC5B;AAoDD;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAStE"}

package/dist/types/index.d.ts

@@ -9,13 +9,21 @@
  * @version 1.1.0
  */
 export { WOLS_VERSION, WOLS_CONTEXT } from './types.js';
-export type { Brand, SpecimenId, SpecimenType, GrowthStage, Strain, Specimen, SpecimenInput, ParseResult, ValidationResult, ValidationError, ValidationWarning, ValidationOptions, SpecimenRef, QRCodeOptions, EncryptionOptions, DecryptionOptions, EncryptedSpecimen, } from './types.js';
+export type { Brand, SpecimenId, SpecimenType, GrowthStage, Strain, Specimen, SpecimenInput, SpecimenMeta, ParseResult, ValidationResult, ValidationError, ValidationWarning, ValidationOptions, IdValidationMode, IdValidator, SpecimenRef, QRCodeOptions, EncryptionOptions, DecryptionOptions, EncryptedSpecimen, } from './types.js';
 export { asSpecimenId, isSpecimenType, isGrowthStage, isStrain, SPECIMEN_TYPES, GROWTH_STAGES, } from './types.js';
+export { registerTypeAlias, resolveTypeAlias, getTypeAliases } from './types.js';
+export { WOLS_TO_PLATFORM_MAP, mapToWolsType, mapFromWolsType, registerPlatformType, } from './types.js';
+export { normalizeGeneration, isValidGeneration } from './types.js';
+export type { GenerationFormat } from './types.js';
 export { WolsErrorCode, WolsError, WolsParseError, WolsValidationError, WolsEncryptionError, } from './errors.js';
 export { createSpecimen, serializeSpecimen } from './specimen.js';
 export { validateSpecimen } from './validator.js';
 export { parseSpecimen } from './parser.js';
-export { toCompactUrl, parseCompactUrl, SPECIES_CODES, getSpeciesFromCode, getCodeFromSpecies, registerSpeciesCode, } from './compact-url.js';
+export { toCompactUrl, parseCompactUrl, parseCompactUrlOrThrow, parseCompactUrlOrNull, SPECIES_CODES, getSpeciesFromCode, getCodeFromSpecies, registerSpeciesCode, } from './compact-url.js';
 export { encryptSpecimen, isEncrypted, decryptSpecimen } from './crypto/index.js';
 export { toQRCode, toQRCodeDataURL, toQRCodeSVG, isQRAvailable, isQRAvailableSync, } from './qr/index.js';
+export { isServer, isBrowser, isWebWorker, isDeno, isBun, getRuntimeEnvironment, supportsWebCrypto, supportsNodeCrypto, isCryptoSupported, supportsTextEncoding, supportsURLAPIs, } from './utils/environment.js';
+export type { RuntimeEnvironment } from './utils/environment.js';
+export { compareVersions, isOutdated, isNewer, getCurrentVersion, registerMigration, canMigrate, migrate, getMigrations, clearMigrations, } from './utils/migration.js';
+export type { VersionComparison, MigrationHandler } from './utils/migration.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAKxD,YAAY,EAEV,KAAK,EACL,UAAU,EAGV,YAAY,EACZ,WAAW,EACX,MAAM,EACN,QAAQ,EACR,aAAa,EAGb,WAAW,EACX,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EAGjB,WAAW,EAGX,aAAa,EAGb,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAKpB,OAAO,EACL,YAAY,EACZ,cAAc,EACd,aAAa,EACb,QAAQ,EACR,cAAc,EACd,aAAa,GACd,MAAM,YAAY,CAAC;AAKpB,OAAO,EACL,aAAa,EACb,SAAS,EACT,cAAc,EACd,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAKrB,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAKlE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAKlD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAK5C,OAAO,EACL,YAAY,EACZ,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAK1B,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAKlF,OAAO,EACL,QAAQ,EACR,eAAe,EACf,WAAW,EACX,aAAa,EACb,iBAAiB,GAClB,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAKxD,YAAY,EAEV,KAAK,EACL,UAAU,EAGV,YAAY,EACZ,WAAW,EACX,MAAM,EACN,QAAQ,EACR,aAAa,EACb,YAAY,EAGZ,WAAW,EACX,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EAGjB,gBAAgB,EAChB,WAAW,EAGX,WAAW,EAGX,aAAa,EAGb,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAKpB,OAAO,EACL,YAAY,EACZ,cAAc,EACd,aAAa,EACb,QAAQ,EACR,cAAc,EACd,aAAa,GACd,MAAM,YAAY,CAAC;AAKpB,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAKjF,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,eAAe,EACf,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAKpB,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAKnD,OAAO,EACL,aAAa,EACb,SAAS,EACT,cAAc,EACd,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAKrB,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAKlE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAKlD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAK5C,OAAO,EACL,YAAY,EACZ,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAK1B,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAKlF,OAAO,EACL,QAAQ,EACR,eAAe,EACf,WAAW,EACX,aAAa,EACb,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAKvB,OAAO,EACL,QAAQ,EACR,SAAS,EACT,WAAW,EACX,MAAM,EACN,KAAK,EACL,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAKjE,OAAO,EACL,eAAe,EACf,UAAU,EACV,OAAO,EACP,iBAAiB,EACjB,iBAAiB,EACjB,UAAU,EACV,OAAO,EACP,aAAa,EACb,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/types/parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/parser.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,QAAQ,EAId,MAAM,YAAY,CAAC;AAyCpB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC,QAAQ,CAAC,CAoGjE"}
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/parser.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,QAAQ,EAKd,MAAM,YAAY,CAAC;AAyCpB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC,QAAQ,CAAC,CAwGjE"}

package/dist/types/specimen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"specimen.d.ts","sourceRoot":"","sources":["../../src/specimen.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAU,MAAM,YAAY,CAAC;AA2BlE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,QAAQ,CAwC7D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CA6C5D"}
+{"version":3,"file":"specimen.d.ts","sourceRoot":"","sources":["../../src/specimen.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAU,MAAM,YAAY,CAAC;AAkClE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,QAAQ,CAsD7D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAiD5D"}

package/dist/types/types.d.ts

@@ -2,7 +2,7 @@
  * WOLS TypeScript Library - Core Types
  *
  * This module defines all the core types, interfaces, and enums
- * for the WeMush Open Labeling Standard (WOLS) v1.1.0.
+ * for the WeMush Open Labeling Standard (WOLS) v1.2.0.
  *
  * @packageDocumentation
  * @module @wemush/wols
@@ -10,7 +10,7 @@
 /**
  * WOLS specification version implemented by this library.
  */
-export declare const WOLS_VERSION = "1.1.0";
+export declare const WOLS_VERSION = "1.2.0";
 /**
  * JSON-LD context URL for WOLS specimens.
  */
@@ -40,14 +40,181 @@ export type SpecimenType = 'CULTURE' | 'SPAWN' | 'SUBSTRATE' | 'FRUITING' | 'HAR
  * Array of valid specimen types for validation.
  */
 export declare const SPECIMEN_TYPES: readonly SpecimenType[];
+/**
+ * Register a custom type alias.
+ *
+ * @param alias - The alias string (case-insensitive, stored uppercase)
+ * @param wolsType - The canonical WOLS SpecimenType
+ *
+ * @example
+ * ```typescript
+ * registerTypeAlias('MYCELIUM_BLOCK', 'SUBSTRATE');
+ * ```
+ */
+export declare function registerTypeAlias(alias: string, wolsType: SpecimenType): void;
+/**
+ * Resolve a type alias to its canonical WOLS type.
+ * Returns the input if it's already a valid SpecimenType or no alias exists.
+ *
+ * @param typeOrAlias - Type string or alias to resolve
+ * @returns Canonical SpecimenType or original string if not found
+ *
+ * @example
+ * ```typescript
+ * resolveTypeAlias('LIQUID_CULTURE') // Returns 'CULTURE'
+ * resolveTypeAlias('CULTURE')        // Returns 'CULTURE'
+ * resolveTypeAlias('unknown')        // Returns 'unknown'
+ * ```
+ */
+export declare function resolveTypeAlias(typeOrAlias: string): SpecimenType | string;
+/**
+ * Get all registered type aliases.
+ *
+ * @returns ReadonlyMap of alias -> SpecimenType mappings
+ */
+export declare function getTypeAliases(): ReadonlyMap<string, SpecimenType>;
+/**
+ * Mapping from WOLS types to common platform type names.
+ *
+ * This provides a centralized lookup for integrations that need to
+ * display user-friendly type names or map to platform-specific values.
+ *
+ * @since 1.2.0
+ */
+export declare const WOLS_TO_PLATFORM_MAP: Readonly<Record<SpecimenType, readonly string[]>>;
+/**
+ * Map a platform-specific type to a WOLS SpecimenType.
+ *
+ * First checks registered aliases, then falls back to direct lookup.
+ *
+ * @param platformType - Platform-specific type name
+ * @returns Matching SpecimenType or null if not found
+ *
+ * @example
+ * ```typescript
+ * mapToWolsType('Liquid Culture') // Returns 'CULTURE'
+ * mapToWolsType('LC')             // Returns 'CULTURE'
+ * mapToWolsType('Unknown Type')   // Returns null
+ * ```
+ *
+ * @since 1.2.0
+ */
+export declare function mapToWolsType(platformType: string): SpecimenType | null;
+/**
+ * Get all platform type names for a WOLS SpecimenType.
+ *
+ * @param wolsType - WOLS SpecimenType
+ * @returns Array of platform type names
+ *
+ * @example
+ * ```typescript
+ * mapFromWolsType('CULTURE')
+ * // Returns ['Liquid Culture', 'LC', 'Agar', 'Petri', 'Slant', 'Culture Plate']
+ * ```
+ *
+ * @since 1.2.0
+ */
+export declare function mapFromWolsType(wolsType: SpecimenType): readonly string[];
+/**
+ * Register a custom platform type mapping.
+ *
+ * This adds to both the alias registry (for resolveTypeAlias) and
+ * can be used for custom platform integrations.
+ *
+ * @param platformType - Platform-specific type name
+ * @param wolsType - WOLS SpecimenType to map to
+ *
+ * @example
+ * ```typescript
+ * registerPlatformType('Mycelium Block', 'SUBSTRATE');
+ * mapToWolsType('Mycelium Block') // Returns 'SUBSTRATE'
+ * ```
+ *
+ * @since 1.2.0
+ */
+export declare function registerPlatformType(platformType: string, wolsType: SpecimenType): void;
 /**
  * Growth stage enum representing specimen lifecycle.
+ *
+ * v1.2.0 introduces research-grade lifecycle tracking with 7 stages:
+ * - INOCULATION: Initial introduction of spawn/culture to substrate
+ * - INCUBATION: Post-inoculation rest period before visible growth (v1.2.0)
+ * - COLONIZATION: Active mycelial growth through substrate
+ * - PRIMORDIA: Pin initiation and early fruit body formation (v1.2.0)
+ * - FRUITING: Active fruit body development and maturation
+ * - SENESCENCE: Declining productivity, end-of-life phase (v1.2.0)
+ * - HARVEST: Mushrooms harvested and processed
  */
-export type GrowthStage = 'INOCULATION' | 'COLONIZATION' | 'FRUITING' | 'HARVEST';
+export type GrowthStage = 'INOCULATION' | 'INCUBATION' | 'COLONIZATION' | 'PRIMORDIA' | 'FRUITING' | 'SENESCENCE' | 'HARVEST';
 /**
  * Array of valid growth stages for validation.
+ * Ordered by typical lifecycle progression.
  */
 export declare const GROWTH_STAGES: readonly GrowthStage[];
+/**
+ * Output format for generation normalization.
+ *
+ * - 'preserve': Keep original format
+ * - 'filial': Normalize to F{n} format (F1, F2, etc.)
+ * - 'numeric': Normalize to numeric format (1, 2, etc.)
+ *
+ * @since 1.2.0
+ */
+export type GenerationFormat = 'preserve' | 'filial' | 'numeric';
+/**
+ * Normalize a generation string to the specified format.
+ *
+ * Accepts multiple input formats:
+ * - Filial: F1, F2, F3, etc.
+ * - Parental: P or P1
+ * - Generational: G1, G2, G3, etc.
+ * - Numeric: 1, 2, 3, etc.
+ *
+ * @param generation - The generation string to normalize
+ * @param format - Target format (default: 'preserve')
+ * @returns Normalized generation string, or original if not parseable
+ *
+ * @example
+ * ```typescript
+ * normalizeGeneration('G2', 'filial')  // Returns 'F2'
+ * normalizeGeneration('3', 'filial')   // Returns 'F3'
+ * normalizeGeneration('F1', 'numeric') // Returns '1'
+ * normalizeGeneration('P', 'filial')   // Returns 'P'
+ * ```
+ *
+ * @since 1.2.0
+ */
+export declare function normalizeGeneration(generation: string, format?: GenerationFormat): string;
+/**
+ * Check if a generation string is valid.
+ *
+ * @param generation - The generation string to validate
+ * @returns True if valid, false otherwise
+ *
+ * @since 1.2.0
+ */
+export declare function isValidGeneration(generation: string): boolean;
+/**
+ * Metadata for specimen round-trip preservation.
+ *
+ * The `_meta` namespace is reserved for implementation-specific metadata
+ * that should be preserved through import/export operations but is not
+ * part of the core WOLS specification.
+ *
+ * @since 1.2.0
+ */
+export interface SpecimenMeta {
+    /** Original ID from source system before WOLS normalization */
+    sourceId?: string;
+    /** ISO 8601 timestamp when specimen was imported */
+    importedAt?: string;
+    /** Identifier of the source system (e.g., "wemush-platform", "mycology-db") */
+    sourceSystem?: string;
+    /** Schema version used by source system */
+    schemaVersion?: string;
+    /** Extensible: additional implementation-specific fields */
+    [key: string]: unknown;
+}
 /**
  * Strain information for a specimen.
  */
@@ -95,14 +262,20 @@ export interface Specimen {
     custom?: Record<string, unknown>;
     /** Cryptographic signature */
     signature?: string;
+    /**
+     * Implementation metadata (preserved through operations).
+     * @since 1.2.0
+     */
+    _meta?: SpecimenMeta;
 }
 /**
  * Input type for createSpecimen().
  * Strain can be a string (auto-expanded) or full Strain object.
+ * Type accepts aliases (e.g., 'LIQUID_CULTURE' -> 'CULTURE') via resolveTypeAlias().
  */
 export interface SpecimenInput {
-    /** Cultivation stage type */
-    type: SpecimenType;
+    /** Cultivation stage type (accepts aliases like 'LIQUID_CULTURE' -> 'CULTURE') */
+    type: SpecimenType | string;
     /** Scientific species name */
     species: string;
     /** String shorthand expands to { name: string } */
@@ -117,6 +290,11 @@ export interface SpecimenInput {
     creator?: string;
     /** Custom vendor-specific fields */
     custom?: Record<string, unknown>;
+    /**
+     * Implementation metadata (preserved through operations).
+     * @since 1.2.0
+     */
+    _meta?: SpecimenMeta;
 }
 /**
  * Import error types for use in ParseResult.
@@ -169,6 +347,18 @@ export interface ValidationResult {
     /** Validation warnings (informational) */
     warnings: ValidationWarning[];
 }
+/**
+ * ID validation mode for flexible ID format support.
+ *
+ * @since 1.2.0
+ */
+export type IdValidationMode = 'strict' | 'ulid' | 'uuid' | 'any';
+/**
+ * Custom ID validator function signature.
+ *
+ * @since 1.2.0
+ */
+export type IdValidator = (id: string) => boolean;
 /**
  * Validation options.
  */
@@ -177,6 +367,24 @@ export interface ValidationOptions {
     allowUnknownFields?: boolean;
     /** Validation strictness level */
     level?: 'strict' | 'lenient';
+    /**
+     * ID format validation mode.
+     *
+     * - 'strict': ID must match `wemush:[a-z0-9]+` (default)
+     * - 'ulid': ID must be a valid ULID after wemush: prefix
+     * - 'uuid': ID must be a valid UUID v4 after wemush: prefix
+     * - 'any': Any non-empty string after wemush: prefix
+     *
+     * @since 1.2.0
+     */
+    idMode?: IdValidationMode;
+    /**
+     * Custom ID validator function.
+     * If provided, overrides idMode.
+     *
+     * @since 1.2.0
+     */
+    customIdValidator?: IdValidator;
 }
 /**
  * Reference data extracted from a compact URL.
@@ -225,15 +433,32 @@ export interface QRCodeOptions {
 }
 /**
  * Encryption options.
+ *
+ * @since 1.2.0 Added `iterations` option for configurable PBKDF2 strength
  */
 export interface EncryptionOptions {
     /** CryptoKey or password string for PBKDF2 */
     key: CryptoKey | string;
     /** Fields to encrypt (partial encryption) */
     fields?: string[];
+    /**
+     * PBKDF2 iteration count for password-based key derivation.
+     *
+     * Higher values increase security but slow down encryption/decryption.
+     * Ignored when `key` is a CryptoKey (already derived).
+     *
+     * - Default: 100000 (100k)
+     * - Minimum: 10000 (10k) - lower values will throw an error
+     * - Recommended: 100000-600000 depending on performance requirements
+     *
+     * @since 1.2.0
+     */
+    iterations?: number;
 }
 /**
  * Encrypted specimen wrapper.
+ *
+ * @since 1.2.0 Added `cryptoVersion` and `iterations` fields for migration support
  */
 export interface EncryptedSpecimen {
     /** Flag indicating this is encrypted */
@@ -246,6 +471,22 @@ export interface EncryptedSpecimen {
     algorithm: 'AES-256-GCM';
     /** Authentication tag (for GCM) */
     tag?: string;
+    /**
+     * Crypto schema version for forward-compatible migrations.
+     * Allows future versions to change key derivation while maintaining
+     * backward compatibility for decryption.
+     *
+     * @since 1.2.0
+     */
+    cryptoVersion?: 'v1';
+    /**
+     * PBKDF2 iteration count used during encryption.
+     * Stored in payload for self-describing decryption (no need to guess).
+     * If absent, defaults to 100000 for backward compatibility.
+     *
+     * @since 1.2.0
+     */
+    iterations?: number;
 }
 /**
  * Decryption options.

package/dist/types/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types/utils/environment.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Environment Detection Utilities
+ *
+ * This module provides runtime environment detection for selecting
+ * appropriate crypto implementations and other environment-specific behavior.
+ *
+ * @module utils/environment
+ * @since 1.2.0
+ */
+/**
+ * Runtime environment type.
+ *
+ * @since 1.2.0
+ */
+export type RuntimeEnvironment = 'node' | 'browser' | 'webworker' | 'deno' | 'bun' | 'unknown';
+/**
+ * Check if running in a server-side Node.js environment.
+ *
+ * @returns True if running in Node.js, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isServer()) {
+ *   // Use Node.js crypto module
+ * }
+ * ```
+ *
+ * @since 1.2.0
+ */
+export declare function isServer(): boolean;
+/**
+ * Check if running in a browser environment.
+ *
+ * @returns True if running in a browser, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isBrowser()) {
+ *   // Use Web Crypto API
+ * }
+ * ```
+ *
+ * @since 1.2.0
+ */
+export declare function isBrowser(): boolean;
+/**
+ * Check if running in a Web Worker environment.
+ *
+ * @returns True if running in a Web Worker, false otherwise
+ *
+ * @since 1.2.0
+ */
+export declare function isWebWorker(): boolean;
+/**
+ * Check if running in Deno environment.
+ *
+ * @returns True if running in Deno, false otherwise
+ *
+ * @since 1.2.0
+ */
+export declare function isDeno(): boolean;
+/**
+ * Check if running in Bun environment.
+ *
+ * @returns True if running in Bun, false otherwise
+ *
+ * @since 1.2.0
+ */
+export declare function isBun(): boolean;
+/**
+ * Get the current runtime environment.
+ *
+ * @returns The detected runtime environment
+ *
+ * @example
+ * ```typescript
+ * const env = getRuntimeEnvironment();
+ * console.log(`Running in: ${env}`);
+ * ```
+ *
+ * @since 1.2.0
+ */
+export declare function getRuntimeEnvironment(): RuntimeEnvironment;
+/**
+ * Check if Web Crypto API is available.
+ *
+ * @returns True if Web Crypto API is available, false otherwise
+ *
+ * @since 1.2.0
+ */
+export declare function supportsWebCrypto(): boolean;
+/**
+ * Check if Node.js crypto module is available.
+ *
+ * Note: This performs a synchronous check and does not actually import the module.
+ *
+ * @returns True if likely running in Node.js with crypto support, false otherwise
+ *
+ * @since 1.2.0
+ */
+export declare function supportsNodeCrypto(): boolean;
+/**
+ * Check if any cryptographic support is available.
+ *
+ * This is useful for determining if encryption/decryption features can be used.
+ *
+ * @returns True if crypto is supported, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isCryptoSupported()) {
+ *   const encrypted = await encryptSpecimen(specimen, { key: password });
+ * } else {
+ *   console.warn('Crypto not supported in this environment');
+ * }
+ * ```
+ *
+ * @since 1.2.0
+ */
+export declare function isCryptoSupported(): boolean;
+/**
+ * Check if TextEncoder/TextDecoder are available.
+ *
+ * @returns True if text encoding is supported, false otherwise
+ *
+ * @since 1.2.0
+ */
+export declare function supportsTextEncoding(): boolean;
+/**
+ * Check if URL and URLSearchParams are available.
+ *
+ * @returns True if URL APIs are supported, false otherwise
+ *
+ * @since 1.2.0
+ */
+export declare function supportsURLAPIs(): boolean;
+//# sourceMappingURL=environment.d.ts.map

package/dist/types/utils/environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../../src/utils/environment.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,SAAS,GAAG,WAAW,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC;AAM/F;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,IAAI,OAAO,CAMlC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAMnC;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,IAAI,OAAO,CAkBrC;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,IAAI,OAAO,CAKhC;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,IAAI,OAAO,CAK/B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,IAAI,kBAAkB,CAO1D;AAMD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAM3C;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAMD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAM9C;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAMzC"}