1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
//! Vendor `application/vnd.pmcp.*` media-type constants (RESEARCH Pattern 3)
//! for every OCI layer this crate packs, plus the standard OCI empty-config
//! blob constants (OCI 1.1's non-null-config-descriptor requirement).
//!
//! # Layer inventory
//!
//! - `ServerPackage` decomposes into content-addressed layers. Exactly ONE
//! binary layer is always present, and it is one of two mutually exclusive
//! shapes: the embedded bootstrap binary ([`MT_SERVER_BOOTSTRAP`] — supplied
//! as raw bytes, never a struct field) OR a binary REFERENCE
//! ([`MT_SERVER_BINARY_REF`] — a small JSON layer naming the digest and
//! media type of a binary the target environment resolves for itself; a
//! pure-config Shape A server carries this one and no bytes at all).
//! Alongside it are the four typed sections — the deploy descriptor
//! ([`MT_SERVER_DEPLOY_DESCRIPTOR`]), the cedar policy set
//! ([`MT_SERVER_CEDAR_POLICY_SET`]), tool metadata
//! ([`MT_SERVER_TOOL_METADATA`]), and the declared config slots
//! ([`MT_SERVER_CONFIG_SLOTS`]) — plus the `name`/`version`/top-level
//! `digest` "envelope" layer ([`MT_SERVER_ENVELOPE`]) so every remaining
//! field round-trips losslessly by plain serialize/deserialize.
//! - Three OPTIONAL vendor-content layers may follow: the author's verbatim
//! server config file ([`MT_SERVER_CONFIG`]), for an OpenAPI-backed server
//! its spec file ([`MT_SERVER_OPENAPI_SPEC`]), and a platform-issued
//! attestation ([`MT_ATTESTATION`]). All three carry raw bytes (never
//! re-derived from a parsed struct); the two file layers record the
//! original file name in their descriptor's
//! `org.opencontainers.image.title` annotation, and the attestation records
//! its subject/issuer/payload-type in its own descriptor's annotations. Any
//! of them may be absent, and absence is exactly the layer NOT being in the
//! manifest — there is no absence marker (D-14). An absent
//! [`MT_SERVER_OPENAPI_SPEC`] layer is the author's declaration of a
//! curated-only server, mirroring `pmcp-openapi-server`'s
//! `--spec: Option<PathBuf>`, never a silent drop of a spec that was
//! supplied; an absent [`MT_ATTESTATION`] layer means the package is simply
//! unattested.
//!
//! An attested package carries TWO digests, and that is by design (D-01):
//! the attestation names the UNATTESTED manifest digest as its subject,
//! while the package that carries the attestation necessarily hashes to
//! something else — the attestation layer and its annotations are inside
//! the manifest the digest covers. An attested package's own digest can
//! therefore never equal the subject it names.
//! - Layers are located at unpack time by MEDIA TYPE, never by position — the
//! optional layers make any positional contract false.
//! - `AgentPackage` and `WorkflowManifest` each pack as STRICTLY ONE JSON layer
//! ([`MT_AGENT_CONFIG`]/[`MT_WORKFLOW_MANIFEST`]) — the whole struct
//! serialized once; no decomposition needed since (unlike `ServerPackage`)
//! they don't carry a large binary blob that must live in its own layer.
//! Neither may carry an attestation (D-08), so for both of them the single
//! layer is the entire inventory and an extra layer is a malformed layout.
//! - `TeamPackage` packs as one [`MT_TEAM_CONFIG`] JSON layer — same shape,
//! same reason — PLUS an OPTIONAL [`MT_ATTESTATION`] layer, because a team
//! is one of the two kinds attestation carriage covers (D-08). A team layout
//! therefore holds one or two layers and nothing else. See the cross-kind
//! bullet below for the rule about what an attestation layer may and may not
//! be read to imply.
//! - [`MT_ATTESTATION`] is this file's ONLY layer media type not owned by a
//! single package kind. It may appear on a server package (`pack_server`)
//! or on a team package (`pack_team`, per D-08), and on neither an agent
//! nor a workflow — an agent that needs an attestation is wrapped as a team
//! of one. Package kind is read from the manifest's `artifactType` plus the
//! typed package layer, NEVER from this layer's presence or spelling. See
//! the constant's own rustdoc for the four reasons the spelling is
//! kind-neutral.
//!
//! Every layer's `Descriptor` uses [`MediaType::Other`] via [`vendor_media_type`]
//! (RESEARCH Pattern 3) — never a hand-rolled parallel media-type enum.
use ;
use FromStr;
// ---------------------------------------------------------------------
// ServerPackage layers
// ---------------------------------------------------------------------
/// The compiled bootstrap Lambda binary — supplied to `pack_server` as raw
/// `&[u8]`, never inlined on `ServerPackage` (cross-AI review: binary
/// payloads are OCI layers, not typed-struct fields).
pub const MT_SERVER_BOOTSTRAP: &str = "application/vnd.pmcp.mcp-server.bootstrap.v1+binary";
/// The `name`/`version`/top-level `digest`/`binary_ref` fields not covered by
/// any of the other typed `ServerPackage` sections.
pub const MT_SERVER_ENVELOPE: &str = "application/vnd.pmcp.mcp-server.envelope.v1+json";
/// The typed equivalent of a `.pmcp/deploy.toml` (`ServerPackage.deploy`).
pub const MT_SERVER_DEPLOY_DESCRIPTOR: &str =
"application/vnd.pmcp.mcp-server.deploy-descriptor.v1+json";
/// The server's cedar-policy set (`ServerPackage.policies`).
pub const MT_SERVER_CEDAR_POLICY_SET: &str =
"application/vnd.pmcp.mcp-server.cedar-policy-set.v1+json";
/// The server's tool/connector metadata (`ServerPackage.tools`).
pub const MT_SERVER_TOOL_METADATA: &str = "application/vnd.pmcp.mcp-server.tool-metadata.v1+json";
/// The server's declared config slots (`ServerPackage.config_slots`).
pub const MT_SERVER_CONFIG_SLOTS: &str = "application/vnd.pmcp.mcp-server.config-slots.v1+json";
/// The author's server config file (`config.toml`), carried VERBATIM as raw
/// bytes. Generic across all three Shape A pure-config siblings (SQL,
/// workbook, OpenAPI) — the config's *dialect* is the server binary's
/// concern, not the package format's, so there is one media type rather than
/// one per kind. The original file name travels in the layer descriptor's
/// `org.opencontainers.image.title` annotation.
pub const MT_SERVER_CONFIG: &str = "application/vnd.pmcp.mcp-server.config.v1+toml";
/// An OpenAPI-backed server's spec file, carried VERBATIM as raw bytes.
/// Unlike [`MT_SERVER_CONFIG`] this one IS per-kind: only an OpenAPI server
/// has a spec, and its bytes are the spec document exactly as the author
/// wrote it (JSON or YAML — the extension travels in the descriptor's
/// `org.opencontainers.image.title` annotation).
pub const MT_SERVER_OPENAPI_SPEC: &str = "application/vnd.pmcp.mcp-server.openapi-spec.v1";
/// A REFERENCE to a server binary the package does not embed: the digest and
/// media type of a blob the *target environment* resolves for itself. The
/// mutually-exclusive counterpart of [`MT_SERVER_BOOTSTRAP`] — a package
/// carries exactly one of the two, never both and never neither. The payload
/// is a canonical-JSON `BinaryRef`.
pub const MT_SERVER_BINARY_REF: &str = "application/vnd.pmcp.mcp-server.binary-ref.v1+json";
// ---------------------------------------------------------------------
// AgentPackage / TeamPackage / WorkflowManifest — one layer each
// ---------------------------------------------------------------------
/// The whole `AgentPackage` struct, serialized as a single JSON layer.
pub const MT_AGENT_CONFIG: &str = "application/vnd.pmcp.agent.config.v1+json";
/// The whole `TeamPackage` struct, serialized as a single JSON layer.
pub const MT_TEAM_CONFIG: &str = "application/vnd.pmcp.team.config.v1+json";
/// The whole `WorkflowManifest` struct, serialized as a single JSON layer.
pub const MT_WORKFLOW_MANIFEST: &str = "application/vnd.pmcp.workflow.manifest.v1+json";
// ---------------------------------------------------------------------
// Cross-kind layers — the media types NOT owned by exactly one package kind
// ---------------------------------------------------------------------
/// A platform-issued attestation ABOUT a package, carried as an OPAQUE layer.
///
/// The bytes are written and read back VERBATIM. This crate never
/// deserializes, parses, sniffs or otherwise interprets them: the attestation
/// format is owned by the issuing platform, not by this crate. Everything this
/// crate reads about an attestation comes from the layer DESCRIPTOR's
/// annotations — [`ANNOTATION_ATTESTATION_SUBJECT`],
/// [`ANNOTATION_ATTESTATION_ISSUER`] and
/// [`ANNOTATION_ATTESTATION_PAYLOAD_TYPE`] — which is what makes "never
/// interprets the payload" literally true while still leaving something to
/// compare.
///
/// The string carries NO format suffix, following
/// [`MT_SERVER_OPENAPI_SPEC`] rather than [`MT_SERVER_CONFIG`]'s `+toml`
/// (D-05): the attestation format is platform-owned and expected to churn, and
/// pinning a format into the layer-index key would turn a format change into a
/// media-type change — a wire break for every already-published CLI.
///
/// # Why the spelling is KIND-NEUTRAL
///
/// 1. **Two carrier kinds exist.** Attestation carriage lands on the server
/// packer AND the team packer (D-08). A media type namespaced to one
/// package kind would make a team package carry a layer whose type names a
/// different kind — a claim that is simply false on disk. The kind
/// qualifier was already wrong at the moment it was written.
/// 2. **Kind-specificity elsewhere in this file tracks a kind-specific
/// PAYLOAD.** [`MT_TEAM_CONFIG`]'s bytes ARE a `TeamPackage`;
/// [`MT_SERVER_ENVELOPE`]'s bytes ARE server envelope fields. An
/// attestation payload is platform-owned opaque bytes whose shape does not
/// vary with the carrying kind, so a kind qualifier here would be false
/// precision rather than the existing convention.
/// 3. **D-05's own reasoning generalizes.** A format suffix was omitted so a
/// format change would not become a media-type change, and a media-type
/// change is a wire break for every already-published CLI. A kind qualifier
/// has the identical failure mode one axis over: adding the second carrier
/// kind would force either a second constant or a lie. One neutral spelling
/// avoids both.
/// 4. **One media type is one mechanism** (D-08: "one mechanism, not two").
/// The duplicate-media-type rejection on the read side, the attestation
/// read helper and the annotated-layer write call site are shared verbatim
/// by the server and team paths with no kind dispatch. Two constants would
/// require a kind-keyed lookup at every read site.
///
/// # This is NOT a package-kind signal
///
/// Package kind is determined by the manifest's `artifactType`
/// ([`ARTIFACT_TYPE_SERVER`] / [`ARTIFACT_TYPE_TEAM`] / [`ARTIFACT_TYPE_AGENT`]
/// / [`ARTIFACT_TYPE_WORKFLOW`]) together with which typed package layer is
/// present. Nothing may infer a package's kind from the presence, absence or
/// spelling of this layer.
///
/// # Rejected alternative
///
/// A PER-KIND PAIR — one attestation media type per carrying package kind,
/// sharing a single annotation vocabulary — was considered and rejected. It
/// buys nothing a reader cannot already get from `artifactType`, while costing
/// a kind-keyed lookup on every read path. (The rejected spellings are
/// deliberately not written out here: two acceptance criteria in this phase
/// negative-grep the source tree for them, and naming them in a comment would
/// make those guards self-invalidating.)
pub const MT_ATTESTATION: &str = "application/vnd.pmcp.attestation.v1";
/// Layer-descriptor annotation key naming the package an attestation is ABOUT.
///
/// The value is the `sha256:<hex>` manifest digest of the **UNATTESTED**
/// package — explicitly NOT the digest of the package that carries this layer.
/// Those two digests necessarily differ: the attestation layer lives inside
/// the manifest whose canonical bytes the carrying package's digest covers
/// (D-01). An attested package's own digest can therefore never equal the
/// subject it names, and that is by design.
///
/// # Why reverse-DNS
///
/// The OCI image-spec annotations document says custom annotation keys SHOULD
/// use reverse domain notation, and reserves the `org.opencontainers`
/// namespace for the spec itself. `vnd.pmcp` is a MEDIA-TYPE prefix, not a
/// domain, so it is the wrong shape for an annotation key. There is no
/// in-repo precedent to follow: this crate's only annotation key today is
/// `oci_spec`'s re-exported `org.opencontainers.image.title`.
pub const ANNOTATION_ATTESTATION_SUBJECT: &str = "run.pmcp.attestation.subject";
/// Layer-descriptor annotation key naming the issuer of an attestation.
///
/// Reverse-DNS for the same reason as [`ANNOTATION_ATTESTATION_SUBJECT`]. The
/// value is issuer-supplied and arrives from outside this repo; this crate
/// carries it and never validates it.
pub const ANNOTATION_ATTESTATION_ISSUER: &str = "run.pmcp.attestation.issuer";
/// Layer-descriptor annotation key naming the attestation payload's OWN media
/// type (e.g. a report-schema JSON document, or a signed envelope).
///
/// Reverse-DNS for the same reason as [`ANNOTATION_ATTESTATION_SUBJECT`].
/// Recording the payload's format HERE rather than in [`MT_ATTESTATION`] is
/// what lets the layer media type stay suffix-free while the format churns.
pub const ANNOTATION_ATTESTATION_PAYLOAD_TYPE: &str = "run.pmcp.attestation.payload-type";
// ---------------------------------------------------------------------
// artifactType per package kind (OCI 1.1 top-level manifest field)
// ---------------------------------------------------------------------
/// `artifactType` for an `mcp-server` package's `ImageManifest`.
pub const ARTIFACT_TYPE_SERVER: &str = "application/vnd.pmcp.mcp-server.v1";
/// `artifactType` for an `agent` package's `ImageManifest`.
pub const ARTIFACT_TYPE_AGENT: &str = "application/vnd.pmcp.agent.v1";
/// `artifactType` for a `team` package's `ImageManifest`.
pub const ARTIFACT_TYPE_TEAM: &str = "application/vnd.pmcp.team.v1";
/// `artifactType` for a `workflow` package's `ImageManifest`.
pub const ARTIFACT_TYPE_WORKFLOW: &str = "application/vnd.pmcp.workflow.v1";
// ---------------------------------------------------------------------
// Standard OCI empty-config blob (OCI 1.1 non-null config descriptor)
// ---------------------------------------------------------------------
/// Standard OCI 1.1 empty-config media type. Registries/validators (ECR)
/// require a non-null config descriptor even for artifact manifests that
/// have no meaningful "config" of their own.
pub const MT_EMPTY_CONFIG: &str = "application/vnd.oci.empty.v1+json";
/// The empty-config blob's exact content — the most minimal valid JSON
/// object.
pub const EMPTY_CONFIG_BLOB: & = b"{}";
/// `sha256:<hex>` of [`EMPTY_CONFIG_BLOB`]. Guarded against drift by the
/// `empty_config_digest_matches_hash_of_empty_json_blob` test below — this
/// constant can never silently diverge from the actual hash of `{}`.
pub const EMPTY_CONFIG_DIGEST: &str =
"sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a";
/// Byte length of [`EMPTY_CONFIG_BLOB`].
pub const EMPTY_CONFIG_SIZE: u64 = 2;
/// Map a vendor media-type string constant into an `oci_spec::image::MediaType`.
/// `MediaType::from(&str)` already routes unrecognized strings to
/// `MediaType::Other` (RESEARCH Pattern 3) — this helper just documents the
/// call site's intent.
/// Build the standard, shared empty-config `Descriptor` — non-null config,
/// required by ECR/OCI 1.1-conformant registries and validators. Callers
/// that actually WRITE the config blob to a layout should prefer
/// `OciLayout::write_blob(MediaType::from(MT_EMPTY_CONFIG), EMPTY_CONFIG_BLOB)`
/// (which persists the bytes AND returns an identical `Descriptor`, since
/// both hash the same fixed bytes); this function exists for callers that
/// only need the descriptor shape (e.g. tests, or a caller building a
/// manifest that references an empty-config blob written elsewhere).