Projexlight Common Services, Agents, HDK & AIM

1 · Overview

Every vertical we ship — Shantam (Seva), Kiana (Realty), Music/Video, BidWork, LeadPulse, FieldOps, OneEstate, future Wellness and Healthcare — reuses 80–90% of the same plumbing: identity, payments, notifications, content, search, analytics, audit, AI gateway, geospatial, dispatch, evidence capture, and a dozen platform agents. Re-implementing this per vertical is the single largest source of waste and the single largest source of drift.

This document describes that shared layer in its v3.1 (complete) form: what lives in projex_common/, the contracts that make it consumable, the HDK native SDKs that field-grade apps depend on, the AIM pool model that lets the platform grow from 1k to 1M+ tenants and petabyte-scale data, the six-layer identity stack that handles every cross-app / cross-tenant scenario the team has identified, and the discipline that keeps it shared rather than copy-pasted.

2 · What's in v3.1 — Quick Map

v3.1 = v2 (complete platform) ∪ v3 (AIM hardening). The table below shows where each capability area lives in this document.

3 · The Three Build-Time Disciplines

Reuse only holds if these three rules are enforced from day one. Every architectural decision in this document derives from one of them.

3A · Opinionated Constraints Doctrine v3.1

The biggest risk to a platform this size is not technology — it is unbounded flexibility. When everything is configurable, nothing is optimizable; developers route around the platform; the rule-of-three governance gets overwhelmed by edge cases. v3.1 commits to a small set of opinionated, lint-enforced constraints that say "this is the way" — and CI rejects anything else.

3A.1 · The constraints

3A.2 · What "opinionated" explicitly forbids

• No alternative routing. If a vertical thinks Pool Router is too slow for their workload, the answer is to fix Pool Router — not write their own. Forks of routing logic are banned.
• No alternative metering. If sdk-meter doesn't price your method correctly, file a catalog issue — don't write a per-vertical billing surface.
• No alternative identity store. If a vertical needs a "lightweight user" concept, the answer is to use Persona with a minimal extension — not to create a parallel user table.
• No alternative event bus. No vertical-private Kafka clusters. If you need topic separation, register a new namespace in the EventTypeRegistry.
• No "we'll add metering later". Methods ship with @meter from PR #1 or they don't ship.

3B · "Localize Complexity" Principle v3.1

Complement to §3A. Where §3A says "this is the only allowed pattern," §3B says "this complexity belongs HERE and only here." The rule: global standards, local behaviors. Anything global has to be agreed by Working Groups; anything local can be decided by the vertical owning it.

3B.1 · Global vs Local table

3B.2 · The rule for deciding global vs local

4 · Architecture Principles

P1–P10 carry forward from v2 unchanged. P11–P15 are introduced by v3 and now form the AIM-hardening core.

5 · Client Platform Strategy

One mobile framework. One web framework. One native SDK layer. One TypeScript contract spanning all three. The decision is locked; the table below records the trade-off so it stays auditable.

Why not Flutter

• Contracts. @projexlight/contracts is TypeScript. Flutter would need a parallel Dart contracts package — breaks discipline #2.
• Web sharing. RN + react-native-web shares business logic with React Web. Flutter Web is not credible at production for this workload.
• "Native performance" parity is a myth here. Camera, AR, AprilTag, biometric are native modules in either world.
• Org throughput. RN keeps backend, web, mobile, and SDK contracts in one language.

6 · HDK — Native SDK Ecosystem

The Hexa Development Kit (HDK) is the native counterpart to the JS/TS SDK packages. It owns the device-side capabilities that the platform needs to ship evidence-grade, offline-capable, sensor-driven experiences. Every HDK module is built once in Kotlin (Android) and Swift (iOS), bridged into React Native, and surfaced behind a TypeScript facade whose contract is registered in @projexlight/contracts.

