feat(api): document concurrency — optimistic writes, advisory locks, lifecycle state

[thewrz]

Context

ADR-018. No native concurrency control or document state exists: concurrent paragraph edits are last-write-wins with no detection, and nothing records that a spec is issued or frozen. Pessimistic checkout is rejected (ADR-005: review must not freeze design). Pre-req for MCP write tools (#44); shrinks #52 to pre-generation + storage + invalidation.

Scope

Create:

• Version preconditions on all content writes (REST + MCP): write carries the content_version it read; stale → 409 with current version
• spec_locks advisory TTL table + acquire/release/steal-after-expiry semantics
• specs.lifecycle_state (draft|issued|archived) + issuance hook from package revisions
• Composed edit gate: native lifecycle_state AND ADR-014 external_state must both permit
• openapi.yaml updated before feat(mcp): Phase 5g — MCP write tools (add_paragraph, update_paragraph, delete_paragraph) #44 starts

Acceptance

• Stale-version write rejected with current version in the error
• Second holder refused while a lock is live; succeeds after expiry
• Archived spec rejects writes
• Issuing a package revision sets lifecycle_state='issued'

Blocked by

#93

Related

#43 (identity for lock holders), #44 (consumer), #52 (consumer)