@wishknish/knishio-client-ts 0.7.7 → 0.7.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wishknish/knishio-client-ts",
-  "version": "0.7.7",
+  "version": "0.7.8",
   "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",

package/src/KnishIOClient.ts

@@ -84,6 +84,7 @@ import QueryUserActivity from '@/query/QueryUserActivity'
 import QueryToken from '@/query/QueryToken'
 import QueryMetaTypeViaAtom from '@/query/QueryMetaTypeViaAtom'
 import QueryMetaTypeViaMolecule from '@/query/QueryMetaTypeViaMolecule'
+import QueryEmbeddingStatus from '@/query/QueryEmbeddingStatus'
 
 // Mutation imports
 import MutationCreateToken from '@/mutation/MutationCreateToken'
@@ -102,6 +103,10 @@ import MutationRequestAuthorizationGuest from '@/mutation/MutationRequestAuthori
 import MutationLinkIdentifier from '@/mutation/MutationLinkIdentifier'
 import MutationPeering from '@/mutation/MutationPeering'
 import MutationAppendRequest from '@/mutation/MutationAppendRequest'
+import MutationProposeMolecule from '@/mutation/MutationProposeMolecule'
+
+// Response imports
+import ResponseProposeMolecule from '@/response/ResponseProposeMolecule'
 
 // Subscribe imports
 import CreateMoleculeSubscribe from '@/subscribe/CreateMoleculeSubscribe'
@@ -116,7 +121,10 @@ import {
   TransferBalanceException,
   WalletShadowException,
   StackableUnitAmountException,
-  AuthorizationRejectedException
+  AuthorizationRejectedException,
+  MolecularHashMismatchException,
+  SignatureMismatchException,
+  AtomIndexException
 } from '@/exception'
 
 // Type imports
@@ -150,6 +158,13 @@ export default class KnishIOClient {
   private $__remainderWallet: Wallet | null = null
   private lastMoleculeQuery: Mutation | null = null
   private abortControllers: Map<string, AbortController> = new Map()
+  private $__capabilityCache: Record<string, boolean> = {}
+  // Promise-chain mutex serializing MutationProposeMolecule submissions on this
+  // client. Without it, concurrent createMolecule() calls both query the same
+  // ContinuID position and both sign with it — the second is rejected with
+  // OTS position reuse. Auth-token flow (MutationRequestAuthorization) inherits
+  // from MutationProposeMolecule so it's covered by the same lock.
+  private $__moleculeChain: Promise<unknown> = Promise.resolve()
 
   /**
    * Enhanced constructor with standardized configuration validation (Phase 2 Enhancement)
@@ -320,6 +335,7 @@ export default class KnishIOClient {
     this.$__authToken = null
     this.$__remainderWallet = null
     this.lastMoleculeQuery = null
+    this.$__capabilityCache = {}
   }
 
   /**
@@ -344,6 +360,20 @@ export default class KnishIOClient {
     }
   }
 
+  /**
+   * Sets the WebSocket (subscription) endpoint for this session.
+   *
+   * F-8a (cross-SDK parity, 2026-06-03): `setUri` only updates the HTTP endpoint; the
+   * subscription socket is built once from the `socket.socketUri` passed at
+   * construction. This lets a caller re-point the socket when the endpoint changes
+   * (mirrors the JS SDK's `setSocketUri`).
+   */
+  setSocketUri(socketUri: string): void {
+    if (this.$__client && 'setSocketUri' in this.$__client) {
+      (this.$__client as any).setSocketUri(socketUri)
+    }
+  }
+
   /**
    * Gets the Knish.IO server URIs
    */
@@ -517,6 +547,24 @@ export default class KnishIOClient {
     return mutation
   }
 
+  /**
+   * Serializes the given async work behind a per-client promise chain. Used to
+   * guarantee that at most one MutationProposeMolecule submission runs at a
+   * time on this client — query position, sign, submit, observe response must
+   * complete before the next one starts, or two callers race for the same OTS
+   * position and the second gets rejected.
+   *
+   * `.then(fn, fn)` runs fn whether the previous holder resolved or rejected;
+   * the queue's `.catch` swallows the rejection so a single failure doesn't
+   * poison every subsequent caller, while the rejection still propagates to
+   * the caller whose fn threw.
+   */
+  private withMoleculeLock<T>(fn: () => Promise<T>): Promise<T> {
+    const result = (this.$__moleculeChain as Promise<unknown>).then(fn, fn) as Promise<T>
+    this.$__moleculeChain = result.catch(() => undefined)
+    return result
+  }
+
   /**
    * Executes a query or mutation
    */
@@ -532,10 +580,42 @@ export default class KnishIOClient {
       })
     }
 
