Add aps schema self-describing contract endpoint (Closes #32)

[0xLeif]

Closes #32.

Summary

New aps schema command: the self-describing contract endpoint from design decision 4 and the precondition for dynamic schema (1.0).

One cacheable JSON document containing:

• cliVersion (asserted equal to aps --version in smoke) and integer schemaVersion (bumped on any contract change; agents compare equality to detect drift)
• state-root precedence (--state-dir > APS_HOME > ~/.aps)
• keys[]: every DemoKey with type, storage, lifetime, and path pattern (incl. the Keychain account for secret)
• commands[]: every subcommand with arguments, flags, payload reference, streaming flag
• payloads: JSON shapes for KeyValuePayload, KeysPayload, WatchEvent, WatchErrorEvent, ResetPayload, StatsPayload, ErrorEnvelope (minimal JSON Schema subset: type/properties/required/array/items)
• errors: the stable code -> exit-code -> meaning/hint table (including corrupt_state)

Static contract only; live state stays in dump (locked interview decision).

Verification (local, worktree)

• swift build clean; 43 tests (3 new: key/command coverage, error-table stability, encoded-document validity), 0 failures
• smoke.sh green incl. new assertions: schemaVersion present, key entries, corrupt_state in the error table, cliVersion == aps --version
• specsync check --force 7/7 files 100%, specsync change check 17 active valid, fledge lanes run verify green
• README agent section leads with aps schema and documents the drift rule plus --experimental-dump-help

SpecSync

• CHG-0018 accepted (feature; REQ-aps-cli-016 with requirement evidence)
• Evidence rebound for CHG-0003, 0004, 0007, 0011, 0012, 0013, 0014, 0015, 0016, 0017 via audited reopen (actor 0xLeif)

Merge note

This branch and #50 both bump the aps-cli spec to v18 and both carry a CHG-0018 id (created on different branches from the same ledger). Whichever merges second should rebase, bump the spec to v19, and renumber its change to CHG-0019 via the ceremony. Happy to do that pass on this PR if #50 lands first.

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[cursor]

Review (agent:cursor) — tested locally

Verdict: Approve after rebase. Feature looks good; SpecSync ID and merge order need fixing.

Tested

• fledge lanes run verify: pass (40 tests + smoke)
• CI: all green
• aps schema returns cliVersion=0.2.0, schemaVersion=1, 7 keys, 8 commands (get/set/watch/dump/keys/reset/stats/schema), payloads include ErrorEnvelope

Required before merge

1. Renumber SpecSync: this PR adds CHG-0018-aps-schema-... but main already has CHG-0018-document-windows-readiness-.... Commit message already acknowledges this; please rename to the next free ID after the merge wave (likely CHG-0022 once Error contract: exit-code taxonomy and JSON error envelope (Closes #31) #50 takes 0021).
2. Merge after Error contract: exit-code taxonomy and JSON error envelope (Closes #31) #50 (error contract). Schema documents exit codes / ErrorEnvelope that Error contract: exit-code taxonomy and JSON error envelope (Closes #31) #50 implements at runtime.
3. Prefer merge after Encrypted-file secret store via swift-crypto (Closes #35) #55 (or rebase once more after Encrypted-file secret store via swift-crypto (Closes #35) #55): schema currently documents keychain_unavailable, but Encrypted-file secret store via swift-crypto (Closes #35) #55 replaces Keychain with secretUnlockFailed / EncryptedFile. Shipping schema before Encrypted-file secret store via swift-crypto (Closes #35) #55 freezes a soon-stale contract.

Suggested merge order

#50 → #53 → #54 → #55 → this PR last (so schema describes the final surface).