@ultrst-armada/kloks 1.0.2 → 1.1.1

package/index.d.ts

@@ -2,4 +2,6 @@ export * from './packages/functions/dist/index.d.ts';
 export * from './packages/state-graph/dist/index.d.ts';
 export * from './packages/audio-midi/dist/index.d.ts';
 export * from './packages/services/dist/index.d.ts';
+export * from './packages/backend/dist/index.d.ts';
 export * from './packages/orchestrations/dist/index.d.ts';
+export * from './packages/contracts/dist/index.d.ts';

package/index.js

@@ -2,4 +2,6 @@ export * from './packages/functions/dist/index.js';
 export * from './packages/state-graph/dist/index.js';
 export * from './packages/audio-midi/dist/index.js';
 export * from './packages/services/dist/index.js';
+export * from './packages/backend/dist/index.js';
 export * from './packages/orchestrations/dist/index.js';
+export * from './packages/contracts/dist/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultrst-armada/kloks",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "private": false,
   "publishConfig": {
     "access": "public",
@@ -84,19 +84,22 @@
       "import": "./packages/backend/dist/execution/index.js",
       "default": "./packages/backend/dist/execution/index.js"
     },
+    "./backend/krnl-services": {
+      "types": "./packages/backend/dist/krnl-services.d.ts",
+      "import": "./packages/backend/dist/krnl-services.js",
+      "default": "./packages/backend/dist/krnl-services.js"
+    },
     "./orchestrations": {
       "types": "./packages/orchestrations/dist/index.d.ts",
       "import": "./packages/orchestrations/dist/index.js",
       "default": "./packages/orchestrations/dist/index.js"
+    },
+    "./contracts": {
+      "types": "./packages/contracts/dist/index.d.ts",
+      "import": "./packages/contracts/dist/index.js",
+      "default": "./packages/contracts/dist/index.js"
     }
   },
-  "scripts": {
-    "build": "pnpm -r run build",
-    "postbuild": "node -e \"import('fs').then(fs => { for (const pkg of fs.readdirSync('packages')) { const d = 'packages/' + pkg + '/dist'; if (!fs.existsSync(d)) continue; for (const f of fs.readdirSync(d, { recursive: true })) { const p = d + '/' + f; if (fs.statSync(p).isFile() && (p.endsWith('.js') || p.endsWith('.d.ts'))) { const c = fs.readFileSync(p, 'utf8'); const n = c.replaceAll('@kloks/', '@ultrst-armada/kloks/').replaceAll('@ultrst/kloks/', '@ultrst-armada/kloks/').replaceAll('\\\"kloks/', '\\\"@ultrst-armada/kloks/').replaceAll('\\'kloks/', '\\'@ultrst-armada/kloks/'); if (c !== n) fs.writeFileSync(p, n); } } } })\"",
-    "test": "vitest run",
-    "typecheck": "pnpm -r run typecheck",
-    "clean": "pnpm -r run clean"
-  },
   "dependencies": {
     "bullmq": "^6.3.8",
     "zod": "^3.24.1",
@@ -119,5 +122,11 @@
     "typescript": "^5.7.3",
     "vitest": "^3.1.0"
   },
-  "packageManager": "pnpm@9.15.0"
-}
+  "scripts": {
+    "build": "pnpm -r run build",
+    "postbuild": "node -e \"import('fs').then(fs => { for (const pkg of fs.readdirSync('packages')) { const d = 'packages/' + pkg + '/dist'; if (!fs.existsSync(d)) continue; for (const f of fs.readdirSync(d, { recursive: true })) { const p = d + '/' + f; if (fs.statSync(p).isFile() && (p.endsWith('.js') || p.endsWith('.d.ts'))) { const c = fs.readFileSync(p, 'utf8'); const n = c.replaceAll('@kloks/', '@ultrst-armada/kloks/').replaceAll('@ultrst/kloks/', '@ultrst-armada/kloks/').replaceAll('\\\"kloks/', '\\\"@ultrst-armada/kloks/').replaceAll('\\'kloks/', '\\'@ultrst-armada/kloks/'); if (c !== n) fs.writeFileSync(p, n); } } } })\"",
+    "test": "vitest run",
+    "typecheck": "pnpm -r run typecheck",
+    "clean": "pnpm -r run clean"
+  }
+}

package/packages/backend/dist/index.js

