settld 0.1.0

package/src/db/migrations/005_multi_tenant.sql

@@ -0,0 +1,106 @@
+-- v1.2: multi-tenant scoping (tenant_id) across core tables.
+
+-- EVENTS: add tenant_id and include it in aggregate uniqueness/ordering.
+ALTER TABLE events
+  ADD COLUMN IF NOT EXISTS tenant_id TEXT NOT NULL DEFAULT 'tenant_default';
+
+UPDATE events SET tenant_id = 'tenant_default' WHERE tenant_id IS NULL;
+
+ALTER TABLE events DROP CONSTRAINT IF EXISTS events_pkey;
+ALTER TABLE events
+  ADD CONSTRAINT events_pkey PRIMARY KEY (tenant_id, aggregate_type, aggregate_id, seq);
+
+ALTER TABLE events DROP CONSTRAINT IF EXISTS events_aggregate_type_aggregate_id_chain_hash_key;
+ALTER TABLE events
+  ADD CONSTRAINT events_tenant_aggregate_chain_hash_key UNIQUE (tenant_id, aggregate_type, aggregate_id, chain_hash);
+
+DROP INDEX IF EXISTS events_by_aggregate;
+CREATE INDEX IF NOT EXISTS events_by_aggregate ON events (tenant_id, aggregate_type, aggregate_id, seq);
+
+-- SNAPSHOTS: tenant-scoped primary key.
+ALTER TABLE snapshots
+  ADD COLUMN IF NOT EXISTS tenant_id TEXT NOT NULL DEFAULT 'tenant_default';
+
+UPDATE snapshots SET tenant_id = 'tenant_default' WHERE tenant_id IS NULL;
+
+ALTER TABLE snapshots DROP CONSTRAINT IF EXISTS snapshots_pkey;
+ALTER TABLE snapshots
+  ADD CONSTRAINT snapshots_pkey PRIMARY KEY (tenant_id, aggregate_type, aggregate_id);
+
+-- OUTBOX: include tenant_id for filtering/debugging.
+ALTER TABLE outbox
+  ADD COLUMN IF NOT EXISTS tenant_id TEXT NOT NULL DEFAULT 'tenant_default';
+
+UPDATE outbox SET tenant_id = 'tenant_default' WHERE tenant_id IS NULL;
+
+DROP INDEX IF EXISTS outbox_unprocessed;
+CREATE INDEX IF NOT EXISTS outbox_unprocessed ON outbox (processed_at, topic, tenant_id, id);
+
+-- IDEMPOTENCY: tenant-scoped key uniqueness.
+ALTER TABLE idempotency
+  ADD COLUMN IF NOT EXISTS tenant_id TEXT NOT NULL DEFAULT 'tenant_default';
+
+UPDATE idempotency SET tenant_id = 'tenant_default' WHERE tenant_id IS NULL;
+
+-- Drop whatever primary key exists (name can vary because v1.0 migration temporarily
+-- renames the table, which can cause the auto-generated PK constraint name to get
+-- a numeric suffix).
+DO $$
+DECLARE pk_name TEXT;
+BEGIN
+  SELECT c.conname
+    INTO pk_name
+  FROM pg_constraint c
+  WHERE c.conrelid = 'idempotency'::regclass
+    AND c.contype = 'p'
+  LIMIT 1;
+
+  IF pk_name IS NOT NULL THEN
+    EXECUTE format('ALTER TABLE idempotency DROP CONSTRAINT %I', pk_name);
+  END IF;
+END $$;
+
+ALTER TABLE idempotency
+  ADD CONSTRAINT idempotency_pkey PRIMARY KEY (tenant_id, principal_id, endpoint, idem_key);
+
+-- LEDGER: tenant-scoped entries and balances.
+ALTER TABLE ledger_entries
+  ADD COLUMN IF NOT EXISTS tenant_id TEXT NOT NULL DEFAULT 'tenant_default';
+
+UPDATE ledger_entries SET tenant_id = 'tenant_default' WHERE tenant_id IS NULL;
+
+ALTER TABLE ledger_entries DROP CONSTRAINT IF EXISTS ledger_entries_pkey;
+ALTER TABLE ledger_entries
+  ADD CONSTRAINT ledger_entries_pkey PRIMARY KEY (tenant_id, entry_id);
+
+ALTER TABLE ledger_balances
+  ADD COLUMN IF NOT EXISTS tenant_id TEXT NOT NULL DEFAULT 'tenant_default';
+
+UPDATE ledger_balances SET tenant_id = 'tenant_default' WHERE tenant_id IS NULL;
+
+ALTER TABLE ledger_balances DROP CONSTRAINT IF EXISTS ledger_balances_pkey;
+ALTER TABLE ledger_balances
+  ADD CONSTRAINT ledger_balances_pkey PRIMARY KEY (tenant_id, account_id);
+
+-- ROBOT RESERVATIONS: tenant-aware overlap prevention.
+ALTER TABLE robot_reservations
+  ADD COLUMN IF NOT EXISTS tenant_id TEXT NOT NULL DEFAULT 'tenant_default';
+
+UPDATE robot_reservations SET tenant_id = 'tenant_default' WHERE tenant_id IS NULL;
+
+ALTER TABLE robot_reservations DROP CONSTRAINT IF EXISTS robot_reservations_pkey;
+ALTER TABLE robot_reservations
+  ADD CONSTRAINT robot_reservations_pkey PRIMARY KEY (tenant_id, job_id);
+
+ALTER TABLE robot_reservations DROP CONSTRAINT IF EXISTS robot_reservations_no_overlap;
+ALTER TABLE robot_reservations
+  ADD CONSTRAINT robot_reservations_no_overlap
+  EXCLUDE USING gist (tenant_id WITH =, robot_id WITH =, "window" WITH &&);
+
+-- NOTIFICATIONS: tenant-aware sink.
+ALTER TABLE notifications
+  ADD COLUMN IF NOT EXISTS tenant_id TEXT NOT NULL DEFAULT 'tenant_default';
+
+UPDATE notifications SET tenant_id = 'tenant_default' WHERE tenant_id IS NULL;
+
+CREATE INDEX IF NOT EXISTS notifications_by_tenant_topic ON notifications (tenant_id, topic, id);

