Skip to content

LangStitch production readiness

Source validation recorded 2026-09-14. This document covers the shared IR, Python SDK/compiler, native Java compiler, and LangTailor desktop/VS Code exporters. The source baseline is followed by publication and remote CI evidence verified on 2026-09-20.

The requirement is zero failing build, compilation, package-installation, and acceptance checks for supported production configurations. It does not mean instantaneous compilation or a guarantee that arbitrary authored source code cannot contain errors. Native implementation bodies are real source code and must pass their language toolchain before release.

Current result and evidence

Publication verified 2026-09-20: Python SDK 0.3.2 on PyPI, Java compiler 0.2.2 on Maven Central, and shared spec 2.2.0 on GitHub are available. The spec release does not publish an npm registry package. LangTailor 0.4.0 is published with Windows x64 and macOS x64/ARM64 installers, macOS update ZIPs, a VSIX, updater manifests, SHA-256 checksums and a release manifest. The same VSIX was published to VS Code Marketplace and Open VSX. The original local checkpoint below remains separate from artifact publication and production acceptance.

  • Shared specification: 25 tests passed, TypeScript build passed. Schema export now includes Go as a target and preserves native bodies.
  • Python SDK: 200 tests passed, two intentional skips for tests that only run when optional dependencies are absent. Actual LangGraph, HTTP, MCP and server dependencies were installed. Source compilation and pip check passed.
  • SDK packaging: version 0.3.2 wheel and source distribution built and passed twine check. A fresh virtual environment installed the wheel, exercised both CLI entrypoints, compiled an IR document and executed the emitted LangGraph application with the expected result.
  • Native Java compiler: 12 tests passed with no skips. Its tests build generated Maven applications and exercise graph execution, reducers, HTTP tools, model output shapes, startup, configuration, authentication, malformed requests and the invoke contract. The packaged CLI also passed smoke checks.
  • IDE generators: 103 tests passed, including actual generated Python, Java and Go compilation/execution. The Java application conformance test also verifies native HTTP tools, mocked model responses, authentication and the common API envelope.
  • Host integration: VS Code extension and Electron main TypeScript builds passed. Focused checks exercised obsolete generated-file cleanup, preservation of unrelated files, invalid paths, missing executables, per-window processes and failed Git operations.

Publication completed on 2026-09-15 after the local checkpoint. The coordinated LangTailor release workflow passed native conformance on Ubuntu, Windows and macOS, built Windows x64 and macOS x64/ARM64 delivery artifacts, verified release checksums and published the canonical VSIX to both extension stores. Its public release manifest records the source revision and dependencies. Repository maintainers can inspect the complete release run; the IDE source repository is private, so public consumers should use the manifest and release assets. These checks do not establish GUI acceptance, signing, container startup or production operational readiness.

Fixed gaps

IR-01 — Saving destroyed platform implementations and runtime settings

The IDE still uses a flat editing model and converts it to IR v2 when saving. Migration previously replaced existing component template maps with an empty map and discarded modern runtime configuration. Typed configuration sections were also reset to an empty array.

Migration and the IDE bridge now preserve component templates, native node bodies, typed configuration sections, target selection, server/model/security/logging settings, checkpointer environment references and observability settings. Repeated-save tests exercise the complete load → edit model → save sequence. This prevents a Java or Go implementation from disappearing during normal visual editing.

The persisted contract uses target.platform values python-langstitch, spring-ai, and go. Generated schemas and project/pack manifest parsing recognize all three values. This schema acceptance does not imply the existing marketplace pack compiler emits Go artifacts.

IR-02 — Capability claims exceeded actual implementations

A shared specification constant now drives the IDE node capability checks. Tests compare it with published capability JSON files. Go has its own capability file. Missing native bodies, unsupported nodes and missing component templates produce actionable export errors instead of successful-looking placeholder projects.