+    if (query instanceof MutationProposeMolecule) {
+      return await this.withMoleculeLock(async () => {
+        const response = await query.execute({ variables: variables || {} })
+        this.handlePositionDrift(response)
+        return response
+      })
+    }
+
     // Execute the query
     return await query.execute({ variables: variables || {} })
   }
 
+  /**
+   * When a ProposeMolecule submission is rejected for a position-related
+   * reason (OTS reuse, ContinuID chain violation, molecular hash mismatch),
+   * the cached remainder wallet and lastMoleculeQuery are stale — the
+   * validator's chain has advanced past what we know. Clear them so the next
+   * createMolecule call re-queries queryContinuId for the authoritative
+   * position. Other failure modes (network, malformed meta, bad signature
+   * bytes) don't imply drift; leave cached state alone.
+   */
+  private handlePositionDrift(response: Response | null): void {
+    if (!(response instanceof ResponseProposeMolecule)) return
+    const exc = response.toException()
+    if (!exc) return
+    if (
+      exc instanceof MolecularHashMismatchException ||
+      exc instanceof AtomIndexException ||
+      (exc instanceof SignatureMismatchException && exc.code === 'OTS_VERIFICATION_FAILED')
+    ) {
+      this.$__remainderWallet = null
+      this.lastMoleculeQuery = null
+      this.log('warn', `KnishIOClient::executeQuery() - position drift detected (${exc.name}/${exc.code}); cleared cached remainder wallet`)
+    }
+  }
+
   /**
    * Sets the secret for this session
    */
@@ -1060,6 +1140,76 @@ export default class KnishIOClient {
     return response
   }
 
+  /**
+   * Probes the connected server to check whether it supports a named root query field.
+   * Result is cached per URI so the network round-trip happens at most once per URI.
+   *
+   * Uses GraphQL introspection which is universally supported by spec-compliant servers.
+   *
+   * @param fieldName - The root Query field name to check (e.g. 'embeddingStatus')
+   * @returns true if the server schema includes the field, false otherwise
+   */
+  async hasQueryField(fieldName: string): Promise<boolean> {
+    const uri = this.$__client.getUri()
+    const cacheKey = `${uri}::${fieldName}`
+
+    if (typeof this.$__capabilityCache[cacheKey] === 'boolean') {
+      return this.$__capabilityCache[cacheKey]!
+    }
+
+    try {
+      const result = await this.$__client.query({
+        query: '{ __schema { queryType { fields { name } } } }',
+        variables: {}
+      })
+
+      const data = result?.data as Record<string, any> | undefined
+      const fields: Array<{ name: string }> = data?.__schema?.queryType?.fields || []
+      const supported = fields.some((f: { name: string }) => f.name === fieldName)
+      this.$__capabilityCache[cacheKey] = supported
+      return supported
+    } catch (err: any) {
+      this.log('warn', `KnishIOClient::hasQueryField() - Capability probe for '${fieldName}' failed: ${err.message}`)
+      this.$__capabilityCache[cacheKey] = false
+      return false
+    }
+  }
+
+  /**
+   * Queries embedding status for one or more meta instances (DataBraid observability).
+   *
+   * If the connected server does not support the embeddingStatus query,
+   * returns null without throwing an error (graceful degradation).
+   *
+   * Single mode: queryEmbeddingStatus({ metaType: 'product', metaId: 'SKU-001' })
+   * Bulk mode:   queryEmbeddingStatus({ instances: [{ metaType: 'product', metaId: 'SKU-001' }, ...] })
+   *
+   * @returns Response with payload(), or null if the server does not support this query
+   */
+  async queryEmbeddingStatus({
+    metaType = null,
+    metaId = null,
+    instances = null
+  }: {
+    metaType?: string | null
+    metaId?: string | null
+    instances?: Array<{ metaType: string; metaId: string }> | null
+  }): Promise<Response | null> {
+    this.log('info', `KnishIOClient::queryEmbeddingStatus() - Checking embedding status for metaType: ${metaType || '(bulk)'}...`)
+
+    const supported = await this.hasQueryField('embeddingStatus')
+
+    if (!supported) {
+      this.log('warn', 'KnishIOClient::queryEmbeddingStatus() - Server does not support embeddingStatus query. Returning null.')
+      return null
+    }
+
+    const query = this.createQuery(QueryEmbeddingStatus)
+    const variables = QueryEmbeddingStatus.createVariables({ metaType, metaId, instances })
+
+    return this.executeQuery(query, variables)
+  }
+
   /**
    * Query cascading meta instances for batchId
    */