@@ -1,3 +1,11 @@
+import {
+  CompositeBackend,
+  EndpointGenerator,
+  createBackend,
+  createCompositeService,
+  createLocalService,
+  createRemoteService
+} from "./chunk-P4HL4C6V.js";
 import {
   CANONICAL_SRKL_URL,
   SrklClient,
@@ -7,14 +15,6 @@ import {
   srklListBackblazeBuckets,
   useSrklServices
 } from "./chunk-MN54ZIKZ.js";
-import {
-  CompositeBackend,
-  EndpointGenerator,
-  createBackend,
-  createCompositeService,
-  createLocalService,
-  createRemoteService
-} from "./chunk-P4HL4C6V.js";
 import "./chunk-LS3HWJBX.js";
 import {
   authorizeB2,

package/packages/contracts/dist/index.d.ts

@@ -0,0 +1,552 @@
+import { z } from 'zod';
+
+/**
+ * @file surface.ts
+ * @description Canonical export surface definitions and consumer compatibility validator.
+ * Enforces: QwnsrRequiredSurface ⊆ KloksPublicContract
+ */
+interface ExportSymbolEntry {
+    name: string;
+    subpath: string;
+    category: 'state-graph' | 'audio-midi' | 'orchestrations' | 'backend' | 'services' | 'functions' | 'contracts';
+    hasZodSchema: boolean;
+}
+/**
+ * Authoritative Canonical Public Contract Surface for Kloks.
+ */
+declare const KLOKS_PUBLIC_SURFACE: ExportSymbolEntry[];
+/**
+ * Surface required by Qwnsr consumer according to docs/01_CONTRACT_FOUNDATION.md & docs/03_LIBRARY_CONTRACT_MIGRATION.md.
+ */
+declare const QWNSR_REQUIRED_SURFACE: string[];
+interface CompatibilityCheckResult {
+    compatible: boolean;
+    missingSymbols: string[];
+    totalRequired: number;
+    totalPresent: number;
+}
+/**
+ * Verifies that all symbols in requiredSurface are exported by Kloks.
+ * Enforces Invariant: QwnsrRequiredSurface ⊆ KloksPublicContract
+ */
+declare function validateConsumerSurfaceCompatibility(requiredSymbols?: string[], publicSurface?: ExportSymbolEntry[]): CompatibilityCheckResult;
+
+/**
+ * @file schemas.ts
+ * @description Runtime Zod Schemas for Kloks Public Contracts and Canonical Models.
+ * Enforces: ∀ public runtime boundary: TypeScriptContract ∧ ZodRuntimeContract
+ */
+
+declare const GraphEntityMetadataSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    type: z.ZodString;
+    archetype: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    description: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodOptional<z.ZodNumber>;
+    updatedAt: z.ZodOptional<z.ZodNumber>;
+    customAttributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    type?: string;
+    id?: string;
+    name?: string;
+    archetype?: string;
+    tags?: string[];
+    description?: string;
+    createdAt?: number;
+    updatedAt?: number;
+    customAttributes?: Record<string, unknown>;
+}, {
+    type?: string;
+    id?: string;
+    name?: string;
+    archetype?: string;
+    tags?: string[];
+    description?: string;
+    createdAt?: number;
+    updatedAt?: number;
+    customAttributes?: Record<string, unknown>;
+}>;
+type GraphEntityMetadata = z.infer<typeof GraphEntityMetadataSchema>;
+declare const SocketPosition2DSchema: z.ZodObject<{
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    x?: number;
+    y?: number;
+}, {
+    x?: number;
+    y?: number;
+}>;
+type SocketPosition2D = z.infer<typeof SocketPosition2DSchema>;
+declare const SocketDirectionSchema: z.ZodEnum<["input", "output", "bidirectional"]>;
+type SocketDirection = z.infer<typeof SocketDirectionSchema>;
+declare const SocketGeometryConfigSchema: z.ZodObject<{
+    radius: z.ZodDefault<z.ZodNumber>;
+    hitRadius: z.ZodDefault<z.ZodNumber>;
+    snapDistance: z.ZodDefault<z.ZodNumber>;
+    direction: z.ZodDefault<z.ZodEnum<["input", "output", "bidirectional"]>>;
+    relativeOffset: z.ZodDefault<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        x?: number;
+        y?: number;
+    }, {
+        x?: number;
+        y?: number;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    radius?: number;
+    hitRadius?: number;
+    snapDistance?: number;
+    direction?: "input" | "output" | "bidirectional";
+    relativeOffset?: {
+        x?: number;
+        y?: number;
+    };
+}, {
+    radius?: number;
+    hitRadius?: number;
+    snapDistance?: number;
+    direction?: "input" | "output" | "bidirectional";
+    relativeOffset?: {
+        x?: number;
+        y?: number;
+    };
+}>;
+type SocketGeometryConfig = z.infer<typeof SocketGeometryConfigSchema>;
+declare const SocketStyleConfigSchema: z.ZodObject<{
+    color: z.ZodString;
+    hoverColor: z.ZodOptional<z.ZodString>;
+    activeColor: z.ZodOptional<z.ZodString>;
+    borderColor: z.ZodOptional<z.ZodString>;
+    borderWidth: z.ZodOptional<z.ZodNumber>;
+    fillOpacity: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    color?: string;
+    hoverColor?: string;
+    activeColor?: string;
+    borderColor?: string;
+    borderWidth?: number;
+    fillOpacity?: number;
+}, {
+    color?: string;
+    hoverColor?: string;
+    activeColor?: string;
+    borderColor?: string;
+    borderWidth?: number;
+    fillOpacity?: number;
+}>;
+type SocketStyleConfig = z.infer<typeof SocketStyleConfigSchema>;
+declare const WireEndpoint2DSchema: z.ZodObject<{
+    nodeId: z.ZodString;
+    socketId: z.ZodString;
+    position: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        x?: number;
+        y?: number;
+    }, {
+        x?: number;
+        y?: number;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    nodeId?: string;
+    socketId?: string;
+    position?: {
+        x?: number;
+        y?: number;
+    };
+}, {
+    nodeId?: string;
+    socketId?: string;
+    position?: {
+        x?: number;
+        y?: number;
+    };
+}>;
+type WireEndpoint2D = z.infer<typeof WireEndpoint2DSchema>;
+declare const WireCurveStyleSchema: z.ZodEnum<["bezier", "linear", "orthogonal", "stepped"]>;
+type WireCurveStyle = z.infer<typeof WireCurveStyleSchema>;
+declare const WireAnimationConfigSchema: z.ZodObject<{
+    animated: z.ZodDefault<z.ZodBoolean>;
+    speed: z.ZodDefault<z.ZodNumber>;
+    direction: z.ZodDefault<z.ZodEnum<["forward", "reverse"]>>;
+    pulseFrequency: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    direction?: "reverse" | "forward";
+    animated?: boolean;
+    speed?: number;
+    pulseFrequency?: number;
+}, {
+    direction?: "reverse" | "forward";
+    animated?: boolean;
+    speed?: number;
+    pulseFrequency?: number;
+}>;
+type WireAnimationConfig = z.infer<typeof WireAnimationConfigSchema>;
+declare const WireVisualConfigSchema: z.ZodObject<{
+    strokeColor: z.ZodString;
+    strokeWidth: z.ZodDefault<z.ZodNumber>;
+    strokeDashArray: z.ZodOptional<z.ZodString>;
+    curveStyle: z.ZodDefault<z.ZodEnum<["bezier", "linear", "orthogonal", "stepped"]>>;
+    curvature: z.ZodDefault<z.ZodNumber>;
+    opacity: z.ZodDefault<z.ZodNumber>;
+    glow: z.ZodDefault<z.ZodBoolean>;
+    glowColor: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    strokeColor?: string;
+    strokeWidth?: number;
+    strokeDashArray?: string;
+    curveStyle?: "bezier" | "linear" | "orthogonal" | "stepped";
+    curvature?: number;
+    opacity?: number;
+    glow?: boolean;
+    glowColor?: string;
+}, {
+    strokeColor?: string;
+    strokeWidth?: number;
+    strokeDashArray?: string;
+    curveStyle?: "bezier" | "linear" | "orthogonal" | "stepped";
+    curvature?: number;
+    opacity?: number;
+    glow?: boolean;
+    glowColor?: string;
+}>;
+type WireVisualConfig = z.infer<typeof WireVisualConfigSchema>;
+declare const NodeDimensions2DSchema: z.ZodObject<{
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    minWidth: z.ZodOptional<z.ZodNumber>;
+    minHeight: z.ZodOptional<z.ZodNumber>;
+    maxWidth: z.ZodOptional<z.ZodNumber>;
+    maxHeight: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    width?: number;
+    height?: number;
+    minWidth?: number;
+    minHeight?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+}, {
+    width?: number;
+    height?: number;
+    minWidth?: number;
+    minHeight?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+}>;
+type NodeDimensions2D = z.infer<typeof NodeDimensions2DSchema>;
+declare const NodeScreenRect2DSchema: z.ZodObject<{
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+}, {
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+}>;
+type NodeScreenRect2D = z.infer<typeof NodeScreenRect2DSchema>;
+declare const NodeHeaderStyleSchema: z.ZodObject<{
+    backgroundColor: z.ZodOptional<z.ZodString>;
+    titleColor: z.ZodOptional<z.ZodString>;
+    iconColor: z.ZodOptional<z.ZodString>;
+    badgeColor: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    backgroundColor?: string;
+    titleColor?: string;
+    iconColor?: string;
+    badgeColor?: string;
+}, {
+    backgroundColor?: string;
+    titleColor?: string;
+    iconColor?: string;
+    badgeColor?: string;
+}>;
+type NodeHeaderStyle = z.infer<typeof NodeHeaderStyleSchema>;
+declare const AudioBusConfigSchema: z.ZodObject<{
+    channelCount: z.ZodDefault<z.ZodNumber>;
+    sampleRate: z.ZodDefault<z.ZodNumber>;
+    bufferSize: z.ZodDefault<z.ZodNumber>;
+    latencyHint: z.ZodDefault<z.ZodEnum<["interactive", "balanced", "playback"]>>;
+}, "strip", z.ZodTypeAny, {
+    channelCount?: number;
+    sampleRate?: number;
+    bufferSize?: number;
+    latencyHint?: "interactive" | "balanced" | "playback";
+}, {
+    channelCount?: number;
+    sampleRate?: number;
+    bufferSize?: number;
+    latencyHint?: "interactive" | "balanced" | "playback";
+}>;
+type AudioBusConfig = z.infer<typeof AudioBusConfigSchema>;
+declare const AudioHardwareStateSchema: z.ZodObject<{
+    contextState: z.ZodEnum<["suspended", "running", "closed", "uninitialized"]>;
+    sampleRate: z.ZodNumber;
+    inputChannels: z.ZodNumber;
+    outputChannels: z.ZodNumber;
+    activeInputDeviceId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    activeOutputDeviceId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    sampleRate?: number;
+    contextState?: "suspended" | "running" | "closed" | "uninitialized";
+    inputChannels?: number;
+    outputChannels?: number;
+    activeInputDeviceId?: string;
+    activeOutputDeviceId?: string;
+}, {
+    sampleRate?: number;
+    contextState?: "suspended" | "running" | "closed" | "uninitialized";
+    inputChannels?: number;
+    outputChannels?: number;
+    activeInputDeviceId?: string;
+    activeOutputDeviceId?: string;
+}>;
+type AudioHardwareState = z.infer<typeof AudioHardwareStateSchema>;
+declare const MidiCommandTypeSchema: z.ZodEnum<["NOTE_ON", "NOTE_OFF", "CONTROL_CHANGE", "PITCH_BEND", "PROGRAM_CHANGE", "AFTERTOUCH", "POLY_PRESSURE", "CLOCK", "START", "CONTINUE", "STOP", "ACTIVE_SENSING", "SYSTEM_RESET"]>;
+type MidiCommandType = z.infer<typeof MidiCommandTypeSchema>;
+declare const MidiEventPayloadSchema: z.ZodObject<{
+    command: z.ZodEnum<["NOTE_ON", "NOTE_OFF", "CONTROL_CHANGE", "PITCH_BEND", "PROGRAM_CHANGE", "AFTERTOUCH", "POLY_PRESSURE", "CLOCK", "START", "CONTINUE", "STOP", "ACTIVE_SENSING", "SYSTEM_RESET"]>;
+    channel: z.ZodDefault<z.ZodNumber>;
+    note: z.ZodOptional<z.ZodNumber>;
+    velocity: z.ZodOptional<z.ZodNumber>;
+    controller: z.ZodOptional<z.ZodNumber>;
+    value: z.ZodOptional<z.ZodNumber>;
+    timestamp: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    timestamp?: number;
+    value?: number;
+    command?: "NOTE_ON" | "NOTE_OFF" | "CONTROL_CHANGE" | "PITCH_BEND" | "PROGRAM_CHANGE" | "AFTERTOUCH" | "POLY_PRESSURE" | "CLOCK" | "START" | "CONTINUE" | "STOP" | "ACTIVE_SENSING" | "SYSTEM_RESET";
+    channel?: number;
+    note?: number;
+    velocity?: number;
+    controller?: number;
+}, {
+    timestamp?: number;
+    value?: number;
+    command?: "NOTE_ON" | "NOTE_OFF" | "CONTROL_CHANGE" | "PITCH_BEND" | "PROGRAM_CHANGE" | "AFTERTOUCH" | "POLY_PRESSURE" | "CLOCK" | "START" | "CONTINUE" | "STOP" | "ACTIVE_SENSING" | "SYSTEM_RESET";
+    channel?: number;
+    note?: number;
+    velocity?: number;
+    controller?: number;
+}>;
+type MidiEventPayload = z.infer<typeof MidiEventPayloadSchema>;
+declare const BackendOperationSchema: z.ZodObject<{
+    name: z.ZodString;
+    service: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    inputSchemaName: z.ZodOptional<z.ZodString>;
+    outputSchemaName: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name?: string;
+    description?: string;
+    service?: string;
+    inputSchemaName?: string;
+    outputSchemaName?: string;
+}, {
+    name?: string;
+    description?: string;
+    service?: string;
+    inputSchemaName?: string;
+    outputSchemaName?: string;
+}>;
+type BackendOperation = z.infer<typeof BackendOperationSchema>;
+declare const PublicContractDefinitionSchema: z.ZodObject<{
+    package: z.ZodString;
+    version: z.ZodString;
+    description: z.ZodString;
+    exports: z.ZodRecord<z.ZodString, z.ZodObject<{
+        types: z.ZodString;
+        import: z.ZodString;
+        default: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        types?: string;
+        import?: string;
+        default?: string;
+    }, {
+        types?: string;
+        import?: string;
+        default?: string;
+    }>>;
+    symbols: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        subpath: z.ZodString;
+        kind: z.ZodEnum<["class", "type", "interface", "function", "const", "object"]>;
+        hasZodSchema: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        name?: string;
+        subpath?: string;
+        kind?: "object" | "function" | "type" | "class" | "interface" | "const";
+        hasZodSchema?: boolean;
+    }, {
+        name?: string;
+        subpath?: string;
+        kind?: "object" | "function" | "type" | "class" | "interface" | "const";
+        hasZodSchema?: boolean;
+    }>, "many">;
+    facades: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        subpath: z.ZodString;
+        runtime: z.ZodEnum<["client", "server"]>;
+        deployment: z.ZodEnum<["local", "remote"]>;
+    }, "strip", z.ZodTypeAny, {
+        id?: string;
+        name?: string;
+        subpath?: string;
+        runtime?: "client" | "server";
+        deployment?: "local" | "remote";
+    }, {
+        id?: string;
+        name?: string;
+        subpath?: string;
+        runtime?: "client" | "server";
+        deployment?: "local" | "remote";
+    }>, "many">;
+    invariants: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    package?: string;
+    version?: string;
+    facades?: {
+        id?: string;
+        name?: string;
+        subpath?: string;
+        runtime?: "client" | "server";
+        deployment?: "local" | "remote";
+    }[];
+    description?: string;
+    exports?: Record<string, {
+        types?: string;
+        import?: string;
+        default?: string;
+    }>;
+    symbols?: {
+        name?: string;
+        subpath?: string;
+        kind?: "object" | "function" | "type" | "class" | "interface" | "const";
+        hasZodSchema?: boolean;
+    }[];
+    invariants?: string[];
+}, {
+    package?: string;
+    version?: string;
+    facades?: {
+        id?: string;
+        name?: string;
+        subpath?: string;
+        runtime?: "client" | "server";
+        deployment?: "local" | "remote";
+    }[];
+    description?: string;
+    exports?: Record<string, {
+        types?: string;
+        import?: string;
+        default?: string;
+    }>;
+    symbols?: {
+        name?: string;
+        subpath?: string;
+        kind?: "object" | "function" | "type" | "class" | "interface" | "const";
+        hasZodSchema?: boolean;
+    }[];
+    invariants?: string[];
+}>;
+type PublicContractDefinition = z.infer<typeof PublicContractDefinitionSchema>;
+declare const ContractSnapshotSchema: z.ZodObject<{
+    package: z.ZodString;
+    version: z.ZodString;
+    timestamp: z.ZodNumber;
+    checksum: z.ZodString;
+    publicSymbols: z.ZodArray<z.ZodString, "many">;
+    normalizedSignatures: z.ZodRecord<z.ZodString, z.ZodString>;
+    zodFingerprints: z.ZodRecord<z.ZodString, z.ZodString>;
+    facades: z.ZodArray<z.ZodString, "many">;
+    events: z.ZodArray<z.ZodString, "many">;
+    commands: z.ZodArray<z.ZodString, "many">;
+    errorCodes: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    package?: string;
+    version?: string;
+    timestamp?: number;
+    checksum?: string;
+    publicSymbols?: string[];
+    normalizedSignatures?: Record<string, string>;
+    zodFingerprints?: Record<string, string>;
+    facades?: string[];
+    events?: string[];
+    commands?: string[];
+    errorCodes?: string[];
+}, {
+    package?: string;
+    version?: string;
+    timestamp?: number;
+    checksum?: string;
+    publicSymbols?: string[];
+    normalizedSignatures?: Record<string, string>;
+    zodFingerprints?: Record<string, string>;
+    facades?: string[];
+    events?: string[];
+    commands?: string[];
+    errorCodes?: string[];
+}>;
+type ContractSnapshot = z.infer<typeof ContractSnapshotSchema>;
+
+/**
+ * @file snapshot.ts
+ * @description Contract snapshot generator, diff engine, and semantic versioning rules.
+ * Enforces:
+ *   implementation_only      => PATCH
+ *   additive_compatible       => MINOR
+ *   breaking_contract_change => MAJOR
+ */
+
+interface ContractDiffResult {
+    versionRecommendation: 'PATCH' | 'MINOR' | 'MAJOR';
+    hasBreakingChanges: boolean;
+    hasAdditiveChanges: boolean;
+    isIdentical: boolean;
+    removedSymbols: string[];
+    addedSymbols: string[];
+    changedSignatures: string[];
+    summary: string;
+}
+/**
+ * Generate canonical contract snapshot for Kloks.
+ */
+declare function createKloksSnapshot(version?: string, surface?: ExportSymbolEntry[]): ContractSnapshot;
+/**
+ * Computes semantic diff between previous and current contract snapshots.
+ */
+declare function diffContractSnapshots(previous: ContractSnapshot, current: ContractSnapshot): ContractDiffResult;
+
+declare const KLOKS_CANONICAL_CONTRACT: {
+    package: string;
+    version: string;
+    getSnapshot: () => {
+        package?: string;
+        version?: string;
+        timestamp?: number;
+        checksum?: string;
+        publicSymbols?: string[];
+        normalizedSignatures?: Record<string, string>;
+        zodFingerprints?: Record<string, string>;
+        facades?: string[];
+        events?: string[];
+        commands?: string[];
+        errorCodes?: string[];
+    };
+    validateCompatibility: (consumerSymbols?: string[]) => CompatibilityCheckResult;
+};
+
+export { type AudioBusConfig, AudioBusConfigSchema, type AudioHardwareState, AudioHardwareStateSchema, type BackendOperation, BackendOperationSchema, type CompatibilityCheckResult, type ContractDiffResult, type ContractSnapshot, ContractSnapshotSchema, type ExportSymbolEntry, type GraphEntityMetadata, GraphEntityMetadataSchema, KLOKS_CANONICAL_CONTRACT, KLOKS_PUBLIC_SURFACE, type MidiCommandType, MidiCommandTypeSchema, type MidiEventPayload, MidiEventPayloadSchema, type NodeDimensions2D, NodeDimensions2DSchema, type NodeHeaderStyle, NodeHeaderStyleSchema, type NodeScreenRect2D, NodeScreenRect2DSchema, type PublicContractDefinition, PublicContractDefinitionSchema, QWNSR_REQUIRED_SURFACE, type SocketDirection, SocketDirectionSchema, type SocketGeometryConfig, SocketGeometryConfigSchema, type SocketPosition2D, SocketPosition2DSchema, type SocketStyleConfig, SocketStyleConfigSchema, type WireAnimationConfig, WireAnimationConfigSchema, type WireCurveStyle, WireCurveStyleSchema, type WireEndpoint2D, WireEndpoint2DSchema, type WireVisualConfig, WireVisualConfigSchema, createKloksSnapshot, diffContractSnapshots, validateConsumerSurfaceCompatibility };