@@ -5,210 +5,90 @@ description: Environment Artifact protocol schemas
55
66{ /* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */ }
77
8- # Environment Artifact Format Protocol (v0)
8+ # Environment Artifact Envelope
99
10- Defines the immutable envelope produced by ` objectstack compile ` and consumed
10+ THE single declaration of the environment artifact envelope ( # 4740 ,
1111
12- by the ObjectStack runtime at boot. The artifact carries everything a runtime instance
12+ # 4535 C10 — maintainer route A′). ` @objectstack/spec/cloud ` re-exports
1313
14- needs to hydrate an environment kernel without reading control-plane DB rows
14+ this file; both entry points resolve to these exact symbols, so the
1515
16- directly.
16+ chosen entry point can never change the shape a consumer gets (the
1717
18- ## Boundary
19-
20- - ** Artifact (this schema):** environment metadata + inlined function code +
21-
22- plugin/driver requirements. Immutable, content-addressable via ` commitId `
23-
24- and ` checksum ` .
25-
26- - ** Deployment Config (NOT in this schema):** business DB coordinates,
27-
28- credentials, environment identity, secrets. Injected at runtime.
18+ #4411 dual-source trap, closed for this name).
2919
30- See ` content/docs/concepts/north-star.mdx ` §6.3 for the runtime-inputs
20+ Describes the response shape of
3121
32- boundary, and ` ROADMAP.md ` M1 for the milestone definition.
22+ ` GET /api/v1/cloud/environments/:environmentId/artifact ` — the assembled
3323
34- ## Storage / Distribution
35-
36- v0 stores the full payload inline. Future revisions may swap ` metadata ` /
37-
38- ` functions ` for a ` payloadRef ` that points at out-of-band storage (S3,
39-
40- signed URL). The envelope shape preserves room for that indirection without
41-
42- a breaking schema bump.
43-
44- <Callout type = " info"
45- ** Source:** ` packages/spec/src/system/environment-artifact.zod.ts `
46- </Callout >
24+ artifact ObjectOS pulls from the control plane, and the shape the runtime
4725
48- ## TypeScript Usage
49-
50- ``` typescript
51- import { EnvironmentArtifactSchema , EnvironmentArtifactChecksumSchema , EnvironmentArtifactFunctionSchema , EnvironmentArtifactFunctionLanguageEnum , EnvironmentArtifactHashAlgorithmEnum , EnvironmentArtifactManifestSchema , EnvironmentArtifactMetadataSchema , EnvironmentArtifactPayloadRefSchema , EnvironmentArtifactRequirementSchema } from ' @objectstack/spec/system'
52- import type { EnvironmentArtifact , EnvironmentArtifactChecksum , EnvironmentArtifactFunction , EnvironmentArtifactManifest , EnvironmentArtifactMetadata , EnvironmentArtifactPayloadRef , EnvironmentArtifactRequirement } from ' @objectstack/spec/system'
53-
54- // Validate data
55- const = EnvironmentArtifactSchema .parse (data );
56- ```
57-
58- ---
59-
60- ## EnvironmentArtifact
61-
62- ObjectStack Environment Artifact envelope (v0)
63-
64- ### Properties
65-
66- | Property | Type | Required | Description |
67- | :--- | :--- | :--- | :--- |
68- | ** schemaVersion** | ` '0.1' ` | ✅ | Environment artifact envelope schema version |
69- | ** environmentId** | ` string ` | ✅ | Environment identifier (control-plane scoped) |
70- | ** commitId** | ` string ` | ✅ | Content-addressable revision id |
71- | ** checksum** | ` { algorithm: Enum<'sha256' \| 'sha384' \| 'sha512'>; value: string } ` | ✅ | Artifact integrity checksum |
72- | ** builtAt** | ` string ` | optional | ISO-8601 timestamp of when the artifact was built |
73- | ** builtWith** | ` string ` | optional | Build tool identifier |
74- | ** metadata** | ` Record<string, any> ` | ✅ | Compiled environment metadata grouped by category |
75- | ** functions** | ` { name: string; language: Enum<'javascript' \| 'typescript'>; code: string; source?: object; … }[] ` | ✅ | Inlined function code packaged with the artifact |
76- | ** manifest** | ` { plugins?: { id: string; version?: string }[]; drivers?: { id: string; version?: string }[]; engine?: object } ` | ✅ | Plugin/driver requirements baked into the artifact |
77- | ** payloadRef** | ` { url: string; expiresAt?: string; checksum: object } ` | optional | Out-of-band payload reference (reserved for future use) |
78-
79-
80- ---
26+ metadata loader parses at boot (` packages/metadata/src/plugin.ts ` ,
8127
82- ## EnvironmentArtifactChecksum
28+ ` _parseAndRegisterArtifact ` — the one runtime Zod parse of this envelope).
8329
84- Artifact integrity checksum
30+ Distinct from the marketplace ` PackageArtifactSchema ` (a .tgz file
8531
86- ### Properties
32+ listing). This envelope wraps the compiled ` ObjectStackDefinitionSchema `
8733
88- | Property | Type | Required | Description |
89- | :--- | :--- | :--- | :--- |
90- | ** algorithm** | ` Enum<'sha256' \| 'sha384' \| 'sha512'> ` | ✅ | Hash algorithm used for the artifact checksum |
91- | ** value** | ` string ` | ✅ | Hex-encoded digest of the artifact body |
34+ produced by ` objectstack compile ` together with control-plane assigned
9235
36+ identity (` commitId ` , ` checksum ` ).
9337
94- ---
95-
96- ## EnvironmentArtifactFunction
97-
98- A single inlined function
99-
100- ### Properties
101-
102- | Property | Type | Required | Description |
103- | :--- | :--- | :--- | :--- |
104- | ** name** | ` string ` | ✅ | Function machine name (snake_case) |
105- | ** language** | ` Enum<'javascript' \| 'typescript'> ` | ✅ | Source language of the function code |
106- | ** code** | ` string ` | ✅ | Inlined function source |
107- | ** source** | ` { path?: string; exportName?: string } ` | optional | Source-map metadata for the function |
108- | ** hash** | ` string ` | optional | Hex SHA-256 of the inlined code |
109-
110-
111- ---
112-
113- ## EnvironmentArtifactFunctionLanguageEnum
114-
115- Source language of the function code
116-
117- ### Allowed Values
118-
119- * ` javascript `
120- * ` typescript `
38+ ## Boundary
12139
40+ - ** Artifact (this schema):** compiled environment metadata plus
12241
123- ---
42+ provenance. Immutable, content-addressable via ` commitId ` and
12443
125- ## EnvironmentArtifactHashAlgorithmEnum
44+ ` checksum ` .
12645
127- Hash algorithm used for the artifact checksum
46+ - ** Deployment Config (NOT in this schema): ** business DB coordinates,
12847
129- ### Allowed Values
48+ credentials, environment identity, secrets. Injected at runtime.
13049
131- * ` sha256 `
132- * ` sha384 `
133- * ` sha512 `
50+ See ` content/docs/concepts/north-star.mdx ` §6.3 for the
13451
52+ runtime-inputs boundary.
13553
136- ---
54+ ## History ( # 4740 )
13755
138- ## EnvironmentArtifactManifest
56+ This file previously documented a richer "v0" envelope — a
13957
140- Plugin/driver requirements baked into the artifact
58+ ` \{ algorithm, value \} ` checksum object, a category-bag ` metadata ` , inlined
14159
142- ### Properties
60+ ` functions[] ` , a required plugin/driver ` manifest ` , and a reserved
14361
144- | Property | Type | Required | Description |
145- | :--- | :--- | :--- | :--- |
146- | ** plugins** | ` { id: string; version?: string }[] ` | optional | |
147- | ** drivers** | ` { id: string; version?: string }[] ` | optional | |
148- | ** engine** | ` { objectstack: string } ` | optional | |
62+ ` payloadRef ` indirection — that NO producer or consumer ever implemented:
14963
64+ ` objectstack compile ` ships function code as standalone runtime modules
15065
151- ---
66+ referenced from the compiled definition, and the control plane has always
15267
153- ## EnvironmentArtifactMetadata
154-
155- Compiled environment metadata grouped by category
156-
157- ### Properties
158-
159- | Property | Type | Required | Description |
160- | :--- | :--- | :--- | :--- |
161- | ** objects** | ` any[] ` | optional | |
162- | ** fields** | ` any[] ` | optional | |
163- | ** views** | ` any[] ` | optional | |
164- | ** apps** | ` any[] ` | optional | |
165- | ** pages** | ` any[] ` | optional | |
166- | ** dashboards** | ` any[] ` | optional | |
167- | ** reports** | ` any[] ` | optional | |
168- | ** flows** | ` any[] ` | optional | |
169- | ** workflows** | ` any[] ` | optional | |
170- | ** triggers** | ` any[] ` | optional | |
171- | ** agents** | ` any[] ` | optional | |
172- | ** tools** | ` any[] ` | optional | |
173- | ** skills** | ` any[] ` | optional | |
174- | ** permissions** | ` any[] ` | optional | |
175- | ** permissionSets** | ` any[] ` | optional | |
176- | ** positions** | ` any[] ` | optional | |
177- | ** translations** | ` any[] ` | optional | |
178- | ** datasources** | ` any[] ` | optional | |
179- | ** datasets** | ` any[] ` | optional | |
180- | ** actions** | ` any[] ` | optional | |
181- | ** apis** | ` any[] ` | optional | |
68+ served the wire shape below (string SHA-256 checksum, ` metadata ` = the
18269
70+ compiled definition). The declaration converged to the live wire shape;
18371
184- ---
72+ the never-implemented keys are tombstoned below (ADR-0049
18573
186- ## EnvironmentArtifactPayloadRef
74+ enforce-or-remove: declared = enforced, or absent).
18775
188- Out-of-band payload reference (reserved for future use)
76+ <Callout type = " info"
77+ ** Source:** ` packages/spec/src/system/environment-artifact.zod.ts `
78+ </Callout >
18979
190- ### Properties
80+ ## TypeScript Usage
19181
192- | Property | Type | Required | Description |
193- | :--- | :--- | :--- | :--- |
194- | ** url** | ` string ` | ✅ | Signed URL pointing at the artifact payload |
195- | ** expiresAt** | ` string ` | optional | ISO-8601 expiry timestamp |
196- | ** checksum** | ` { algorithm: Enum<'sha256' \| 'sha384' \| 'sha512'>; value: string } ` | ✅ | Checksum of the referenced payload |
82+ ``` typescript
83+ import { Sha256DigestSchema } from ' @objectstack/spec/system'
84+ import type { Sha256Digest } from ' @objectstack/spec/system'
19785
86+ // Validate data
87+ const = Sha256DigestSchema .parse (data );
88+ ```
19889
19990---
20091
201- ## EnvironmentArtifactRequirement
202-
203- A plugin or driver dependency declaration
204-
205- ### Properties
206-
207- | Property | Type | Required | Description |
208- | :--- | :--- | :--- | :--- |
209- | ** id** | ` string ` | ✅ | Plugin/driver package id |
210- | ** version** | ` string ` | optional | SemVer range required by the environment |
211-
21292
21393---
21494
0 commit comments