@sguild/dispatcher 2.0.0 → 2.0.1

package/contracts/platform-comms/README.md

@@ -0,0 +1,84 @@
+# Platform Comms
+
+**Status:** v1.0.0
+**Date:** 2026-05-17
+**Owner:** platform (comms ingress)
+**Consumers:** sales (cadence reset), platform-warehouse (analytics ingestion)
+**Related ADRs:** ADR-0001 (tenant_id), ADR-0002 (canonical entity ID template), ADR-0003 (Person canonical and Guardian routing), ADR-0005 (event envelope), ADR-0009 (dispatcher transport, producer transactional guarantee)
+**Related contracts:** Event Envelope Contract (`../event-envelope/README.md`), Identity Contract (`../identity/README.md`), Lead Lifecycle Contract (`../lead-lifecycle/README.md`)
+**Sub-specs (authoritative):** `schema/payloads/platform.comms.inbound-v1.json`
+**Validations:** none yet
+
+## 1. Purpose and scope
+
+This contract specifies the Platform-owned inbound communications signal used by Sales to reset cadence when a Person sends an inbound SMS or places an inbound voice call. Platform owns provider ingress, Person resolution, tenancy scoping, consent and opt-out checks, Guardian-aware routing checks, and normalized dispatcher emission. Sales owns the cadence reaction after it consumes the dispatcher event.
+
+In scope: the event name, payload shape, producer responsibilities, consumer responsibilities, privacy constraints, and versioning rules for `platform.comms.inbound`.
+
+Out of scope: provider webhook payload formats, raw SMS body text, call audio, call transcripts, outbound messaging APIs, Sales cadence state transitions, and the operator read surface for full communication details. Raw provider payloads and full message content stay in Platform-owned storage and do not ride on the dispatcher event.
+
+## 2. Normative language
+
+The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted per RFC 2119.
+
+## 3. Terminology
+
+**Inbound communication.** A customer-originated SMS or voice call received through a communications provider and resolved by Platform to a canonical Person.
+
+**Cadence reset signal.** The dispatcher event Sales consumes to stop or reset outbound cadence timing because the customer contacted Sguild first.
+
+**Communication ID.** A Platform-owned identifier for the stored inbound communication. Consumers treat it as opaque and use Platform read APIs, not provider payloads, when they need operator-safe detail.
+
+## 4. Event types
+
+### 4.1 `platform.comms.inbound`
+
+Emitted by Platform after an inbound SMS or inbound voice call has passed provider ingress, tenant resolution, Person resolution, consent checks, and Guardian-aware routing checks, and has been routed to Sales as a cadence-reset signal.
+
+The event envelope subject SHALL be the canonical `person_id`. The actor SHALL be `system:platform`. The payload carries the same `person_id` for warehouse convenience and consumer-side validation. Payload v1 is authoritative at `schema/payloads/platform.comms.inbound-v1.json`.
+
+Known `channel` values at v1 are `sms` and `voice_call`. New channel values are additive only when consumers can safely ignore them.
+
+The payload SHALL NOT carry full SMS body text, call transcript text, provider raw payloads, or contact details. `body_preview` MAY carry an operator-safe preview or summary and MAY be null.
+
+## 5. Producer responsibilities
+
+Platform SHALL emit `platform.comms.inbound` only after resolving the communication to a canonical Person and determining that Sales should receive the cadence-reset signal.
+
+Platform SHALL keep raw provider payloads, full body text, transcripts, and contact details in Platform-owned storage, not on the event payload.
+
+Platform SHALL set the event subject to `person_id`, set actor to `system:platform`, and publish with `schema_version=1`.
+
+Platform SHALL set payload `tenant_id` from dispatcher runtime context, not from untrusted provider input.
+
+Platform SHOULD publish inside the same transaction that records the normalized communication when such storage exists at the call site. If the ingress path has no domain write in the current implementation phase, the publish may run as its own dispatcher insert while preserving the same payload validation and idempotency checks available to the caller.
+
+## 6. Consumer responsibilities
+
+Sales consumes `platform.comms.inbound` as a cadence-reset signal. Sales SHALL NOT treat the event as the canonical source of full message content, call transcript, phone number, or communication-provider details beyond the safe metadata explicitly present in the payload.
+
+Consumers SHALL deduplicate by `(consumer, event_id)` through the dispatcher SDK.
+
+Consumers SHALL treat `communication_id` and `provider_message_id` as opaque identifiers.
+
+Platform warehouse ingests the event for cross-domain communication and cadence analytics.
+
+## 7. Security and privacy
+
+This event deliberately minimizes PII. It carries Person and organization identifiers, channel, timing, provider name, provider message identifier, routing metadata, and an optional safe preview. It MUST NOT carry raw provider payloads, phone numbers, SMS bodies, call audio, or transcripts.
+
+Consumers MAY log `event_id`, `person_id`, and `communication_id`. Consumers SHOULD avoid long-lived logging of `body_preview` unless there is a clear operator need.
+
+## 8. Versioning
+
+This contract follows the additive-discipline pattern from the Event Envelope Contract. New optional fields and new safe-to-ignore enum-like values may land as v1.x changes. Removing fields, renaming fields, narrowing accepted values, or adding content-bearing PII requires a major version bump and a deprecation window.
+
+Per-event `schema_version` is scoped to `platform.comms.inbound`.
+
+## 9. Trigger to revisit
+
+Revisit this contract if Sales needs content-bearing message detail on the event, if another domain needs to consume inbound comms for load-bearing workflows, if provider ingress cannot reliably resolve to Person before event emission, or if a future channel cannot be represented additively by the v1 payload.
+
+## 10. Change log
+
+- **v1.0.0** (2026-05-17): Initial release. Adds `platform.comms.inbound` for inbound SMS and voice-call cadence reset signals per `2026-05-17-platform-cadence-inbound-comms-position`.