package/src/db/migrations/006_contracts.sql

@@ -0,0 +1,27 @@
+-- v1.2: contracts (tenant/customer/site scoped policies for SLA/credits/evidence retention).
+
+CREATE TABLE IF NOT EXISTS contracts (
+  tenant_id TEXT NOT NULL DEFAULT 'tenant_default',
+  contract_id TEXT NOT NULL,
+  name TEXT NOT NULL,
+  customer_id TEXT,
+  site_id TEXT,
+  template_id TEXT,
+  is_default BOOLEAN NOT NULL DEFAULT FALSE,
+  contract_json JSONB NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  PRIMARY KEY (tenant_id, contract_id)
+);
+
+CREATE INDEX IF NOT EXISTS contracts_by_scope ON contracts (tenant_id, customer_id, site_id, template_id, is_default, contract_id);
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_indexes WHERE schemaname = current_schema() AND indexname = 'contracts_one_default_per_tenant'
+  ) THEN
+    CREATE UNIQUE INDEX contracts_one_default_per_tenant ON contracts (tenant_id) WHERE is_default;
+  END IF;
+END $$;
+

package/src/db/migrations/007_artifacts_deliveries_correlations.sql

@@ -0,0 +1,53 @@
+-- v1.4: artifacts (immutable snapshots), deliveries (export retries), correlations (external key -> job).
+
+CREATE TABLE IF NOT EXISTS artifacts (
+  tenant_id TEXT NOT NULL,
+  artifact_id TEXT NOT NULL,
+  artifact_type TEXT NOT NULL,
+  job_id TEXT NOT NULL,
+  at_chain_hash TEXT NOT NULL,
+  source_event_id TEXT NOT NULL,
+  artifact_hash TEXT NOT NULL,
+  artifact_json JSONB NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  PRIMARY KEY (tenant_id, artifact_id)
+);
+
+CREATE INDEX IF NOT EXISTS artifacts_by_job ON artifacts (tenant_id, job_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS artifacts_by_type ON artifacts (tenant_id, artifact_type, created_at DESC);
+
+CREATE TABLE IF NOT EXISTS deliveries (
+  id BIGSERIAL PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  destination_id TEXT NOT NULL,
+  artifact_type TEXT NOT NULL,
+  artifact_id TEXT NOT NULL,
+  artifact_hash TEXT NOT NULL,
+  dedupe_key TEXT NOT NULL,
+  state TEXT NOT NULL DEFAULT 'pending', -- pending|delivered|failed
+  attempts INTEGER NOT NULL DEFAULT 0,
+  next_attempt_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  claimed_at TIMESTAMPTZ,
+  worker TEXT,
+  last_status INTEGER,
+  last_error TEXT,
+  delivered_at TIMESTAMPTZ,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  UNIQUE (tenant_id, dedupe_key)
+);
+
+CREATE INDEX IF NOT EXISTS deliveries_due ON deliveries (tenant_id, state, next_attempt_at, id);
+
+CREATE TABLE IF NOT EXISTS correlations (
+  tenant_id TEXT NOT NULL,
+  site_id TEXT NOT NULL,
+  correlation_key TEXT NOT NULL,
+  job_id TEXT NOT NULL,
+  expires_at TIMESTAMPTZ,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  PRIMARY KEY (tenant_id, site_id, correlation_key)
+);
+
+CREATE INDEX IF NOT EXISTS correlations_by_job ON correlations (tenant_id, job_id);
+

package/src/db/migrations/008_delivery_ingest_hardening.sql

@@ -0,0 +1,52 @@
+-- v1.4.1: delivery ordering + receipts + ingest external event id dedupe/DLQ.
+
+-- Deliveries: ordering + ACK status.
+ALTER TABLE deliveries ADD COLUMN IF NOT EXISTS scope_key TEXT NOT NULL DEFAULT '';
+ALTER TABLE deliveries ADD COLUMN IF NOT EXISTS order_seq BIGINT NOT NULL DEFAULT 0;
+ALTER TABLE deliveries ADD COLUMN IF NOT EXISTS priority INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE deliveries ADD COLUMN IF NOT EXISTS order_key TEXT;
+ALTER TABLE deliveries ADD COLUMN IF NOT EXISTS acked_at TIMESTAMPTZ;
+ALTER TABLE deliveries ADD COLUMN IF NOT EXISTS ack_received_at TIMESTAMPTZ;
+
+CREATE INDEX IF NOT EXISTS deliveries_order
+  ON deliveries (tenant_id, state, next_attempt_at, scope_key, order_seq, priority, id);
+
+-- Receiver ACK receipts (idempotent per delivery).
+CREATE TABLE IF NOT EXISTS delivery_receipts (
+  tenant_id TEXT NOT NULL,
+  delivery_id BIGINT NOT NULL,
+  destination_id TEXT NOT NULL,
+  artifact_hash TEXT NOT NULL,
+  received_at TIMESTAMPTZ,
+  acked_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  PRIMARY KEY (tenant_id, delivery_id)
+);
+
+CREATE INDEX IF NOT EXISTS delivery_receipts_by_destination
+  ON delivery_receipts (tenant_id, destination_id, acked_at DESC);
+
+-- Ingest dedupe + rejection tracking (DLQ).
+CREATE TABLE IF NOT EXISTS ingest_records (
+  tenant_id TEXT NOT NULL,
+  source TEXT NOT NULL,
+  external_event_id TEXT NOT NULL,
+  status TEXT NOT NULL, -- accepted|rejected
+  reason TEXT,
+  job_id TEXT,
+  site_id TEXT,
+  correlation_key TEXT,
+  event_type TEXT,
+  event_at TIMESTAMPTZ,
+  received_at TIMESTAMPTZ,
+  accepted_event_id TEXT,
+  record_json JSONB NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  PRIMARY KEY (tenant_id, source, external_event_id)
+);
+
+CREATE INDEX IF NOT EXISTS ingest_records_by_status
+  ON ingest_records (tenant_id, status, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS ingest_records_by_job
+  ON ingest_records (tenant_id, job_id, created_at DESC);
+

package/src/db/migrations/009_auth_keys.sql

@@ -0,0 +1,21 @@
+-- v1.5: tenant-scoped API auth keys (hashed secrets + scopes + lifecycle).
+
+CREATE TABLE IF NOT EXISTS auth_keys (
+  tenant_id TEXT NOT NULL,
+  key_id TEXT NOT NULL,
+  secret_hash TEXT NOT NULL,
+  scopes TEXT[] NOT NULL,
+  status TEXT NOT NULL CHECK (status IN ('active','rotated','revoked')),
+  description TEXT,
+  expires_at TIMESTAMPTZ,
+  last_used_at TIMESTAMPTZ,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  rotated_at TIMESTAMPTZ,
+  revoked_at TIMESTAMPTZ,
+  PRIMARY KEY (tenant_id, key_id)
+);
+
+CREATE INDEX IF NOT EXISTS auth_keys_by_tenant_status
+  ON auth_keys (tenant_id, status, key_id);
+

package/src/db/migrations/010_signer_keys.sql

@@ -0,0 +1,25 @@
+-- v1.6: tenant-scoped signer key registry (purpose + lifecycle).
+
+CREATE TABLE IF NOT EXISTS signer_keys (
+  tenant_id TEXT NOT NULL,
+  key_id TEXT NOT NULL,
+  public_key_pem TEXT NOT NULL,
+  purpose TEXT NOT NULL CHECK (purpose IN ('robot','operator','server')),
+  status TEXT NOT NULL CHECK (status IN ('active','rotated','revoked')),
+  description TEXT,
+  valid_from TIMESTAMPTZ,
+  valid_to TIMESTAMPTZ,
+  last_used_at TIMESTAMPTZ,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  rotated_at TIMESTAMPTZ,
+  revoked_at TIMESTAMPTZ,
+  PRIMARY KEY (tenant_id, key_id)
+);
+
+CREATE INDEX IF NOT EXISTS signer_keys_by_tenant_status
+  ON signer_keys (tenant_id, status, key_id);
+
+CREATE INDEX IF NOT EXISTS signer_keys_by_tenant_purpose
+  ON signer_keys (tenant_id, purpose, key_id);
+

package/src/db/migrations/011_ops_audit.sql

@@ -0,0 +1,33 @@
+-- v1.8: append-only ops audit log for privileged actions.
+
+CREATE TABLE IF NOT EXISTS ops_audit (
+  id BIGSERIAL PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  actor_key_id TEXT,
+  actor_principal_id TEXT,
+  action TEXT NOT NULL,
+  target_type TEXT,
+  target_id TEXT,
+  request_id TEXT,
+  at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  details_hash TEXT NOT NULL,
+  details_json JSONB
+);
+
+CREATE INDEX IF NOT EXISTS ops_audit_by_tenant_at
+  ON ops_audit (tenant_id, at DESC, id DESC);
+
+CREATE OR REPLACE FUNCTION ops_audit_immutable() RETURNS trigger AS $$
+BEGIN
+  RAISE EXCEPTION 'ops_audit is immutable';
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS ops_audit_no_update ON ops_audit;
+CREATE TRIGGER ops_audit_no_update BEFORE UPDATE ON ops_audit
+FOR EACH ROW EXECUTE FUNCTION ops_audit_immutable();
+
+DROP TRIGGER IF EXISTS ops_audit_no_delete ON ops_audit;
+CREATE TRIGGER ops_audit_no_delete BEFORE DELETE ON ops_audit
+FOR EACH ROW EXECUTE FUNCTION ops_audit_immutable();
+

package/src/db/migrations/012_retention.sql

@@ -0,0 +1,16 @@
+-- v1.9: retention support (expires_at) for high-volume tables.
+
+ALTER TABLE ingest_records
+  ADD COLUMN IF NOT EXISTS expires_at TIMESTAMPTZ;
+
+CREATE INDEX IF NOT EXISTS ingest_records_by_expires
+  ON ingest_records (tenant_id, expires_at)
+  WHERE expires_at IS NOT NULL;
+
+ALTER TABLE deliveries
+  ADD COLUMN IF NOT EXISTS expires_at TIMESTAMPTZ;
+
+CREATE INDEX IF NOT EXISTS deliveries_by_expires
+  ON deliveries (tenant_id, expires_at)
+  WHERE expires_at IS NOT NULL;
+

package/src/db/migrations/013_perf_indexes.sql

@@ -0,0 +1,18 @@
+-- v2.0: performance indexes for hot ops/worker queries.
+
+-- Outbox: claim scans benefit from a partial index on pending rows.
+CREATE INDEX IF NOT EXISTS outbox_pending_by_topic_claimed
+  ON outbox (topic, claimed_at, attempts, id)
+  WHERE processed_at IS NULL;
+
+-- Deliveries: ops listing is ordered by id DESC and filtered by tenant/state.
+CREATE INDEX IF NOT EXISTS deliveries_by_tenant_id_desc
+  ON deliveries (tenant_id, id DESC);
+
+CREATE INDEX IF NOT EXISTS deliveries_by_tenant_state_id_desc
+  ON deliveries (tenant_id, state, id DESC);
+
+-- Ingest records: DLQ listing is ordered by received_at/created_at.
+CREATE INDEX IF NOT EXISTS ingest_records_by_tenant_status_received
+  ON ingest_records (tenant_id, status, received_at DESC, created_at DESC);
+

package/src/db/migrations/014_contracts_v2.sql

@@ -0,0 +1,68 @@
+-- v2.0: contracts-as-code (hash-addressed contract documents + signatures).
+
+CREATE TABLE IF NOT EXISTS contracts_v2 (
+  tenant_id TEXT NOT NULL DEFAULT 'tenant_default',
+  contract_id TEXT NOT NULL,
+  contract_version INTEGER NOT NULL,
+
+  status TEXT NOT NULL DEFAULT 'DRAFT', -- DRAFT|PUBLISHED|ACTIVE|SUPERSEDED|TERMINATED
+  effective_from TIMESTAMPTZ,
+  effective_to TIMESTAMPTZ,
+
+  contract_hash TEXT, -- sha256 hex of canonical ContractDocument bytes; set on publish
+  policy_hash TEXT,   -- hash of compiled contract policy template; set on activate (semantics v2)
+  compiler_id TEXT,   -- compiler identifier recorded on activate
+
+  scope_customer_id TEXT,
+  scope_site_id TEXT,
+  scope_zone_id TEXT,
+  scope_template_id TEXT,
+  scope_skill_id TEXT,
+
+  doc_json JSONB NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+
+  PRIMARY KEY (tenant_id, contract_id, contract_version)
+);
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_indexes WHERE schemaname = current_schema() AND indexname = 'contracts_v2_contract_hash_unique'
+  ) THEN
+    CREATE UNIQUE INDEX contracts_v2_contract_hash_unique ON contracts_v2 (tenant_id, contract_hash) WHERE contract_hash IS NOT NULL;
+  END IF;
+END $$;
+
+CREATE INDEX IF NOT EXISTS contracts_v2_by_status ON contracts_v2 (tenant_id, status, effective_from DESC NULLS LAST, contract_id, contract_version);
+CREATE INDEX IF NOT EXISTS contracts_v2_by_scope ON contracts_v2 (
+  tenant_id,
+  scope_customer_id,
+  scope_site_id,
+  scope_zone_id,
+  scope_template_id,
+  scope_skill_id,
+  status
+);
+
+CREATE TABLE IF NOT EXISTS contract_signatures_v2 (
+  tenant_id TEXT NOT NULL DEFAULT 'tenant_default',
+  contract_hash TEXT NOT NULL,
+  party_role TEXT NOT NULL, -- platform|operator|customer
+  signer_key_id TEXT NOT NULL,
+  signature TEXT NOT NULL, -- base64 signature over contract_hash (hex bytes)
+  signed_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  PRIMARY KEY (tenant_id, contract_hash, party_role)
+);
+
+CREATE TABLE IF NOT EXISTS contract_compilations_v2 (
+  tenant_id TEXT NOT NULL DEFAULT 'tenant_default',
+  contract_hash TEXT NOT NULL,
+  policy_hash TEXT NOT NULL,
+  compiler_id TEXT NOT NULL,
+  diagnostics_json JSONB,
+  compiled_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  PRIMARY KEY (tenant_id, contract_hash, policy_hash, compiler_id)
+);
+

package/src/db/migrations/015_parties.sql

@@ -0,0 +1,16 @@
+-- v1.?: parties registry for Connect-style settlement
+
+CREATE TABLE IF NOT EXISTS parties (
+  tenant_id TEXT NOT NULL,
+  party_id TEXT NOT NULL,
+  party_role TEXT NOT NULL, -- 'platform' | 'operator' | 'customer' | 'subcontractor' | 'insurer'
+  display_name TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'active', -- 'active' | 'suspended' | 'terminated'
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+
+  PRIMARY KEY (tenant_id, party_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_parties_role ON parties(tenant_id, party_role, status);
+

package/src/db/migrations/016_ledger_allocations.sql

@@ -0,0 +1,18 @@
+-- v1.?: per-party attribution for each ledger posting (Connect v1)
+
+CREATE TABLE IF NOT EXISTS ledger_allocations (
+  tenant_id TEXT NOT NULL,
+  entry_id TEXT NOT NULL,
+  posting_id TEXT NOT NULL, -- stable posting index within entry.postings (e.g. 'p0', 'p1')
+  party_id TEXT NOT NULL,
+  party_role TEXT NOT NULL, -- 'platform' | 'operator' | 'customer' | 'subcontractor' | 'insurer'
+  currency TEXT NOT NULL,
+  amount_cents BIGINT NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+
+  PRIMARY KEY (tenant_id, entry_id, posting_id, party_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_ledger_allocations_party ON ledger_allocations(tenant_id, party_id, created_at);
+CREATE INDEX IF NOT EXISTS idx_ledger_allocations_entry ON ledger_allocations(tenant_id, entry_id);
+

package/src/db/migrations/017_party_statements.sql

@@ -0,0 +1,31 @@
+-- v1.7: Party statements (Connect v1 rollups) + allocation metadata.
+
+-- Ledger allocations: carry account_id to support statement breakdown/payout derivation without re-parsing ledger entry JSON.
+ALTER TABLE ledger_allocations
+  ADD COLUMN IF NOT EXISTS account_id TEXT;
+
+CREATE INDEX IF NOT EXISTS idx_ledger_allocations_entry_posting
+  ON ledger_allocations(tenant_id, entry_id, posting_id);
+
+-- Per-party monthly statements (closeable, immutable once closed).
+CREATE TABLE IF NOT EXISTS party_statements (
+  tenant_id TEXT NOT NULL,
+  party_id TEXT NOT NULL,
+  period TEXT NOT NULL, -- YYYY-MM
+  basis TEXT NOT NULL DEFAULT 'settledAt',
+  status TEXT NOT NULL DEFAULT 'OPEN', -- OPEN|CLOSED
+  statement_hash TEXT NOT NULL,
+  artifact_id TEXT NOT NULL,
+  artifact_hash TEXT NOT NULL,
+  closed_at TIMESTAMPTZ,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  PRIMARY KEY (tenant_id, party_id, period)
+);
+
+CREATE INDEX IF NOT EXISTS party_statements_by_period_status
+  ON party_statements(tenant_id, period, status);
+
+CREATE INDEX IF NOT EXISTS party_statements_by_party_period
+  ON party_statements(tenant_id, party_id, period);
+

package/src/db/migrations/018_finance_account_map.sql

@@ -0,0 +1,12 @@
+-- vNext: tenant-scoped finance account mapping (GL export mapping).
+
+CREATE TABLE IF NOT EXISTS finance_account_maps (
+  tenant_id TEXT PRIMARY KEY,
+  mapping_hash TEXT NOT NULL,
+  mapping_json JSONB NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS finance_account_maps_updated_at ON finance_account_maps (updated_at DESC);
+

package/src/db/migrations/019_ledger_allocations_account_id.sql

@@ -0,0 +1,7 @@
+-- vNext: ledger allocations include account_id for finance exports and statement classification.
+
+ALTER TABLE ledger_allocations
+  ADD COLUMN IF NOT EXISTS account_id TEXT;
+
+CREATE INDEX IF NOT EXISTS idx_ledger_allocations_account ON ledger_allocations(tenant_id, account_id);
+

package/src/db/migrations/020_artifacts_source_event_unique.sql

@@ -0,0 +1,10 @@
+-- v1.??: enforce one artifact per (job + type + source_event_id) when source_event_id is present.
+-- This prevents duplicate settlement-backed WorkCertificates and similar finance-final artifacts.
+
+CREATE UNIQUE INDEX IF NOT EXISTS artifacts_unique_by_job_type_source_event
+  ON artifacts (tenant_id, job_id, artifact_type, source_event_id)
+  WHERE source_event_id <> '';
+
+CREATE INDEX IF NOT EXISTS artifacts_by_job_type_source_event
+  ON artifacts (tenant_id, job_id, artifact_type, source_event_id);
+

package/src/db/migrations/021_artifacts_by_job_created_at_id.sql

@@ -0,0 +1,6 @@
+-- v1.??: support stable pagination and deterministic ordering for per-job artifact listing.
+-- Order contract: created_at DESC, artifact_id DESC.
+
+CREATE INDEX IF NOT EXISTS artifacts_by_job_created_at_id
+  ON artifacts (tenant_id, job_id, created_at DESC, artifact_id DESC);
+

package/src/db/migrations/022_governance_uniqueness.sql

@@ -0,0 +1,28 @@
+-- v1.15: governance semantic uniqueness constraints (DB-backed).
+
+-- Tenant governance: only one TENANT_POLICY_UPDATED per effectiveFrom per tenant.
+CREATE UNIQUE INDEX IF NOT EXISTS governance_tenant_policy_effective_from_unique
+  ON events (tenant_id, (payload_json->>'effectiveFrom'))
+  WHERE aggregate_type = 'month'
+    AND aggregate_id = 'governance'
+    AND type = 'TENANT_POLICY_UPDATED';
+
+-- Global governance: server signer key lifecycle uniqueness.
+CREATE UNIQUE INDEX IF NOT EXISTS governance_server_key_registered_unique
+  ON events (tenant_id, (payload_json->>'keyId'))
+  WHERE aggregate_type = 'month'
+    AND aggregate_id = 'governance'
+    AND type = 'SERVER_SIGNER_KEY_REGISTERED';
+
+CREATE UNIQUE INDEX IF NOT EXISTS governance_server_key_revoked_unique
+  ON events (tenant_id, (payload_json->>'keyId'))
+  WHERE aggregate_type = 'month'
+    AND aggregate_id = 'governance'
+    AND type = 'SERVER_SIGNER_KEY_REVOKED';
+
+CREATE UNIQUE INDEX IF NOT EXISTS governance_server_key_rotated_old_unique
+  ON events (tenant_id, (payload_json->>'oldKeyId'))
+  WHERE aggregate_type = 'month'
+    AND aggregate_id = 'governance'
+    AND type = 'SERVER_SIGNER_KEY_ROTATED';
+

package/src/db/migrations/023_marketplace_tasks.sql

@@ -0,0 +1,45 @@
+-- v1.16: persist marketplace tasks and bids for cross-process durability.
+
+CREATE TABLE IF NOT EXISTS marketplace_tasks (
+  tenant_id TEXT NOT NULL,
+  task_id TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'open',
+  capability TEXT,
+  poster_agent_id TEXT,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  task_json JSONB NOT NULL,
+  PRIMARY KEY (tenant_id, task_id)
+);
+
+CREATE INDEX IF NOT EXISTS marketplace_tasks_by_tenant_status_created
+  ON marketplace_tasks (tenant_id, status, created_at DESC, task_id DESC);
+
+CREATE INDEX IF NOT EXISTS marketplace_tasks_by_tenant_capability_status_created
+  ON marketplace_tasks (tenant_id, capability, status, created_at DESC, task_id DESC);
+
+CREATE INDEX IF NOT EXISTS marketplace_tasks_by_tenant_poster_status_created
+  ON marketplace_tasks (tenant_id, poster_agent_id, status, created_at DESC, task_id DESC);
+
+CREATE TABLE IF NOT EXISTS marketplace_task_bids (
+  tenant_id TEXT NOT NULL,
+  task_id TEXT NOT NULL,
+  bid_id TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'pending',
+  bidder_agent_id TEXT,
+  amount_cents BIGINT,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  bid_json JSONB NOT NULL,
+  PRIMARY KEY (tenant_id, task_id, bid_id),
+  CONSTRAINT marketplace_task_bids_task_fkey
+    FOREIGN KEY (tenant_id, task_id)
+    REFERENCES marketplace_tasks (tenant_id, task_id)
+    ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS marketplace_task_bids_by_task_status_amount_created
+  ON marketplace_task_bids (tenant_id, task_id, status, amount_cents ASC, created_at ASC, bid_id ASC);
+
+CREATE INDEX IF NOT EXISTS marketplace_task_bids_by_task_bidder_status
+  ON marketplace_task_bids (tenant_id, task_id, bidder_agent_id, status, bid_id ASC);