Why it keeps up with wherever AI goes
In plain language
Models will keep changing — new providers, new capabilities, new output formats, new embedding models — faster than any Solution should have to be rebuilt. MagWorks is built so that the fast-moving parts sit behind contracts that already absorb change today, and the parts that must never change are append-only substrate. Each line below is shipped code, with the mechanism and the decision record behind it.
Models and providers are adapters
One model gateway; Amazon Bedrock and OpenAI adapters behind the same contract; every adapter declares what each model can do; every step routes by declared capability with a fallback chain and its own retry budget. A new model is a routing change and a capability declaration. A new provider is an adapter behind the same interface, with its SDK isolated so no existing deployment changes. A Solution's authored definition never names provider internals.
→ The AI runtime · ADR-0012, ADR-0020, ADR-0021
Prompts are versioned artifacts
Content-hashed versions, published by pointer move, promoted or rolled back with evaluation evidence attached to the exact hash. Improving a prompt for a new model never edits what is running; it publishes a new version beside it, and every flip is a self-contained ledger row. Prompt identity is the pointer, so ten thousand prompts sharing a model cannot collide.
→ ADR-0011, ADR-0036
Knowledge survives the embedding model
Vector indexes are a rebuildable projection, never canonical state; documents and their provenance are the truth. Every vector carries the document version, chunker, embedder, model and content hash that produced it. Changing the embedding model is a re-index, verified by the same hash chain that detects drift today.
→ The knowledge substrate · ADR-0018, ADR-0023, ADR-0031
Output shape and streaming are solved once, at the gateway
Structured output is enforced by constrained decoding at the model boundary for any model whose declaration supports it; onboarding a model is a registry row, a test row and a live smoke — never adapter code. Streaming has one frozen semantics across providers, with finalisation as the sole authoritative fold. Every Solution gains both without changing.
→ ADR-0024, ADR-0039
The action vocabulary is governed
Generate, Tool and Human Review are the actions today, all measured and audited through one generic runtime (I-14, I-15). New action types enter through an ADR with an explicit disposition — additive, refinement or breaking — so growth is deliberate and every existing Solution keeps running through it. The composition grammar grew the same way: routing in July, tools in September, each an additive step-union member with the authored artifact remaining the complete truth of control flow.
→ Constitution · ADR-0025 · composition ADR-0013, ADR-0015
History is append-only and replayable
Ledger, run records, transition rows and cost records are never migrated; only live records evolve, through a forward-only runner that is structurally incapable of touching truth. What happened last year is trusted without re-running it, whichever models exist then.
→ Tenancy and records · ADR-0019, ADR-0033
The layers change at their own speed
Substrate, composition and product are separate repositories, separate version lines and separate releases, joined only by published artifacts. A substrate minor can ship a new provider without a composition release; the product upgrades behind its own mirror tests. Change is absorbed one layer at a time, never all at once.
→ The idea · ADR-0008, ADR-0016, composition ADR-0001
The proof it already happened
- A second provider (OpenAI) was added behind the existing gateway contract, with provider-attributed attempt traces, in one substrate release.
- Streaming was added to both providers against a contract frozen a wave earlier, without changing the unary path.
- Structured output moved from prompt-instructed to gateway-enforced, validated live against the active envelope models, with no capability changes by default.
- Identity-first prompt resolution replaced tuple resolution as an additive minor, with the legacy path kept until no live definition needed it.
- The composition grammar gained routing, coalesced outputs and tool steps as additive members; existing capabilities serialised byte-identically.
Each of those is the pattern the next change will follow.