[AI-0320] feat: add metadata publication handshake

[Xuepoo]

Priority: P1 | Area: agent | Labels: feat,P1,area:agent | Milestone: v0.1.0 | RFC: AIQ-38 / S-1 | Task: AI-0320

Summary

• Add a bounded helper-side metadata publication and acknowledgement vocabulary for S-1.
• Bind acknowledgements to exact publication identity, snapshot version, and SHA-256 payload digest.
• Reject replay, superseded, duplicate, malformed, oversized, duplicate-key, credential-like, and publication-ID-reuse inputs without ambient authority.
• Preserve tolerant E2 behavior and keep AI-0303 stale/missing enforcement disabled until Core transport integration exists.

Verification

• Independent review approved (PX-1404).
• 113 endpoint tests passed.
• Workspace check/test, clippy, formatting, Markdown lint, and diff checks passed.
• Full workspace check used locked dependencies; no network, credential, provider I/O, or transport behavior was introduced.

This PR defines the helper-side contract only. Core publication transport and normal ai.* version flow remain separate integration work.

Summary by CodeRabbit

• New Features
  • Added a metadata publication and acknowledgement flow that accepts validated, up-to-date publications and confirms them only when the acknowledgement matches.
  • Added safeguards for publication size, metadata content, duplicate or replayed identifiers, and sensitive values.
• Bug Fixes
  • JSON number parsing now rejects malformed numbers, including leading-zero integers and incomplete fractions or exponents.
• Documentation
  • Documented publication limits, validation rules, and acknowledgement behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository UI (base), Organization UI (inherited)
• Review profile: CHILL
• Plan: Advanced
• Run ID: c61fd28c-f3de-41f9-91e0-5124b5fb578e

📥 Commits

Reviewing files that changed from the base of the PR and between 8a08923 and 368b232.

📒 Files selected for processing: 3

• crates/bitty-ai-endpoint/API.md
• crates/bitty-ai-endpoint/src/lib.rs
• crates/bitty-ai-endpoint/src/metadata_publication.rs

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

📝 Walkthrough

The endpoint now exposes an in-memory metadata publication handshake. It validates bounded publication frames, metadata, and SHA-256 digests, tracks accepted publication IDs, and acknowledges only the current pending publication. JSON number parsing rejects malformed number forms.

Changes: Metadata publication

Layer / File(s)	Summary
Strict JSON number parsing crates/bitty-ai-endpoint/src/lib.rs	The JSON parser now rejects leading-zero integers and fractions or exponents without required digits. Tests cover accepted and rejected forms.
Publication validation and acknowledgement crates/bitty-ai-endpoint/src/metadata_publication.rs, crates/bitty-ai-endpoint/src/lib.rs, crates/bitty-ai-endpoint/API.md	The public module validates publication frames, metadata, and digests; tracks accepted IDs; and acknowledges exact matches to the pending publication. Tests cover validation and state behavior. The API document describes the protocol and its integration boundary.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Feature

Merge Risk: ⚪ Minimal · up to 368b2

No merge-blocking issue is established. Confirm that the handshake design is recorded in the canonical documentation before merging.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 34.48% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 29 functions across 2 files. (1 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely identifies the main change: adding the AI-0320 metadata publication handshake.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 34.48% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 29 functions across 2 files. (1 skipped: 1 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

• Fix all pre-merge checks with AI

✨ Finishing Touches: 💡 1

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}