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
//! Local OCI Image Layout pack/unpack (the titular scope): serialize
//! each of the four package types into an OCI Image Layout on disk with
//! custom `application/vnd.pmcp.*` media types per layer, content-address
//! each blob by sha256, and verify every blob's digest before deserializing
//!. Pure local disk I/O — no network, no `oci-client` — so
//! the registry push/pull can consume these exact `oci_spec::image`
//! types with zero translation.
//!
//! - [`config_validation`] — pack-time validation of a config server's
//! `[[config_slots]]` declaration block against the package's slot list.
//! - [`media_types`] — vendor media-type constants per layer + the standard
//! OCI empty-config blob constants.
//! - [`layout`] — [`OciLayout`], the local Image Layout directory
//! reader/writer (`oci-layout` + `index.json` + `blobs/sha256/<hex>`).
//! - [`pack`] — `pack_server`/`pack_agent`/`pack_team`/`pack_workflow`.
//! - [`unpack`] — `unpack_server`/`unpack_agent`/`unpack_team`/`unpack_workflow`.
//!
//! # Artifact tar framing
//!
//! A package has two on-disk forms: the layout DIRECTORY described above, which
//! is the identity-bearing working form, and an uncompressed `.tar` of that
//! directory, which is the movable carriage envelope. This section is the
//! NORMATIVE rule for that tar.
//!
//! It is addressed to TWO implementers — this SDK and the pmcp.run platform —
//! and it is not a description of what any one of them happens to do today. The
//! platform PRODUCES the tar that `cargo pmcp package pull` consumes, and the
//! SDK produces the tar `cargo pmcp package save` emits, so this is the one
//! artifact shape the two sides must agree on byte-for-byte. Where the
//! platform's own handoff document (`docs/design/package-portability-pmcp-run-handoff.md`
//! §5.1, *"a tar of `index.json` + `blobs/`"*) is silent, this section states an
//! answer and labels it as an SDK assumption awaiting confirmation rather than
//! leaving the next implementer to guess.
//!
//! ## Entry inventory
//!
//! Exactly three entry shapes are legal, all at the archive ROOT:
//!
//! 1. the layout marker file, `oci-layout`;
//! 2. `index.json`;
//! 3. `blobs/sha256/<hex>`, where `<hex>` is exactly 64 lowercase hexadecimal
//! characters.
//!
//! Nothing else. An unrecognized path shape is a REFUSAL, never an entry to
//! skip silently. Reason: a reader that skips what it does not recognize has an
//! output that is not a function of its input, and gives a producer a channel
//! for bytes no reader accounts for.
//!
//! ## No wrapper directory
//!
//! `index.json` is at the archive root. A leading component — a package name, a
//! `./` prefix, an `oci/` folder — is a refusal. Reason: the reader must be able
//! to identify an entry from its path alone, without first guessing which prefix
//! a producer chose to wrap the layout in.
//!
//! ## No absolute paths, no parent-directory components
//!
//! An entry path that is absolute, or that carries a `..` component, is a
//! refusal. This is the zip-slip defence, stated at the CONTRACT level rather
//! than left to one implementation: untarring attacker-controlled bytes is a
//! path-traversal surface, and an artifact arrives from a network the handoff
//! itself says is never trusted.
//!
//! The SDK's own reader goes further, and any implementer is encouraged to do
//! the same: it never writes an archive-supplied path at all. Entries are parsed
//! into memory, gated, and then written through [`OciLayout::write_blob`], whose
//! destination is derived from a digest THIS code computed over bytes it is
//! holding. An archive path is a lookup key during validation and never a
//! filesystem destination, which makes traversal unrepresentable rather than
//! filtered — and a filter is only ever the list of traversals someone thought
//! of. That stronger construction is a recommendation; the path prohibition
//! above stays NORMATIVE for implementers who do join archive paths onto disk.
//!
//! ## Regular files only
//!
//! Every entry's type flag must be regular file. Symlinks, hardlinks, directory
//! entries, fifos and device entries are all refusals. Reason: a symlink or
//! hardlink is an escape primitive — a request to create a named object pointing
//! somewhere the archive does not contain — and a directory entry is
//! unnecessary, because the three legal paths above already imply the only
//! structure a layout has.
//!
//! ## No duplicate paths
//!
//! A path appearing more than once is a refusal, never last-wins. Reason: two
//! entries claiming one path is an authoring bug or an attack, and last-wins
//! merging lets a hostile writer append a benign-looking entry that shadows a
//! real one after the real one has already been inspected.
//!
//! ## Uncompressed
//!
//! The artifact is a PLAIN tar. It is not gzipped, zstd-compressed or otherwise
//! wrapped. Reason: §5.1 names no compression, and adding one buys nothing while
//! creating a decompression-bomb surface over untrusted bytes.
//!
//! **This is an SDK ASSUMPTION awaiting platform confirmation, not a settled
//! fact about the platform.** It is written as an explicit open question in the
//! vendored SDL at `contracts/pmcp-run/portability-v1.graphql` (on
//! `getPackageArtifact`'s `downloadUrl` field), which records it as the single
//! highest-value thing on that page to confirm: if the platform gzips, `pull`
//! refuses every real artifact AND `save` produces a shape the platform cannot
//! read.
//!
//! ## Reproducible headers
//!
//! Entry headers are NORMALIZED and entry ORDER is fixed.
//!
//! - Normalized headers: mtime `0`, uid `0`, gid `0`, empty user name, empty
//! group name, a fixed regular-file mode (`0o644`), and a `ustar` header so no
//! PAX (`x`/`g`) or GNU long-name (`L`/`K`) extension record is emitted.
//! - Fixed order: the layout marker first, then `index.json`, then every blob
//! sorted lexicographically by its hex digest. Directory-iteration order is
//! not defined by any filesystem, so a writer must sort rather than emit what
//! `read_dir` handed it.
//!
//! Consequence, which is the reason the rule exists: packing the same layout
//! twice yields BYTE-IDENTICAL archives. The artifact can therefore be compared,
//! cached and digested by transport machinery without spurious differences, and
//! a fixture can pin a writer's output exactly.
//!
//! ## The layout marker
//!
//! §5.1 is silent about `oci-layout`, so the rule states it. MEASURED fact that
//! makes the answer safe: NOTHING in this crate ever READS the marker file — a
//! grep of `crates/pmcp-package/src/` finds only the write in
//! [`layout::OciLayout::create`], doc comments, and one `#[cfg(test)]`
//! read-back.
//!
//! Therefore:
//!
//! - EMIT it on write. A plain `tar -xf` of the artifact then yields a valid OCI
//! image layout for a human debugging by hand.
//! - ACCEPT it on read, IGNORE its content, and always REGENERATE it through
//! [`layout::OciLayout::create`].
//! - Do NOT REQUIRE it on read. An implementation that omits the marker still
//! interoperates, which is what keeps this rule from breaking a producer that
//! read §5.1 literally.
//!
//! **Also an SDK assumption awaiting platform confirmation:** whether the
//! platform's own reader TOLERATES the extra marker entry alongside `index.json`
//! and `blobs/`. If its untar is strict about its entry inventory, an extra
//! entry is a refusal. That question is likewise written into
//! `contracts/pmcp-run/portability-v1.graphql`.
//!
//! ## Fixture provenance — the rule that makes this enforceable
//!
//! The worked examples of every rule above live at
//! `crates/pmcp-package/tests/golden_fixtures/artifact_tar_v1/`: one conformant
//! tar (shipped as a pair with `conformant.layout/`, the unpacked directory it
//! was authored from) and one hostile sibling per violation.
//!
//! **Those fixtures are CHECKED-IN BYTES and are NEVER REGENERATED FROM THE
//! WRITER UNDER TEST.** A fixture produced by the code it tests is a tautology:
//! it agrees with that code by construction and therefore cannot detect the
//! drift it exists to detect. This is the provenance property the platform and
//! the SDK adopted jointly (handoff §3.2) in place of the earlier question of
//! where the corpus should live.
//!
//! ## The boundary this section deliberately does not cross
//!
//! This crate holds the RULE. The CODEC that implements it —
//! `cargo-pmcp/src/commands/package/artifact.rs`, the only module in the
//! repository that names `tar::` — lives in `cargo-pmcp`.
//!
//! That split is deliberate and must not be "tidied up" by moving the reader in.
//! It exists so that no archive dependency enters this crate's resolved
//! dependency graph, which is machine-enforced by the crate-local
//! `[bans].allow` allowlist in `crates/pmcp-package/deny.toml` (Phase 122). The
//! friction of that gate is the feature: adding `tar` here would be a
//! supply-chain decision disguised as a refactor.
pub use ;
pub use OciLayout;
pub use ;
pub use ;
use crate;
use crate;
/// The three single-layer package kinds (agent/team/workflow) share ONE
/// pack/unpack path: serialize to a single canonical-JSON config layer under a
/// vendor media type, wrapped in a manifest carrying the kind's `artifactType`.
/// This trait is the single source of truth binding each kind to its
/// media-type / artifact-type / layer-name constants, so
/// [`pack::pack_single_layer`] and [`unpack::unpack_single_layer`] are fully
/// generic over it (no per-kind copy-paste). `ServerPackage` is deliberately
/// NOT a member — it is multi-layer (bootstrap + envelope + 4 typed sections)
/// and keeps its own bespoke pack/unpack path.
pub