AliothStudio consists of two chains with separated responsibilities; understanding their boundary is the precondition for using the platform correctly:
| Chain | Responsibility | Driven by | Output |
|---|---|---|---|
| Model release chain | Structural evolution of the data substrate (tables/columns/inheritance/dimension codes) | Meta Model Center (human channel) | Alioth/v* release package (DDL · seed · machine-readable contract · verification report) |
| Application building chain | Assembling business applications on the frozen substrate | AppAgent agent + developers | Application configuration, Service backend, module frontend, Deploy/{ns} deployment package |
| Dependency | Purpose |
|---|---|
| PostgreSQL 14+ | Data substrate (model v10.0 is a table-inheritance structure) |
| mise | Unified entry point for tasks and environments (mise run <task>) |
| Rust toolchain / pnpm / bun | Backend build, frontend build, scripting toolchain |
# Development database initialization (replayed from the release snapshot; DROPs and rebuilds the target database — aliothstudio_dev only)
bash scripts/db/reset-db.sh --dev
# Meta platform (model management + AppAgent): backend :4949, frontend :49494
mise run meta
# Namespace development environment (Gateway + SSO), {ns} ∈ alioth | wz | avic | cosmic | se | mat
mise run dev:{ns}aliothstudio ← staging aliothstudio_pre → development aliothstudio_dev → test aliothstudio_test. Environments are forcibly bound to DATABASE_URL; all schema queries go through cd Meta/backend && mise run schema-info -- <command> (the DB is the single source of truth — inferring from DDL files is forbidden).All structural evolution is performed through the Meta frontend Model Center: creating collections (attaching to a parent table to form an inheritance), registering fields, and maintaining dimension codes (scene/factor/function). Registering collections and fields is programmatically synchronized by the platform into physical tables and inheritance attachments — developers write no table-creation DDL at all.
Once a release is initiated from the Model Center, the pipeline exports the isahl schema (pg_dump --schema-only + 268 seed tables' data + the dimension seed seed-dimensions.sql), post-processes it into pure CREATE/ALTER form, writes it to Alioth/v{version}/, and performs a full rebuild verification in a dedicated verification database (structure round-trip + seed round-trip + uid uniqueness), with the report written to disk as verify-report.json. The latest release is currently v10.0.44: 1022 isahl tables, 1204 inheritance edges; all 268 seed tables verified round-trip consistent, verification status verified. The release pipeline emits 7 progress events (prepare / schema / isahl_dump / seed_dimensions / manifest / verify / done); the collection row layer is declared and carried by the model-side row_layer (abstract / carry), and an unadjudicated parent table holding rows blocks the release.
Model landing and the DB derived surface are coupled in the same batch: refresh-derived-artifacts.ts is the sole refresh entry point for the four derived artifacts fk-index, relation-index, value-domain-columns, and dk-projection-tables, and is wired into reset-db.sh; the artifact diff is the model-topology review surface, and anti-removal is enforced by gate W9.
Business semantics are located through three-dimensional coordinates: dk_scene (scene), dk_factor (factor), dk_function (function). Dimension codes are automatically composed from a category code + a serial symbol (e.g. JC = system management). Coordinates are interpreted locally per namespace; every API of a Service statically binds a fixed coordinate triple.
The application building chain is driven by AppAgent, with the following standard tool sequence:
analyze_ontology # requirements/prototype → OntologyModel IR (with hard five-domain completeness validation)
build_module # flow-plan → module.json (module declaration)
build_block # flow-plan → block.json (capability block declaration)
transfer_ontology # ontology alignment → alignment-graph.json + mapped-entities.json
generate_service_api # ontology entities → Service backend (Rust, static coordinate binding)
compose_app # module assembly → app.json + extensions/*.yaml + prototype artifactsArtifact locations: Pre-Proc/{ns}/Apps/{app}/ (app.json, extensions, process artifacts) and Pre-Proc/{ns}/Sources/Apps/{Modules,Blocks,Services}/ (module/block/service declarations and code). The entry shape of ontology mapping artifacts (ontology-output.json) is validated by the contract gate, and coordinates must be real DB codes.
| Layer | Key constraints |
|---|---|
| Module | Scene/Factor composition container; required fields of module.json complete; DashboardPage forbidden (a root path that jumps straight to an entity list page) |
| Block | Capability unit; the IDs referenced by factors/services must exist (orphan references have a dedicated gate) |
| Service backend | Standard skeleton of handlers/models/repositories/services; static binding of the coordinate triple (split APIs for the same table under different coordinates); auth middleware forbidden (the Gateway handles NGAC uniformly); the tracing crate forbidden inside modules |
| Frontend | State management is always Jotai v2; measurement fields follow the "numeric value + unit radio" format; integrate against the real backend, mocks forbidden; data access uniformly goes through the @alioth/api resource-level transport (list/get/mutate, with the envelope unwrapped via items()/unwrap()); reference selectors always use the ReferenceSelectDescriptor descriptor — extrapolating contracts from endpoint types is forbidden |
zc_id_lifecycle_r_* relation tables; entities may not create their own state columns (flag is used only by state dictionary rows)dk_function from one of the six prefixes (_f_/_t_ are derived automatically; hand-written literals are forbidden)qk_* columns are value-space pointers (bigint); arithmetic on them is forbidden, and reads go through _refs resolutionApplication-level extensions (constraints / rules / statemachines / workflows) are placed in Pre-Proc/{ns}/Apps/{app}/extensions/ and loaded when the Gateway starts. This is the only driver surface through which extensions take effect — validation, rules, and flows can be adjusted without regenerating code.
# The only build entry point (feature gating + target isolation + automatic signing)
bash scripts/build-ns.sh <NAMESPACE> release # or dev (debug mode)
# Release (syncs Apps / seed / .env / apps.json; does not build by itself)
bash scripts/deploy/release-to-namespace.sh <NAMESPACE>Artifacts: Deploy/{ns}/bin/{ns}-server (namespaces with OpenActivity enabled additionally have Deploy/{ns}/Open/bin/openactivity-server). Releasing to the production stage automatically restarts the Gateway. Non-namespace applications (Meta / SSO) go through scripts/meta|sso/deploy.sh and land in Release/.
The repository enforces quality through a "specification execution substrate": every checkable specification is paired with a check script + baseline + gate registration (currently 229 items: 137 in the commit stage / 92 in the push stage). The specification library now holds 403 capability living specifications; every MUST/NEVER clause must declare its enforcement point (gate id / script / test path) through the structured field "enforcement surface" — prose declarations are no longer passed. High-frequency items:
| Gate | What it blocks | Stage |
|---|---|---|
check-isahl-ddl-boundary | Any isahl structure write that bypasses the channel | commit |
check-leaf-insert | INSERT not landing on a leaf table / hand-written _f_/_t_ literals | commit |
check-code-semantics | Type/enum semantics written into a code column | commit |
check-ontology-contract | Ontology mapping artifact shape / forged coordinates | commit |
check-bridge-host-domain | Misplaced host domain on the left end of a relation table | commit |
formal-proofs | Lean theorem build failure or proof placeholders | push |
check-all (T1/T2) | Version alignment / OpenSpec compliance / i18n / Service DAG, etc. | push |
No local environment is needed to experience the full platform: https://cosmic-tools.shop/ offers an online SaaS learning edition of AliothStudio — a streamlined deployment for individual users (core modeling, application assembly, and runtime workflows are fully available; enterprise-grade multi-namespace orchestration and the release pipeline are omitted). Suggested path: sign up and enter → follow Chapters 2–7 of this handbook in order → self-check your artifacts against the gate list in Chapter 8.
Companion document: "Alioth Model Theory White Paper" — understand the mathematical structure behind every constraint in this handbook.
© 2025-2026 Hangzhou Yuqi Technology Co., Ltd. (CosmicTools.ltd).