package/contracts/platform-comms/schema/payloads/platform.comms.inbound-v1.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/platform-comms/schema/payloads/platform.comms.inbound-v1.json",
+  "title": "platform.comms.inbound payload v1",
+  "description": "Payload for the platform.comms.inbound event_type at schema_version 1. Platform emits this after inbound SMS or inbound voice-call provider ingress resolves to a canonical Person, passes tenant, consent, opt-out, and Guardian-aware routing checks, and routes to Sales as a cadence-reset signal. The envelope subject is the person_id and actor is system:platform. The payload intentionally excludes full SMS body text, call transcript text, raw provider payloads, and contact details; raw communications stay in Platform-owned storage.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "communication_id",
+    "person_id",
+    "tenant_id",
+    "organization_id",
+    "channel",
+    "received_at",
+    "provider",
+    "provider_message_id",
+    "routing_result",
+    "guardian_routed",
+    "body_preview"
+  ],
+  "properties": {
+    "communication_id": {
+      "type": "string",
+      "description": "Platform-owned identifier for the normalized inbound communication. Consumers treat it as opaque and use Platform read APIs for any operator-safe detail.",
+      "minLength": 5,
+      "maxLength": 128,
+      "pattern": "^com_[A-Za-z0-9._:-]+$"
+    },
+    "person_id": {
+      "type": "string",
+      "description": "Canonical Person that the inbound communication resolved to. Mirrors the event envelope subject. per_<UUID v7 canonical> per ADR-0002.",
+      "pattern": "^per_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "tenant_id": {
+      "type": "string",
+      "description": "Tenant discriminator. Mirrors the event envelope tenant_id and is set from dispatcher runtime context, not provider input.",
+      "minLength": 1,
+      "maxLength": 64
+    },
+    "organization_id": {
+      "type": "string",
+      "description": "Customer organization scope resolved by Platform before emission. Opaque to this contract because organization identifier shape is Platform-owned.",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "channel": {
+      "type": "string",
+      "enum": ["sms", "voice_call"],
+      "description": "Inbound communications channel. v1 covers SMS and voice calls; future channel values require an additive contract update and consumer-safe rollout."
+    },
+    "received_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When Platform received or accepted the provider signal. UTC ISO 8601."
+    },
+    "provider": {
+      "type": "string",
+      "description": "Provider identifier, for example twilio. Human-readable and safe for logs.",
+      "minLength": 1,
+      "maxLength": 100
+    },
+    "provider_message_id": {
+      "type": "string",
+      "description": "Opaque provider-side message or call identifier. Consumers do not parse it.",
+      "minLength": 1,
+      "maxLength": 200
+    },
+    "routing_result": {
+      "type": "string",
+      "enum": ["sales"],
+      "description": "The Platform routing decision that made this a Sales cadence-reset signal. Non-Sales inbound communications do not emit this event at v1."
+    },
+    "guardian_routed": {
+      "type": "boolean",
+      "description": "True when the inbound communication was resolved through a Guardian-aware route for a minor Person."
+    },
+    "body_preview": {
+      "type": ["string", "null"],
+      "description": "Optional operator-safe preview or summary. Must not contain the full SMS body, full call transcript, raw provider payload, or contact details.",
+      "maxLength": 280
+    }
+  }
+}

package/contracts/platform-geography-snapshot/README.md

@@ -0,0 +1,205 @@
+# Platform Geography Snapshot Contract
+
+**Status:** v0.1.0
+**Date:** 2026-05-16
+**Owner:** Platform (identity service, envelope steward)
+**Consumers:** Sales, Delivery (reference-holder and optional consumer)
+**Related ADRs:** ADR-0001 (tenant_id), ADR-0003 (canonical entity discipline), ADR-0005 (event envelope, pending), ADR-0013 (Platform-owned canonical geography)
+**Sub-specs (authoritative):** n/a
+**Validations:** n/a
+
+## 1. Purpose and scope
+
+This contract defines the geography-snapshot event stream that lets consuming domains keep a local mirror of the cross-domain geography catalog (Markets and Service Areas). Today the canonical reads happen against Platform's synchronous `GET /api/geography/catalog`, which works well in steady state but offers no graceful degradation when Platform is unreachable. The snapshot stream lets a consumer build a local read replica from event-sourced upserts, fall back to that replica when the live API errors, and replay history on demand.
+
+The first consumer is Sales, which caches the snapshot in its `platform_location_snapshot` Postgres table (per ADR-0001 phase 1 slice 1.4) and uses the cache as a fallback in its geographies resolver. Other domains (Delivery, Revenue) may register as consumers in later minor versions if a similar resilience need emerges; the contract is shaped for many consumers, not Sales-specifically.
+
+In scope: event names and payload shapes for Markets and Service Areas, producer/consumer responsibilities, versioning policy. Out of scope at v0.1: Lesson Sites (Delivery-owned, not consumed by Sales today; add in v0.2 when a consumer requests them), Markets-to-Service-Area cross-reference event sequencing (the event payloads carry the parent reference inline, sequencing is best-effort), the synchronous catalog API itself (this contract is the eventually-consistent companion to that API, not a replacement).
+
+The geography ownership boundary is settled per ADR-0013: Platform owns canonical Market identity and canonical Service Area identity. Delivery owns lesson sites, lesson-site config, coverage, assignment, scheduling, and other delivery facts that reference `service_area_id`. This contract codifies the producer split that boundary implies: Platform produces all v0.1 `geography.market.*` and `geography.service-area.*` events, and Delivery is a reference-holder and optional consumer rather than a co-producer.
+
+## 2. Normative language
+
+The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted per RFC 2119.
+
+## 3. Terminology
+
+- **Market.** A canonical geography record at the Operations base level (Oahu and Dallas today). Platform-owned canonical entity. Identifier prefix reserved per ADR-0002.
+- **Service Area.** A Platform-owned routing region within a Market. Service Areas point at Markets via `market_id`; Delivery-owned operational rows may reference `service_area_id`.
+- **Lesson Site.** A Delivery-owned physical or virtual location within a Service Area. Not in scope at v0.1.
+- **Snapshot.** A consumer's local mirror of the geography catalog populated from events; not the canonical store.
+- **Producer.** The domain authoritative for a given record type and responsible for emitting that record's lifecycle events.
+- **Envelope.** The Platform-stewarded event envelope (ADR-0005, pending) that wraps every payload defined here.
+
+## 4. Surface
+
+### 4.1 Event types
+
+Four event types compose v0.1, two per entity:
+
+- `geography.market.upserted` (Platform produces): emitted on Market mint or any subsequent change to a canonical field. Payload §4.2.
+- `geography.market.archived` (Platform produces): emitted when a Market transitions to `archived` (soft delete). Payload §4.3.
+- `geography.service-area.upserted` (Platform produces): emitted on Service Area mint or any subsequent change to a canonical field. Payload §4.4.
+- `geography.service-area.archived` (Platform produces): emitted when a Service Area transitions to `archived`. Payload §4.5.
+
+Consumers SHALL treat unknown event types as safe-to-ignore.
+
+### 4.2 `geography.market.upserted` payload
+
+```json
+{
+  "market_id": "mkt_018f4d5a-1234-7abc-8def-0123456789ab",
+  "tenant_id": "tnt_default",
+  "slug": "oahu",
+  "name": "Oahu",
+  "status": "active",
+  "metadata": {},
+  "created_at": "2026-05-16T15:00:00Z",
+  "updated_at": "2026-05-16T15:00:00Z"
+}
+```
+
+Field semantics:
+
+| Field        | Type       | Required | Notes                                                                                          |
+|--------------|------------|----------|------------------------------------------------------------------------------------------------|
+| `market_id`  | string     | yes      | Platform-minted, `mkt_<UUID v7>` per ADR-0002. Immutable.                                       |
+| `tenant_id`  | string     | yes      | Tenant scope per ADR-0001. Singleton in v0.1; reserved for multi-tenant without a major bump. |
+| `slug`       | string     | yes      | Stable lookup key (kebab-case). Unique per tenant.                                              |
+| `name`       | string     | yes      | Operator-facing label.                                                                          |
+| `status`     | string     | yes      | One of `active`, `archived`. New values SHALL be appended in minor versions.                    |
+| `metadata`   | object     | optional | Free-form Platform-internal metadata. Non-contractual; consumers MUST NOT build business behavior on its keys. |
+| `created_at` | RFC 3339   | yes      | UTC. Immutable after mint.                                                                      |
+| `updated_at` | RFC 3339   | yes      | UTC. Bumped on every emit.                                                                      |
+
+### 4.3 `geography.market.archived` payload
+
+```json
+{
+  "market_id": "mkt_018f4d5a-1234-7abc-8def-0123456789ab",
+  "tenant_id": "tnt_default",
+  "archived_at": "2026-05-16T15:00:00Z",
+  "reason": "operator_action"
+}
+```
+
+| Field         | Type     | Required | Notes                                                                                |
+|---------------|----------|----------|--------------------------------------------------------------------------------------|
+| `market_id`   | string   | yes      | Identifies the Market being archived. The `upserted` row stays present.              |
+| `tenant_id`   | string   | yes      | Tenant scope.                                                                        |
+| `archived_at` | RFC 3339 | yes      | UTC.                                                                                 |
+| `reason`      | string   | optional | Free-form short reason code. Consumer behavior SHALL NOT depend on a specific value. |
+
+### 4.4 `geography.service-area.upserted` payload
+
+```json
+{
+  "service_area_id": "sva_018f4d5a-1234-7abc-8def-0123456789ab",
+  "tenant_id": "tnt_default",
+  "market_id": "mkt_018f4d5a-1234-7abc-8def-0123456789ab",
+  "slug": "honolulu",
+  "name": "Honolulu",
+  "status": "active",
+  "metadata": {},
+  "created_at": "2026-05-16T15:00:00Z",
+  "updated_at": "2026-05-16T15:00:00Z"
+}
+```
+
+| Field             | Type     | Required | Notes                                                                                      |
+|-------------------|----------|----------|--------------------------------------------------------------------------------------------|
+| `service_area_id` | string   | yes      | Platform-minted, `sva_<UUID v7>` per ADR-0002 (reserved; promote on first use).             |
+| `tenant_id`       | string   | yes      | Tenant scope.                                                                              |
+| `market_id`       | string   | yes      | Parent Market reference. Forward reference; Platform's `market.upserted` for this id MAY arrive after this event under non-FIFO transports. |
+| `slug`            | string   | yes      | Stable lookup key.                                                                         |
+| `name`            | string   | yes      | Operator-facing label.                                                                     |
+| `status`          | string   | yes      | One of `active`, `archived`.                                                               |
+| `metadata`        | object   | optional | Free-form Platform-internal metadata. Non-contractual; consumers MUST NOT build business behavior on its keys. |
+| `created_at`      | RFC 3339 | yes      | UTC. Immutable after mint.                                                                 |
+| `updated_at`      | RFC 3339 | yes      | UTC. Bumped on every emit.                                                                 |
+
+### 4.5 `geography.service-area.archived` payload
+
+Same shape as §4.3 with `service_area_id` in place of `market_id`.
+
+### 4.6 Envelope
+
+Every event payload rides the Platform-stewarded event envelope (ADR-0005, pending). The envelope carries `event_type`, `tenant_id`, `correlation_id`, `actor`, `subject`, `schema_version`, and the payload. This contract's payloads occupy the envelope's payload slot; envelope rules (idempotency keys, redelivery, ordering) live in the envelope contract.
+
+`schema_version` SHALL be an integer payload schema version registered in `contracts/event-types-registry.json`. The four v0.1 event payloads use `schema_version: 1`. Contract README versions use semantic versions independently from payload schema versions. Consumers SHALL treat unknown future integer schema versions as incompatible until their payload schemas are registered and mirrored locally.
+
+## 5. Versioning policy
+
+### 5.1 Semantic versioning
+
+- **Patch** (0.1.0 → 0.1.1): editorial clarifications, typo fixes. No behavioral change.
+- **Minor** (0.1.x → 0.2.0): additive changes. New optional fields, new event types (e.g., Lesson Site events when needed), appended `status` enum values. Consumers on older minors continue to work.
+- **Major** (0.x.y → 1.0.0): breaking changes. Removal, type change, narrowing enum values, breaking payload changes. v1.0.0 is the milestone where Lesson Sites are likely to join.
+
+### 5.2 Deprecation policy
+
+On major-version publication, the previous major enters a two-week deprecation window per the org-standard contract-currency rule. Consumers running against deprecated versions after the window contribute to drift.
+
+### 5.3 Additive discipline within a major
+
+New fields MUST default to null or a backwards-compatible value. New enum values MUST be appended; consumers MUST treat unknown enum values as safe-to-ignore.
+
+## 6. Consumer responsibilities
+
+### 6.1 Subscribe at-least-once
+
+Consumers SHALL subscribe via the standard envelope rail with at-least-once delivery semantics. Idempotency keys on the envelope let the consumer detect redelivery; the snapshot upsert SHALL be idempotent on `(tenant_id, market_id)` or `(tenant_id, service_area_id)`.
+
+### 6.2 Forward references tolerated
+
+A `service-area.upserted` event MAY arrive before the `market.upserted` for its parent. Consumers SHALL tolerate the forward reference (e.g., by storing the parent id and surfacing label-only rendering until the parent arrives), not by failing the upsert. A reconciliation pass (§6.4) is the recovery path for permanently-missing parents.
+
+### 6.3 Resolver fallback
+
+Consumers that maintain a snapshot SHOULD fall back to snapshot reads when the live geography catalog is unreachable. The fallback is best-effort and SHALL be labeled in the consumer's UI or audit log as "from cache, last synced <timestamp>" so operators can distinguish live data from stale.
+
+### 6.4 Periodic reconciliation
+
+Consumers SHOULD run a daily reconciliation pass against the live catalog API: any local snapshot row not present in the live catalog is a candidate to mark `archived` locally; any live row not in the snapshot is a candidate for resync. Reconciliation is a backstop for missed events, not a substitute for the event stream.
+
+### 6.5 Tenant scoping
+
+Every snapshot read and write SHALL carry `tenant_id` from auth context. Cross-tenant reads are prohibited.
+
+### 6.6 Reference by ID
+
+Consumers MUST store geography references as `market_id` / `service_area_id` values, not as denormalized copies of names. Display-layer caching via the snapshot table is permitted; long-term references to slugs or names are not.
+
+## 7. Producer responsibilities
+
+### 7.1 Event fidelity
+
+Producers SHALL emit the appropriate event (`upserted` or `archived`) for every mutation of a canonical field before the corresponding API mutation response returns. Consumers MAY assume that a successful API response implies the corresponding event has been published with at-least-once delivery.
+
+### 7.2 Uniqueness
+
+Producers SHALL ensure Platform-minted `market_id` and `service_area_id` uniqueness within a tenant. Collisions are a critical integrity bug.
+
+### 7.3 Parent existence at archive time
+
+Producers SHOULD NOT archive a Market while live Service Areas reference it; archive child Service Areas first, then the Market. The contract does not enforce this; it surfaces in operator workflows.
+
+### 7.4 Initial bootstrap
+
+When a new consumer subscribes, producers SHALL offer a one-shot replay of all currently `active` records via the envelope contract's replay surface (or an out-of-band initial fetch against the synchronous catalog API). v0.1 leaves the replay mechanism to the envelope contract; a consumer integrating without replay support uses the catalog API for a one-time initial fill.
+
+## 8. Security and privacy
+
+Geography records carry no PII. Market and Service Area names are operator-facing labels (Oahu, Honolulu) and are not user-derived. Consumers MAY log `market_id`, `service_area_id`, `slug`, and `name` freely. `metadata` payloads MAY contain producer-internal operational state; consumers SHALL NOT depend on metadata field shapes across version bumps.
+
+Access to the event stream is gated by tenant auth context per the envelope contract. Cross-tenant reads are prohibited.
+
+## 9. Future work
+
+- **v0.2 Lesson Site events.** Add `geography.lesson-site.upserted` and `geography.lesson-site.archived`, produced by Delivery, when a consumer requests them. Sales does not consume Lesson Sites today; Delivery uses them internally.
+- **v1.0.0.** Promote to v1 when the contract has shipped with at least one production consumer for two stable weeks and the Markets canonical-entity migration is past its operational checkpoint.
+- **Markets-internal canonical-entity surface.** Platform's `mkt_` prefix is reserved here; final shape (display fields, lifecycle states beyond `active`/`archived`, Org parentage) lands as Platform's Markets migration concretizes. Contract additive-discipline applies.
+
+## 10. Change log
+
+- **v0.1.0** (2026-05-16): Initial draft. Proposed by Sales in `2026-05-16-sales-platform-geography-snapshot-contract-proposal`, then amended after Platform and Delivery responses on the same thread. Platform owns all four Market and Service Area v0.1 emitters per ADR-0013. Delivery is a reference-holder and optional consumer, not a Service Area lifecycle producer. Lesson Sites deferred to v0.2.

