# v0.13.0 Package-Status Parity Audit

Companion to [`docs/PACKAGE_STATUS.md`](./PACKAGE_STATUS.md). This document
records the per-export parity audit used to decide posture for deprecated
and archived packages at v0.13.0. It is hand-maintained; the generator at
`scripts/generate-surface-status.mjs` does not produce it.

**Scope:** v0.13.0 only. The table is frozen at v0.13.0 tag time and
revisited at the next release. If any `Equivalent?` cell moves to `yes`
before the next release opens, it is a pre-condition for retirement.

---

## Why this audit exists

The v0.13.0 release keeps `@peac/disc@0.13.0` published as a one-release
deprecated compatibility alias because `@peac/cli` (published) and
`apps/api` depend on it via `workspace:*`. Removing `@peac/disc` from
`scripts/publish-manifest.json` while published packages depend on it
would produce a `@peac/cli@0.13.0` tarball with an unsatisfiable
`@peac/disc@0.13.0` dependency: release-breaking. Installability beats
surface-count optics.

Before a later release retires `@peac/disc` from the workspace and
publish manifest, every export currently used by internal consumers MUST
have a verified equivalent in `@peac/policy-kit` (or another canonical
public surface). This audit is the migration checklist.

---

## `@peac/disc` → canonical replacement parity table

Each export of `@peac/disc` (see `packages/discovery/src/index.ts`) is
audited against its canonical replacement. `Equivalent?` is `yes` only
if the replacement is byte-identical in behavior and is already on a
public surface; `partial` means the replacement exists but differs in
semantics a consumer might care about; `no` means migration requires
net new work before `@peac/disc` can be retired.