The Python/Java pack intersection no longer claims streaming or run events are implemented on both targets. Java and Go reject MCP integrations; Python has a real adapter. Transport and settings restrictions still require generator-specific validation: a supported node kind does not promise every possible setting for that node.

SDK-01 — Generated MCP tools did not execute real transports

The SDK now owns the official MCP client session lifecycle for stdio, SSE and streamable HTTP. It validates transport settings, tool names, object arguments and environment references, applies timeouts, reports tool errors and avoids silently nesting a synchronous call inside a running event loop. HTTP transports are exercised against real local MCP servers. Generated Python projects import this adapter and declare the MCP dependency extra.

The compiler also checks emitted Python syntax, module-name collisions and malformed graph references. It emits valid Python booleans/defaults, honors selected native bodies, handles scalar versus list model output, and preserves declared message replacement behavior.

JVM-01 — Native Java bodies and tools were substituted with placeholders

Both Java emitters require actual Java implementations for functions and inline tools. A body declares Object result; the runtime writes that result to the configured output key. Null results remain valid. Template transformers execute their template, and state patches respect append versus replace reducers.

HTTP registry tools perform JSON POST requests, with endpoint validation, connect/read timeouts, non-success status handling, invalid-JSON errors and a 4 MiB response cap. Endpoints may reference env:VARIABLE. MCP, bound model tools/agents and advanced unsupported node kinds fail clearly.

Generated LLM nodes now use Spring AI, skip empty prompt components, preserve scalar/list output shape and emit numeric option types that compile. Keyword/name handling, escaped metadata, graph target validation and router termination prevent several classes of generated compilation or execution errors. Graphs without LLM nodes do not require OpenAI initialization merely to start.

GO-01 — Go was absent as an executable target

The IDE now emits a native Go module and HTTP service using the standard library. Supported execution includes functions, native/HTTP tools, response templates, OpenAI-compatible LLM calls and routers. It does not invoke a Python or Java runtime.

The runtime validates state values, initializes declared defaults, applies append/replace reducers, isolates request state, observes cancellation and maximum graph steps, and converts node panics to execution errors. It limits incoming bodies to 1 MiB, outgoing responses to 4 MiB, and applies request/upstream deadlines. Generated projects include tests, a Dockerfile and run instructions. Container build/run acceptance is still pending.

IDE-01 — Export, preview and execution selected the wrong runtime

Go is available as a persisted target and export option. Native implementation editors are available for functions, inline tools, registry tools and code transformers. Python, Java and Go are stored independently in bodiesByPlatform; one language is not inferred from another.

Code previews use the selected target. Unsupported exports report an error without crashing the designer. Java and Go previews are read-only because reverse synchronization is not implemented; native bodies are edited in the designer. The host explicitly reports the native debugging limitation instead of attempting Python debugpy on another language.

VS Code Build now waits for actual toolchain exit status. Desktop build/test/run synchronizes current sources, isolates generated directories, removes only previously generated obsolete files, prevents overlapping builds and tracks server processes per window. Failed compilation, tests, spawn and Git operations no longer produce a success result. A server launch message means the operating system created the process; HTTP readiness remains visible in output and is not yet an automatic IDE gate.

Authoring portable graphs

Use the same topology and state field names, but provide native implementations for language-specific behavior. For a function with outputKey: "answer":

{
  "bodiesByPlatform": {
    "python-langstitch": "return {\"answer\": state.get(\"query\", \"\")}",
    "spring-ai": "Object result = state.get(\"query\");",
    "go": "return State{\"answer\": state[\"query\"]}, nil"
  }
}

Python and Go bodies return state patches; Java bodies assign the output value to result. Python legacy full function definitions remain accepted. Go bodies receive ctx context.Context and state State. Arbitrary extra Go imports currently need to be added to exported code; the IR does not yet provide a general per-node import/dependency editor.

The common HTTP contract is:

POST /invoke
Content-Type: application/json
X-API-Key: <value of the configured API-key environment variable>

{"state":{"query":"hello"}}