package/src/core/Molecule.ts

@@ -259,14 +259,13 @@ export default class Molecule {
     const atomMeta = new AtomMeta(meta)
     atomMeta.addPolicy(policy)
 
-    const wallet = Wallet.create({
-      secret: this.secret!,
-      bundle: this.sourceWallet!.bundle!,
-      token: 'USER'
-    })
-
+    // F-3 (cross-SDK parity, 2026-06-03): sign the policy (R-isotope) atom from the
+    // established ContinuID source wallet, NOT a freshly-derived Wallet.create() at a
+    // random position. As the signing atom in createPolicy(), a fresh-wallet position
+    // is unknown to the validator → "ContinuID chain validation failed: signing
+    // position … not found as wallet". Mirrors createRule(), which uses this.sourceWallet.
     this.addAtom(Atom.create({
-      wallet,
+      wallet: this.sourceWallet!,
       isotope: 'R',
       metaType,
       metaId,

package/src/index.ts

@@ -94,6 +94,9 @@ export { default as QueryAtom } from './query/QueryAtom'
 export { default as QueryMetaType } from './query/QueryMetaType'
 export { default as QueryMetaTypeViaAtom } from './query/QueryMetaTypeViaAtom'
 
+// DataBraid Embedding Observability
+export { default as QueryEmbeddingStatus } from './query/QueryEmbeddingStatus'
+
 // Phase 2 Tier 2 Priority 3: Essential Query Operations
 export { default as QueryContinuId } from './query/QueryContinuId'
 export { default as QueryBatch } from './query/QueryBatch'
@@ -134,6 +137,10 @@ export { default as ResponseCreateMeta } from './response/ResponseCreateMeta'
 export { default as ResponseMetaType } from './response/ResponseMetaType'
 export { default as ResponseMetaTypeViaAtom } from './response/ResponseMetaTypeViaAtom'
 
+// DataBraid Embedding Observability
+export { default as ResponseEmbeddingStatus } from './response/ResponseEmbeddingStatus'
+export type { EmbeddingStatusItem } from './response/ResponseEmbeddingStatus'
+
 // Phase 2 Tier 2 Priority 2: Token Operations
 export { default as ResponseCreateToken } from './response/ResponseCreateToken'
 export { default as ResponseRequestTokens } from './response/ResponseRequestTokens'

package/src/libraries/GraphQLClient.ts

@@ -301,6 +301,21 @@ export default class GraphQLClient implements IGraphQLClient {
     })
   }
 
+  /**
+   * F-8a (cross-SDK parity, 2026-06-03): re-point the GraphQL-subscription WebSocket
+   * without changing the HTTP endpoint. `setUri` only updates `serverUri`, leaving the
+   * subscription socket pinned to whatever was passed at construction; this lets a
+   * caller re-derive the socket when the endpoint changes.
+   */
+  setSocketUri(socketUri: string): void {
+    this.socketUri = socketUri
+    this.$__client = this.createUrqlClient({
+      serverUri: this.serverUri,
+      socket: { socketUri },
+      encrypt: this.cipherLink
+    })
+  }
+
   socketDisconnect(): void {
     if (this.socketUri) {
       this.unsubscribeAll()

package/src/query/QueryEmbeddingStatus.ts

@@ -0,0 +1,130 @@
+/*
+                               (
+                              (/(
+                              (//(
+                              (///(
+                             (/////(
+                             (//////(                          )
+                            (////////(                        (/)
+                            (////////(                       (///)
+                           (//////////(                      (////)
+                           (//////////(                     (//////)
+                          (////////////(                    (///////)
+                         (/////////////(                   (/////////)
+                        (//////////////(                  (///////////)
+                        (///////////////(                (/////////////)
+                       (////////////////(               (//////////////)
+                      (((((((((((((((((((              (((((((((((((((
+                     (((((((((((((((((((              ((((((((((((((
+                     (((((((((((((((((((            ((((((((((((((
+                    ((((((((((((((((((((           (((((((((((((
+                    ((((((((((((((((((((          ((((((((((((
+                    (((((((((((((((((((         ((((((((((((
+                    (((((((((((((((((((        ((((((((((
+                    ((((((((((((((((((/      (((((((((
+                    ((((((((((((((((((     ((((((((
+                    (((((((((((((((((    (((((((
+                   ((((((((((((((((((  (((((
+                   #################  ##
+                   ################  #
+                  ################# ##
+                 %################  ###
+                 ###############(   ####
+                ###############      ####
+               ###############       ######
+              %#############(        (#######
+             %#############           #########
+            ############(              ##########
+           ###########                  #############
+          #########                      ##############
+        %######
+
+        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 Query from './Query'
+import ResponseEmbeddingStatus from '../response/ResponseEmbeddingStatus'
+import { gql } from '@urql/core'
+import type { GraphQLClient } from '../types/graphql'
+import type KnishIOClient from '../KnishIOClient'
+
+/**
+ * QueryEmbeddingStatus - Query for retrieving DataBraid embedding status.
+ *
+ * Supports both single-instance and bulk modes:
+ * - Single: { metaType: 'product', metaId: 'SKU-001' }
+ * - Bulk:   { instances: [{ metaType: 'product', metaId: 'SKU-001' }, ...] }
+ *
+ * Returns embedding state (PENDING, STALE, COMPLETE) for each instance,
+ * allowing apps to render spinner badges and completion indicators.
+ *
+ * NOTE: Only available on servers with EMBEDDING_ENABLED=true.
+ * Use KnishIOClient.queryEmbeddingStatus() which handles capability
+ * detection and returns null for unsupported servers.
+ */
+export default class QueryEmbeddingStatus extends Query {
+  /**
+   * Create new QueryEmbeddingStatus instance
+   */
+  constructor(graphQLClient: GraphQLClient, knishIOClient: KnishIOClient) {
+    super(graphQLClient, knishIOClient)
+
+    this.$__query = gql`query( $metaType: String, $metaId: String, $instances: [EmbeddingStatusInput!] ) {
+      embeddingStatus( metaType: $metaType, metaId: $metaId, instances: $instances ) {
+        metaType,
+        metaId,
+        state,
+        totalMetas,
+        embeddedCount,
+        embeddedAt,
+        model
+      }
+    }`
+  }
+
+  /**
+   * Builds a GraphQL-friendly variables object for embedding status queries.
+   *
+   * Single mode: createVariables({ metaType: 'product', metaId: 'SKU-001' })
+   * Bulk mode:   createVariables({ instances: [{ metaType: 'product', metaId: 'SKU-001' }, ...] })
+   */
+  static createVariables({
+    metaType = null,
+    metaId = null,
+    instances = null
+  }: {
+    metaType?: string | null
+    metaId?: string | null
+    instances?: Array<{ metaType: string; metaId: string }> | null
+  } = {}): Record<string, any> {
+    const variables: Record<string, any> = {}
+
+    if (instances && instances.length > 0) {
+      variables.instances = instances
+    }
+
+    if (metaType) {
+      variables.metaType = metaType
+    }
+
+    if (metaId) {
+      variables.metaId = metaId
+    }
+
+    return variables
+  }
+
+  /**
+   * Returns a Response object
+   */
+  override createResponse(json: any): ResponseEmbeddingStatus {
+    return new ResponseEmbeddingStatus({
+      query: this,
+      json
+    })
+  }
+}

package/src/response/ResponseEmbeddingStatus.ts

@@ -0,0 +1,107 @@
+/*
+                               (
+                              (/(
+                              (//(
+                              (///(
+                             (/////(
+                             (//////(                          )
+                            (////////(                        (/)
+                            (////////(                       (///)
+                           (//////////(                      (////)
+                           (//////////(                     (//////)
+                          (////////////(                    (///////)
+                         (/////////////(                   (/////////)
+                        (//////////////(                  (///////////)
+                        (///////////////(                (/////////////)
+                       (////////////////(               (//////////////)
+                      (((((((((((((((((((              (((((((((((((((
+                     (((((((((((((((((((              ((((((((((((((
+                     (((((((((((((((((((            ((((((((((((((
+                    ((((((((((((((((((((           (((((((((((((
+                    ((((((((((((((((((((          ((((((((((((
+                    (((((((((((((((((((         ((((((((((((
+                    (((((((((((((((((((        ((((((((((
+                    ((((((((((((((((((/      (((((((((
+                    ((((((((((((((((((     ((((((((
+                    (((((((((((((((((    (((((((
+                   ((((((((((((((((((  (((((
+                   #################  ##
+                   ################  #
+                  ################# ##
+                 %################  ###
+                 ###############(   ####
+                ###############      ####
+               ###############       ######
+              %#############(        (#######
+             %#############           #########
+            ############(              ##########
+           ###########                  #############
+          #########                      ##############
+        %######
+
+        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 type Query from '../query/Query'
+import Response from './Response'
+
+/**
+ * EmbeddingStatusItem shape returned by the server.
+ */
+export interface EmbeddingStatusItem {
+  /** Metadata type (echoed from input) */
+  metaType: string
+  /** Instance identifier (echoed from input) */
+  metaId: string
+  /** Embedding state: 'PENDING' | 'STALE' | 'COMPLETE' */
+  state: 'PENDING' | 'STALE' | 'COMPLETE'
+  /** Total meta rows for this instance */
+  totalMetas: number
+  /** Rows with current-model embeddings */
+  embeddedCount: number
+  /** Unix epoch of most recent embedding, or null */
+  embeddedAt: number | null
+  /** Model name used for embeddings, or null */
+  model: string | null
+}
+
+/**
+ * ResponseEmbeddingStatus - Response for EmbeddingStatus Query
+ *
+ * Payload is an array of EmbeddingStatusItem objects.
+ */
+export default class ResponseEmbeddingStatus extends Response {
+  /**
+   * Class constructor
+   */
+  constructor({
+    query,
+    json
+  }: {
+    query: Query
+    json: any
+  }) {
+    super({
+      query,
+      json,
+      dataKey: 'data.embeddingStatus'
+    })
+  }
+
+  /**
+   * Returns the array of embedding status items, or null if empty.
+   */
+  override payload(): EmbeddingStatusItem[] | null {
+    const items = this.data()
+
+    if (!items || !Array.isArray(items) || items.length === 0) {
+      return null
+    }
+
+    return items as EmbeddingStatusItem[]
+  }
+}

package/src/response/ResponseProposeMolecule.ts

@@ -50,6 +50,10 @@ import Response from './Response'
 import Dot from '../libraries/Dot'
 import Molecule from '../core/Molecule'
 import type Query from '../query/Query'
+import type BaseException from '../exception/BaseException'
+import MolecularHashMismatchException from '../exception/MolecularHashMismatchException'
+import SignatureMismatchException from '../exception/SignatureMismatchException'
+import AtomIndexException from '../exception/AtomIndexException'
 
 /**
  * Response for proposing new Molecules
@@ -143,6 +147,49 @@ export default class ResponseProposeMolecule extends Response {
     return Dot.get(this.data(), 'reason', 'Invalid response from server') as string
   }
 
+  /**
+   * Map this rejection to a typed SDK exception when the failure mode is one
+   * we know about. Returns null on success or for rejections we don't have a
+   * typed class for.
+   *
+   * This is the single place pattern-matching against validator reason strings
+   * lives — consumers (KnishIOClient cache invalidation, callers needing to
+   * branch on failure mode) can `instanceof`-switch on the result instead.
+   * Future validator versions can rephrase reasons (or populate a structured
+   * field in the response payload) without breaking callers.
+   */
+  toException(): BaseException | null {
+    if (this.success()) return null
+    const reason = this.reason()
+    const lc = reason.toLowerCase()
+
+    if (/molecularhashmismatch|hash.*mismatch/.test(lc)) {
+      return new MolecularHashMismatchException(reason, {
+        details: { reason },
+        code: 'HASH_MISMATCH'
+      })
+    }
+    if (/ots.*position.*reuse|position.*already.*used|ots.*verification/.test(lc)) {
+      return new SignatureMismatchException(reason, {
+        details: { reason },
+        code: 'OTS_VERIFICATION_FAILED'
+      })
+    }
+    if (/continuid.*chain|previousposition|chain.*violation/.test(lc)) {
+      return new AtomIndexException(reason, {
+        details: { reason },
+        code: 'INDEX_CONFLICT'
+      })
+    }
+    if (/signature.*verification|signature.*invalid/.test(lc)) {
+      return new SignatureMismatchException(reason, {
+        details: { reason },
+        code: 'VERIFICATION_FAILED'
+      })
+    }
+    return null
+  }
+
   /**
    * Returns payload object
    * Matches JavaScript SDK payload method exactly