@wishknish/knishio-client-ts 0.9.4 → 0.9.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wishknish/knishio-client-ts",
-  "version": "0.9.4",
+  "version": "0.9.6",
   "productName": "Knish.IO TypeScript SDK Client",
   "description": "TypeScript implementation of the Knish.IO SDK to consume Knish.IO GraphQL APIs with enhanced type safety.",
   "license": "GPL-3.0-or-later",
@@ -58,32 +58,30 @@
     "fips-203"
   ],
   "dependencies": {
-    "@noble/post-quantum": "^0.5.4",
-    "@thumbmarkjs/thumbmarkjs": "^0.19.1",
-    "@urql/core": "^5.2.0",
-    "graphql": "^16.11.0",
-    "graphql-ws": "^6.0.7",
-    "isomorphic-fetch": "^3.0.0",
-    "jssha": "^3.3.1",
+    "@noble/post-quantum": "^0.7.0",
+    "@urql/core": "^6.0.3",
+    "graphql": "^16.14.2",
+    "graphql-ws": "^6.2.1",
+    "jssha": "^3.3.2",
     "tslib": "^2.8.1",
-    "wonka": "^6.3.5",
-    "zod": "^3.23.8"
+    "wonka": "^6.3.6",
+    "zod": "^4.5.4"
   },
   "devDependencies": {
-    "@types/isomorphic-fetch": "^0.0.39",
     "@types/jssha": "^3.0.0",
-    "@types/node": "^22",
-    "@typescript-eslint/eslint-plugin": "^8.63.0",
-    "@typescript-eslint/parser": "^8.63.0",
-    "@vitest/coverage-v8": "^4.1.10",
-    "eslint": "^9",
-    "prettier": "^3",
+    "@types/node": "^26",
+    "@typescript-eslint/eslint-plugin": "^8.67.0",
+    "@typescript-eslint/parser": "^8.67.0",
+    "@vitest/coverage-v8": "^4.1.11",
+    "eslint": "^10",
+    "prettier": "^3.9.6",
     "tsup": "^8.5.1",
-    "tsx": "^4.23.0",
+    "tsx": "^4.23.12",
     "typescript": "^5",
-    "vite": "^7",
-    "vite-plugin-dts": "^5.0.3",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.11"
+  },
+  "resolutions": {
+    "wonka": "6.3.6"
   },
   "browserslist": [
     "> 1%",
@@ -103,7 +101,6 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "test:ui": "vitest --ui",
-    "dev": "vite",
     "prepublishOnly": "npm run build",
     "selftest": "npm run build && node self-test.cjs"
   },
@@ -113,7 +110,7 @@
     "README.md",
     "LICENSE"
   ],
-  "packageManager": "yarn@4.6.0",
+  "packageManager": "yarn@4.15.0",
   "engines": {
     "node": ">=18.0.0"
   }

package/src/KnishIOClient.ts

@@ -104,6 +104,7 @@ import MutationLinkIdentifier from '@/mutation/MutationLinkIdentifier'
 import MutationPeering from '@/mutation/MutationPeering'
 import MutationAppendRequest from '@/mutation/MutationAppendRequest'
 import MutationProposeMolecule from '@/mutation/MutationProposeMolecule'
+import MutationReplenishToken from '@/mutation/MutationReplenishToken'
 
 // Response imports
 import ResponseProposeMolecule from '@/response/ResponseProposeMolecule'
