Skip to content

Clarify discovery roles, make dist-pin authoritative, and split checksum surfaces (Model A)#5

Open
GsCommand wants to merge 1 commit intomainfrom
codex/differentiate-.well-known-files
Open

Clarify discovery roles, make dist-pin authoritative, and split checksum surfaces (Model A)#5
GsCommand wants to merge 1 commit intomainfrom
codex/differentiate-.well-known-files

Conversation

@GsCommand
Copy link
Copy Markdown
Contributor

Motivation

  • Two near-duplicate discovery descriptors caused drift risk and unclear semantics for the current vs snapshot descriptor.
  • dist-pin/ was ambiguous between a local staging area and a publish bundle, which undermined release integrity.
  • The repo used a single blended checksums.txt that mixed current release truth with archival and bundle artifacts, making verification noisy.

Description

  • Adopted Model A: .well-known/agent.json is the current pointer and .well-known/agent-cards-v1.1.0.json is the frozen v1.1.0 snapshot, and both files now include explicit meta.descriptor_role fields.
  • Extended schemas/v1.1.0/agent.descriptor.schema.json to allow exactly the pointer/snapshot meta fields and updated .well-known/* JSON to set descriptor_role, current_pointer_target, and frozen_release.
  • Enforced the relationship in scripts/validate-cards.mjs so the pointer may differ only in the allowed pointer fields and fail validation on any other drift.
  • Declared dist-pin/agent-cards/v1.1.0 a committed authoritative publish bundle by removing it from .gitignore, adding it to package.json files, documenting the intent in README.md, and adding bundle mirroring checks in scripts/validate-cards.mjs.
  • Replaced the blended checksum surface with scoped artifacts by implementing scripts/generate-checksums.mjs to generate/verify checksums-v1.1.0.txt (current release), checksums-v1.0.0.txt (archival), and bundle-local dist-pin/.../checksums.txt, and removed the single checksums.txt.
  • Updated meta/manifest.json, README.md, and dist-pin/ bundle copies so manifest and docs point readers to the canonical checksums-v1.1.0.txt and the bundle-local checksums files.

Testing

  • Ran npm run validate (which runs validate:cards, checksum verification and tsc --noEmit) and it completed successfully.
  • Ran npm run validate:cards to exercise schema + discovery relationship + dist-pin mirroring checks and it passed.
  • Generated and verified checksums with node scripts/generate-checksums.mjs and node scripts/generate-checksums.mjs --verify (invoked via npm run generate:checksums / npm run validate:checksums) and all generated and bundle-local checksum files matched their expected scopes.

Codex Task

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant