Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.xandrlabs.ai/llms.txt

Use this file to discover all available pages before exploring further.

A solve call is the primary operation in ALX Protocol. You send a structured intent to the server, which selects or generates the best-matching artifact, executes a plan, and returns a response envelope carrying the result, execution metadata, and session context. All types in this document are exported from @alx/protocol and constitute canonical wire shapes with compatibility guarantees (see WG-01).

​
Wire-level guarantees

The following guarantees apply to every solve request and response:
GuaranteeRule
WG-01All protocol-owned wire shapes MUST live in @alx/protocol
WG-02Every major protocol surface MUST expose ok, correlationId, and protocol in the envelope
WG-08A failed request MUST NOT report ok: true
WG-09If run.failed is emitted, it MUST carry ok: false
WG-10If run.completed is emitted, it MUST carry ok: true

​
Types

​
SolveCallInput

The top-level request shape you send to initiate a solve.
​
intent
SolveIntentShape
required
Describes what the solver should accomplish. Contains three fields:
  • verb — the action to perform (e.g. "deploy", "refactor", "analyze")
  • target — the subject of the action (e.g. "api", "service", "codebase")
  • domain — the knowledge domain scoping the solve (e.g. "engineering", "security")
​
context
object
Arbitrary key-value context passed to the solver. Use this to provide environment details, file paths, or any runtime state relevant to the intent.
​
meta
object
Request metadata such as userId. Not used for artifact selection but preserved in session history.
​
options
SolveCallOptions
Execution control options. See SolveCallOptions below.

​
SolveCallOptions

​
dryRun
boolean
When true, the solver evaluates and plans without executing side effects. Useful for previewing what a solve would do.
​
force
boolean
When true, bypasses confidence thresholds. Use this when you want execution to proceed even if the solver’s confidence score is below the minimum.
​
session
string
Session ID to resume. When provided, the solver loads prior session context before planning.
​
capture
object
Controls whether the run is recorded to session history.
  • enabled (boolean) — set to true to record this run
  • scope (string) — e.g. "personal" or "team"

​
SolveResult

Returned inside SolveResponseEnvelope.result. Carries the quantitative outcome of the solve.
​
improvement
number
Numeric improvement score for this run, typically in the range [0, 1]. Reflects how much better the artifact-guided outcome is relative to baseline.
​
metrics
object
Arbitrary key-value metrics produced during execution. Shape varies by solver implementation.

​
SolveResponseEnvelope

The complete response shape returned by a solve call. All fields listed here are canonical wire fields unless noted as ergonomic aliases.
​
ok
boolean
required
true if the request succeeded; false if it failed. A failed request MUST NOT return ok: true (WG-08).
​
correlationId
string
required
Opaque request identifier for tracing. Treat as a string; do not parse its structure.
​
protocol
object
required
Protocol negotiation envelope. Contains protocol_version (string) and optionally capabilities (array of strings). See Protocol negotiation.
​
success
boolean
Alias for ok at the domain level. Both fields are present in the current protocol version.
​
executionId
string
Opaque identifier for this specific execution run.
​
artifact
object
Reference to the artifact selected or produced by the solver. Contains at minimum { id: string }.
​
result
SolveResult
Quantitative outcome of the solve. See SolveResult above.
​
confidence
object
Solver confidence for the selected artifact. Contains:
  • score (number) — confidence value in [0, 1]
  • reason (string) — human-readable explanation
​
execution
object
Execution metadata including:
  • cached (boolean) — whether a cached result was used
  • fallbackUsed (boolean) — whether a fallback artifact was used
  • durationMs (number) — wall-clock duration in milliseconds
  • session (object) — session context with id and resumed fields
​
steps
array
Ordered list of execution steps. Each step contains label, success, and actionId.
​
learning
object
Post-run learning state. Contains:
  • memoryUpdated (boolean)
  • artifactStatsUpdated (boolean)
​
error
object | null
null on success. On failure, a ProtocolError object with type, code, message, and optionally suggestion and details.

​
Canonical vs ergonomic alias fields

Canonical fields carry compatibility guarantees across minor releases. Ergonomic alias fields are convenience shortcuts that may exist alongside canonical fields but are not the primary compatibility contract.
Canonical fieldErgonomic aliasNotes
result.improvementimprovementAlias may appear at the top level of some responses
confidence.scoreconfidenceScoreAlias for the confidence score
confidence.reasonreasonAlias for the confidence reason string
execution.cachedcachedAlias at top level
execution.fallbackUsedfallbackUsedAlias at top level
correlationIdidempotencyKeyAlias used in some request contexts
artifactselectMetaAlias in some selection-focused responses
Always read canonical fields when writing protocol-compliant code. Ergonomic aliases MAY be removed or renamed in a major release.

​
Protocol negotiation

The protocol field in every envelope supports optional capability negotiation. You include a capabilities array in your request to advertise features you support; the server echoes back which capabilities it accepted. 
// Request envelope fragment
{
  "protocol_version": "1.1",
  "capabilities": ["private-kb-context", "deterministic-query"]
}

// Server response fragment
{
  "client": {
    "protocol_version": "1.1",
    "capabilities": ["private-kb-context", "deterministic-query"]
  },
  "acceptedCapabilities": ["private-kb-context"],
  "unsupportedCapabilities": ["deterministic-query"]
}
Capability advertisement is informational only — it is not proof of authorization. Unknown capabilities MUST be ignored, not rejected (WG-07). Do not require a capability to be advertised before using a stable canonical field.

​
Complete request and response example

// Solve request
{
  "intent": {
    "verb": "deploy",
    "target": "api",
    "domain": "engineering"
  },
  "context": {
    "projectPath": "/workspace/api",
    "environment": "prod"
  },
  "meta": {
    "userId": "user_123"
  },
  "options": {
    "dryRun": false,
    "force": false,
    "session": "session_abc123",
    "capture": {
      "enabled": true,
      "scope": "personal"
    }
  }
}

// Solve response
{
  "ok": true,
  "correlationId": "req_123",
  "protocol": {
    "protocol_version": "1.1",
    "capabilities": ["runs", "sessions"]
  },
  "success": true,
  "executionId": "exec_123",
  "artifact": { "id": "artifact_42" },
  "result": {
    "improvement": 0.24,
    "metrics": {}
  },
  "confidence": {
    "score": 0.91,
    "reason": "Strong artifact match"
  },
  "execution": {
    "cached": false,
    "fallbackUsed": false,
    "durationMs": 1820,
    "session": {
      "id": "session_abc123",
      "resumed": true
    }
  },
  "steps": [
    { "label": "select artifact", "success": true, "actionId": "step_1" },
    { "label": "execute plan",    "success": true, "actionId": "step_2" }
  ],
  "learning": {
    "memoryUpdated": true,
    "artifactStatsUpdated": true
  },
  "error": null
}