# Packer Specs

This directory contains the normative packer specification set.

## Purpose

Specs define the official packer contract.

They exist to make behavior, constraints, interfaces, and artifact guarantees stable across implementation and review.

The current domain also has a bootstrap draft in [`../Prometeu Packer.md`](../Prometeu%20Packer.md).
That draft can be used as source material, but long-term normative content should be decomposed into focused specs here.

## Expected Format

The exact structure may vary by document, but a packer spec should usually contain:

1. Title
2. Status
3. Scope or Applies To
4. Purpose
5. Authority and Precedence
6. Normative Inputs
7. Core Rules
8. Non-Goals
9. Exit Criteria

Some specs may also include:

- artifact schemas,
- invariants,
- diagnostic contracts,
- examples,
- migration notes,
- explicit TODO sections for tracked unresolved items.

## Writing Rules

- Write in normative language.
- Integrate only decisions that have already been closed.
- Keep debate history and option analysis out of the spec body.
- Preserve clear boundaries between adjacent packer specs.
- Use TODO only for explicitly tracked unresolved items, not as a substitute for agenda work.

## Upstream Rule

Specs should normally be fed by:

1. agendas that frame the open topic,
2. decisions that close the architectural question,
3. pull-request plans that define propagation,
4. then spec integration.

If a spec edit would require guessing an unresolved design choice, stop and surface the missing decision first.

## Current Corpus

The current packer core corpus is:

1. [`1. Domain and Artifact Boundary Specification.md`](./1.%20Domain%20and%20Artifact%20Boundary%20Specification.md)
2. [`2. Workspace, Registry, and Asset Identity Specification.md`](./2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
3. [`3. Asset Declaration and Virtual Asset Contract Specification.md`](./3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
4. [`4. Build Artifacts and Deterministic Packing Specification.md`](./4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
5. [`5. Diagnostics, Operations, and Studio Integration Specification.md`](./5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
6. [`6. Versioning, Migration, and Trust Model Specification.md`](./6.%20Versioning,%20Migration,%20and%20Trust%20Model%20Specification.md)

## Reading Order

Recommended order:

1. domain and artifact boundary;
2. workspace and identity;
3. asset declaration;
4. build artifacts;
5. diagnostics and Studio operation model;
6. versioning and trust.