Add governed contact point snapshots

README.md

@@ -74,13 +74,16 @@ It must not own:
 
 ## First Capabilities
 
-The module exposes three core-mediated capabilities:
+The module exposes four core-mediated capabilities:
 
 - `addresses.lookup`: read-only contact/recipient lookup for autocomplete.
 - `addresses.recipient_source`: immutable recipient snapshots for campaign,
   reporting, mail-build, forms, portal, and postbox workflows.
 - `addresses.contact_writer`: address-book-scoped write decisions and contact
   creation for local or otherwise writable sources.
+- `addresses.contact_point_resolution`: purpose-aware, channel-neutral
+  resolution and immutable snapshots for email, postal, internal-mail, and
+  portal targets.
 
 `addresses.recipient_source` returns:
 
@@ -98,10 +101,13 @@ address. Email-oriented consumers snapshot email targets and whole-contact
 entries with a usable email address; postal-only entries remain valid list
 members for later postal/document workflows.
 
-Consumers must store their own immutable snapshot when they need historical
-evidence. The addresses module remains the owner of the reusable source, not of
-the consumer's historical records. Consumers must resolve these capabilities
-through the platform registry and must not import address ORM/service internals.
+Legacy `addresses.recipient_source` consumers must store their own immutable
+snapshot when they need historical evidence. Channel-neutral consumers may use
+the dedicated freeze operation described below. The addresses module remains
+the owner of reusable sources; domain consumers remain responsible for linking
+their own records to snapshot evidence. Consumers must resolve these
+capabilities through the platform registry and must not import address
+ORM/service internals.
 
 `addresses.contact_writer` returns an explicit decision before a consumer shows
 or executes write actions: allowed/blocked, reason, user-facing message,
@@ -109,6 +115,22 @@ required scopes, source kind, read-only state, and provenance. The decision is
 address-book specific; broader policy modules may later contribute to the same
 decision path, but consumers should not import or duplicate policy logic.
 
+For channel-neutral consumers, `addresses.contact_point_resolution` supersedes
+the email-only shape without removing it. It accepts local contact IDs and
+stable provider references such as `idm:identity:<id>`, applies an effective
+date, communication purpose, address purpose, fallback rule, locale, and
+domestic/international postal formatting, and returns candidates plus excluded
+targets with stable reason codes. Bounded previews are live. A frozen snapshot
+stores the complete values, source and governance revisions, provenance, and a
+deterministic hash in Addresses so later contact edits cannot rewrite evidence.
+
+The corresponding HTTP API is available below `/api/v1/addresses`:
+
+- `POST /contact-points/resolve`
+- `POST /contact-point-sources/preview`
+- `POST /contact-point-snapshots`
+- `GET /contact-point-snapshots/{snapshot_id}`
+
 ## Design Documents
 
 - [Address module architecture](docs/ADDRESS_MODULE_ARCHITECTURE.md)