| `@peac/disc` export                                  | Kind     | Current behavior                                                                                                                                                                                                                                   | Canonical replacement                                                                                                                      | Equivalent? | Action before retirement                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ---------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `parse(input: string, opts?)`                        | function | Tolerant `peac.txt` policy-document parser. Strips legacy `verify:` / `public_keys:` / `jwks:` lines, returns `ParseResult`, emits structured `PEAC_LEGACY_PEAC_TXT_KEY_FIELD` `DeprecationWarning`. Wraps `@peac/policy-kit.parsePolicyDocument`. | `@peac/policy-kit.parsePolicyDocument` + thin tolerant wrapper maintained in `@peac/policy-kit` or inlined in consumer call sites          | partial     | Move the tolerant-stripping behavior (legacy `verify` / `public_keys` / `jwks` line handling + structured DeprecationWarning emission) into `@peac/policy-kit` as `parsePolicyDocumentTolerant` (or similar) before removing `@peac/disc`. Consumers: `packages/cli/src/lib/conformance/validators.ts` calls `parseDiscovery` directly.                                                                                                                                                                      |
| `emit(doc: PolicyDocument): string`                  | function | Emits a `peac-policy/0.1` YAML document back from a parsed `PolicyDocument`.                                                                                                                                                                       | `@peac/policy-kit.serializePolicyYaml`                                                                                                     | partial     | Confirm `serializePolicyYaml` produces the same on-wire format as `@peac/disc.emit` for the `peac.txt` profile. If not, port `emit` to `@peac/policy-kit` under a stable name before retirement. No current internal consumer calls `emit`; keep as-is for external back-compat.                                                                                                                                                                                                                             |
| `validate(doc: unknown): boolean`                    | function | Runs `@peac/policy-kit.validatePolicy` against a candidate policy document and returns a boolean.                                                                                                                                                  | `@peac/policy-kit.validatePolicy`                                                                                                          | yes         | Migrate consumers to call `validatePolicy` directly. No API change required.                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `discover(options: DiscoverOptions)`                 | function | Remote fetch of `/.well-known/peac.txt` with SSRF-aware `fetch` injection, timeout (`DEFAULT_TIMEOUT_MS = 5000`), byte cap (`MAX_BYTES = 262144`), redirect policy, structured errors. Wraps `parse()` on success.                                 | **NO direct equivalent in `@peac/policy-kit`.** `@peac/policy-kit` has no remote-fetch surface; it only operates on already-fetched bytes. | **no**      | **Blocker for retirement.** Decide ONE of: (a) port `discover()` into `@peac/policy-kit` with the same SSRF-aware shape (preferred; keeps `@peac/policy-kit` pure by surface only: delegate fetch to a caller-supplied client); or (b) provide a thin shim elsewhere (e.g. `@peac/protocol`) that combines `ssrfSafeFetch` from `@peac/net-node` with `parsePolicyDocument`; or (c) keep `@peac/disc` published for longer . Consumers: `packages/cli/src/commands/discover.ts`, `apps/api/src/verifier.ts`. |
| `__resetLegacyWarningForTests`                       | function | Test hook that resets the one-shot legacy-field warning.                                                                                                                                                                                           | equivalent test hook wherever tolerant parse lives                                                                                         | partial     | Ship alongside whichever module owns the tolerant parse. Internal only (prefixed `__`).                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `__resetDiscDeprecationWarningForTests`              | function | Test hook that resets the `PEAC_DISC_DEPRECATED` warning.                                                                                                                                                                                          | N/A                                                                                                                                        | N/A         | Remove when `@peac/disc` retires; no replacement needed.                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `MAX_BYTES: 262144`                                  | constant | 256 KiB size cap for `peac.txt` fetch response, per `docs/specs/PEAC-TXT.md` §6.1.                                                                                                                                                                 | Port to `@peac/policy-kit` as `PEAC_TXT_MAX_BYTES`                                                                                         | no          | Add `PEAC_TXT_MAX_BYTES` constant to `@peac/policy-kit` before retirement. Normative value.                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `WELL_KNOWN_PATH: '/.well-known/peac.txt'`           | constant | RFC 8615 well-known path for the `peac.txt` surface.                                                                                                                                                                                               | Port to `@peac/policy-kit` as `PEAC_TXT_WELL_KNOWN_PATH`                                                                                   | no          | Add to `@peac/policy-kit` before retirement.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `DEFAULT_TIMEOUT_MS: 5000`                           | constant | Default fetch timeout for `discover()`.                                                                                                                                                                                                            | Move with `discover()` port                                                                                                                | no          | Folds into `discover()` migration decision above.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `ParseResult`, `ValidationOptions`, `PolicyDocument` | types    | Re-exports from `@peac/disc/types`; `PolicyDocument` is already the `@peac/policy-kit` shape.                                                                                                                                                      | `@peac/policy-kit` exports them directly                                                                                                   | yes         | No action. Consumers already can import from `@peac/policy-kit`.                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `PeacDiscovery`, `PublicKeyInfo`                     | types    | Legacy types retained for one minor to keep imports compiling. Already `@deprecated`. No normative meaning post-v0.12.14 (peac.txt is policy-document-only; key discovery flows via `peac-issuer.json` → `jwks_uri`).                              | None (types intentionally retired)                                                                                                         | yes         | Remove with `@peac/disc`. No port.                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `DiscoverFetch`, `DiscoverOptions`                   | types    | Shape of the fetch-injection API for `discover()`.                                                                                                                                                                                                 | Move with `discover()` port                                                                                                                | no          | Folds into `discover()` migration decision.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

### Current compatibility coverage

The following items must be true in the current repo before `@peac/disc` can be removed from the workspace and publish manifest:

1. **Port `discover()` (and the `MAX_BYTES` / `WELL_KNOWN_PATH` / `DEFAULT_TIMEOUT_MS` constants it relies on) to a canonical public surface.** Preferred home: `@peac/policy-kit` gets the constants + a fetch-injection-shaped `loadPolicyDocumentRemote(options)` that accepts a caller-supplied SSRF-aware fetch. Explicit note: `@peac/policy-kit` remains a pure parser package; remote fetch is done by the caller-supplied fetch, never by the package itself (consistent with the post-v0.12.14 no-network-in-parsers invariant).
2. **Port the tolerant-stripping behavior** of `parse()` (legacy `verify:` / `public_keys:` / `jwks:` line handling + `PEAC_LEGACY_PEAC_TXT_KEY_FIELD` structured DeprecationWarning) into `@peac/policy-kit` under a stable name (e.g. `parsePolicyDocumentTolerant`).
3. **Migrate active internal consumers:**
   - `packages/cli/src/commands/discover.ts` → `@peac/policy-kit.loadPolicyDocumentRemote` (or equivalent).
   - `packages/cli/src/lib/conformance/validators.ts` → `@peac/policy-kit.parsePolicyDocumentTolerant`.
   - `apps/api/src/verifier.ts` → either `@peac/policy-kit.loadPolicyDocumentRemote` or fold into the `/v1/verify` handler's existing issuer-config resolver (this migration may be coupled with the legacy `/verify` handler rewire).
4. **Confirm `validate()` consumers are migrated** to `@peac/policy-kit.validatePolicy` (minor; boolean signature).
5. **Run pack + install smoke** (`pnpm pack --filter @peac/cli`; `tar -xOf *.tgz package/package.json | jq .dependencies`) to confirm no published package depends on `@peac/disc` at retirement tag time.

If step 1 is not completed, `@peac/disc` must remain published as a compatibility alias for longer.

---

## `@peac/core` → canonical replacement parity (already archived)

| `@peac/core` export                              | Kind      | Replacement                                                  | Equivalent? | Status                                                                                                                                                                                                                       |
| ------------------------------------------------ | --------- | ------------------------------------------------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `verifyReceipt(jws, keys)`                       | function  | `@peac/protocol.verifyReceipt` (canonical JWKS-based verify) | yes         | Archived. `apps/api/src/verifier.ts` deleted; the legacy `POST /verify` route now delegates in-process to `/v1/verify` and stamps RFC 9745 / RFC 8594 / RFC 8288 headers. `@peac/core` removed from `apps/api/package.json`. |
| `canonicalPolicyHash`                            | function  | Canonical `computePolicyDigestJcs` from `@peac/protocol`     | yes         | Archived. No active consumer.                                                                                                                                                                                                |
| `VerifyKeySet`                                   | type      | Canonical key-set type from `@peac/protocol`                 | yes         | Archived. No active consumer.                                                                                                                                                                                                |
| Legacy `peac.receipt/0.9` signing / verify paths | functions | No current-wire replacement; archive is verify-only.         | N/A         | Archived under `archive/0.9.0-0.9.14/packages-core/`. Historical npm versions `<=0.9.14` remain installable for verify-only use; `@peac/core` is not published at v0.13.0 or later.                                          |

---

## `@peac/pref` → canonical replacement parity (already retired)

| `@peac/pref` export                                    | Kind     | Replacement                                                 | Equivalent? | Status                                          |
| ------------------------------------------------------ | -------- | ----------------------------------------------------------- | ----------- | ----------------------------------------------- |
| `resolveAIPref`, `parseContentUsage`, `resolveSignals` | function | `@peac/mappings-content-signals` (direct canonical path)    | yes         | Migrated (v0.12.14 converged; archived v0.13.0) |
| `PrefResolver`, `ResolveContext` types                 | types    | `@peac/mappings-content-signals` exports                    | yes         | Migrated                                        |
| `fetchRobots` (deprecated throwing stub)               | function | Caller-supplied fetch into `@peac/mappings-content-signals` | yes         | Retired (throwing stub removed at archive)      |

No further migration work required; all `@peac/pref` exports have canonical equivalents in `@peac/mappings-content-signals` as of v0.12.14 convergence.

---

## Change log for this audit

| Date       | Change                                                                                                                                                                                                                                                                                                                                                                  |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 2026-04-24 | Initial audit drafted. `@peac/disc` is a published deprecated compatibility alias; retirement requires the 5 current-compatibility items above to be satisfied. `@peac/core` archived (source moved to `archive/0.9.0-0.9.14/packages-core/`; legacy `/verify` handler rewired to delegate in-process to `/v1/verify`). `@peac/pref` migration complete as of v0.12.14. |
