Documentation

QuantumOS Integration

@kynetra/fx-quantumos binds deployment, canonical events, and hybrid RAG to one dependency-aware FXFabric. Use direct transports in-process or an explicit HTTPS bridge without coupling application code to QuantumOS internals.

What the integration guarantees#

Dependency-ordered startup, startup rollback, reverse shutdown, and bounded health checks.
Tenant, correlation, and idempotency context on bridge requests.
Deterministic SHA-256 chunks, bulk source replacement, and bounded embedding concurrency.
Tenant and SKU filtering before hybrid lexical/vector ranking.
Source diversity, thresholds, retrieval diagnostics, and grounded citations.

Warning

Bridge paths are required configuration. Kynetra FX does not invent QuantumOS endpoints, and a successful local contract test is not evidence of a live QuantumOS deployment.

Configure the bridge#

src/quantumos.ts

import { createQuantumOSFabric, createQuantumOSHttpBridge, mockAi } from '@kynetra/fx'
 
const bridge = createQuantumOSHttpBridge({
  baseUrl: process.env.QUANTUMOS_BRIDGE_URL!,
  token: () => Promise.resolve(process.env.QUANTUMOS_BRIDGE_TOKEN!),
  paths: {
    health: '/fx/health',
    deployments: '/fx/deployments',
    events: '/fx/events',
    ragReplace: '/fx/rag/replace',
    ragVectorSearch: '/fx/rag/vector',
    ragLexicalSearch: '/fx/rag/lexical'
  }
})
 
export const quantum = createQuantumOSFabric({
  id: 'resolve-api:tenant-a',
  tenantId: 'tenant-a',
  ai: mockAi({ dim: 32 }), // replace with the production AiPort
  deployment: bridge.deployment,
  events: {
    transport: bridge.events,
    source: 'kynetra-fx',
    moduleId: 'resolve-api',
    version: '1.0.0'
  },
  rag: bridge.rag
})
 
await quantum.fabric.start()

Deploy with traceability#

src/deploy.ts

const correlationId = crypto.randomUUID()
const deployment = await quantum.deployments.deploy({
  tenantId: 'tenant-a',
  correlationId,
  idempotencyKey: 'resolve-api:1.0.0:tenant-a',
  manifest: {
    serviceId: 'resolve-api',
    name: 'Resolve API',
    version: '1.0.0',
    target: 'cloudflare-worker',
    baseUrl: 'https://resolve.example.com',
    healthPath: '/health',
    tenantMode: 'multi',
    capabilities: ['rag', 'events']
  }
})
 
await quantum.events.publish({
  type: 'deployment.requested',
  tenantId: 'tenant-a',
  correlationId,
  data: { deploymentId: deployment.id }
})

RAG pipeline#

Ingestion embeds every batch before replacing source data, so an embedding failure leaves the previous source intact. Retrieval runs vector and lexical search concurrently, fuses ranks, applies score and source caps, and returns diagnostics with every result.

src/knowledge.ts

await quantum.rag.ingest([{
  tenantId: 'tenant-a',
  sourceId: 'manual-1',
  sourceTitle: 'Resolve manual',
  sourceKind: 'manual',
  sku: 'RESOLVE-PRO',
  text: manualText
}])
 
const result = await quantum.rag.answer({
  tenantId: 'tenant-a',
  sku: 'RESOLVE-PRO',
  query: 'How is rollback handled?',
  topK: 6,
  maxPerSource: 2,
  minScore: 0.08
})
 
console.log(result.answer, result.citations, result.diagnostics)

Hand-in gate#

Verify tenancy

Prove two tenants and two SKUs cannot retrieve each other's chunks.

Verify deployment

Test idempotent deploy, status polling, health, and rollback on staging.

Verify evidence

Record deployment and request IDs, contract results, release URL, and rollback owner.

PreviousSelf-hosting NextWASM handlers