OSS-first docs
These docs teach the open system first: contracts, generated surfaces, runtimes, governance, and incremental adoption. Studio shows up as the operating layer on top, not as the source of truth.
A contract edition is the storage-agnostic lifecycle envelope around a typed TS contract. It lets humans and AI agents draft, review, experiment, publish, migrate, roll back, and archive contract changes without hiding authority, evidence, or storage behavior in runtime code.
Version taxonomy
| Name | Meaning | Typical owner | | --- | --- | --- | | contractVersion | Public contract semantics, usually matching the contract meta/version. | Contract author | | editionVersion | Lifecycle envelope revision for a specific draft, experiment, migration, rollback, or release candidate. | Steward workflow | | storageRevision | Physical persistence revision: Git commit/path selector or database revision id. | Storage adapter | | releaseVersion | Deployment/promoted release capsule that consumed an edition. | Release workflow | | experimentVersion | Experiment allocation/variant revision using the edition. | Experiment owner |
Rollback and migration are lifecycle states/events/evidence, not version numbers. They can create new editionVersion and storageRevision values, but the reason must stay explicit in lifecycle and evidence refs.
Storage kinds
| Storage | Use when | Required evidence | | --- | --- | --- | | file | Stable source-of-truth, Git review, build/deploy reproducibility, package exports. Same-file multi-edition is allowed only with selector/build metadata. | Git/path refs; selector refs for same-file multi-edition | | database | Realtime collaboration, long-living processes, quick AI/human iteration, vertical-specific drafts, and live governance. | Revision/history refs and rollback refs | | hybrid | Sync/projection state between file and database, not a third canonical store. | Source/target refs, conflict state, sync evidence refs |
Lifecycle and authority
Lifecycle states are draft, review, published, experiment, deprecated, archived, rollback, and migration. Authority is policy-per-vertical and can permit suggest-only AI, draft patches, reversible application, autonomous stewardship, human approval, or mixed control.
Promotion and sync are blocked without evidence. Published editions require test, replay, rollback, and promotion evidence. Breaking and migration-required intents require migration refs. Experiments require experiment refs and an experimentVersion.
Primitive mapping matrix
| Primitive | Edition role | | --- | --- | | agent-step-observability | Records AI/human suggestions, auto-apply decisions, and approval gates. | | ai-improvement | Produces draft patches, reversible applies, and evidence-linked improvement loops. | | experiments | Carries A/B allocations and experimentVersion for contract variants. | | ContractSpec Connect | Supplies policy verdicts, compatibility gates, and escalation evidence. | | release/replay capsules | Prove promoted editions are reproducible and rollback-ready. | | graph evolution commands | Provide human/AI editing surfaces for draft and migration flows. | | database contract surfaces | Persist realtime revisions, collaboration history, and rollback anchors. |
Managed CompanyOS posture
Managed CompanyOS should start with file-backed published editions for stable contracts and database-backed experiment editions for fast vertical iteration. Database drafts materialize to file patches before release unless the vertical policy explicitly grants database authority for that lifecycle state.