SEIF Docs

ADR 006 — Versioned context and tool contracts

Accepted for implementation 2026-10-12 by the owner's explicit instruction. Extends ADRs 002–005. This is a Workstation product contract, not a change to SEIF Protocol ontology. Commercial differentiation remains a hypothesis to validate with customers.

Problem

The Workstation can release, explain and reproduce context, but an application still defines the callable tools independently. A context release can therefore refer to a missing tool, an incompatible argument schema or an operation that should not be offered for the current objective. The Estuda side-panel pilot did not exercise tool execution. Context-only success is insufficient evidence for a managed agent service.

Decision

  1. Projects declare a bounded tool catalogue: stable id, model-facing name, version, description, argument and optional result schemas, read/write effect, approval requirement, timeout and call limit. Profiles explicitly include or exclude tools; omission denies disclosure. Source material cannot grant tools. Executors, URLs and credential values are absent from Builds.
  2. The immutable Build covers context, tool contracts, policies and deterministic tests. Builds containing tools require seif.context-runtime.v2; tool-free Builds retain v1 and their definition digests. Older runtimes must refuse a tool Build rather than silently ignore its policy.
  3. Deployment Bindings map tools to fixed authenticated HTTP executors. context-tool-executor.v1 exposes describe and execute. Readiness verifies exact tool version and contract digest. Required unavailable tools block resolution; optional unavailable tools are omitted. The resolved model-facing schemas have an explicit digest and contribute to the combined estimated token budget.
  4. The Runtime hosts a tool gateway alongside the read-only context resolver. A call is bound to its retained context, Build, deployment, tool contract and caller-chosen call id. It validates arguments, current executor compatibility, objective disclosure and call limits before dispatch. The backend still enforces tenant authorization and domain invariants. Model messages and observed traces grant no domain authority.
  5. Write tools require an operator approval tied to the exact context, tool, call id and argument fingerprint, with a five-minute lifetime. Resolved tool contexts expire after fifteen minutes; existing receipts remain inspectable without repeating dispatch. Application credentials cannot approve. Managed operation uses a human-only Registry capability and a separate runner approval credential; standalone operation uses a separately supplied approval token. Approved calls still undergo backend authorization.
  6. Dispatch intent is persisted before network I/O. A repeated call id never dispatches again within the retained context; changed arguments conflict. Timeouts, interrupted responses and unresolved prior dispatches are UNKNOWN, not safe-to-retry failures. This is bounded dispatch deduplication, not exactly-once execution. Executors receive an idempotency key and must persist domain deduplication for durable business effects. Losing response content never justifies repeating an action.
  7. Traces separate offered tools, reported model disclosure, gateway validation/dispatch and executor-reported results. Argument/result fingerprints are keyed under metadata retention; raw arguments are never retained by the gateway. Replay re-evaluates context and tool selection from retained observations and never re-executes effects. Application quality and business outcomes remain externally evaluated.
  8. Context Tests cover tool inclusion/exclusion, executor version/schema compatibility and allowed/denied synthetic calls. Tests execute no business actions. The inherited regression corpus and reviewed incident guards retain these obligations even if a candidate removes or weakens its tests. Historical guard review covers tool fixtures and expectations.
  9. Native Design exposes tool authoring and per-profile disclosure. Preview, tests, Build comparison and observation expose tool decisions. TypeScript/Python clients expose schema disclosure and execution without owning the model loop. A portable reference Project, authenticated executor and runnable proof demonstrate the complete workflow.
  10. HTTP/JSON plus documented JSON Schema constraints is the integration boundary. Future n8n and LangChain adapters can resolve context, bind returned schemas and route callbacks through the gateway without changing artifact semantics. Official n8n HTTP Request and LangChain tool APIs support that composition; dedicated adapters are not claimed as implemented merely because the HTTP contract exists.

Validation and commercial delivery

Acceptance requires schema rejection (unsupported constraints fail explicitly), old Build compatibility, incompatible executor refusal, actual HTTP dispatch, denied/excluded tools, required-tool failures, combined budget enforcement, exact approval binding and expiry, application approval denial, concurrent duplicate suppression, restart uncertainty, metadata privacy, inherited promotion blocking, effect-free replay, native authoring and standalone packaging.

The customer deliverable is a versioned Context Project, immutable Build, self-contained Runtime, environment-specific bindings, regression corpus and documented application integration. Generic execution and governance are product features; customer-specific business tools remain owned implementations behind the executor contract.

The first acceptance proof uses synthetic Estuda-shaped scenarios and a labelled deterministic model where needed. A real SaaS adoption trial must separately measure setup effort, application quality, latency and incident recurrence. No test pass is presented as a real production incident avoided or proven financial return.

Tradeoffs

The supported schema subset is bounded and documented; unsupported JSON Schema keywords are refused. All writes require human approval in this contract version. Executor outages may block required objectives. Retention expiry ends gateway deduplication and replay eligibility; context references then fail closed. Runtime failures do not prove whether an external write occurred. HA, model hosting and autonomous approval are outside this contract.

Primary integration references: n8n HTTP Request and LangChain tools.