Data Vault Reference

-- store.store
create table store (
  id            uuid primary key,
  legal_name    text not null,
  display_name  text not null,
  banner        text,
  corridor_id   uuid references corridor(id),
  geo           geography(point, 4326),
  cuisine_tags  text[],
  heritage_tier int  not null default 1,
  onboarded_at  timestamptz not null default now(),
  active        boolean not null default true
);

-- catalog.sku
create table sku (
  id              uuid primary key,
  gtin            text unique,
  name_en         text not null,
  name_native     jsonb not null,        -- {ar, ur, es, bn, fa, tr, fr...}
  category        text not null,
  heritage        boolean not null default false,
  origin_country  text,
  origin_region   text,
  certifications  jsonb,
  shelf_life_days int,
  unit            text not null
);

-- store.shelf
create table shelf (
  store_id  uuid references store(id),
  sku_id    uuid references sku(id),
  qty       numeric not null,
  expires   date,
  updated   timestamptz not null,
  primary key (store_id, sku_id, expires)
);

-- supply.supplier
create table supplier (
  id           uuid primary key,
  name         text not null,
  origin       text not null,
  reliability  numeric not null default 0.5,
  lanes        text[],
  certifications jsonb
);

-- supply.shipment
create table shipment (
  id           uuid primary key,
  supplier_id  uuid references supplier(id),
  lane         text not null,
  payload      jsonb not null,            -- [{sku_id, qty}]
  shipped_at   timestamptz,
  eta          timestamptz,
  arrived_at   timestamptz,
  status       text not null default 'planned'
);

// All events are append-only, partitioned by store_id (or supplier_id for L3).
type Event =
  | Scan
  | Reorder
  | Expire
  | Shipment
  | HouseholdSignal
  | SupplyTick
  | RefrigerationTick
  | Exception;

interface Envelope<T extends Event> {
  id:        string;             // ulid
  ts:        string;             // ISO-8601
  source:    "pos" | "shelf" | "app" | "supplier" | "system";
  store_id?: string;
  supplier_id?: string;
  payload:   T;
  trace_id:  string;
  schema_v:  number;
}

// Consumers
//  · Demand-V2          → forecast/sku/{store_id}
//  · Restock-Policy(RL) → action/restock/{store_id}
//  · Lane-Health        → forecast/lane/{lane_id}
//  · Substitution-Graph → graph/sub/{sku_id}
//  · Merchant-LLM       → channel/merchant/{store_id}

// 1. POS → Spine (every scan)
POST /v1/spine/scan
  headers: x-store-key, x-trace
  body:    { sku_gtin, qty, price, ts }

// 2. Spine → Restock-Policy (every minute, per store)
GET  /v1/policy/restock/:store_id
  → 200 { actions: [{ sku_id, qty, supplier_id, by }] }

// 3. Restock-Policy → Supplier API (handshake)
POST /v1/supply/order
  body: { supplier_id, lane, items, requested_eta }
  → 202 { shipment_id, confirmed_eta, lane_risk }

// 4. Customer App → Spine (intent)
POST /v1/intent/basket
  body: { hh_id, items: [{sku_gtin, qty}], geo }
  → 200 { fulfillment: { mesh_node, eta_min, batched_with } }

// 5. B2B Subscriber → Data Orchestration
POST /v1/data/query
  headers: x-tier (silver|gold|sovereign)
  body:    { cohort, metric, window, geo }
  → 200 { series: [...], confidence }