Successful responses contain {"result": {...state...}}. Existing Java input/query requests and Go raw-state requests retain their legacy response format. Prefer the common envelope for new clients. GET /health supports startup checks. Authentication defaults require an API key; explicitly selecting security.auth: "none" disables it. Bearer authentication is available in Python/Go; Java currently accepts none or api_key.

For the current portable core, use no checkpointer, disable streaming, and avoid Python lifecycle hooks, RAG, agents, remote subgraphs, HITL and intent classifiers on native targets. Python has additional capabilities, but each requires its own acceptance coverage. Use final unconditional router branches when a default path is intended. Go supports a wider scalar condition subset than the current Java translator; Java portable branches should use constants or string equality with state.get("key").

Release acceptance and remaining gates

RELEASE-01 — Coordinated dependencies published

Completed for shared spec 2.2.0, Python SDK 0.3.2, Java compiler 0.2.2 and LangTailor 0.4.0. The spec and SDK revisions are pinned in the IDE release workflow; conformance installs the published Python SDK from PyPI. The SDK release validates a clean wheel installation, and Java publication verifies its packaged CLI before uploading to Maven Central. Generated Python MCP projects require SDK 0.3.2 or newer.

For future releases, publish compatible dependencies before the IDE and pin the tested versions. Preserve checksums, source revision and package versions in the release manifest, and verify installation from public package registries.

RELEASE-02 — Operating-system CI passed; installer acceptance remains open

Native generated-application tests and IDE source builds passed on Ubuntu, Windows and macOS in the 0.4.0 release workflow. Windows x64 and macOS x64/ARM64 artifacts were packaged and published; Linux desktop installers are not part of this release. A successful packaging job is distinct from interactive GUI acceptance on each architecture.

Still required: clean VSIX installation and extension activation, Electron terminal/runtime smoke tests, installer upgrade/rollback, container build and non-root health/invoke/shutdown tests. The 0.4.0 desktop release is unsigned and macOS is not notarized; signed delivery remains required for environments whose policy demands it. ARM64 artifact availability does not establish ARM64 GUI acceptance.

RELEASE-03 — Prove production operational behavior

The conformance tests exercise real local HTTP servers and mocked model responses. Live paid-provider credentials, hosted backend deployment, load/soak, end-to-end TLS, proxies, rate limits, retries, secret rotation and service recovery have not been verified in this work.

Acceptance: representative production graphs pass load/error/recovery tests; authentication and configured CORS are verified at the deployment boundary; no secrets or prompt content leak through logs; timeouts and retry policy are explicit; health/readiness and graceful shutdown are observed by deployment automation. JVM request limits/deadlines and cross-runtime error status/envelope parity require further work.

RELEASE-04 — Close settings and state-semantic differences

The save/load bridge preserves runtime configuration, but preservation is not proof that every setting is executed on every target. The flat IDE settings model remains a design debt. Typed configuration accessor generation, provider settings, state defaults/types, tracing, logging sinks/rotation and deployment values need broader target-by-target conformance. Go implements explicit state defaults/type checks; equivalent guarantees must be established for Python and Java before claiming full state parity. Some Python registry helper modules still contain starter behavior; their existence must not be represented as production enforcement of policies or retrieval.

Acceptance: a shared fixture asserts the same defaults, merge behavior, configuration values and validation errors through all three HTTP APIs; unsupported settings are rejected instead of ignored. Typed runtime settings and editor-only preferences should eventually be separate in-memory types with explicit mappings.

RELEASE-05 — Desktop dependency maintenance remains open

The desktop dependency review identified Electron 36 as behind supported patch levels and reported advisories involving adm-zip 0.5.18, fast-uri 3.1.2 and js-yaml 4.3.0. Those dependencies were not changed in the published 0.4.0 artifacts. This record does not establish exploitability in LangTailor; review current advisory details, update the affected dependencies, rebuild installers and repeat native-module and GUI acceptance before treating the desktop as a production-hardened release. Status recorded 2026-09-20.

