@terminals-tech/sdk 1.0.0 → 2.0.0-rc.1

package/dist/index.d.ts

@@ -620,7 +620,11 @@ declare function calculateCoherenceWithExplanations(input: CoherenceInput, confi
 /**
  * Validation Primitives (IO Boundary Security)
  *
- * Uses Ajv for JSON Schema validation.
+ * JSON Schema validation engine using Ajv. This is one of several validation
+ * engines behind the stable proof contract ({@link Validated}, {@link Untrusted},
+ * {@link unbrand}). The proof contract is engine-agnostic — TS-first boundaries
+ * may use Zod; data-first boundaries use this Ajv path; native boundaries use
+ * Rust serde. The branded types are the stable public API, not the engine.
  *
  * IMPORTANT: This module is NOT compatible with Vercel Edge Runtime (Middleware)
  * because Ajv uses `new Function()` for schema compilation. For Edge-compatible
@@ -1029,7 +1033,7 @@ declare function kuramotoStep(phases: ArrayLike<number>, omega: ArrayLike<number
 /**
  * Signal types for cross-layer communication
  */
-type SignalType = "health_update" | "circuit_change" | "convergence_update" | "coherence_update" | "resonance_update" | "tensor_state_update" | "task_complete" | "task_failed" | "adaptation_required" | "backpressure_warning" | "audio_metrics_update" | "mesh_update" | "mesh_query" | "session_state_change" | "skill_capture_started" | "skill_action_recorded" | "skill_capture_completed" | "skill_crystallized" | "skill_training_started" | "skill_training_completed" | "skill_artifact_activated" | "skill_suggested" | "skill_executed" | "skill_peer_review" | "skill_delegation" | "skill_agent_refine" | "skill_selection" | "skill_backpressure" | "skill_budget_exceeded" | "skill_error" | "interaction_created" | "interaction_status_changed" | "deploy_scaffold" | "deploy_push" | "deploy_build" | "deploy_status" | "deploy_preview" | "deploy_live" | "deploy_error" | "potentiation_rising" | "potentiation_peak" | "potentiation_discharge" | "potentiation_reset" | "action_dispatched" | "action_executed" | "action_failed" | "combo_completed" | "input_surface_changed" | "forge_scene_saved" | "forge_iteration_recorded" | "forge_profile_crystallized" | "forge_profile_requested" | "integration_connected" | "integration_disconnected" | "integration_heartbeat" | "integration_error" | "ui_navigation" | "ui_surface_opened" | "ui_surface_closed" | "ui_interaction" | "ui_error_shown" | "ui_search" | "artifact_preview" | "manifold_node_added" | "manifold_edge_added" | "manifold_query" | "manifold_snapshot" | "connector_status_changed" | "connector_sync_started" | "connector_sync_complete" | "connector_sync_error" | "connector_document_indexed" | "graph_entity_upserted" | "graph_relationship_added" | "graph_traversal_complete" | "intent_signal_emitted" | "oscillator_phase_updated" | "oscillator_suggestion_generated" | "journey_note_created" | "journey_note_deleted" | "journey_edge_created" | "journey_cluster_created" | "journey_replay_entered" | "journey_replay_exited" | "journey_spatial_navigate" | "journey_completed" | "boundary_crossed" | "boundary_sealed" | "convergence_declared" | "convergence_lost" | "crystallization_declared" | "crystallization_melted" | "chat_message_sent" | "chat_message_received" | "chat_error" | "coherence_gate_accepted" | "coherence_gate_rejected" | "manifold_geodesic_computed" | "manifold_distance_measured" | "sematon_created" | "sematon_witnessed" | "sematon_folded" | "sematon_realized" | "sematon_expired" | "voice_identity_encoded" | "voice_speaking_started" | "voice_speaking_completed" | "voice_chunk_scheduled" | "voice_coherence_mapped";
+type SignalType = "health_update" | "circuit_change" | "convergence_update" | "coherence_update" | "resonance_update" | "tensor_state_update" | "task_complete" | "task_failed" | "adaptation_required" | "backpressure_warning" | "audio_metrics_update" | "mesh_update" | "mesh_metrics_update" | "mesh_query" | "session_state_change" | "skill_capture_started" | "skill_action_recorded" | "skill_capture_completed" | "skill_crystallized" | "skill_training_started" | "skill_training_completed" | "skill_artifact_activated" | "skill_suggested" | "skill_executed" | "skill_peer_review" | "skill_delegation" | "skill_agent_refine" | "skill_selection" | "skill_backpressure" | "skill_budget_exceeded" | "skill_error" | "interaction_created" | "interaction_status_changed" | "deploy_scaffold" | "deploy_push" | "deploy_build" | "deploy_status" | "deploy_preview" | "deploy_live" | "deploy_error" | "potentiation_rising" | "potentiation_peak" | "potentiation_discharge" | "potentiation_reset" | "action_dispatched" | "action_executed" | "action_failed" | "combo_completed" | "input_surface_changed" | "forge_scene_saved" | "forge_iteration_recorded" | "forge_profile_crystallized" | "forge_profile_requested" | "integration_connected" | "integration_disconnected" | "integration_heartbeat" | "integration_error" | "ui_navigation" | "ui_surface_opened" | "ui_surface_closed" | "ui_interaction" | "ui_error_shown" | "ui_search" | "artifact_preview" | "manifold_node_added" | "manifold_edge_added" | "manifold_query" | "manifold_snapshot" | "connector_status_changed" | "connector_sync_started" | "connector_sync_complete" | "connector_sync_error" | "connector_document_indexed" | "graph_entity_upserted" | "graph_relationship_added" | "graph_traversal_complete" | "intent_signal_emitted" | "oscillator_phase_updated" | "oscillator_suggestion_generated" | "journey_note_created" | "journey_note_deleted" | "journey_edge_created" | "journey_cluster_created" | "journey_replay_entered" | "journey_replay_exited" | "journey_spatial_navigate" | "journey_completed" | "boundary_crossed" | "boundary_sealed" | "convergence_declared" | "convergence_lost" | "crystallization_declared" | "crystallization_melted" | "chat_message_sent" | "chat_message_received" | "chat_error" | "coherence_gate_accepted" | "coherence_gate_rejected" | "manifold_geodesic_computed" | "manifold_distance_measured" | "sematon_created" | "sematon_witnessed" | "sematon_folded" | "sematon_realized" | "sematon_expired" | "voice_identity_encoded" | "voice_speaking_started" | "voice_speaking_completed" | "voice_chunk_scheduled" | "voice_coherence_mapped";
 /**
  * Layer-aware signal for AXON cross-layer communication
  */
@@ -1344,6 +1348,326 @@ interface PlatformConfig {
     audio?: AudioSourceConfig;
 }
 
+/**
+ * L0 Sematon — The Smallest Meaning-Bearing Unit
+ *
+ * The sematon is the atomic unit of operational meaning in Terminals OS.
+ * It carries a typed payload, convergence witness, p-adic address,
+ * information-theoretic metrics, and a constructor flag that guarantees
+ * the Deutsch-Marletto invariant: after transforming an input, the
+ * sematon retains the ability to transform again.
+ *
+ * The sematon unifies Signal<T>, ContextNode, FractalSnapshot,
+ * ConvergenceWitness, and CombinatorEvent into a single formal type
+ * at the L0 foundation layer.
+ *
+ * Core Engine Primitive.
+ *
+ * @license BUSL-1.1
+ * @copyright © 2026 Intuition Labs LLC. All rights reserved. Patent Pending.
+ * @module core/L0/sematon
+ */
+/**
+ * Payload kind classification for sematons.
+ * Determines how the payload is interpreted across layers.
+ */
+type SematonKind = "signal" | "context" | "fractal" | "witness" | "combinator" | "interaction" | "custom";
+/**
+ * Convergence witness snapshot embedded in a sematon.
+ * Minimal subset of ConvergenceWitness for portability.
+ */
+interface SematonWitness {
+    /** Kuramoto order parameter R in [0, 1] */
+    R: number;
+    /** Shannon entropy of activation distribution */
+    activationEntropy: number;
+    /** Whether convergence criteria are met */
+    converged: boolean;
+    /** Step at which this witness was taken */
+    step: number;
+}
+/**
+ * The Sematon — smallest meaning-bearing unit with operational consequence.
+ *
+ * Generic over T (the payload type):
+ *   T = Signal payload at signal kind
+ *   T = ContextNode metadata at context kind
+ *   T = FractalSnapshot at fractal kind
+ *   T = arbitrary at custom kind
+ */
+interface Sematon<T = unknown> {
+    /** Unique identifier */
+    readonly id: string;
+    /** Payload kind classification */
+    readonly kind: SematonKind;
+    /** The meaning-bearing payload */
+    readonly payload: T;
+    /** Convergence witness at creation time */
+    readonly witness: SematonWitness;
+    /** p-adic address for hierarchical locality */
+    readonly padicAddress: string;
+    /** Shannon entropy of payload (bits) */
+    readonly entropy: number;
+    /** Semantic density (bits per token) */
+    readonly density: number;
+    /** The resistance to constructive transformation: H / (ρ * R) */
+    readonly impedance: number;
+    /** Deterministic content hash (FNV-1a) */
+    readonly shapeHash: string;
+    /**
+     * Constructor flag: can this sematon participate in further transformations?
+     * True iff: witness has converged AND entropy is finite AND payload is non-empty.
+     * This is the Deutsch-Marletto invariant.
+     */
+    readonly constructive: boolean;
+    /** Creation timestamp */
+    readonly createdAt: number;
+    /** Source layer or surface that produced this sematon */
+    readonly source: string;
+}
+/**
+ * Folded (serializable) representation of a Sematon.
+ * Suitable for JSON serialization, mesh relay, or persistence.
+ */
+interface FoldedSematon {
+    id: string;
+    kind: SematonKind;
+    payload: string;
+    witness: SematonWitness;
+    padicAddress: string;
+    entropy: number;
+    density: number;
+    impedance: number;
+    shapeHash: string;
+    constructive: boolean;
+    createdAt: number;
+    source: string;
+}
+interface SematonConfig<T> {
+    kind: SematonKind;
+    payload: T;
+    witness: SematonWitness;
+    padicAddress?: string;
+    source?: string;
+}
+/**
+ * Create a new Sematon from configuration.
+ */
+declare function createSematon<T>(config: SematonConfig<T>): Sematon<T>;
+/**
+ * Get the Shannon entropy of a sematon's payload.
+ */
+declare function sematonEntropy<T>(sematon: Sematon<T>): number;
+/**
+ * Get the semantic density of a sematon.
+ */
+declare function sematonDensity<T>(sematon: Sematon<T>): number;
+/**
+ * Check if a sematon can participate in further transformations.
+ * This is the Deutsch-Marletto constructor invariant.
+ */
+declare function isRealizable<T>(sematon: Sematon<T>): boolean;
+/**
+ * Compute distance between two sematons using payload cosine similarity
+ * weighted by witness R proximity.
+ *
+ * Distance in [0, 1] where 0 = identical, 1 = maximally different.
+ */
+declare function sematonDistance<T>(a: Sematon<T>, b: Sematon<T>): number;
+/**
+ * Fold a Sematon into a JSON-serializable representation.
+ * HVM γ (construct) — compress for handoff, persistence, or relay.
+ */
+declare function foldSematon<T>(sematon: Sematon<T>): FoldedSematon;
+/**
+ * Unfold a serialized representation back into a Sematon.
+ * HVM δ (duplicate) — expand from handoff, persistence, or relay.
+ */
+declare function unfoldSematon<T>(folded: FoldedSematon): Sematon<T>;
+
+/**
+ * ELI5 Result Types for @terminals-tech/agent
+ *
+ * Wraps internal Sematon<TerminalRunResult> into developer-friendly types.
+ * Theory stays in the engine; developers get plain objects.
+ *
+ * @license MIT
+ * @module agent/result
+ */
+
+/**
+ * Execution receipt — cryptographic proof that the workflow executed.
+ * This is a Sematon under the hood, but developers see "receipt".
+ */
+type ExecutionReceipt = Sematon<TerminalRunResult>;
+/**
+ * A single execution step in the workflow trace.
+ */
+interface Step {
+    /** Which agent ran this step */
+    agent: string;
+    /** Step output data */
+    output: unknown;
+    /** Step index in the execution sequence */
+    index: number;
+}
+/**
+ * Per-agent performance report.
+ */
+interface AgentReport {
+    /** Agent node ID */
+    id: string;
+    /** Agent output data */
+    output: unknown;
+}
+/**
+ * The developer-facing result from Terminal.run().
+ *
+ * Provides direct access to outputs, coherence score, and execution proof
+ * without requiring knowledge of Sematons or Kuramoto dynamics.
+ */
+interface TerminalResult {
+    /** The text output from the final agent in the workflow */
+    text: string;
+    /** Coherence score: 0-1 measure of agent alignment quality */
+    coherence: number;
+    /** Execution receipt — proof the workflow ran correctly */
+    receipt: ExecutionReceipt;
+    /** Ordered execution steps */
+    steps: Step[];
+    /** Per-agent performance reports */
+    agents: AgentReport[];
+    /** Total execution time in milliseconds */
+    duration: number;
+}
+
+/**
+ * Terminal.create() Developer API
+ *
+ * The developer-facing entry point for creating and running multi-agent
+ * terminal workflows. Translates semantic configuration into the internal
+ * StackManifestV0 / OrchestratorV0 infrastructure and wraps results as
+ * Sematon<TerminalRunResult>.
+ *
+ * This is a headless API -- no React, no "use client".
+ *
+ * @license BUSL-1.1
+ * @copyright 2026 Intuition Labs LLC. All rights reserved. Patent Pending.
+ * @module agent-sdk/terminal
+ */
+
+/**
+ * Agent definition within a terminal workflow.
+ */
+interface TerminalAgent {
+    /** Role name for the agent (e.g. "researcher", "writer", "reviewer") */
+    role: string;
+    /** Optional capability declarations for this agent */
+    capabilities?: string[];
+}
+/**
+ * Coherence configuration for convergence-aware execution.
+ */
+interface TerminalCoherenceConfig {
+    /** Kuramoto R threshold for constructive sematon flag (default: 0.6) */
+    threshold?: number;
+    /** Ground truth strings for coherence grounding */
+    groundTruth?: string[];
+}
+/**
+ * Developer-facing configuration for Terminal.create().
+ *
+ * Named TerminalCreateConfig to avoid collision with the internal
+ * TerminalConfig from core/terminal.ts.
+ */
+interface TerminalCreateConfig {
+    /** Agent definitions -- each becomes a provider.chat.v1 node */
+    agents: TerminalAgent[];
+    /** The task prompt driving the workflow */
+    task: string;
+    /** Coherence / convergence settings */
+    coherence?: TerminalCoherenceConfig;
+    /** LLM provider identifier (e.g. "openrouter", "anthropic") */
+    provider?: string;
+    /** Model identifier (e.g. "claude-sonnet-4-20250514") */
+    model?: string;
+}
+/**
+ * Developer-facing configuration — the simplified public interface.
+ * Extends TerminalCreateConfig with orchestration and verification options.
+ */
+interface TerminalConfig extends TerminalCreateConfig {
+    /** Orchestration strategy for multi-agent execution */
+    orchestration?: "sequential" | "parallel" | "society" | "consensus";
+    /** Enable DRM execution verification (generates execution receipts) */
+    verify?: boolean;
+    /** Enable streaming mode */
+    stream?: boolean;
+}
+/**
+ * Result payload wrapped inside a Sematon after Terminal.run().
+ */
+interface TerminalRunResult {
+    /** Collected outputs from all agent nodes, keyed by node ID */
+    outputs: Record<string, unknown>;
+    /** Total execution duration in milliseconds */
+    duration: number;
+}
+/**
+ * Terminal -- the developer-facing orchestration API.
+ *
+ * Usage:
+ * ```ts
+ * const t = await Terminal.create({
+ *   agents: [
+ *     { role: "researcher" },
+ *     { role: "writer", capabilities: ["markdown"] },
+ *   ],
+ *   task: "Write a technical summary of quantum error correction",
+ *   coherence: { threshold: 0.7 },
+ *   provider: "openrouter",
+ *   model: "anthropic/claude-sonnet-4-20250514",
+ * });
+ *
+ * const result = await t.run();
+ * console.log(result.payload.outputs);
+ * ```
+ */
+declare class Terminal {
+    /** Unique terminal identifier */
+    readonly id: string;
+    private readonly config;
+    private readonly manifest;
+    private constructor();
+    /**
+     * Create a new Terminal from semantic configuration.
+     *
+     * Translates the developer-friendly config into internal stack manifests,
+     * registers required nodes, and returns a ready-to-run Terminal.
+     */
+    static create(config: TerminalCreateConfig): Promise<Terminal>;
+    /**
+     * Execute the terminal workflow and return a Sematon-wrapped result.
+     *
+     * Uses OrchestratorV0 to run the DAG, then wraps the output
+     * in a Sematon<TerminalRunResult> with convergence witness.
+     */
+    run(): Promise<Sematon<TerminalRunResult>>;
+    /**
+     * Static convenience: create and run a terminal in one call.
+     * Returns a developer-friendly TerminalResult instead of a raw Sematon.
+     */
+    static run(config: TerminalConfig): Promise<TerminalResult>;
+    /**
+     * Chain a new terminal execution from a previous Sematon result.
+     *
+     * Extracts `prev.payload.outputs` and injects them as `previousOutputs`
+     * in the config overrides, then creates a new Terminal, runs it, and
+     * returns the new Sematon.
+     */
+    static chain(prev: Sematon<unknown>, config: Partial<TerminalCreateConfig>): Promise<Sematon<TerminalRunResult>>;
+}
+
 /**
  * Terminal SDK — High-level Terminal management
  *
@@ -1363,9 +1687,13 @@ type terminal_PlatformIdentity = PlatformIdentity;
 type terminal_PlatformTheme = PlatformTheme;
 type terminal_SurfaceId = SurfaceId;
 type terminal_TaskStatus = TaskStatus;
+type terminal_Terminal = Terminal;
+declare const terminal_Terminal: typeof Terminal;
+type terminal_TerminalCreateConfig = TerminalCreateConfig;
+type terminal_TerminalRunResult = TerminalRunResult;
 declare const terminal_createInteractionWithEvents: typeof createInteractionWithEvents;
 declare namespace terminal {
-  export { type terminal_Interaction as Interaction, type terminal_InteractionStatus as InteractionStatus, type terminal_InteractionType as InteractionType, type terminal_LayerLevel as LayerLevel, type terminal_PlatformConfig as PlatformConfig, type terminal_PlatformIdentity as PlatformIdentity, type terminal_PlatformTheme as PlatformTheme, type terminal_SurfaceId as SurfaceId, type terminal_TaskStatus as TaskStatus, createInteractionWithEvents as createInteraction, terminal_createInteractionWithEvents as createInteractionWithEvents };
+  export { type terminal_Interaction as Interaction, type terminal_InteractionStatus as InteractionStatus, type terminal_InteractionType as InteractionType, type terminal_LayerLevel as LayerLevel, type terminal_PlatformConfig as PlatformConfig, type terminal_PlatformIdentity as PlatformIdentity, type terminal_PlatformTheme as PlatformTheme, type terminal_SurfaceId as SurfaceId, type terminal_TaskStatus as TaskStatus, terminal_Terminal as Terminal, type terminal_TerminalCreateConfig as TerminalCreateConfig, type terminal_TerminalRunResult as TerminalRunResult, createInteractionWithEvents as createInteraction, terminal_createInteractionWithEvents as createInteractionWithEvents };
 }
 
 /**
@@ -1962,143 +2290,6 @@ declare function checkCompatibility(shapeA: TypeShape, shapeB: TypeShape): numbe
  */
 declare function canEmbed(source: TypeShape, target: TypeShape): boolean;
 
-/**
- * L0 Sematon — The Smallest Meaning-Bearing Unit
- *
- * The sematon is the atomic unit of operational meaning in Terminals OS.
- * It carries a typed payload, convergence witness, p-adic address,
- * information-theoretic metrics, and a constructor flag that guarantees
- * the Deutsch-Marletto invariant: after transforming an input, the
- * sematon retains the ability to transform again.
- *
- * The sematon unifies Signal<T>, ContextNode, FractalSnapshot,
- * ConvergenceWitness, and CombinatorEvent into a single formal type
- * at the L0 foundation layer.
- *
- * Core Engine Primitive.
- *
- * @license BUSL-1.1
- * @copyright © 2026 Intuition Labs LLC. All rights reserved. Patent Pending.
- * @module core/L0/sematon
- */
-/**
- * Payload kind classification for sematons.
- * Determines how the payload is interpreted across layers.
- */
-type SematonKind = "signal" | "context" | "fractal" | "witness" | "combinator" | "interaction" | "custom";
-/**
- * Convergence witness snapshot embedded in a sematon.
- * Minimal subset of ConvergenceWitness for portability.
- */
-interface SematonWitness {
-    /** Kuramoto order parameter R in [0, 1] */
-    R: number;
-    /** Shannon entropy of activation distribution */
-    activationEntropy: number;
-    /** Whether convergence criteria are met */
-    converged: boolean;
-    /** Step at which this witness was taken */
-    step: number;
-}
-/**
- * The Sematon — smallest meaning-bearing unit with operational consequence.
- *
- * Generic over T (the payload type):
- *   T = Signal payload at signal kind
- *   T = ContextNode metadata at context kind
- *   T = FractalSnapshot at fractal kind
- *   T = arbitrary at custom kind
- */
-interface Sematon<T = unknown> {
-    /** Unique identifier */
-    readonly id: string;
-    /** Payload kind classification */
-    readonly kind: SematonKind;
-    /** The meaning-bearing payload */
-    readonly payload: T;
-    /** Convergence witness at creation time */
-    readonly witness: SematonWitness;
-    /** p-adic address for hierarchical locality */
-    readonly padicAddress: string;
-    /** Shannon entropy of payload (bits) */
-    readonly entropy: number;
-    /** Semantic density (bits per token) */
-    readonly density: number;
-    /** The resistance to constructive transformation: H / (ρ * R) */
-    readonly impedance: number;
-    /** Deterministic content hash (FNV-1a) */
-    readonly shapeHash: string;
-    /**
-     * Constructor flag: can this sematon participate in further transformations?
-     * True iff: witness has converged AND entropy is finite AND payload is non-empty.
-     * This is the Deutsch-Marletto invariant.
-     */
-    readonly constructive: boolean;
-    /** Creation timestamp */
-    readonly createdAt: number;
-    /** Source layer or surface that produced this sematon */
-    readonly source: string;
-}
-/**
- * Folded (serializable) representation of a Sematon.
- * Suitable for JSON serialization, mesh relay, or persistence.
- */
-interface FoldedSematon {
-    id: string;
-    kind: SematonKind;
-    payload: string;
-    witness: SematonWitness;
-    padicAddress: string;
-    entropy: number;
-    density: number;
-    impedance: number;
-    shapeHash: string;
-    constructive: boolean;
-    createdAt: number;
-    source: string;
-}
-interface SematonConfig<T> {
-    kind: SematonKind;
-    payload: T;
-    witness: SematonWitness;
-    padicAddress?: string;
-    source?: string;
-}
-/**
- * Create a new Sematon from configuration.
- */
-declare function createSematon<T>(config: SematonConfig<T>): Sematon<T>;
-/**
- * Get the Shannon entropy of a sematon's payload.
- */
-declare function sematonEntropy<T>(sematon: Sematon<T>): number;
-/**
- * Get the semantic density of a sematon.
- */
-declare function sematonDensity<T>(sematon: Sematon<T>): number;
-/**
- * Check if a sematon can participate in further transformations.
- * This is the Deutsch-Marletto constructor invariant.
- */
-declare function isRealizable<T>(sematon: Sematon<T>): boolean;
-/**
- * Compute distance between two sematons using payload cosine similarity
- * weighted by witness R proximity.
- *
- * Distance in [0, 1] where 0 = identical, 1 = maximally different.
- */
-declare function sematonDistance<T>(a: Sematon<T>, b: Sematon<T>): number;
-/**
- * Fold a Sematon into a JSON-serializable representation.
- * HVM γ (construct) — compress for handoff, persistence, or relay.
- */
-declare function foldSematon<T>(sematon: Sematon<T>): FoldedSematon;
-/**
- * Unfold a serialized representation back into a Sematon.
- * HVM δ (duplicate) — expand from handoff, persistence, or relay.
- */
-declare function unfoldSematon<T>(folded: FoldedSematon): Sematon<T>;
-
 /**
  * L0 Realizability Trace — Constructor Proof Runtime
  *