1. Scope & Architectural Boundary

This document defines the normative requirements for software directories, catalog registries, aggregators, and automated crawlers (collectively termed Registries) that consume, index, and present MSR JSON manifests.

The MSR Standard is an open, independent protocol. A registry (such as MySoftRank, a package index, or an AI discovery agent) is an independent consumer implementation. To claim MSR Conformance, a registry MUST satisfy the ingestion, network safety, cache discipline, and schema fidelity rules specified herein.

2. Zero-Account Ingestion & Canonical Discovery

Traditional software directories require manual, multi-page form registration behind vendor accounts, causing stale metadata and high onboarding friction. Conforming registries MUST support automated manifest ingestion:

• Canonical Discovery: Registries MUST support automatic resolution of manifests at the well-known URI specified in RFC 0001: https://<primary_domain>/.well-known/msr.json.
• Zero-Account Ingestion: Registries SHOULD provide an open submission interface allowing any user, developer, or agent to submit a manifest URI without requiring prior user account registration.
• Domain-Bound Authority: Serving a valid manifest over TLS at the product's official root domain (entity.primary_domain) constitutes primary cryptographic and transport authority for technical product metadata. Registries MUST treat this source as authoritative over unverified third-party submissions.

3. Network Safety & SSRF Defense

Allowing arbitrary URL intake introduces Server-Side Request Forgery (SSRF) and resource exhaustion risks. Any crawler or ingestion pipeline in a conforming registry MUST enforce the following safeguards prior to making outbound HTTP requests:

1. Pre-Flight DNS Resolution: The registry crawler MUST resolve target hostnames before issuing requests and strictly reject:
   • Loopback addresses (127.0.0.0/8, ::1).
   • RFC 1918 private subnets (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16).
   • Link-local and cloud provider metadata addresses (169.254.0.0/16, fe80::/10).
2. Redirect Re-Validation: HTTP redirects (301, 302, 307, 308) MUST be validated against the same IP safety filters at every hop. Registries MUST limit redirect depth to a maximum of 5 hops.
3. Protocol & Port Enforcement: Only https:// (and optionally http:// for local sandbox testing) on default ports (443 and 80) is permitted. Custom ports are forbidden.
4. Resource Caps: Connection timeouts MUST NOT exceed 8 seconds. Payload downloads MUST be capped at 1 MB; larger files MUST terminate the connection immediately to prevent memory exhaustion attacks.

4. Semantic Caching & Polling Discipline

Registries MUST be good citizens of the open web and avoid hammering vendor infrastructure:

• Conditional Requests: Registries MUST store the ETag and Last-Modified response headers returned by publishers. Periodic refresh crawlers MUST send If-None-Match and If-Modified-Since headers.
• 304 Handling: On receiving 304 Not Modified, registries MUST NOT re-parse the manifest or alter database records.
• Polling Intervals: Automated crawling intervals MUST NOT exceed once per 6 hours per domain, except when triggered by explicit author webhooks or manual cache purge requests.
• Backoff Etiquette: When a publisher server returns HTTP 429 Too Many Requests or 5xx, the registry MUST respect Retry-After headers and apply exponential backoff.

5. Ingestion Dialects & Canonical Normalization

To facilitate ecosystem migration while preserving the integrity of MSR JSON, registries MAY accept legacy and transitional formats, provided they are normalized to the canonical schema:

Normalization Rules

• Monetary Integrity: Floating-point values (e.g. Program_Cost_Dollars: 29.99) MUST be normalized to exact integer minor units (starting_price_cents: 2999) accompanied by an ISO 4217 currency code ("USD").
• Language Localization: Legacy descriptions (e.g. Char_Desc_250) MUST be assigned to explicit BCP 47 language tags (e.g. entity.descriptions.en.summary).
• Semantic Versioning: Non-conforming version strings MUST be converted or annotated to comply with SemVer 2.0 syntax.
• Artifact Integrity: Legacy download URLs (e.g. Primary_Download_URL) mapped into releases.latest.artifacts[] MUST be flagged with "verified": false until an SHA-256 digest is independently computed or verified.

6. Domain Authority vs. Vendor Claim Verification

While submission and read-only indexing are zero-account and frictionless, administrative control over a registry listing requires verified domain authority:

• Read & Sync Tier: Open to all. Any agent or user can trigger synchronization of a publicly accessible manifest. The manifest's domain is authoritative for product information.
• Vendor Claim Tier: Actions such as replying to user reviews, configuring paid sponsorship placements, or managing private analytics MUST require domain ownership verification via:
  1. DNS TXT Challenge: A DNS record matching _msr-challenge=<token> on the entity.primary_domain.
  2. Domain Email Confirmation: Verification email dispatched to an address under the same domain (e.g. security@<primary_domain>).
  3. Cryptographic Signature: Manifest signed with an Ed25519 key registered in DNS per RFC 0003.

7. Zero-Drift Rule: Non-Corruption of the Canonical Schema

A registry MUST NOT fork, mutate, or introduce proprietary enum values into the canonical schema while referencing the canonical schema identifier https://msrjson.org/schemas/msr-2.0.json.

Registry-specific operational attributes (e.g. internal review aggregations, editorial rankings, click counters, sponsorship flags) MUST be stored in the registry's own private database. They MUST NOT be injected into published MSR JSON manifests.