refactor: archive @peac/core and remove deprecated compatibility surfaces#702
Merged
refactor: archive @peac/core and remove deprecated compatibility surfaces#702
Conversation
Retire the ProofMethodSchema alias and the PROOF_METHODS constant. Transport-binding values (http-message-signature, dpop, mtls, jwk-thumbprint) are now inlined directly on AgentProofSchema.method. Trust-root proof models remain on ProofTypeSchema; transport-binding and trust-root stay separate. Source + tests: - packages/schema/src/agent-identity.ts: delete ProofMethodSchema, PROOF_METHODS, and the ProofMethod type. Inline the 4-value enum on AgentProofSchema.method. Runtime validation surface for AgentProof is unchanged (same accepted values, same rejection surface). - packages/schema/src/index.ts: remove the ProofMethodSchema schema export and the ProofMethod type export from the barrel. - packages/schema/src/actor-binding.ts: JSDoc rewritten to describe the transport-binding enum as inlined on AgentProofSchema.method and to record that transport-binding and trust-root taxonomies remain separate surfaces by design. - packages/schema/__tests__/agent-identity.test.ts: exercise the four values through AgentProofSchema.parse. Import list trimmed of removed symbols. - packages/schema/__tests__/actor-binding.test.ts: no-overlap assertion text references the inline method enum instead of the removed ProofMethodSchema export. - packages/schema/__tests__/proof-method-deprecation.test.ts: deleted; the deprecated surface it covered is gone. - tests/tooling/api-contract.test.ts: flip the deprecation-era assertion to a removal assertion (contract MUST NOT include ProofMethodSchema / PROOF_METHODS). - tests/tooling/__snapshots__/api-contract.test.ts.snap: drop the ProofMethod / PROOF_METHODS / ProofMethodSchema entries. Schema contract snapshot: - contracts/api/schema.json: regenerated via pnpm api-contract:extract. The diff is the three removed entries plus corresponding total-count decrements. - docs/releases/api-surface/schema.txt: exact 3-line removal (ProofMethod, ProofMethodSchema, PROOF_METHODS). Active-doc teaching updates: - docs/STABILITY-CONTRACT.md: ProofMethodSchema row flipped to Removed with the inline-enum migration note; table expanded to 4 columns with per-row status text. - docs/MIGRATION_CURRENT.md: new ProofMethodSchema removal section with per-call-site migration guidance (inline enum, derive type from schema, keep ProofTypeSchema separate). - docs/specs/AGENT-IDENTITY.md: AgentProof.method annotation shows the inlined enum instead of the removed ProofMethod type. - docs/specs/AGENT-IDENTITY-PROFILE.md: §1.1 / §1.2 / §3.4 / §9.1 rewritten to describe the method enum as inlined on AgentProofSchema.method and to state the decision to keep transport-binding and trust-root taxonomies separate. No wire format change. No kernel / crypto / protocol semantic change. The Wire 0.2 receipt shape and JWS envelope are untouched; only the Zod schema surface for AgentProof changes by inlining the same enum values it always accepted.
Snapshot-cleanup follow-on to the ProofMethodSchema removal. These
diffs are not caused by the schema change; they are a snapshot refresh
surfaced by the full `bash scripts/release/api-surface-lock.sh
--update` regeneration pass plus the archival of `@peac/sdk`.
Contents:
- contracts/api/{crypto,kernel,protocol}.json: benign extraction
timestamp bump (2026-04-22 -> 2026-04-24). Value and type export
lists unchanged for these three packages.
- docs/releases/api-surface/schema.txt: regenerated to current
@peac/schema .d.ts state. Picks up legitimate v0.12.x schema
surface additions that had drifted since the prior snapshot:
AttributionExtension / AttributionExtensionSchema,
AmountMinorStringSchema, COMPLIANCE_EXTENSION_KEY,
COMPLIANCE_STATUSES, ComplianceExtension / ComplianceStatus,
CONSENT_EXTENSION_KEY, CONSENT_STATUSES, ConsentExtension /
ConsentStatus, CONTENT_SIGNAL_SOURCES, getComplianceExtension,
getConsentExtension, getPrivacyExtension, getProvenanceExtension,
getPurposeExtension, getSafetyExtension, isValidAmountMinor, and
related exports. All already exported from @peac/schema source; the
snapshot was stale. The prior commit (ProofMethodSchema removal)
carried only the 3-line semantic removal; this commit carries the
snapshot refresh so the semantic commit stays clean for review.
- docs/releases/api-surface/kernel.txt: pick up legitimate v0.12.x
kernel surface additions that had drifted since the prior snapshot:
EXTENSION_BUDGET, EXTENSION_GROUPS, ExtensionGroupEntry,
PILLAR_VALUES, PROOF_TYPES, ProofTypeEntry, RECEIPT_TYPES,
ReceiptTypeEntry, TYPE_TO_EXTENSION_MAP, findExtensionGroup,
findProofType, findReceiptType, and related exports. All already
exported from @peac/kernel source; the snapshot was stale.
- docs/releases/api-surface/protocol.txt: similar snapshot refresh
for JWK / JWKS and related protocol exports that had drifted since
the prior snapshot.
- docs/releases/api-surface/sdk.txt: deleted. @peac/sdk source was
archived in prior releases; tracking the absent package produced a
"package not found" sentinel on regeneration. Historical snapshot
preserved in git history.
- scripts/release/api-surface-lock.sh: TRACKED_PACKAGES updated to
drop @peac/sdk with an inline comment pointing to archive/sdk-js/.
No source change. No behavior change. No wire format change.
A2A v0.3.0 compatibility was deprecated in v0.12.3 (upstream stabilization to A2A v1.0.0) with the removal target publicly stated as v0.13.0 in docs/STABILITY-CONTRACT.md. @peac/mappings-a2a now validates A2A v1.0.0 shapes only. Surfaces removed: - Agent Card top-level `url` field. The A2AAgentCard interface no longer declares `url`; cards without a valid `supportedInterfaces[0].url` are rejected by normalizeAgentCard (returns null) and by discoverAgentCard (skipped during validation). - `TASK_STATE_V03_TO_V1` map and the `normalizeTaskState` function that mapped kebab-case v0.3.0 states (`working`, `completed`, `input-required`, ...) to v1.0.0 prefixed SCREAMING_SNAKE_CASE (`TASK_STATE_WORKING`, `TASK_STATE_COMPLETED`, `TASK_STATE_INPUT_REQUIRED`, ...). Callers must supply v1.0.0 TaskState values directly. - `/.well-known/agent.json` legacy discovery fallback. Only the v1.0.0 canonical path `/.well-known/agent-card.json` is consulted. - `NormalizedAgentCard.version` discriminant (always v1.0.0 now; no longer useful). - Deprecation-warning plumbing (`warnV03Deprecated` internal state and `_resetDeprecationWarning` test hook). v0.3.0 inputs are rejected outright rather than normalized with a warning. Source + tests: - packages/mappings/a2a/src/types.ts: top-of-file docstring rewritten to v1.0.0 only with an explicit removal note; section heading "A2A Agent Card types (v0.3.0 + v1.0.0)" becomes "A2A Agent Card types (v1.0.0)"; `A2AAgentCard` loses its `url?` field and gains a doc note that `supportedInterfaces[0].url` is required; `TASK_STATE_V03_TO_V1` map deleted with an inline removal note. `A2A_MAX_CARRIER_SIZE = 65_536`, `A2A_V1_TASK_STATE`, `A2A_V1_MESSAGE_ROLE`, `A2APeacPayload`, and the carrier-payload and message-shape types are preserved. - packages/mappings/a2a/src/normalizers.ts: full rewrite. Keeps `isV1AgentCard`, `normalizeAgentCard`, `selectBestInterface`, and the `NormalizedAgentCard` type (minus the `version` field). normalizeAgentCard now returns null for any non-v1.0.0 shape instead of synthesizing a v0.3.0 fallback. - packages/mappings/a2a/src/discovery.ts: fetch path array reduced to `['/.well-known/agent-card.json']`; inline comment updated to "v1.0.0 validation; v0.3.0 rejected". - packages/mappings/a2a/src/attach.ts: docstring reframed to name the behavior as the A2A extension-URI metadata convention (inherited from v0.3.0 and carried forward in v1.0.0). Behavior is unchanged; only the citation text is updated. - packages/mappings/a2a/src/index.ts: barrel drops `TASK_STATE_V03_TO_V1`, `normalizeTaskState`, and `_resetDeprecationWarning` exports. Top-of-file docstring rewritten to v1.0.0 only. - packages/mappings/a2a/tests/normalizers.test.ts: rewritten. isV1AgentCard tests now cover the v1.0.0 positive path and three negative shapes (empty supportedInterfaces, missing supportedInterfaces, empty URL). normalizeAgentCard tests cover v1.0.0 positive cases, explicit v0.3.0 rejection, hybrid card precedence (v1.0.0 over legacy url), multiple-interface handling, and capability preservation. selectBestInterface tests unchanged. The deprecated normalizeTaskState describe block is gone; its coverage moved to explicit rejection assertions in normalizeAgentCard and to the source-level grep gate. - packages/mappings/a2a/tests/discovery.test.ts: VALID_AGENT_CARD, AGENT_CARD_NO_PEAC, and AGENT_CARD_WITH_PARAMS fixtures rewritten to the v1.0.0 supportedInterfaces shape. The "Falls back to /.well-known/agent.json" positive test is flipped to a "does NOT fall back" negative assertion proving the v0.3.0 legacy path is no longer consulted. Active-doc teaching updates: - docs/MIGRATION_CURRENT.md: new A2A v0.3.0 removal section. - docs/STABILITY-CONTRACT.md: A2A row flipped to Removed with stability and removed-in context. - docs/REFERENCE_ARCHITECTURES.md, docs/specs/A2A-RECEIPT-PROFILE.md, docs/specs/DISCOVERY-PROFILE.md, docs/specs/EVIDENCE-CARRIER-CONTRACT.md, docs/specs/INTEROP.md, integrator-kits/a2a/README.md, packages/mappings/a2a/README.md, AGENTS.md: tightened to v1.0.0-only references. No wire format change. No kernel / crypto / protocol semantic change.
Two small consistency fixes on top of the A2A v0.3.0 removal:
1. Add @peac/mappings-a2a to the API-surface tracking gate.
The A2A v0.3.0 removal deleted three public exports
(TASK_STATE_V03_TO_V1, normalizeTaskState, and
_resetDeprecationWarning) from a published package. Grep confirmed
zero in-repo callers, but because @peac/mappings-a2a is on npm
`latest`, external consumers deserve an explicit snapshot-tracked
contract.
- scripts/release/api-surface-lock.sh: add @peac/mappings-a2a to
TRACKED_PACKAGES with an inline note explaining why the package
was added alongside the v0.3.0 removal.
- docs/releases/api-surface/mappings-a2a.txt: new snapshot
(68 public exports). Confirmed absent: TASK_STATE_V03_TO_V1,
normalizeTaskState, _resetDeprecationWarning. Confirmed present:
normalizeAgentCard, isV1AgentCard, selectBestInterface,
A2A_MAX_CARRIER_SIZE.
- `bash scripts/release/api-surface-lock.sh` now PASSes nine
tracked packages (was eight).
2. Tighten runtime-vs-type wording on the Agent Card shape.
A2AAgentCard still declares a `[key: string]: unknown` index
signature, so TypeScript structurally accepts literals with a
stray `url: string` property. The v0.3.0 removal is enforced at
runtime by normalizeAgentCard (returns null) and discoverAgentCard
(skips invalid cards), not at the type level. The prior commit
message and JSDoc were ambiguous on this point.
- packages/mappings/a2a/src/types.ts: JSDoc rewritten to name the
rejection layer (runtime, not types) and the reason the index
signature stays (tolerate unknown incoming JSON fields).
- docs/MIGRATION_CURRENT.md: A2A v0.3.0 removal section rewritten
to say "rejected at runtime" instead of just "no longer
accepted," with an explicit note that the index signature
remains and type-level rejection is not claimed.
No source behavior change. No wire format change. Runtime rejection
behavior for v0.3.0 shapes is byte-stable with the prior commit; the
change is in how precisely the repo describes that rejection.
Rewire the legacy `POST /verify` route to delegate in-process to the canonical `POST /v1/verify` handler. Every alias response carries Deprecation (RFC 9745), Sunset: Sat, 01 Nov 2026 00:00:00 GMT (RFC 8594), and Link rel="deprecation" (RFC 8288) headers. The alias stays runtime-reachable through the advertised Sunset date. apps/api no longer depends on @peac/core. Delete the v0.9.x VerifierV13 implementation, its Hono and Express wrappers, and the ambient type shim. Drop the external marker for @peac/core from the tsup config. Archive packages/core/ to archive/0.9.0-0.9.14/packages-core/. @peac/core is not published at v0.13.0 or later; historical npm versions <=0.9.14 remain installable for verify-only use of historical peac.receipt/0.9 records. Activate the corresponding line in the release maintainer's post-release deprecate script. Drop @peac/core from tsconfig.base.json path mappings, from the publish manifest, and from the now-unused bench-verify and assert-core-exports helpers. Remove the legacy `/verify` stanza from the public OpenAPI contract; HOSTED_VERIFY_CONTRACT.md now documents the alias-only runtime behavior. Update MIGRATION, PACKAGE_STATUS, PACKAGE_STATUS_V0.13.0_PARITY, STABILITY-CONTRACT, COMPATIBILITY_MATRIX, DEPRECATION_POLICY, and SECURITY to describe present-state compatibility coverage. Add two regression tests: - apps/api/tests/legacy-verify-alias-headers.test.ts asserts all three headers are present on every alias response and absent on the canonical /v1/verify response. - apps/api/tests/legacy-verify-alias-pre-sunset.test.ts asserts status parity and response-shape parity between the alias and canonical paths and pins the Sunset header value. Migrate the nightly crypto smoke from the archived @peac/core primitives to the @peac/crypto public sign/verify round-trip. Refresh facts.json metrics to match the post-archive state (build_targets=99, test_files=310, tests=7672).
The new legacy-verify-alias test files used em dashes in their describe labels, which the repo code-punctuation rule forbids in TypeScript sources. Replace them with ASCII colons. Update scripts/pack-install-smoke.sh to import from the current @peac/schema public surface (ProofTypeSchema, AgentProofSchema with the inlined method enum, CommerceExtensionSchema). The old smoke imported ProofMethodSchema and PROOF_METHODS, which were removed in an earlier commit on this branch.
The schema expects a key_id string and rejects the earlier sketch that passed `type` and `value`. Use the real shape (method + key_id + dpop_proof) and drop a stale decision-record reference from the AgentProofSchema JSDoc.
@peac/crypto emits index.mjs (ESM) and index.cjs (CJS); the previous path referenced a non-existent index.js, so the migrated smoke would have crashed the first time the nightly workflow fired.
jithinraj
changed the title
Move the deprecation-header stamping + /v1/verify delegation into a single exported helper. Production routing (/verify and /api/v1/verify) and the two alias regression tests now go through the same code path, so header set, header values, and delegation target cannot drift between them. Behavior unchanged. Response bytes, header values, and route semantics are identical to the prior inline implementation.
jithinraj
force-pushed
the
fix/v0.13.0-scheduled-removals
branch
from
35eefed to
af59284
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Removes announced compatibility surfaces and archives
@peac/core. Adds regression tests that pin the legacyPOST /verifyalias to its advertised Sunset date and response-shape parity withPOST /v1/verify.Scope
Layer 1 schema, one Layer 4 mappings package, the reference verifier, and release / docs surfaces. No wire format change. No new signing envelope. No new public package. Runtime
POST /verifystays reachable as a deprecated compatibility alias.Changes
@peac/schema: removeProofMethodSchema; inline transport-binding values (http-message-signature,dpop,mtls,jwk-thumbprint) onAgentProofSchema.method.@peac/mappings-a2a: remove the A2A v0.3.0 compatibility surface. v1.0.0supportedInterfaces[]is required; top-levelurlcards, kebab-case TaskState values, and the legacy/.well-known/agent.jsondiscovery path are no longer accepted.apps/api: rewire the legacyPOST /verifyhandler to delegate in-process to the canonicalPOST /v1/verifyhandler. Every alias response stamps RFC 9745Deprecation: true, RFC 8594Sunset: Sat, 01 Nov 2026 00:00:00 GMT, and RFC 8288Link: <https://www.peacprotocol.org/docs/migration>; rel="deprecation".apps/api/src/{verifier.ts, routes.ts, peac-core.d.ts}; drop@peac/corefromapps/api/package.jsonand from the tsup external list.packages/core/toarchive/0.9.0-0.9.14/packages-core/.@peac/coreis not published at v0.13.0 or later. Historical npm versions<=0.9.14remain installable for verify-only use of historicalpeac.receipt/0.9records.packages/sdk-js/workspace stub./verifystanza from the public OpenAPI contract (packages/schema/openapi/verify.yaml).docs/HOSTED_VERIFY_CONTRACT.mdnow documents the alias-only runtime behavior.scripts/release/npm-deprecate-v0.13.0.shfor the release maintainer to mark@peac/core@<=0.9.14and@peac/sdk@<=0.10.2deprecated on npm after the package release is complete. Historical tarballs are not unpublished.@peac/mappings-a2ain the public API surface lock; refresh surface snapshots for the surfaces whose public shape changed.@peac/coreprimitives to the@peac/cryptopublic sign/verify round-trip.Tests added
apps/api/tests/legacy-verify-alias-headers.test.tsasserts all three deprecation headers are stamped on every alias response (/verifyand/api/v1/verify), and that the canonical/v1/verifyresponse does not carry them.apps/api/tests/legacy-verify-alias-pre-sunset.test.tsasserts status-code parity and response-shape parity between the alias and the canonical route on invalid input, and pins theSunsetheader to the advertised date byte-for-byte.