package/contracts/platform-geography-snapshot/schema/payloads/geography.market.archived-v1.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/platform-geography-snapshot/schema/payloads/geography.market.archived-v1.json",
+  "title": "geography.market.archived payload v1",
+  "description": "Payload for Platform-produced geography.market.archived at schema_version 1. Emitted when a canonical Market transitions to archived. The envelope subject is market_id and actor is system:platform.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "market_id",
+    "tenant_id",
+    "archived_at"
+  ],
+  "properties": {
+    "market_id": {
+      "type": "string",
+      "description": "Platform-minted Market id. mkt_<UUID v7 canonical> per ADR-0002.",
+      "pattern": "^mkt_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "tenant_id": {
+      "type": "string",
+      "description": "Tenant discriminator. Mirrors the event envelope tenant_id.",
+      "minLength": 1,
+      "maxLength": 64
+    },
+    "archived_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "reason": {
+      "type": "string",
+      "description": "Optional short reason code. Consumer behavior SHALL NOT depend on a specific value.",
+      "minLength": 1,
+      "maxLength": 100
+    }
+  }
+}

package/contracts/platform-geography-snapshot/schema/payloads/geography.market.upserted-v1.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/platform-geography-snapshot/schema/payloads/geography.market.upserted-v1.json",
+  "title": "geography.market.upserted payload v1",
+  "description": "Payload for Platform-produced geography.market.upserted at schema_version 1. Emitted when a canonical Market is minted or when a canonical Market field changes without transitioning to archived. The envelope subject is market_id and actor is system:platform.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "market_id",
+    "tenant_id",
+    "slug",
+    "name",
+    "status",
+    "created_at",
+    "updated_at"
+  ],
+  "properties": {
+    "market_id": {
+      "type": "string",
+      "description": "Platform-minted Market id. mkt_<UUID v7 canonical> per ADR-0002.",
+      "pattern": "^mkt_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "tenant_id": {
+      "type": "string",
+      "description": "Tenant discriminator. Mirrors the event envelope tenant_id.",
+      "minLength": 1,
+      "maxLength": 64
+    },
+    "slug": {
+      "type": "string",
+      "description": "Stable kebab-case lookup key.",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "maxLength": 100
+    },
+    "name": {
+      "type": "string",
+      "description": "Operator-facing Market label.",
+      "minLength": 1,
+      "maxLength": 200
+    },
+    "status": {
+      "type": "string",
+      "enum": ["active", "archived"]
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Optional, non-contractual Platform metadata. Consumers MUST NOT build business behavior on these keys.",
+      "additionalProperties": true
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "updated_at": {
+      "type": "string",
+      "format": "date-time"
+    }
+  }
+}