@@ -1836,27 +1837,55 @@ export default class KnishIOClient {
   }
 
   /**
-   * Replenish tokens
+   * Replenish a non-finite token supply.
+   * Matches JS SDK KnishIOClient.replenishToken (KnishIOClient.js:2195-2231).
    */
   async replenishToken({
     token,
     amount = null,
     units = null,
-    sourceWallet: _sourceWallet = null
+    sourceWallet = null
   }: {
     token: TokenSlug | string
     amount?: number | string | null
-    units?: string[] | null
+    units?: Array<[string, string, Record<string, any>?]> | null
     sourceWallet?: Wallet | null
   }): Promise<Response> {
     this.log('info', `KnishIOClient::replenishToken() - Replenishing ${amount || 'units'} of ${token}...`)
 
-    // Similar to requestTokens but with specific replenishment logic
-    return this.requestTokens({
-      token,
-      amount,
-      units
+    if (!sourceWallet) {
+      sourceWallet = (await this.queryBalance({ token }))?.payload() as Wallet | null
+    }
+    if (!sourceWallet) {
+      throw new TransferBalanceException('Source wallet is missing or invalid.')
+    }
+
+    // Remainder wallet (same token, so the V-isotope pair conserves)
+    const remainderWallet = sourceWallet.createRemainder(this.getSecret())
+
+    const molecule = await this.createMolecule({
+      sourceWallet,
+      remainderWallet
+    })
+    molecule.replenishToken({
+      amount: Number(amount ?? 0),
+      units: units ?? []
     })
+    molecule.sign({ bundle: this.getBundle() })
+    molecule.check()
+
+    const mutation = await this.createMoleculeMutation({
+      mutationClass: MutationReplenishToken,
+      molecule
+    })
+
+    const response = await this.executeQuery(mutation)
+
+    if (!response) {
+      throw new CodeException('Token replenishment failed')
+    }
+
+    return response
   }
 
   /**

package/src/core/AtomMeta.ts

@@ -47,6 +47,7 @@ License: https://github.com/WishKnish/KnishIO-Client-TS/blob/master/LICENSE
 */
 
 import Meta, { type NormalizedMeta } from './Meta'
+import PolicyMeta from './PolicyMeta'
 
 // Configuration constants matching JS SDK
 const USE_META_CONTEXT = false
@@ -172,12 +173,19 @@ export default class AtomMeta {
    * @return This instance for chaining
    */
   addPolicy(policy: Record<string, any>): AtomMeta {
-    // For now, just stringify the policy
-    // TODO: Implement PolicyMeta class if needed
+    // Normalise through PolicyMeta before serialising. PolicyMeta.fillDefault adds a default
+    // entry for every meta key not already covered by the caller's policy, so the stored string
+    // carries materially more than the input — and this string is hashed into the atom, so a
+    // raw JSON.stringify(policy) diverges from every other SDK.
+    // Matches JS SDK AtomMeta.addPolicy (AtomMeta.js:170-175), including passing
+    // Object.keys(this.meta): `meta` is a NormalizedMeta[] in both SDKs, so these are array
+    // indices rather than meta key names. Faithful to the JS behaviour — do not "correct" it.
+    const policyMeta = new PolicyMeta(policy, Object.keys(this.meta))
+
     this.merge({
-      policy: JSON.stringify(policy)
+      policy: policyMeta.toJson()
     })
-    
+
     return this
   }
 

package/src/core/Molecule.ts

@@ -755,6 +755,67 @@ export default class Molecule {
     return this
   }
 
+  /**
+   * Replenishes non-finite token supplies.
+   * Matches JS SDK Molecule.replenishToken (Molecule.js:521-566) exactly.
+   *
+   * Two orderings here are load-bearing for the molecular hash and must not be reordered:
+   * the remainder balance is computed BEFORE the source balance is overwritten, and the
+   * source V-atom is added BEFORE the remainder V-atom.
+   */
+  replenishToken({
+    amount,
+    units = []
+  }: {
+    amount: number
+    units?: Array<[string, string, Record<string, any>?]>
+  }): Molecule {
+    if (amount < 0) {
+      throw new NegativeAmountException('Molecule::replenishToken() - Amount to replenish must be positive!')
+    }
+
+    if (!this.sourceWallet || !this.remainderWallet) {
+      throw new Error('Source and remainder wallets required for token replenishment')
+    }
+
+    if (units.length) {
+      // Prepare token units to formatted style
+      const formatted = Wallet.getTokenUnits(units)
+
+      // Merge token units with source wallet & new items
+      this.remainderWallet.tokenUnits = this.sourceWallet.tokenUnits
+      for (const unit of formatted) {
+        this.remainderWallet.tokenUnits.push(unit)
+      }
+      this.remainderWallet.balance = String(this.remainderWallet.tokenUnits.length)
+
+      // Override first atom's token units to replenish values
+      this.sourceWallet.tokenUnits = formatted
+      this.sourceWallet.balance = String(this.sourceWallet.tokenUnits.length)
+    } else {
+      // Update wallet's balances
+      this.remainderWallet.balance = String(Number(this.sourceWallet.balance) + amount)
+      this.sourceWallet.balance = String(amount)
+    }
+
+    // Initializing a new Atom to remove tokens from source
+    this.addAtom(Atom.create({
+      isotope: 'V',
+      wallet: this.sourceWallet,
+      value: Number(this.sourceWallet.balance)
+    }))
+
+    this.addAtom(Atom.create({
+      isotope: 'V',
+      wallet: this.remainderWallet,
+      value: Number(this.remainderWallet.balance),
+      metaType: 'walletBundle',
+      metaId: this.remainderWallet.bundle!
+    }))
+
+    return this
+  }
+
   /**
    * Initialize authorization request
    * Creates U-isotope (authorization) atom for requesting auth token

package/src/core/Wallet.ts

@@ -51,6 +51,7 @@ import { randomString, chunkSubstr, isHex } from '@/libraries/strings'
 import { generateBundleHash, generateSecret, shake256, generateBatchId } from '@/libraries/crypto'
 import WalletCredentialException from '@/exception/WalletCredentialException'
 import { isBundleHash } from '@/types'
+import TokenUnit from '@/core/TokenUnit'
 // Post-quantum cryptography for ML-KEM768 key encapsulation
 import { ml_kem768 } from '@noble/post-quantum/ml-kem.js'
 
@@ -271,12 +272,13 @@ export default class Wallet {
   }
 
   /**
-   * Get formatted token units from raw data
-   * Stub implementation for now
+   * Map raw token-unit tuples to TokenUnit instances.
+   * Matches JS SDK Wallet.getTokenUnits (Wallet.js:190-196). The serialised shape reaches hashed
+   * atom meta via AtomMeta.setAtomWallet -> JSON.stringify(getTokenUnitsData()), so returning raw
+   * tuples here would diverge from every other SDK.
    */
-  static getTokenUnits(unitsData: any[]): any[] {
-    // TODO: Implement TokenUnit class if needed
-    return unitsData
+  static getTokenUnits(unitsData: Array<[string, string, Record<string, any>?]>): TokenUnit[] {
+    return unitsData.map(unitData => TokenUnit.createFromDB(unitData))
   }
 
   /**

package/src/index.ts

@@ -359,7 +359,10 @@ export {
 // VERSION AND SDK INFORMATION
 // =============================================================================
 
-export const SDK_VERSION = '1.0.0'
+// MUST equal package.json's "version". The CI `version consistency` job enforces this via
+// .github/scripts/check-version.sh, which parses this exact line — keep the literal form
+// `export const SDK_VERSION = '<semver>'` intact so the gate can read it.
+export const SDK_VERSION = '0.9.6'
 export const SDK_NAME = 'KnishIO-Client-TS'
 export const COMPATIBLE_SERVER_VERSIONS = [4, 5]
 

package/src/instance/rules/Callback.ts

@@ -69,7 +69,7 @@ const CallbackParamsSchema = z.object({
   action: z.string().min(1, 'Action cannot be empty'),
   metaType: z.union([z.string(), z.null()]).optional(),
   metaId: z.union([z.string(), z.null()]).optional(),
-  meta: z.union([z.instanceof(Meta), z.record(z.unknown()), z.null()]).optional(),
+  meta: z.union([z.instanceof(Meta), z.record(z.string(), z.unknown()), z.null()]).optional(),
   address: z.union([z.string(), z.null()]).optional(),
   token: z.union([z.string(), z.null()]).optional(),
   amount: z.union([z.string(), z.null()]).optional(),

package/src/libraries/GraphQLClient.ts

@@ -141,16 +141,30 @@ export default class GraphQLClient implements IGraphQLClient {
     return createClient({
       url: serverUri,
       exchanges,
-      // PQ-transport Phase E: when encryption is on, route fetch through the CipherHash wrapper
-      // (encrypt the request body to the validator's ML-KEM pubkey, decrypt the response).
-      // Omitted → urql uses the global fetch (plaintext).
-      ...(this.cipherLink ? { fetch: ((input: any, init: any) => this.cipherFetch(input, init)) as typeof fetch } : {}),
+      // urql 5 had no default and always POSTed; urql 6 defaults to 'within-url-limit', which
+      // URL-encodes short queries and sends NO body. That would silently disable the CipherHash
+      // envelope below — cipherFetch's `typeof init.body === 'string'` guard fails on a GET, so
+      // the query would leave as plaintext URL parameters with no error. Pin POST explicitly.
+      preferGetMethod: false,
+      // Always route through our own fetch. Two reasons: (1) PQ-transport Phase E — when
+      // encryption is on, cipherFetch wraps the request body in the CipherHash envelope and
+      // decrypts the response; (2) the 60s timeout. urql's makeFetchSource unconditionally
+      // overwrites init.signal with its own AbortController, so a signal returned from
+      // fetchOptions() is discarded and never fired. Combining it here is the only place it
+      // survives.
+      fetch: ((input: RequestInfo | URL, init?: RequestInit) => {
+        const timeoutSignal = AbortSignal.timeout(60000)
+        // Keep urql's own signal so teardown still aborts; AbortSignal.any needs Node >= 18.17.
+        const signal = init?.signal && typeof AbortSignal.any === 'function'
+          ? AbortSignal.any([init.signal, timeoutSignal])
+          : (init?.signal ?? timeoutSignal)
+        const timedInit: RequestInit = { ...init, signal }
+        return this.cipherLink ? this.cipherFetch(input, timedInit) : fetch(input, timedInit)
+      }) as typeof fetch,
       fetchOptions: () => ({
         headers: {
           'X-Auth-Token': this.$__authToken
-        },
-        // Add 60 second timeout
-        signal: AbortSignal.timeout(60000)
+        }
       })
     })
   }

package/src/libraries/UrqlClientWrapper.ts

@@ -155,12 +155,17 @@ class UrqlClientWrapper {
     return createClient({
       url: serverUri,
       exchanges,
+      // urql 6 defaults preferGetMethod to 'within-url-limit', sending short queries as GET with
+      // no body. Keep the urql-5 behaviour (always POST) so this client matches GraphQLClient and
+      // cannot silently change the wire format if it is ever put back into use.
+      preferGetMethod: false,
+      // No `signal` here: urql's makeFetchSource overwrites init.signal with its own
+      // AbortController, so a timeout passed through fetchOptions() is silently discarded and
+      // never fires. GraphQLClient applies its 60s timeout inside a wrapping `fetch` instead.
       fetchOptions: () => ({
         headers: {
           'X-Auth-Token': this.$__authToken
-        },
-        // Add 60 second timeout for debugging
-        signal: AbortSignal.timeout(60000)
+        }
       })
     })
   }

package/src/libraries/crypto.ts

@@ -659,13 +659,11 @@ export function verifyOTSSignature(
     const enumerated = enumerateMolecularHash(base17Hash)
     const normalized = normalizeMolecularHash(enumerated)
     
-    // Step 2: Process OTS fragments (handle compression if needed)
-    let ots = otsFragments
+    // Step 2: Fragments must be the uncompressed 2048-character form. Base64-compressed
+    // signatures are not supported and are rejected here rather than expanded.
+    const ots = otsFragments
     if (ots.length !== 2048) {
-      // If not 2048 chars, it might be base64 compressed - for now, assume uncompressed
-      if (ots.length !== 2048) {
-        return false // Invalid signature length
-      }
+      return false
     }
     
     // Step 3: Subdivide OTS into 16 segments of 128 characters each

package/src/mutation/MutationReplenishToken.ts

@@ -0,0 +1,28 @@
+/*
+        Powered by Knish.IO: Connecting a Decentralized World
+
+Please visit https://github.com/WishKnish/KnishIO-Client-TS for information.
+
+License: https://github.com/WishKnish/KnishIO-Client-TS/blob/master/LICENSE
+*/
+
+import MutationProposeMolecule from './MutationProposeMolecule'
+
+/**
+ * Mutation for replenishing a non-finite token supply.
+ *
+ * The JS SDK submits replenishment through `MutationProposeMolecule` directly
+ * (KnishIOClient.js:2226-2230), but that class is abstract here because it declares
+ * `fillMolecule`. This subclass exists to provide the concrete type; it inherits the identical
+ * `ProposeMolecule(molecule: $molecule)` document from the base, so the request on the wire is
+ * the same one the JS SDK sends.
+ *
+ * `fillMolecule` is intentionally a no-op: KnishIOClient.replenishToken builds the V-atom pair
+ * via Molecule.replenishToken, then signs and checks the molecule, before this mutation is
+ * constructed. There is nothing left to fill.
+ */
+export default class MutationReplenishToken extends MutationProposeMolecule {
+  override fillMolecule(): void {
+    // Intentionally empty — the molecule arrives fully built, signed and checked.
+  }
+}

package/src/schemas/index.ts

@@ -62,6 +62,21 @@ import { z } from 'zod'
 const hexStringRegex = /^[0-9a-fA-F]+$/
 const base17HashRegex = /^[0-9a-g]+$/
 
+// Zod 3's `.url()` was `try { new URL(v) } catch` and returned the input UNCHANGED.
+// Zod 4's `z.url()` returns the normalized `URL.href` instead — it strips default ports and
+// lowercases the host — and there is no opt-out. The parsed `uri` is the endpoint the client
+// actually talks to (KnishIOClient destructures it out of the validated config), so a
+// refinement is used here: it validates exactly as v3 did without rewriting the value.
+const urlString = (message = 'Invalid URL') =>
+  z.string().refine((value) => {
+    try {
+      new URL(value)
+      return true
+    } catch {
+      return false
+    }
+  }, message)
+
 export const HexStringSchema = z.string()
   .regex(hexStringRegex, 'Must be a valid hexadecimal string')
   .brand<'HexString'>()
@@ -102,7 +117,7 @@ export const MetaIdSchema = z.string()
   .brand<'MetaId'>()
 
 export const BatchIdSchema = z.string()
-  .min(1, 'Batch ID cannot be empty')
+  .regex(/^[0-9a-fA-F]{64}$/, 'Batch ID must be 64 hexadecimal characters')
   .brand<'BatchId'>()
 
 export const CellSlugSchema = z.string()
@@ -115,7 +130,7 @@ export const CellSlugSchema = z.string()
 // =============================================================================
 
 export const AtomIsotopeSchema = z.enum(['C', 'V', 'U', 'T', 'M', 'I', 'R', 'B', 'F'], {
-  errorMap: () => ({ message: 'Invalid atom isotope. Must be one of: C, V, U, T, M, I, R, B, F' })
+  error: 'Invalid atom isotope. Must be one of: C, V, U, T, M, I, R, B, F'
 })
 
 // =============================================================================
@@ -135,7 +150,7 @@ export const AtomMetaDataSchema = z.object({
 }).strict()
 
 export const MetaDataSchema: z.ZodType<Record<string, any>> = z.lazy(() =>
-  z.record(z.union([
+  z.record(z.string(), z.union([
     MetaDataValueSchema,
     MetaDataSchema,
     z.array(MetaDataSchema)
@@ -186,7 +201,7 @@ export const MoleculeParamsSchema = z.object({
 // =============================================================================
 
 export const KnishIOClientConfigSchema = z.object({
-  uri: z.union([z.string().url(), z.array(z.string().url())]).optional(),
+  uri: z.union([urlString(), z.array(urlString())]).optional(),
   cellSlug: z.union([CellSlugSchema, z.string(), z.null()]).optional(),
   client: z.unknown().optional(),
   socket: z.unknown().optional(),
@@ -209,7 +224,7 @@ export const AuthTokenParamsSchema = z.object({
 export const AuthParamsSchema = z.object({
   cellSlug: z.union([CellSlugSchema, z.string(), z.null()]).optional(),
   encrypt: z.boolean().optional(),
-  callback: z.function().args(z.unknown()).returns(z.void()).optional()
+  callback: z.custom<(arg: unknown) => void>((value) => typeof value === 'function').optional()
 }).strict()
 
 export const GuestAuthParamsSchema = z.object({
@@ -224,7 +239,7 @@ export const TransferParamsSchema = z.object({
   recipient: z.union([WalletAddressSchema, z.string()]),
   amount: z.union([z.number().positive(), z.string().min(1)]),
   token: z.union([TokenSlugSchema, z.string()]).optional(),
-  callbackUrl: z.union([z.string().url(), z.null()]).optional(),
+  callbackUrl: z.union([urlString(), z.null()]).optional(),
   metaType: z.union([MetaTypeSchema, z.string(), z.null()]).optional(),
   metaId: z.union([MetaIdSchema, z.string(), z.null()]).optional(),
   meta: z.union([MetaDataSchema, z.null()]).optional()
@@ -278,7 +293,7 @@ export const MetaQueryParamsSchema = z.object({
   value: z.union([z.string(), z.null()]).optional(),
   latest: z.union([z.boolean(), z.null()]).optional(),
   filter: z.union([z.array(MetaFilterSchema), z.null()]).optional(),
-  queryArgs: z.union([z.record(z.unknown()), z.null()]).optional(),
+  queryArgs: z.union([z.record(z.string(), z.unknown()), z.null()]).optional(),
   count: z.union([z.number().int().min(1), z.null()]).optional(),
   countBy: z.union([z.string(), z.null()]).optional(),
   cellSlug: z.union([CellSlugSchema, z.string(), z.null()]).optional()
@@ -316,7 +331,7 @@ export const SignatureResultSchema = z.object({
 
 export const GraphQLRequestSchema = z.object({
   query: z.string().min(1, 'GraphQL query cannot be empty'),
-  variables: z.record(z.unknown()).optional(),
+  variables: z.record(z.string(), z.unknown()).optional(),
   operationName: z.union([z.string(), z.null()]).optional()
 }).strict()
 
@@ -327,13 +342,13 @@ export const GraphQLErrorSchema = z.object({
     column: z.number().int().min(1)
   })).optional(),
   path: z.array(z.union([z.string(), z.number()])).optional(),
-  extensions: z.record(z.unknown()).optional()
+  extensions: z.record(z.string(), z.unknown()).optional()
 }).strict()
 
 export const GraphQLResponseSchema = z.object({
   data: z.unknown().optional(),
   errors: z.array(GraphQLErrorSchema).nullable().optional(),
-  extensions: z.record(z.unknown()).optional()
+  extensions: z.record(z.string(), z.unknown()).optional()
 }).strict()
 
 // =============================================================================
@@ -343,8 +358,8 @@ export const GraphQLResponseSchema = z.object({
 export const SubscriptionOptionsSchema = z.object({
   operationName: z.string().optional(),
   query: z.string().optional(),
-  variables: z.record(z.unknown()).optional(),
-  callback: z.function().args(z.unknown()).returns(z.void()).optional()
+  variables: z.record(z.string(), z.unknown()).optional(),
+  callback: z.custom<(arg: unknown) => void>((value) => typeof value === 'function').optional()
 }).strict()
 
 // =============================================================================
@@ -364,7 +379,7 @@ export const ValidationResultSchema = z.object({
 
 export const ErrorContextSchema = z.object({
   operation: z.string().optional(),
-  parameters: z.record(z.unknown()).optional(),
+  parameters: z.record(z.string(), z.unknown()).optional(),
   timestamp: z.number().int().min(0).optional(),
   stack: z.string().optional()
 }).strict()
@@ -407,7 +422,7 @@ export const KnishIOErrorTypeSchema = z.enum([
  * Validates and parses data using a Zod schema with enhanced error messages
  */
 export function parseWithSchema<T>(
-  schema: z.ZodSchema<T>,
+  schema: z.ZodType<T>,
   data: unknown,
   context?: string
 ): T {
@@ -428,7 +443,7 @@ export function parseWithSchema<T>(
  * Type-safe validation that returns a result object instead of throwing
  */
 export function validateWithSchema<T>(
-  schema: z.ZodSchema<T>,
+  schema: z.ZodType<T>,
   data: unknown
 ): { success: true; data: T } | { success: false; error: string } {
   const result = schema.safeParse(data)
@@ -444,7 +459,7 @@ export function validateWithSchema<T>(
  * Validates multiple values with their respective schemas
  */
 export function validateMultiple<T extends Record<string, any>>(
-  validations: { [K in keyof T]: { schema: z.ZodSchema<T[K]>; data: unknown } }
+  validations: { [K in keyof T]: { schema: z.ZodType<T[K]>; data: unknown } }
 ): T {
   const result = {} as T
   

package/src/types/assertions.ts

@@ -399,12 +399,12 @@ export function assertBatchId(
 ): asserts value is BatchId {
   if (!isBatchId(value)) {
     throw new AssertionError(
-      createAssertionMessage('BatchId (UUID format)', value, context),
+      createAssertionMessage('BatchId (64-character hex)', value, context),
       'BatchId',
       value,
       { 
         operation: 'batch_id_assertion',
-        expected: 'UUID v4 format',
+        expected: '64-character hexadecimal string',
         actual: value,
         field: context
       }

package/src/validation/ValidationService.ts

@@ -182,9 +182,7 @@ export class ValidationService {
         KNISHIO_SERVER_SDK_VERSION: process.env.KNISHIO_SERVER_SDK_VERSION
       }
 
-      // cast: EnvironmentConfig uses .default()/.optional() so its inferred input≠output type and
-      // doesn't structurally match safeParse's ZodType<T> param; ZodTypeAny sidesteps the mismatch.
-      const parseResult = safeParse(Schemas.EnvironmentConfig as z.ZodTypeAny, env)
+      const parseResult = safeParse(Schemas.EnvironmentConfig, env)
       
       if (!parseResult.success) {
         return {