Establish primitive quality tiers and enforce production contract coverage

[vincenzoml]

Problem

Several primitive namespaces are still mixed quality: some production-oriented, some legacy/test/demo-oriented, and some with low contract coverage (e.g., arrays/test namespaces).

Why this matters

• Inconsistent quality undermines replaceable execution semantics and long-term API confidence.
• Low-coverage primitives can silently regress with runtime refactors.

Scope

1. Define primitive quality tiers:

• Tier A: stable production primitives
• Tier B: experimental primitives
• Tier C: test/demo-only primitives

2. Enforce registry metadata to expose tier/stability and documentation links.
3. Add per-primitive contract conformance tests for Tier A set.
4. Move/flag demo/test primitives so they are not presented as production defaults.
5. Reduce stale primitive files and dead code paths.

Non-goals

• Rewriting every primitive implementation immediately.
• Removing experimental namespaces needed for ongoing research.

Deliverables

• Updated primitive API docs with tiering policy.
• Registry support for stability/tier metadata.
• New contract suite + minimum coverage target for Tier A primitives.
• Cleanup PR removing or archiving stale primitive modules.

Acceptance criteria

• list-primitives can surface tier/stability metadata (or a documented equivalent output path).
• Tier A primitives have passing contract tests in CI.
• Demo/test primitives are clearly segregated from production UX.

Risks

• Temporary user confusion due to reclassification.

Mitigations

• Keep aliases for one release cycle and publish migration notes.