package/contracts/platform-geography-snapshot/schema/payloads/geography.service-area.archived-v1.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/platform-geography-snapshot/schema/payloads/geography.service-area.archived-v1.json",
+  "title": "geography.service-area.archived payload v1",
+  "description": "Payload for Platform-produced geography.service-area.archived at schema_version 1. Emitted when a canonical Service Area transitions to archived. The envelope subject is service_area_id and actor is system:platform.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "service_area_id",
+    "tenant_id",
+    "archived_at"
+  ],
+  "properties": {
+    "service_area_id": {
+      "type": "string",
+      "description": "Platform-minted Service Area id. sva_<UUID v7 canonical> per ADR-0002.",
+      "pattern": "^sva_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "tenant_id": {
+      "type": "string",
+      "description": "Tenant discriminator. Mirrors the event envelope tenant_id.",
+      "minLength": 1,
+      "maxLength": 64
+    },
+    "archived_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "reason": {
+      "type": "string",
+      "description": "Optional short reason code. Consumer behavior SHALL NOT depend on a specific value.",
+      "minLength": 1,
+      "maxLength": 100
+    }
+  }
+}

package/contracts/platform-geography-snapshot/schema/payloads/geography.service-area.upserted-v1.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/platform-geography-snapshot/schema/payloads/geography.service-area.upserted-v1.json",
+  "title": "geography.service-area.upserted payload v1",
+  "description": "Payload for Platform-produced geography.service-area.upserted at schema_version 1. Emitted when a canonical Service Area is minted or when a canonical Service Area field changes without transitioning to archived. The envelope subject is service_area_id and actor is system:platform.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "service_area_id",
+    "tenant_id",
+    "market_id",
+    "slug",
+    "name",
+    "status",
+    "created_at",
+    "updated_at"
+  ],
+  "properties": {
+    "service_area_id": {
+      "type": "string",
+      "description": "Platform-minted Service Area id. sva_<UUID v7 canonical> per ADR-0002.",
+      "pattern": "^sva_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "tenant_id": {
+      "type": "string",
+      "description": "Tenant discriminator. Mirrors the event envelope tenant_id.",
+      "minLength": 1,
+      "maxLength": 64
+    },
+    "market_id": {
+      "type": "string",
+      "description": "Parent Market id. mkt_<UUID v7 canonical> per ADR-0002.",
+      "pattern": "^mkt_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "slug": {
+      "type": "string",
+      "description": "Stable kebab-case lookup key within the parent Market.",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "maxLength": 100
+    },
+    "name": {
+      "type": "string",
+      "description": "Operator-facing Service Area label.",
+      "minLength": 1,
+      "maxLength": 200
+    },
+    "status": {
+      "type": "string",
+      "enum": ["active", "archived"]
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Optional, non-contractual Platform metadata. Consumers MUST NOT build business behavior on these keys.",
+      "additionalProperties": true
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "updated_at": {
+      "type": "string",
+      "format": "date-time"
+    }
+  }
+}