Feature parity backlog

  • RAG and agents: these nodes remain blocked by the supported export capability checks. Replace placeholder retrieval/embedding and agent delegation paths, then test actual retrieval relevance, provider failures, cancellation, tool invocation and agent routing. Do not claim production RAG because a generated registry helper imports successfully.
  • Native MCP: Java and Go need actual sessions, transport adapters, schemas, authentication, cancellation, tool errors and cleanup tests before enabling their MCP capability.
  • Checkpointing and resumability: durable stores, lifecycle cleanup, TTL, concurrent runs, resume compatibility and human interrupts need native implementations and persistence tests. Current Python export checks permit only no checkpointer or memory.
  • Streaming and events: define a shared event protocol and test token/node ordering, disconnects, cancellation, terminal errors and security before advertising Java/Go event parity.
  • Native subgraphs and classifiers: implement composition, state boundaries, recursion limits and real classification. Java/Go currently reject subgraphs, HITL and intent-classifier nodes.
  • Go custom components, pack compiler and reverse sync: target recognition in the schema is complete; multi-platform marketplace pack production, imported dependencies, native code-to-graph parsing and integrated debugging are not.
  • Built-in templates and policy helpers: audit every starter connector, guardrail, business rule, persona and generated helper for placeholder returns, unenforced policy or hidden external setup. Compile/import tests are insufficient to certify their business behavior.
  • Backend architecture: the PHP hosted marketplace and FastAPI local/platform API paths still need a documented authority boundary, target support contract and end-to-end IDE integration checks. This batch does not validate the websites, marketplace or hosted production deployment.

Reproduce the checks

Install Node.js/npm, Python with a repository virtual environment, JDK 21, Maven and Go. The checked-in CI uses Node 22, Python 3.12 and Go 1.26 for IDE conformance; SDK CI covers its declared Python versions. Clone langstitch-docs, langstitch-spec, langstitch-sdk, langstitch-spring-ai and langtailor from the LangStitch organization as sibling directories. From their parent workspace, use PowerShell 7:

python -m venv langstitch-sdk/.venv
./langstitch-docs/scripts/verify-production.ps1 -InstallDependencies

Subsequent runs can omit -InstallDependencies. The tracked verification script resolves the sibling workspace relative to its own location, so it also runs from inside the documentation repository. Use -Workspace /path/to/workspace for another checkout layout. It stops on a nonzero exit code and writes a transcript and machine-readable command results under the workspace's .verification. It builds/tests the spec, validates SDK compilation/dependencies/tests/distributions, verifies Java including its generated projects, executes IDE native conformance and builds all three IDE source bundles.

On this Windows host the default user temporary directory caused a JDK selector/socket initialization failure independent of LangStitch. Verification passed with this process-local override:

./langstitch-docs/scripts/verify-production.ps1 -JavaSocketTempDirectory C:/Windows/Temp

The script restores environment variables afterward. This workaround is not a global JDK setting and is unnecessary on machines where the default temporary directory supports the JDK's socket initialization.

Final workspace verification

The complete workspace script passed on 2026-09-14: 12 checks, zero nonzero exit codes. This includes specification build/tests; SDK dependency, compilation, test and package checks; native Java verification; all 103 IDE tests; the canvas production build; the VS Code webview/extension build; and the Electron renderer/main build.

Local evidence at that checkpoint: .verification/verification-20260914-180920.json contains each command and exit code; the adjacent .log contains the full transcript. These workspace logs are not published documentation artifacts. Running the tracked script creates equivalent evidence for the reader's checkout. The local Java socket-directory override described above was active. Remaining warnings were a third-party Python deprecation and Vite bundle-size warnings; neither caused a compilation or build failure. Remote CI was pending at that source-validation checkpoint and subsequently passed for the published 0.4.0 release. Packaged GUI/container acceptance and the operational gates above remain open.