flowchart TB
  classDef rn fill:#0f1422,stroke:#6aa9ff,color:#e6ecf5;
  classDef bridge fill:#1a2234,stroke:#c9a86a,color:#e6ecf5;
  classDef native fill:#241622,stroke:#ff6b6b,color:#e6ecf5;
  classDef ctr fill:#16241c,stroke:#5dd39e,color:#e6ecf5;

  RN["React Native app
(SevaApp · RealtyApp · FieldOpsApp · HealthcareApp · KioskApp)"]:::rn
  TS["TypeScript facade
@projexlight/hdk-* packages"]:::bridge
  CTR["@projexlight/contracts
HDK module interfaces · identity layers"]:::ctr
  AND["Android Native
Kotlin · AndroidX · CameraX"]:::native
  IOS["iOS Native
Swift · AVFoundation · CoreMotion"]:::native

  RN --> TS --> AND
  TS --> IOS
  TS -. types .-> CTR
  AND -. emits envelope events with encounter_id .-> RN
  IOS -. emits envelope events with encounter_id .-> RN
    

6.1 · The ten HDK modules

6.2 · HDK installation order

1. @projexlight/contracts           (TS shapes, no native deps)
2. @projexlight/sdk-identity         (TS facade)
3. @projexlight/sdk-pool-router      (TS — required by every data-touching module)
4. @projexlight/hdk-idp              (native: biometric, PIN)
5. @projexlight/hdk-permissions      (native: layered enforcement)
6. @projexlight/hdk-diagnostic       (native: telemetry — required by all subsequent)
7. @projexlight/hdk-camera           (native: depends on permissions + diagnostic)
8. @projexlight/hdk-map              (native: depends on permissions)
9. @projexlight/hdk-scanner          (native: optional, depends on camera)
10. @projexlight/hdk-image-editor    (TS + native renderer)
11. @projexlight/hdk-video-editor    (TS + native renderer)
12. @projexlight/hdk-measure         (native: depends on camera + AR)
13. @projexlight/hdk-watermark       (TS + native renderer)

6A · Conflict Resolution Model for HDK Offline Sync v3.1

Every HDK module that does offline-write (camera, map, scanner, image-editor, video-editor, measure, watermark) eventually faces the same problem: multiple devices, multiple users, concurrent edits, offline windows, then reconnect. Without a centralized model, every module reinvents conflict handling — and field-ops verticals hit unresolvable collisions in week 1 of production.

6A.1 · The five resolution strategies

Every event type registered in the EventTypeRegistry (§8B + sdk-audit) declares one of these strategies as its conflict_policy. hdk-sync reads the policy and applies it on reconnect.

6A.2 · How a conflict is resolved (the flow)

sequenceDiagram
  participant D1 as Device 1 (offline)
  participant D2 as Device 2 (offline)
  participant SYNC as hdk-sync
  participant POL as ConflictPolicy
(from contracts)
  participant AUD as sdk-audit
  participant HR as Human-Review queue
(if needed)

  D1->>D1: Edit at t=10 (offline)
  D2->>D2: Edit at t=12 (offline)

  Note over D1,D2: Both reconnect

  D1->>SYNC: Replay queue: edit@t=10
  D2->>SYNC: Replay queue: edit@t=12

  SYNC->>POL: getPolicy(event_type)
  POL->>SYNC: strategy=CRDT|LWW|merge|event-sourcing|human-review

  alt CRDT
    SYNC->>SYNC: mathematical merge → single state
    SYNC->>AUD: record both inputs + merged output
  else LWW
    SYNC->>SYNC: t=12 wins (newer)
    SYNC->>AUD: record loser t=10 in audit
  else Merge Policy
    SYNC->>SYNC: field-level merge — if collision → escalate
    SYNC->>AUD: record per-field decisions
  else Event Sourcing
    SYNC->>SYNC: append both in causal order
    SYNC->>AUD: full event history preserved
  else Human Review
    SYNC->>HR: queue both versions with diff
    HR->>SYNC: human picks winner
    SYNC->>AUD: record human decision + reason
  end

  SYNC->>D1: ack with resolved state
  SYNC->>D2: ack with resolved state
    

6A.3 · What contracts owns

// In @projexlight/contracts/conflict.ts

export type ConflictPolicy =
  | { kind: 'crdt'; type: 'g-counter' | 'pn-counter' | 'lww-set' | 'or-set' | 'rga-text' }
  | { kind: 'lww' }
  | { kind: 'merge'; field_policies: Record<string, FieldPolicy> }
  | { kind: 'event-sourcing' }
  | { kind: 'human-review'; queue: string; delegation: ApprovalRoute };

export type FieldPolicy = 'additive' | 'max' | 'min' | 'last-write' | 'veto-conflict';

// Each event type in the EventTypeRegistry declares its policy:
export const EventTypeRegistry = {
  'content.note.edit.v1':   { policy: { kind: 'crdt', type: 'rga-text' }, ... },
  'device.location.update.v1': { policy: { kind: 'lww' }, ... },
  'payment.charge.v1':      { policy: { kind: 'event-sourcing' }, ... },
  'profile.pii.update.v1':  { policy: { kind: 'human-review', queue: 'pii-review', delegation: 'tenant-admin' }, ... },
  // ... every event type registered
} as const;

6A.4 · Guarantees

• No silent data loss. Every conflict produces an audit entry with both inputs and the resolved output. Losing writes are recorded, not discarded.
• Per-event-type discipline. Authors choose a policy once when registering an event type; resolution is mechanical thereafter. No "we forgot to handle this conflict" surprises.
• Human-review queue bounded. Only events declared human-review consume human attention. CRDT / LWW / event-sourcing / merge handle 90%+ of conflicts without humans.
• Audit chain integrity preserved. The audit hash chain records the resolution decision; tamper-evident verification still works across reconnects.
• Replay-safe. hdk-sync's replay engine is idempotent; re-applying the queue produces identical resolutions (composes with deterministic replay for agents — see §18A).

7 · Identity Foundation — Three Pillars + Six Layers

The enterprise identity stack rests on three pillars (carried from v2) and is expressed through a six-layer entity stack (introduced in v3).

7.1 · The scope hierarchy — four scope levels

7.2 · Canonical master entities (v2 baseline)

MDM holds these entities and their canonical IDs. Every other service and vertical stores its domain rows against these IDs — never duplicating personal, location, or device data.

7.3 · The six identity layers v3

v2 left identity at "person_id + tenant_id". v3 expands to a six-layer entity stack. Each layer answers a question no other layer can; each carries its own audit trail, encryption key tier, and consent gates.

7.4 · The full identity tuple on every request

{
  "person_id":           "pers_01HXYZ...",          // L1 master
  "app_id":              "healthcare",              // app scope
  "app_identity_id":     "apid_01HXYZ...",          // L2
  "tenant_id":           "ten_hosp_a",              // tenant scope
  "tenant_membership_id":"tmb_01HXYZ...",           // L3
  "persona_id":          "pers_01HXYZ_patient",     // L4
  "persona_role":        "patient",
  "encounter_id":        "enc_01HXYZ_visit_42",     // L5 optional
  "relationship_ids":    ["rel_01HXYZ_dr_smith"],   // L6 optional
  "device_uuid":         "dev_01HXYZ...",
  "consent_refs":        ["cnst_01HXYZ_phi_read"],
  "session_id":          "sess_01HXYZ..."
}

7.5 · Person bands — Profile · Preference · Notification · Secure Data

v2 introduced four bands of sensitivity hanging off the person. v3 re-homes them to their proper layer:

7.6 · MDM methodology — Registry · Consolidation · Coexistence · Centralization

The MDM layer is not a single style; it adapts per entity and per maturity. The four classic patterns live side-by-side:

7.7 · Cross-domain reuse — the system of system

The same identity foundation underpins every domain. Each domain adds extension schemas hanging off the canonical IDs and personas — it does not duplicate them.

8 · AIM Pool Architecture v3

The platform pivots from "Postgres per service" to "Postgres per service per pool" — and we add capacity by adding pools, not by sharding tables. This is the single largest scaling decision in v3.1.

8.1 · Why no sharding

8.2 · Pool families

8.3 · Pool indexing

Each pool is identified by a stable, never-reused index: admin-001, app-onestate-014, app-healthcare-007, evidence-003.

// Tenant row in the Pool Registry
{
  "tenant_id":          "ten_01HXYZ...",
  "org_id":             "org_proj_in",
  "isolation_tier":     "S | P | G",
  "region":             "ap-south-1",
  "admin_pool_index":   "admin-014",
  "app_pool_index": {
    "healthcare":       "app-healthcare-007",
    "ecommerce":        "app-ecommerce-022",
    "onestate":         "app-onestate-004",
    "seva":             "app-seva-002"
  },
  "evidence_pool_index":"evidence-003",
  "status":             "ACTIVE | PROVISIONING | MIGRATING | SUSPENDED | TOMBSTONE"
}

8.4 · Pool capacity targets

8.5 · Scale projection

flowchart TB
  classDef router fill:#1a2234,stroke:#c9a86a,color:#e6ecf5;
  classDef admin fill:#0f1422,stroke:#6aa9ff,color:#e6ecf5;
  classDef appp fill:#16241c,stroke:#5dd39e,color:#e6ecf5;
  classDef ev fill:#241622,stroke:#ff6b6b,color:#e6ecf5;
  classDef ten fill:#1d1830,stroke:#b88dff,color:#e6ecf5;

  T1["Hospital A · tier S"]:::ten
  T2["Hospital B · tier P"]:::ten
  T3["Shantam · tier S"]:::ten
  T4["ContractorCo · tier S"]:::ten
  T5["KianaRealty · tier G"]:::ten

  ROUTER["Pool Router"]:::router

  AP1[("admin-001
~3000 tenants")]:::admin
  AP2[("admin-002
~2500 tenants")]:::admin

  HC1[("app-healthcare-001")]:::appp
  HC2[("app-healthcare-002")]:::appp
  EC1[("app-ecommerce-001")]:::appp
  SV1[("app-seva-001")]:::appp
  FO1[("app-fieldops-001")]:::appp
  RE1[("app-realty-001 · dedicated")]:::appp

  EV1[("evidence-001")]:::ev
  EV2[("evidence-002")]:::ev

  T1 --> ROUTER
  T2 --> ROUTER
  T3 --> ROUTER
  T4 --> ROUTER
  T5 --> ROUTER
  ROUTER -. admin .-> AP1
  ROUTER -. admin .-> AP2
  T1 -. healthcare .-> HC1
  T2 -. healthcare .-> HC2
  T3 -. seva .-> SV1
  T4 -. fieldops .-> FO1
  T5 -. realty .-> RE1
  T2 -. ecommerce .-> EC1
  T1 -. evidence .-> EV1
  T2 -. evidence .-> EV2
  T4 -. evidence .-> EV1
    

8A · Pool Placement Matrix v3.1

Every SDK's data has to land in some pool. Without an explicit matrix, each SDK team makes its own placement decision and the petabyte-scale isolation guarantees from §8 erode. This section is the canonical authority — every new SDK declares its placement here before merging contracts.

8A.1 · Pool families (recap + extensions)

8A.2 · Per-SDK pool placement

8A.3 · Three new primitives required by the v3.1 additions

1 · person_pool_residency registry

Required by sdk-data-rights for DSAR fan-out. Lives in person's home Admin Pool. Schema:

person_pool_residency (
  person_id           uuid not null,
  pool_index          text not null,            -- which pool holds data
  data_class          text not null,            -- 'persona-ext' | 'encounter' | 'relationship' | 'evidence' | 'agent-memory'
  first_touched_at    timestamptz not null,
  last_touched_at     timestamptz not null,
  primary key (person_id, pool_index, data_class)
)

Every data-bearing SDK writes a row on first-touch for a (person, pool, class) tuple. Weekly reconciliation job compares the registry against actual data presence — a discrepancy halts DSAR completion until investigated. Without this registry, "I erased this person's data" is unverifiable across hundreds of pools.

2 · Cross-pool lineage projection (Warehouse view)

Required by sdk-lineage. In-pool lineage edges (record A in App Pool X derived from record B in same App Pool X) stay in the pool's lineage subgraph for sync queries. Cross-pool lineage edges (parsed doc in Evidence Pool E → derived record in App Pool A → AI score from sdk-ai-gateway) are projected asynchronously into a Warehouse table:

warehouse.cross_pool_lineage (
  edge_id          uuid not null,
  source_pool      text not null,
  source_record    text not null,
  target_pool      text not null,
  target_record    text not null,
  edge_type        text not null,               -- 'extracted_from' | 'derived_from' | 'merged_from' | ...
  tenant_id        uuid not null,
  occurred_at      timestamptz not null
)

"Show me the full derivation chain for record X" first resolves in-pool, then queries the Warehouse projection for cross-pool hops. Hot path stays in-pool; cross-pool reasoning is async-acceptable.

3 · Sub-tenant pool placement policy: hybrid

When parent_tenant_id is set, the default policy is:

• Sub-tenant shares parent's Admin Pool and App Pools by default. The sub-tenant gets its own tenant_id, RLS isolates rows, audit and billing roll up through the parent chain via CTE traversal.
• A sub-tenant can opt out to Tier-P or Tier-G at provisioning or via migration. The Pool Capacity Steward allocates dedicated pools; audit roll-up still references the parent.
• This keeps the common case (50-hospital HIE, 500-franchise chain) cheap and simple, while preserving the option of premium isolation for sub-tenants that need it (a flagship hospital that wants its own pool for data residency or SLA).

8A.4 · The CI rules that keep this matrix honest

• Pool-placement declaration mandatory. Every new SDK PR must update this matrix; CI fails otherwise.
• Cross-pool reads require @cross_pool_sanctioned(reason). Only sdk-identity-resolver, sdk-data-rights, sdk-analytics, and sdk-lineage's warehouse projection are sanctioned. Any other SDK attempting cross-pool reads fails the build.
• Vector-store partitioning enforced. Lint blocks any agent or RAG SDK from constructing a vector-store client without a tenant-scoped namespace argument.
• Person-pool-residency write enforced. Lint blocks any data-bearing SDK from inserting a row referencing person_id without also upserting the residency registry.

8B · Polyglot Persistence Doctrine v3.1

Postgres is the right choice — but not for everything. v3.1 commits to polyglot persistence: each workload routed to the storage engine designed for it. The Pool Placement Matrix in §8A is the per-SDK lookup; this section is the principle that explains why.

8B.1 · The workload → storage map

8B.2 · The rules

9 · Pool Routing & Registry v3

The Pool Router resolves (tenant_id, app_id, pool_family) → connection string for every domain query. It is the most performance-critical lookup in the platform: p99 ≤ 5 ms.

9.1 · Registry data model

TABLE pool (
  pool_index            text primary key,
  pool_family           text,                 -- 'admin' | 'app' | 'evidence'
  app_id                text,                 -- only when family='app'
  region                text,
  status                text,                 -- ACTIVE | DRAINING | MAINTENANCE | RETIRED | QUARANTINE
  capacity_tenants      int,
  current_tenants       int,
  capacity_bytes        bigint,
  current_bytes         bigint,
  primary_endpoint      text,
  replica_endpoints     text[],
  kek_arn               text,
  isolation_class       text                  -- 'shared' | 'dedicated'
);

TABLE tenant_pool_map (
  tenant_id             text primary key,
  admin_pool_index      text references pool,
  evidence_pool_index   text references pool,
  app_pool_index        jsonb,
  region                text,
  status                text,
  created_at            timestamptz,
  migrated_at           timestamptz
);

9.2 · Resolution path

sequenceDiagram
  autonumber
  participant C as Client
  participant GW as API Gateway
  participant ID as Identity
  participant RT as Pool Router SDK
  participant CACHE as Redis
  participant REG as Pool Registry
  participant DB as App Pool

  C->>GW: POST /v1/encounters/E_001/notes
  GW->>ID: validate JWT, extract identity tuple
  ID-->>GW: { tenant_id, app_id=healthcare, person_id, ... }
  GW->>RT: route(tenant_id, app_id)
  RT->>CACHE: GET tenant:ten_001:pool:healthcare
  CACHE-->>RT: app-healthcare-007 (cache hit)
  RT-->>GW: dsn
  GW->>DB: query routed to app-healthcare-007 only
    

9.3 · Cache & consistency rules

• TTL. Tenant→pool entries cache 300s. Pool metadata 60s. Status flips broadcast invalidate.
• Local copy. Every service holds an in-process LRU (10k entries) over Redis.
• Cache miss. ≤ 5 ms Postgres read. p99 ≤ 20 ms cold.
• Migration safety. MIGRATING tenants route through the migration coordinator.

9.4 · SDK usage

import { withTenant } from "@projexlight/sdk-pool-router";

const result = await withTenant({ tenantId, appId: "healthcare" }, async (db) => {
  return await db.encounters.fetch({ id: encounterId });
});

The SDK refuses to issue an untenanted query against any application pool. Cross-tenant queries go through the warehouse.

v3.1 Every typed SDK method declared with @meter(...) is auto-wrapped at build time by sdk-meter's codegen so a check() precedes the call and a report() emits the usage event. SDK authors do not write metering code by hand. See §10A.

9.5 · What lives where

10 · Multi-Level Encryption — End-to-End

v2 established the four-tier key hierarchy (root · app · tenant · person/device/org). v3.1 keeps all of it and adds two tiers: Pool KEK (per pool) and Encounter Key (per encounter).

flowchart TB
  classDef root fill:#1a2234,stroke:#c9a86a,color:#e6ecf5;
  classDef pool fill:#0f1422,stroke:#6aa9ff,color:#e6ecf5;
  classDef ten fill:#16241c,stroke:#5dd39e,color:#e6ecf5;
  classDef per fill:#241622,stroke:#ff6b6b,color:#e6ecf5;
  classDef enc fill:#1d1830,stroke:#b88dff,color:#e6ecf5;

  ROOT["Regional Root CMK
HSM-backed (per region)"]:::root
  POOLK["Pool KEK (per pool) v3
wraps tenant keys held in pool"]:::pool
  TENK["Tenant Key (per tenant_id)
wraps memberships, personas, encounters"]:::ten
  PERK["Person Key (per person_id)
wraps master + secure-data + app identities"]:::per
  ENCK["Encounter Key (per encounter_id) v3
wraps medical/financial payloads"]:::enc
  DEVK["Device Key (per device_uuid)
wraps biometric templates"]:::per
  ORGK["Org Key (per org_id)
wraps cross-tenant rollups"]:::per

  ROOT --> POOLK
  POOLK --> TENK
  TENK --> ENCK
  ROOT --> PERK
  PERK --> DEVK
  ROOT --> ORGK
    

10.1 · What is encrypted where

10.2 · Right-to-erasure mechanics

10A · Metering, Pricing & Billing v3.1

Pay-as-you-use is the platform's structural billing model. Every typed SDK call is gated, metered, and priced per-method per-tenant per-app. The implementation lives in two SDKs (sdk-meter in W1 and sdk-billing in W4) and is bolted into every other SDK via build-time codegen — SDK authors annotate methods with @meter(...) and never write metering code by hand.

10A.1 · Data flow

flowchart LR
  classDef sdk fill:#1a2234,stroke:#c9a86a,color:#e6ecf5;
  classDef meter fill:#1d1830,stroke:#b88dff,color:#e6ecf5;
  classDef bill fill:#16241c,stroke:#5dd39e,color:#e6ecf5;
  classDef store fill:#0f1422,stroke:#6aa9ff,color:#e6ecf5;

  CALL["Any SDK method
annotated @meter(sku,unit,tier)"]:::sdk
  CHK["sdk-meter · check()
≤ 2ms sync"]:::meter
  RDS[("Redis
quota state + live counter")]:::store
  EXEC["SDK body
(actual work)"]:::sdk
  REP["sdk-meter · report()
async, fire-and-forget"]:::meter
  KFK[("Kafka
usage.events.v1
partition by tenant_id")]:::store
  PROC["Per-pool stream processor"]:::meter
  CH[("ClickHouse
hourly · daily · monthly
rollups")]:::store
  CHN[("Hash-chained ledger
(tenant, day) → Audit")]:::store
  BIL["sdk-billing · monthly
apply pricing.catalog.vN"]:::bill
  INV["Invoice
(per SDK · per method ·
per app · per BU · per persona)"]:::bill
  PAY["sdk-payment → Stripe / Razorpay"]:::sdk
  LIVE["Customer /billing/live
≤ 60s lag"]:::bill

  CALL -->|"Phase 1"| CHK
  CHK -->|read| RDS
  CHK -->|ALLOW/WARN| EXEC
  CHK -->|DENY → throw QuotaExceeded| CALL
  EXEC -->|"Phase 2"| REP
  REP --> KFK
  KFK --> PROC
  PROC --> CH
  PROC --> CHN
  PROC --> RDS
  CH --> BIL
  RDS --> LIVE
  BIL --> INV
  INV --> PAY
    

10A.2 · The @meter decorator (what SDK authors actually write)

// What an SDK author writes — once, at method definition:
@meter({ sku: 'identity.jwt.mint', unit: 'call', tier: 'core' })
async mintToken(req: MintRequest, ctx: Ctx): Promise<Token> { ... }

// What codegen produces at build time (never edited by hand):
async mintToken(req, ctx) {
  const gate = await meter.check({                        // Phase 1 — sync, ≤ 2ms p99
    sku: 'identity.jwt.mint',
    tenant_id: ctx.tenant_id, app_id: ctx.app_id, actor: ctx.actor,
  });
  if (gate.decision === 'DENY') throw new QuotaExceeded(gate.reason);

  const result = await originalMintToken(req, ctx);

  meter.report({                                          // Phase 2 — async, idempotent
    event_id: ulid(),
    sku: 'identity.jwt.mint',
    units: 1,
    dimensions: {                                         // six-layer attribution from JWT
      org_id, app_id, tenant_id, bu_id, persona_id, encounter_id, pool_index,
      actor_kind, actor_id, region, latency_ms, bytes_in, bytes_out,
    },
    occurred_at: now(),
  });
  return result;
}

10A.3 · Pricing modes

10A.4 · Catalog versioning

• Schema lives in @projexlight/contracts as a typed const — every SKU, unit, and pricing mode is type-checked at compile time. Catalog schema changes require a contracts PR (high signal, CI catches orphan SKUs).
• Rates live in a Postgres table in the Admin Pool — editable by Finance without a code release. Constraint: every active SKU must have a rate row.
• Versioning. pricing.catalog.v2 ships, existing tenants stay on v1 until renewal. Every invoice records the catalog_id it was generated against — bills never use "current rates" by accident.
• Reprice-dry-run. Any month can be recomputed against any catalog version; Finance previews the delta before applying. Raw units are immutable; only the price applied at invoice time changes.

10A.5 · SLAs

10A.6 · Pool-aware aggregation

Rollups happen per-pool (the natural shard from §9). The Admin Pool consolidates per-tenant totals. Cross-pool aggregation goes through the warehouse only — never live cross-pool joins, matching the existing v3.1 isolation guarantee. Billing rows for a tenant live in that tenant's Admin Pool.

10A.7 · Where this beats AWS / GCP / Azure / Stripe

11 · Access Control Mesh — ABAC + ReBAC + Encounter Grants

Authorization in v3.1 is the conjunction of three evaluators. Every read or write passes all three or fails.

11.1 · Decision flow

sequenceDiagram
  autonumber
  participant U as User · Dr.Smith
  participant GW as API Gateway
  participant POL as Policy SDK · ABAC
  participant REB as ReBAC SDK
  participant GRT as Encounter Grants
  participant DB as App pool
  participant AUD as Audit

  U->>GW: GET /v1/patients/Ravi/chart
  GW->>POL: ABAC(actor=Dr.Smith, target=Ravi.chart)
  POL-->>GW: structural OK
  GW->>REB: relationship(Dr.Smith ↔ Ravi)?
  REB-->>GW: active primary-care relationship
  GW->>GRT: time-bounded grant?
  GRT-->>GW: not required
  GW->>DB: read chart (decrypt via encounter key)
  DB-->>GW: payload
  GW->>AUD: log{actor, target, evaluators, decision, snapshot}
  GW-->>U: chart
    

11.2 · Cross-tenant access

Default: zero cross-tenant access. A doctor at Hospital A cannot see a chart from Hospital B even for the same person. Exception: explicit cross-tenant Relationship + Consent receipt. Cross-tenant reads always go through a re-encryption proxy.

11A · Platform Control Planes & Obligation-Based Authorization v3.2

A platform-layer design discussion (gaps/Analyze1.md) and its architectural critique (gaps/Analyze2.md) proposed a platform of eight explicit control planes and warned against the failure mode of one flat "platform" carrying overlapping identity truth. v3.1 already realizes most of that model at the application layer; v3.2 makes the mapping explicit and commits to the handful of upgrades the critique correctly identifies as necessary. The full capability scoring lives in ../insignia/ProjexCloud-vs-Insignia-Reality-Report-v2.html.

11A.1 · The eight planes → owning packages

11A.2 · The five-identities discipline

11A.3 · Obligation-bearing authorization v3.2 (P16)

v3.1's access mesh returned a bare verdict. That leaves field masking and row filtering to every caller — the exact drift the critique flags (Scenario 7: "API allows, UI hides field, API still leaks it"). v3.2 extends the decision to carry obligations the gateway/service enforces server-side.

// @projexlight/sdk-policy — EvaluatePolicyResult, v3.2
export interface EvaluatePolicyResult {
  decision: 'ALLOW' | 'DENY';
  reason: string;
  layers_used: string[];
  projection_version: number;
  cached: boolean;
  obligations?: {                          // ← v3.2
    mask_fields?: string[];                // e.g. ['ssn','profit_margin'] — redacted server-side
    row_filter?: Record<string, unknown>;  // e.g. { tenant_id, region: ['US','EU'] }
    audit_level?: 'standard' | 'sensitive_access';
    ttl_seconds?: number;                  // decision cache lifetime
  };
}

11A.4 · The minted Platform Principal Token v3.2 (P17)

The resolved IdentityContext is already ProjexCloud's normalized subject identity. v3.2 has the gateway mint a signed, short-TTL, audience-bound token from it for east-west calls, so no downstream service ever trusts a forwarded header or a raw external claim.

// Minted by api-gateway after resolveIdentityContext(); verified by every service
{
  "sub": "platform-principal:person:p_123",
  "auth_assurance": "mfa",
  "app_id": "healthcare", "tenant_id": "hospital-a", "bu_id": "...",
  "root_tenant_id": "...", "reseller_id": "...",
  "persona_ids": ["persona_doctor_..."],
  "effective_scopes": ["chart:read"],
  "aud": "platform-services",       // audience-bound — not replayable elsewhere
  "iss": "projexcloud-gateway",
  "exp": 900                         // short TTL; re-mint on refresh
}

Services verify iss/aud/exp and the signature, then read the principal — they never re-derive identity from user-supplied input. (When the service mesh of §11A.6 lands, this token rides on top of mTLS workload identity; until then it is the sole internal trust anchor.)

11A.5 · Consent as a gating decision input v3.2 (P18)

sdk-consent already owns purpose registry, grants, receipts, and cross-border checks, and active consents already surface in IdentityContext.active_consents. v3.2 wires that receipt into the access decision as a first-class, purpose-gated input: for a purpose-bound resource, a missing or revoked receipt is a DENY with reason consent_absent — it fails closed. Consent remains distinct from authorization: a doctor may be authorized to read a chart for treatment yet have no consent to use it for marketing.

11A.6 · Fail-closed PDP & audited break-glass v3.2

• Fail closed for sensitive classes. If the policy evaluator is unavailable, sensitive-resource access denies; only low-risk decisions may serve from a short-TTL cache.
• Explicit break-glass. Emergency access is an audited path routed through sdk-approval (scoped, time-bounded, certificate-of-action), never a silent fallback. Every degraded decision is recorded with reason.

11A.7 · Deferred by design — and why

11A.8 · Resource Ownership Registry v3.2

The most grounded concern in gaps/Analyze1.md: infrastructure resources — droplets, clusters, databases, buckets, registries, Kafka topics — get created and deleted with no clear owner. Without ownership, platform security and cost control are impossible. v3.2 makes ownership a hard precondition for provisioning, reconciled through GitOps.

// platform.resource_registry — every provisioned resource has exactly one row
{
  "resource_id": "rds-hospital-a-app-pool-03",
  "type": "postgres" | "k8s_cluster" | "bucket" | "kafka_topic" | "registry" | "vm" | "droplet",
  "environment": "prod" | "staging" | "dev",
  "owner": "person_id_of_accountable_human",
  "team": "platform-data",
  "repo": "git@…/infra-pools",
  "terraform_module": "modules/app-pool",
  "cloud_account": "aws-prod-2",
  "cost_center": "CC-4471",
  "data_classification": "restricted" | "confidential" | "internal" | "public",
  "network_zone": "corp_vpn" | "public_edge" | "isolated",
  "created_by": "…", "approved_by": "…",
  "created_at": "2026-06-14T…", "expires_at": "2026-12-31T…" | null
}

This is an operations/GitOps program, not an application SDK — it sits beside the platform rather than inside it. A thin sdk-resource-registry read API can surface ownership to the admin app, but the source of truth is GitOps-managed infrastructure state.

11A.9 · Open strategic decisions that gate the deferrals v3.2

The §11A.7 items are deferred not because they're hard but because they depend on business decisions not yet made. Recording them here makes each deferral a conscious "pending decision X," not an oversight. These are the decisions the Reality Report, gaps/Analyze3.md, and the gaps/Analyze4.md follow-up all leave open because engineering cannot answer them alone. D-1 and D-2 decide whether a deferred item becomes Required; D-3 decides whether it should be promoted to Planned ahead of that trigger.

11A.10 · D-1 provisional resolution — Healthcare vertical (multi-source patient data) v3.2

EMPI design note (extends sdk-identity-resolver)

The EMPI is the one large (L) build and must be its own workstream — in healthcare a false merge exposes the wrong patient's PHI and a false split fragments a record, so it is regulated-grade. It adds, behind the existing resolver interface: deterministic + probabilistic matching (name · DOB · address · phone · external IDs), confidence scores, a POSSIBLY_SAME candidate-link state (never a forced merge), a steward review queue (sdk-approval-governed adjudication), merge / unmerge as reversible compensating events (no destructive deletes), and match-quality calibration monitoring. Downstream systems continue to store the canonical ID — they never carry raw identity truth.

11A.11 · Coverage map — analysis gaps → status → backlog v3.2

Every concern raised across gaps/Analyze1.md…Analyze4.md, mapped to its current disposition. Read honestly: Shipped = implemented in the 91-package build today; Designed + Backlogged = design committed here (v3.2) and scheduled as Projexlight work, not yet merged code; Deferred = consciously deferred against a named decision (§11A.9).

12 · Tenancy & Verticals

Two orthogonal axes. Tenant = a customer organization (Shantam, Kiana, Harmony Wellness, ContractorCo, Hospital A). Vertical = a productized domain bundle (Seva, Realty, Music, BidWork, LeadPulse, FieldOps, Healthcare, eCommerce, OneEstate). One tenant subscribes to one or more verticals; one vertical serves many tenants.

flowchart TB
  classDef plat fill:#1a2234,stroke:#c9a86a,color:#e6ecf5;
  classDef vert fill:#16241c,stroke:#5dd39e,color:#e6ecf5;
  classDef ten fill:#241622,stroke:#ff6b6b,color:#e6ecf5;

  subgraph COMMON["projex_common · horizontal capabilities + HDK + Pool Router"]
    direction LR
    IDS["Identity"]:::plat
    POOL["Pool Router"]:::plat
    PAY["Payment"]:::plat
    GEO["Map/Geo"]:::plat
    DSP["Dispatch"]:::plat
    AGW["AI Gateway"]:::plat
    ELSE["…29 services · 12 agents · 10 HDK modules"]:::plat
  end

  subgraph SEVA["Seva"]
    DON["Donation"]:::vert
  end
  subgraph REALTY["Realty"]
    PROP["Property · Visit"]:::vert
  end
  subgraph FIELDOPS["FieldOps"]
    STM["Storm Estimation"]:::vert
    CTR["Contractor Settlement"]:::vert
  end
  subgraph MUSIC["Music"]
    CAT["Catalog · Rights"]:::vert
  end
  subgraph HC["Healthcare · new"]
    CHART["Chart · Rx · Care plan"]:::vert
  end
  subgraph EC["eCommerce · new"]
    ORD["Order · Cart · Catalog"]:::vert
  end

  T1["Shantam"]:::ten
  T2["Kiana"]:::ten
  T3["ContractorCo"]:::ten
  T4["Hospital A"]:::ten
  T5["BookStore"]:::ten

  T1 --> SEVA
  T2 --> REALTY
  T3 --> FIELDOPS
  T4 --> HC
  T5 --> EC

  SEVA --> COMMON
  REALTY --> COMMON
  FIELDOPS --> COMMON
  HC --> COMMON
  EC --> COMMON
  MUSIC --> COMMON
    

12.1 · Isolation tiers

12.2 · Resolution path

flowchart LR
  classDef edge fill:#0f1422,stroke:#6aa9ff,color:#e6ecf5;
  classDef gw fill:#1a2234,stroke:#c9a86a,color:#e6ecf5;
  classDef svc fill:#16241c,stroke:#5dd39e,color:#e6ecf5;
  classDef store fill:#241622,stroke:#ff6b6b,color:#e6ecf5;

  USER(["Browser · RN · Kiosk"]):::edge
  CDN["CDN"]:::edge
  GW["API Gateway · Kong
resolves tenant_id + vertical_id"]:::gw
  TEN["Tenant Mgmt
plan · tier · region · modules · pool indices"]:::svc
  IDP["Identity
JWT carries six-layer tuple"]:::svc
  POOL["Pool Router
tenant_id + app_id → dsn"]:::svc
  SVC["Common service
routed query against one pool"]:::svc
  PG[("Postgres pool · RLS within")]:::store
  RC[("Redis · routing cache")]:::store

  USER --> CDN --> GW
  GW --> TEN
  GW -->|JWT| IDP
  GW --> POOL
  POOL --> RC
  POOL --> SVC
  SVC --> PG
    

13 · Workspace Layout

A single pnpm + turbo workspace under projex_common/. Every service, agent, package, and HDK module is its own workspace member.

projex_common/
├── README.md
├── package.json
├── pnpm-workspace.yaml
├── turbo.json
├── tsconfig.base.json
│
├── docs/
│   ├── Architecture.html                   ← v1 (historical)
│   ├── Architecture-v2.html                ← v2 (historical)
│   ├── v3/Architecture-v3.html             ← v3 (AIM only)
│   ├── v3.1/Architecture-v3.1.html         ← THIS · canonical
│   ├── v3.1/SDK-Build-Plan-v3.1.html
│   ├── v3.1/AIM-Identity-Model-v3.1.html
│   ├── Common-Services-and-Agents.md
│   ├── Data-Design.md
│   └── Data-Request-Manifests.md
│
├── packages/                               ← TS/JS packages
│   ├── contracts/                @projexlight/contracts
│   ├── sdk-pool-router/          @projexlight/sdk-pool-router    ← v3 NEW
│   ├── sdk-secrets/              @projexlight/sdk-secrets
│   ├── sdk-vault/                @projexlight/sdk-vault
│   ├── sdk-audit/                @projexlight/sdk-audit
│   ├── sdk-tenant/               @projexlight/sdk-tenant
│   ├── sdk-identity/             @projexlight/sdk-identity
│   ├── sdk-consent/              @projexlight/sdk-consent
│   ├── sdk-policy/               @projexlight/sdk-policy
│   ├── sdk-rebac/                @projexlight/sdk-rebac           ← v3 NEW
│   ├── sdk-profile/              @projexlight/sdk-profile
│   ├── sdk-persona/              @projexlight/sdk-persona         ← v3 NEW
│   ├── sdk-device/               @projexlight/sdk-device
│   ├── sdk-geo/                  @projexlight/sdk-geo
│   ├── sdk-feature-flags/        @projexlight/sdk-feature-flags
│   ├── sdk-media/                @projexlight/sdk-media
│   ├── sdk-notification/         @projexlight/sdk-notification
│   ├── sdk-payment/              @projexlight/sdk-payment
│   ├── sdk-workflow/             @projexlight/sdk-workflow
│   ├── sdk-search/               @projexlight/sdk-search
│   ├── sdk-crm/                  @projexlight/sdk-crm
│   ├── sdk-engagement/           @projexlight/sdk-engagement      ← v3 NEW
│   ├── sdk-content/              @projexlight/sdk-content
│   ├── sdk-service-request/      @projexlight/sdk-service-request
│   ├── sdk-event/                @projexlight/sdk-event
│   ├── sdk-campaign/             @projexlight/sdk-campaign
│   ├── sdk-social/               @projexlight/sdk-social
│   ├── sdk-ai-gateway/           @projexlight/sdk-ai-gateway
│   ├── sdk-taxonomy/             @projexlight/sdk-taxonomy
│   ├── sdk-knowledge-rag/        @projexlight/sdk-knowledge-rag
│   ├── sdk-parsing/              @projexlight/sdk-parsing
│   ├── sdk-agent-runtime/        @projexlight/sdk-agent-runtime
│   ├── sdk-conversation/         @projexlight/sdk-conversation
│   ├── sdk-recommendation/       @projexlight/sdk-recommendation
│   ├── sdk-analytics/            @projexlight/sdk-analytics
│   ├── sdk-storm/                @projexlight/sdk-storm
│   ├── sdk-dispatch/             @projexlight/sdk-dispatch
│   ├── sdk-assignment/           @projexlight/sdk-assignment
│   ├── sdk-lead-scoring/         @projexlight/sdk-lead-scoring
│   ├── sdk-evidence/             @projexlight/sdk-evidence
│   ├── sdk-diagnostic-telemetry/ @projexlight/sdk-diagnostic-telemetry
│   ├── design-system/            @projexlight/design-system
│   ├── i18n/                     @projexlight/i18n
│   ├── branding/                 @projexlight/branding
│   ├── config/                   @projexlight/config
│   └── telemetry/                @projexlight/telemetry
│
├── native/                                 ← HDK native modules
│   ├── hdk-map · hdk-camera · hdk-idp · hdk-permissions · hdk-scanner
│   ├── hdk-image-editor · hdk-video-editor · hdk-measure
│   ├── hdk-watermark · hdk-diagnostic
│
├── services/                               ← horizontal microservices (29 + pool-router service)
│   ├── identity · tenant-management · user-profile · persona · engagement
│   ├── payment · notification · crm · service-request · content
│   ├── course · event · campaign · social-ingestion · analytics
│   ├── search · media · workflow · audit · ai-gateway
│   ├── knowledge-rag · conversation · recommendation · feature-flags
│   ├── map-geo · storm · dispatch · assignment · lead-scoring
│   ├── field-ops-evidence · diagnostic-telemetry · pool-registry
│
├── agents/                                 ← 12 horizontal agents (unchanged)
│
└── infra/
    ├── helm/ · terraform/ · k8s/

14 · Layered View

14.1 · Top-level stack

flowchart TB
  classDef ch fill:#0f1422,stroke:#6aa9ff,color:#e6ecf5;
  classDef gw fill:#1a2234,stroke:#c9a86a,color:#e6ecf5;
  classDef common fill:#1a2234,stroke:#c9a86a,color:#e6ecf5;
  classDef vert fill:#16241c,stroke:#5dd39e,color:#e6ecf5;
  classDef ag fill:#241622,stroke:#ff6b6b,color:#e6ecf5;
  classDef hdk fill:#1d1830,stroke:#b88dff,color:#e6ecf5;
  classDef aim fill:#241622,stroke:#b88dff,color:#e6ecf5;

  subgraph L1["1 · Channels"]
    SW["Seva · Realty · Music · FieldOps · Healthcare · eCommerce apps"]:::ch
  end
  subgraph LHDK["2 · HDK — device-side"]
    HDK["10 native modules"]:::hdk
  end
  subgraph LGW["3 · Edge & Gateway"]
    GW["Kong API Gateway · per-vertical BFFs"]:::gw
  end
  subgraph LAIM["4 · AIM Foundation · v3"]
    AIM["Identity · Tenant · Pool Router · Persona · Engagement · ReBAC · Policy · Vault"]:::aim
  end
  subgraph LSVC["5 · Common Services"]
    SVC["29 horizontal services across 6 clusters"]:::common
  end
  subgraph LVERT["6 · Vertical Services"]
    VS["Seva · Realty · Music · FieldOps · Healthcare · eCommerce vertical services"]:::vert
  end
  subgraph LAG["7 · Agents"]
    AGN["12 horizontal agents"]:::ag
  end

  L1 --> LHDK --> LGW --> LAIM --> LSVC --> LVERT
  LAG -.calls.-> LAIM
  LAG -.calls.-> LSVC
  LAG -.calls.-> LVERT
  LSVC -.events.-> LAG
  LVERT -.events.-> LAG
    

14.2 · Common Services clusters

flowchart LR
  classDef cluster fill:#1a2234,stroke:#c9a86a,color:#e6ecf5;
  classDef new fill:#1d1830,stroke:#b88dff,color:#e6ecf5;

  subgraph IDT["Identity, Tenancy & AIM"]
    A1["Identity"]:::cluster
    A2["User Profile"]:::cluster
    A3["Tenant Mgmt"]:::cluster
    A4["Feature Flags"]:::cluster
    A5["Pool Router · v3"]:::new
    A6["Persona · v3"]:::new
    A7["Engagement · v3"]:::new
    A8["ReBAC · v3"]:::new
  end
  subgraph ENG["Engagement"]
    B1["CRM"]:::cluster
    B2["Service Request"]:::cluster
    B3["Notification"]:::cluster
    B4["Campaign"]:::cluster
    B5["Social Ingestion"]:::cluster
  end
  subgraph CCM["Commerce · Content · Media"]
    C1["Payment"]:::cluster
    C2["Content"]:::cluster
    C3["Course"]:::cluster
    C4["Event"]:::cluster
    C5["Media"]:::cluster
    C6["Search"]:::cluster
  end
  subgraph OPS["Operations"]
    D1["Workflow"]:::cluster
    D2["Audit"]:::cluster
    D3["Analytics"]:::cluster
    D4["Diagnostic-Telemetry"]:::new
  end
  subgraph FLD["Geo · Dispatch · Evidence"]
    F1["Map / Geo"]:::new
    F2["Storm"]:::new
    F3["Dispatch"]:::new
    F4["Assignment"]:::new
    F5["Lead Scoring"]:::new
    F6["Field-Ops Evidence"]:::new
  end
  subgraph AIL["AI Layer"]
    E1["AI Gateway"]:::cluster
    E2["Knowledge / RAG"]:::cluster
    E3["Conversation"]:::cluster
    E4["Recommendation"]:::cluster
  end
    

14.3 · Platform spine & data plane

flowchart LR
  classDef plat fill:#1a2234,stroke:#c9a86a,color:#e6ecf5;
  classDef data fill:#0f1422,stroke:#5dd39e,color:#e6ecf5;
  classDef use fill:#16241c,stroke:#5dd39e,color:#e6ecf5;

  subgraph SPINE["Platform Spine"]
    BUS["Kafka
envelope-wrapped events"]:::plat
    TMP["Temporal
durable workflows"]:::plat
    OBS["OTel · Grafana · Langfuse"]:::plat
    SEC["Secrets · KMS · HSM"]:::plat
  end
  subgraph DATA["Data Plane · per pool"]
    PG[("Postgres pool · per service per pool")]:::data
    RD[("Redis
cache · sessions · pool routing")]:::data
    OS[("OpenSearch
full-text")]:::data
    CHC[("ClickHouse
OLAP · cross-pool warehouse")]:::data
    S3[("S3
media · evidence")]:::data
    VEC[("pgvector / Pinecone
embeddings")]:::data
    POSTGIS[("PostGIS
bbox · routing")]:::data
  end

  CONS["Common & vertical services"]:::use
  AGENTS["Agents"]:::use
  HDK["HDK modules · device"]:::use

  CONS -- emit/consume --> BUS
  HDK -- emit --> BUS
  CONS -- run --> TMP
  CONS --> PG
  CONS --> RD
  CONS --> OS
  CONS --> CHC
  CONS --> S3
  CONS --> VEC
  CONS --> POSTGIS
  CONS -.metrics/logs/traces.-> OBS
  CONS -.fetch keys.-> SEC
  AGENTS -- consume --> BUS
    

15 · Worked Scenarios

End-to-end flows showing how pools, identity layers, encryption, and the access mesh compose.

person:            admin-india-007 (home)
app_identity:      admin-india-007
hospital_a:
  membership · persona (identity): admin-014
  chart, encounters:                app-healthcare-007
  evidence (scans):                 evidence-002
hospital_b:
  membership · persona (identity): admin-021
  chart, encounters:                app-healthcare-002
  evidence (scans):                 evidence-004

16 · Common Services Catalogue

29 horizontal services (v2 baseline) + 4 AIM services introduced by v3. Each owns its data, exposes a versioned HTTP API, emits envelope-wrapped events, and is consumed by every vertical that needs the capability.

16.1 · Drop-in services (zero-change reuse)

16.2 · Generalize-then-share (Rule of Three)

16.3 · On-device AI policy

17 · Permission Architecture (three layers)

Three independent layers, each enforced at a different boundary. A request only succeeds if all three say yes. Symmetric between web and mobile — only the enforcement points differ. v3 integration: Layer 2 now consults the full ABAC + ReBAC + Encounter Grants mesh, not just role checks.

flowchart TB
  classDef l1 fill:#0f1422,stroke:#6aa9ff,color:#e6ecf5;
  classDef l2 fill:#16241c,stroke:#5dd39e,color:#e6ecf5;
  classDef l3 fill:#241622,stroke:#ff6b6b,color:#e6ecf5;
  classDef store fill:#1a2234,stroke:#c9a86a,color:#e6ecf5;

  subgraph LAY1["Layer 1 · App consent"]
    C["Tenant consent + module subscription"]:::l1
  end
  subgraph LAY2["Layer 2 · Access Mesh · v3"]
    R["ABAC + ReBAC + Encounter Grants"]:::l2
  end
  subgraph LAY3["Layer 3 · Device permissions"]
    D["OS-level permissions"]:::l3
  end

  RC[("Redis permission cache")]:::store
  DEV[("On-device permission cache")]:::store

  C --> R --> D
  R -. fetches .-> RC
  R -. syncs .-> DEV
    

17.1 · Offline behavior

• App downloads JSON permission blob on first online login, caches on-device via hdk-permissions.
• Subsequent launches validate from cache. Role changes from cloud sync next online.
• Camera / capture / map continue offline; artifacts queue locally; events flush on reconnect.
• Consent grants/revokes log locally with timestamp + location and replay to Audit on reconnect.

18 · Common AI Agents

Twelve agents that subscribe to platform events and call platform APIs. Tenant-scoped, budget-capped, audited. v3: every agent action now resolves through ABAC + ReBAC; agents acting on behalf of a persona must respect relationships and encounter grants.

18A · Agent Isolation Runtime v3.1

§18 lists the 12 platform agents. This section is the runtime that makes them safely deployable at scale. Without these four primitives — capability tokens, execution TTL, deterministic replay, sandboxed memory — a single prompt-engineering mistake leaks Tenant A's context into Tenant B's agent. The leak is catastrophic and irreversible.

18A.1 · The four primitives

18A.2 · The agent invocation flow

sequenceDiagram
  participant U as User
(persona)
  participant AGR as sdk-agent-runtime
  participant POL as sdk-policy + ReBAC
  participant CAP as Capability Issuer
(runtime internal)
  participant TOOL as SDK tool
(e.g., sdk-crm)
  participant MET as sdk-meter
  participant MEM as Sandboxed Memory
(tenant namespace)
  participant AUD as sdk-audit
  participant TRC as sdk-trace

  U->>AGR: Trigger agent (intent, persona_id, tenant_id)
  AGR->>POL: Check persona may invoke this agent
  POL-->>AGR: ALLOW
  AGR->>AGR: Start TTL clock (e.g., 30s)
  AGR->>MEM: Load tenant-scoped context (physical namespace)
  AGR->>AGR: Planner produces action plan
  loop For each planned tool call
    AGR->>CAP: Mint capability token (agent_id, tool, args, scope)
    CAP-->>AGR: signed token
    AGR->>TOOL: invoke(args, token)
    TOOL->>MET: gate.check(token, sku, tenant)
    MET-->>TOOL: ALLOW (token valid, in scope)
    TOOL->>TOOL: execute
    TOOL->>AUD: state change with token id + agent_chain
    TOOL-->>AGR: result
  end
  AGR->>AGR: Write execution log (content-addressed)
  AGR->>AUD: agent run complete (log hash, deterministic)
  AGR->>TRC: emit trace span across the whole run
  AGR-->>U: result

  Note over AGR: If TTL expires mid-loop: terminate, cancel
in-flight tools, rollback compensable steps
    

18A.3 · What this prevents

18A.4 · Operational requirements

• Capability issuer keys rotate per region; signing keys vaulted via sdk-secrets.
• Execution log retention = the longer of (90 days, the longest action's compensation window). Logs are deterministic-replay artifacts, not telemetry.
• Vector-store partitioning is verified at deployment time; the runtime refuses to start if a single namespace spans multiple tenant_ids.
• TTL budgets visible to operators per agent class; spikes in TTL-expiry rate page on-call.
• Cross-tenant leakage CI runs synthetic Tenant A/B prompt collisions on every PR touching sdk-agent-runtime or any tool used by agents; one leak fails the merge.

19 · Contracts & Event Envelope

The contracts package @projexlight/contracts is the keystone. Every service, every agent, every vertical, every HDK module depends on it.

19.1 · Event envelope (v3.1)

{
  "tenant_id":      "uuid",
  "vertical_id":    "seva | realty | music | bidwork | leadpulse | fieldops | healthcare | ecommerce | common",
  "pool_index":     "app-healthcare-007",       // v3 · which pool produced this
  "event_id":       "uuid",
  "event_type":     "encounter.opened.v1",
  "occurred_at":    "2026-05-20T10:15:32Z",
  "actor": {
    "type":         "user | agent | system | tenant_admin | super_admin | hdk_device",
    "person_id":    "pers_...",                  // v3 · master person
    "persona_id":   "pers_...patient",           // v3 · which hat
    "id":           "...",
    "display_name": "..."
  },
  "encounter_id":   "enc_...",                   // v3 · when within an encounter scope
  "payload":        { ... },
  "schema_version": 1,
  "correlation_id": "uuid",
  "causation_id":   "uuid",
  "device": {
    "device_id":    "uuid",
    "platform":     "ios | android",
    "app_version":  "...",
    "online":       true
  }
}

19.2 · Versioning rules

• Additive: bump schema_version, keep topic.
• Breaking: new topic X.v2; producers dual-write; consumers migrate; v1 retired after every consumer cuts over.
• Deprecation: marked in contracts for at least two minor versions before removal.
• Validation: producers and consumers validate against zod schema; CI runs cross-consumer contract tests.

20 · What Stays Vertical (do not lift)

These services stay in their respective verticals — lifting them would smuggle domain assumptions into Common.

21 · Adoption Playbook for a New Vertical

21.1 · Sample tenant manifest · Healthcare

tenant: hospital-a
vertical: healthcare
isolation_tier: governed         # Tier G for PHI
pool_assignment:
  admin_pool_index:    admin-014   # auto-assigned
  app_pool_index:
    healthcare:        app-healthcare-007   # dedicated for Tier G
  evidence_pool_index: evidence-002
  region:              ap-south-1
modules:
  identity: enabled
  pool_router: enabled
  persona: enabled
  engagement: enabled
  rebac: enabled
  profile: enabled
  payment: enabled
  notification: enabled
  audit: enabled
  feature_flags: enabled
  search: enabled
  workflow: enabled
  analytics: enabled
  media: enabled
  ai_gateway: enabled
  field_ops_evidence: enabled       # imaging captures
  diagnostic_telemetry: enabled
  # not used in healthcare
  storm: disabled
  donation: disabled
hdk:
  hdk_idp: enabled
  hdk_permissions: enabled
  hdk_diagnostic: enabled
  hdk_camera: enabled
persona_kinds:
  - patient
  - doctor
  - nurse
  - admin
encounter_kinds:
  - visit
  - admission
  - surgery
  - er_episode
  - outpatient
branding:
  primary: "#0ea5e9"
  logo: "hospital_a.svg"
  default_lang: "en"
deployment:
  android: standard
  ios: standard
  web: enabled

22 · Pool Lifecycle & Tenant Migration v3

22.1 · Pool states

22.2 · Tenant migration (Standard → Premium → Governed)

1. Mark tenant MIGRATING. Router queues writes; live reads OK on source.
2. Snapshot source pool's rows for this tenant. Encrypted backup to target.
3. Replay queued writes against target until lag = 0.
4. Atomic cutover: update tenant_pool_map, fan-out invalidate router caches.
5. Mark tenant ACTIVE on target. Source rows tombstoned for delete after retention.
6. Audit logs both pools across the cutover.

22.3 · Disaster recovery

• Per-pool PITR. 7-day for shared, 35-day for Tier G.
• Cross-region replica. Tier G pools have a warm replica in a paired region; failover < 5 min.
• Restore granularity. Pool restore brings back all that pool's tenants; tenant-only restore is an offline migration from the restored pool.

22A · Deployment Variants v3.1

The default deployment is Projexlight-operated multi-tenant SaaS in our regional cloud. Enterprise and regulated buyers often need stricter variants. v3.1 documents four variants so the SDK estate is built with these constraints in mind — not retrofitted under sales pressure.

22A.1 · BYOK / CMEK — Customer-Managed Encryption Keys

Tenants who require their own KMS keys as a hard policy (regulated finance, healthcare networks, government suppliers) can plug their own KMS into the Vault key hierarchy.

• Placement in the key tree. The customer's CMK becomes the wrapping key for the Tenant Key — sitting between Pool KEK and Tenant Key. Pool KEK is platform-controlled; Tenant Key (and everything under it: Person, Encounter, Device, Org keys for this tenant) is unwrappable only via the customer's CMK.
• Customer revoke = service halt. If the customer revokes the CMK, all reads for that tenant return undecryptable. This is the contractual point of BYOK — the customer can pull the plug. We surface the operational risk in the contract and require change-control protocols.
• Supported KMS providers. AWS KMS (via grant), GCP KMS (via key handle), HSM (CloudHSM or on-prem via PKCS#11). sdk-vault abstracts the provider.
• Rotation. Customer rotates their CMK on their cadence; platform re-wraps Tenant Key transparently; no re-encryption of leaf data required.
• Audit. Every CMK use logged to BOTH platform Audit and (optionally) shipped to customer's SIEM.

22A.2 · Sovereign Cloud — FedRAMP / IL5 / China PIPL / EU sovereign

For workloads that cannot run on the default commercial regions: US Federal (FedRAMP High, IL5/IL6 for DoD), China PIPL (data-must-stay-in-China + Chinese cloud), EU sovereign (no US hyperscaler control plane), Russia data localization, Saudi/UAE data localization.

• Sovereign region = isolated pool family. A sovereign region has its own Admin Pools, App Pools, Evidence Pools, Vector Stores, Warehouse, and KMS. No data, telemetry, audit, or control-plane signal leaves the region. Pool Router federation manifest treats sovereign regions as terminal — no cross-region routing.
• Sovereign control plane. Operated by an in-region partner (a US-cleared MSP for FedRAMP, a Chinese cloud for PIPL). Projexlight ships container images + Terraform; partner runs the cluster; we provide remote-only L3 support under joint-authority procedures.
• SDK estate identical. The 54 SDKs run unchanged. What changes is the deployment topology (no cross-region anything) and the operator (in-region partner instead of Projexlight).
• Audit + compliance. Each sovereign region attests its own SOC2/FedRAMP/PIPL audit separately; cross-region attestation impossible by design.

22A.3 · On-Prem / Air-Gapped Deployment

For banks, defense contractors, intelligence agencies, and a small set of regulated healthcare buyers, fully on-prem deployment is a hard requirement.

• Packaged as a Kubernetes distribution. Single-cluster footprint of the platform: Admin Pool + one App Pool per app + Evidence Pool + Vector Store + Vault + KMS + Kafka + ClickHouse + Temporal. Sized for a single-tenant or small-network deployment.
• Air-gapped updates. Quarterly signed-bundle releases delivered via approved physical media or one-way data diode. Update tooling validates signature, applies migrations, rolls back on failure.
• Reduced SDK estate by config. AI Gateway operates against locally-hosted models (Llama, Mistral) instead of cloud APIs. Webhook delivery limited to in-cluster endpoints. Federation hooks disabled. Some features (cross-region replication, hyperscaler KMS) marked unavailable.
• Telemetry stays in-cluster. No phone-home for usage, billing, or operational metrics. Customer reports own usage to their finance team; billing is contract-based, not metered.
• Pricing model differs. On-prem deployments are flat-fee + support, not pay-as-you-use. sdk-meter still runs (for internal cost-tracking) but sdk-billing produces internal-use reports, not invoices.

22A.4 · Active-Active Multi-Region (Tier-G+)

v3 defined Tier-G as warm replica + failover. Some buyers (global banks, payment networks, life-critical healthcare) require active-active — writes accepted in multiple regions simultaneously.

• Conflict-free domain restricted. Active-active is offered only for SDKs whose data model tolerates eventual consistency without conflict (audit append, telemetry, notifications, search indexes). OLTP SDKs with strong-consistency requirements (identity, payment, encounter open/close) stay single-region active.
• Per-tenant routing. Each tenant pinned to a home region for OLTP; read replicas in paired regions for low-latency reads. Writes to non-home region routed back (with audited cross-region latency).
• RPO/RTO targets. Tier-G+ commits to RPO ≤ 5s, RTO ≤ 60s; achieved via synchronous replication for audit/payment, async for everything else.
• Failover drills. Monthly chaos drill rotates a tenant's home region; if RPO/RTO targets not met, tier downgraded until fixed.
• Cost. Active-active is a 3–4× infrastructure cost; only offered as Tier-G+ contract addendum.

23 · Governance & Ownership

23.1 · Service & module ownership

Names below are the current primary owners. Each named owner has a deputy.

24 · Cross-Vertical Roadmap

25 · Glossary