WeaveKit Docs
Reference

Contract freeze (G1)

What is frozen at 1.0 and how the engine evolves after it.

From 1.0 the engine's public contract is frozen under a single CONTRACT_VERSION (exported from @weave-kit/engine, also returned by GET /version as contractVersion and embedded in the OpenAPI document as info.x-contract-version). CONTRACT_VERSION is currently 2 (the 2.0 major). See Migrating to 2.0.

What is frozen

SurfaceFrozen at
schema.json on-disk formatSCHEMA_FORMAT_VERSION (6)
workflow.json on-disk formatWORKFLOW_FORMAT_VERSION (2)
Pagination cursorsCURSOR_VERSION (1)
REST routesthe adapters/rest route set
MCP tool namessearch_records / get_record / create_record / update_record / delete_record + list_objects / describe_object + workflow_transition + list_approvals / approve_approval / reject_approval
MCP prompt namesthe built-in prompts explore_data / object_guide / build_filter / run_workflow (host PromptsProvider names are not frozen)
Event typesrecord.created / updated / deleted / transitioned, audit.event, schema.changed, schema.drift, lifecycle.shutdown
Error codesthe SchemaError message keys (code), mapped to HTTP status by mapSchemaError
data-access / RBAC contractsObjectDataAccess, DataAccessContext, resolvePermission / buildRowScope
Audit / evidence queriesAuditQuery / AuditQueryResult, EvidenceQuery / EvidenceQueryResult (keyset cursor / nextCursor)
Observability & traceMETRIC_NAMES, MetricsSink / TraceSink, parseTraceparent / TraceContext
Package exportsthe . entry point (types re-exported from the package root)

A test (tests/unit/contract-freeze.test.ts) pins the single-source values above, so any change to them fails the build until it is a deliberate, version-bumping change.

How the engine evolves after 1.0

  • Additive by default. New fields, routes, tools, error codes, options and exports are allowed in a minor/patch release and do not bump CONTRACT_VERSION.
  • Deprecation. A surface to be removed is first marked deprecated and kept for at least one minor release; removal happens only at a major release and bumps CONTRACT_VERSION.
  • Experimental. Unstable surfaces live under the @weave-kit/engine/experimental subpath and are not covered by the freeze; they may change in any release. New externally-visible capabilities land here first and graduate to the stable . surface (an additive minor) once their shape has proven out.
  • Formats self-migrate. schema.json / workflow.json older versions are migrated on read (weave schema:upgrade / weave workflow:upgrade stamp the current version), so a format bump is additive in practice.

Extension seams (never frozen shut)

Enterprise/custom extensions build on stable seams that keep evolving additively: AuthVerifier / IdentitySource, ApprovalsBackend, guardrails policies, AuditSink / AuditQueryEngine, EventPublisher, EvidenceSink, MetricsSink / TraceSink, WorkflowBackend / WorkflowTimerStore / WorkflowCoordinator, CounterStore. New methods may be added; existing signatures are not broken.

On this page