Tenant Spine: Fortress, Operational Cache and Flow Model
Status: current derived implementation contract
Date: 2026-07-29
Authority: ARCHITECTURE_LOCK.md → IMPLEMENTATION_CONTRACT_v1.1.md → CONSOLIDATED_PRODUCT_PLATFORM_CONTRACT_v1.2.md
Implementation: migrations/035_canonical_spine_schema_fortress.sql → 037_pure_entity_spine_tables.sql → 038_tenant_lifecycle_entity_tables.sql → 039_tenant_network_scope_and_promotion_flow.sql → 040_scope_global_events_provenance_and_evidence.sql → 041_app_category_entity_domain_classification.sql → 042_real_tenant_rls_and_runtime_scope.sql
1. Resolved model
IntegrateWise stores one tenant-level entity model. It does not create a
database schema, table family, or cache partition for a department.
Tenant
→ Tenant Account
→ Spine Network
→ canonical entities, relationships, events and evidence
→ RBAC-scoped Workbench projections
Role, department, industry, team, work objective and active context determine
the projection a user receives. They never determine where canonical truth is
physically stored.
This preserves cross-functional work. A single account, person, task, document,
risk, decision or outcome can be projected in the relevant user views without
copying its truth into a Sales, Finance, Customer Success, Engineering or any
other department database.
The supplied Spine references are applied as follows:
- Account Intelligence's field-rich tables become typed, tenant-scoped entities
and relationships; they are not a separate customer-success database. - The Workbench IA's tables, views and pages remain three different primitives:
entities hold truth; views are RBAC lenses; pages/canvases hold narrative and
may propose governed changes. - The Mental Model's evidence chain, connector schema expansion and contextual
Twin are retained, subject to the frozen Gateway, Pipeline and Governance
boundaries. - The Company Wiki's company, initiative, work-item, decision and knowledge
lifecycles are modeled as tenant lifecycle events with evidence and exit
criteria, not merely user activity logs.
2. Two stores, one source of truth
| Store | Technology and owner | Contains | Does not contain |
|---|---|---|---|
| Canonical Spine / Fortress | Neon Postgres, written only by Pipeline promotion / Governed Spine Writers | governed entity state, typed relationships, version history, lifecycle events, evidence links, approvals, audit, promotion records and canonical change outbox | short-lived UI state, a browser-owned source of truth, raw provider credentials, or unreviewed AI memory as truth |
| Operational Spine | D1 and KV, managed by Pipeline and Projection Engine | bounded entity/projection cache, active context, idempotency, sync receipts, connector health, candidate staging and expiry-bound runtime activity | independent truth, permanent durable memory, authority decisions, or a direct path into canonical tables |
The operational store is a cache and staging boundary. It is rebuildable from
Fortress and R2 evidence. If an operational record matters after its expiry, it
must be promoted through the governed path; it must not be retained merely
because it happened to exist in a cache.
Fortress commit
→ canonical change outbox
→ Pipeline / Projection Engine
→ D1/KV operational cache and invalidation
→ Workbench projection
Operational candidate or connector intake
→ evidence + promotion queue
→ policy and required approval
→ Governed Spine Writer
→ Fortress commit
3. Tenant scope and stable identifiers
Every tenant-owned entity, relation, event, evidence link, promotion, cache
entry and log uses this scope envelope.
| Scope concern | Physical field | Meaning |
|---|---|---|
| Isolation boundary | tenant_id | The tenant that owns the record and policy context. Always required. |
| Tenant operating account | tenant_account_id | References spine_tenant_accounts.account_id. This is the tenant's root account identifier. |
| Tenant Spine Network | spine_network_id | References the tenant-account-specific spine_networks record. It groups the entity graph, connector bindings, events and projections for that operating network. |
| Workspace context | workspace_id | Optional active working scope within the tenant; never replaces tenant_id. |
| Entity identity | <entity>_id and canonical_id | Stable row identity and deduplication/merge identity. |
| Connector install binding | connector_binding_id | The authenticated user/tenant/provider-workspace installation binding. |
| Connector connection | spine_connection_id | The canonical connection for one provider connection. It is lineage for imported data, not the tenant network root. |
| Traceability | trace_id, correlation_id, source_flow | The end-to-end route through a Flow A-D operation. |
Every entity additionally carries a provider-neutral classification address:
app_category → business_domain → lifecycle_stage
app_category classifies the entity source, business_domain is the RBAC
classification, and lifecycle_stage is the cross-domain routing key. The
full registry is APP_CATEGORY_ENTITY_DOMAIN_CLASSIFICATION.md.
The distinction matters:
spine_network_id = the tenant's IW-Spine-Network
spine_connection_id = one connector/provider connection inside that network
spine_connection_id remains correct for connector-specific lineage. It cannot
substitute for spine_network_id, because a tenant network has many connector
connections and also includes user-created, imported and governed entities.
tenant_account_id is deliberately used on tenant-scoped tables rather than a
generic account_id: spine_accounts.account_id already identifies a business
account/customer entity. The two are different concepts and must not collide.
4. Entity-first lifecycle model
Every durable lifecycle object gets a typed canonical entity table. Generic
spine_entities remains the compatibility graph/identity layer while typed
tables become the canonical materialized home for their entity families.
| Lifecycle family | Canonical typed tables | Typical lifecycle events |
|---|---|---|
| Tenant identity and authority | spine_organizations, spine_workspaces, spine_users, spine_memberships, spine_roles, spine_permissions, spine_tenant_accounts, spine_networks | tenant created, membership granted, role changed, policy changed |
| People and organizational operating model | spine_persons, spine_teams, spine_processes, spine_objectives, spine_projects, spine_outcomes | person identified, team formed, objective set, project advanced, outcome verified |
| Work and coordination | spine_tasks, spine_work_items, spine_workflows, spine_approvals, spine_decisions, spine_timeline_events | work created, assigned, blocked, proposed, approved, completed |
| Communications and evidence | spine_messages, spine_calendar_events, spine_meetings, spine_calls, spine_documents, spine_conversations, spine_activities, spine_evidence_links, spine_provenance | message ingested, meeting completed, document linked, evidence attached |
| Continuity and knowledge | memory_items, memory_promotion_queue, org_memory_items, knowledge_documents, knowledge_chunks, spine_signals | observation triaged, memory proposed, promoted, superseded, signal resolved |
| Customer and commercial lifecycle | spine_accounts, spine_leads, spine_opportunities, spine_contracts, spine_subscriptions, spine_invoices, spine_renewals, spine_orders, spine_campaigns, spine_vendors | lead qualified, opportunity advanced, contract signed, invoice paid, renewal decided |
| Product, delivery and operations | spine_products, spine_features, spine_releases, spine_sprints, spine_tickets, spine_incidents, spine_budgets, spine_expenses, spine_assets | requirement proposed, feature built, release verified, incident resolved, expense approved |
| Integration and platform control | spine_connector_catalog, integration_connections, spine_connector_installations, integration_provider_schemas, integration_schema_mappings, spine_schema_version_events | connector authorized, binding validated, schema discovered, sync completed, scope revoked |
The Account Intelligence reference maps cleanly into this tenant model:
| Reference entity | Tenant canonical representation |
|---|---|
| Account Master | spine_accounts |
| People Team | spine_persons + tenant-scoped relationships to spine_accounts |
| Business Context | typed business-context entity associated to an account through spine_relationships |
| Strategic Objectives | spine_objectives |
| Capabilities and API Portfolio | spine_assets / capability registry plus typed relationships |
| Value Streams and Initiatives | spine_processes and spine_projects |
| Health Metrics and Signals | spine_signals, timeline events and entity-specific measurement records |
| Risk Register | typed risk entity linked to affected entities and mitigation work |
| Engagement Log | spine_activities, linked messages, meetings and calls |
| Success Plan and Task Manager | spine_projects / plans plus spine_tasks and spine_work_items |
The typed entity expansion is additive. A future table is added because it owns
a stable business entity and lifecycle—not because a user interface introduces
a new tab.
5. Flow A-D: one routing model, four kinds of material
All flows carry the same scope envelope. Flow classification decides handling
and promotion policy; it never creates a departmental partition.
| Flow | Material | Operational handling | Canonical promotion | Canonical output |
|---|---|---|---|---|
| A — structured operational data | Provider records, tuples, state changes, metrics and lifecycle updates | Connector intake, idempotency, schema validation and a bounded normalized candidate | Deterministic normalization creates a candidate. The promotion queue and policy decide whether it can be system-promoted or requires review. | Typed entity/version/relationship/event rows with external identity, provenance and connector lineage. |
| B — documents and communications | Emails, messages, meetings, calls, transcripts, documents, attachments and raw provider artifacts | Preserve raw evidence in R2; cache only retrieval metadata and extracted candidate links in D1/KV | Triage and policy promote only validated entity links, extracted actions, decisions, signals or knowledge. | Evidence record, source link, permitted structured entity changes and searchable knowledge references. |
| C — AI and cognitive context | Twin sessions, plans, reasoning outputs, agent tool results, brainstorming and memory candidates | Store bounded session/context and proposal staging. No Flow C component writes canonical business truth. | Always through Triage → promotion record → the required human approval → Governed Spine Writer. | Approved memory, knowledge, decision, task, signal or other explicitly typed entity with cited evidence. |
| D — platform binding and control | Authenticated identity, tenant/account/network resolution, RBAC, consent, connector bindings, schema compatibility, policy, entitlement and runtime configuration | Verify and cache only short-lived resolved context; record operational health and idempotency state | Governed platform write for binding/control records. Flow D validates the authority envelope for A/B/C; it does not partition business truth. | Connector and schema binding records, consent, policy/audit and resolved scope for every other flow. |
Flow event record
Every material event is represented in spine_flow_events with:
tenant_id + tenant_account_id + spine_network_id
+ flow (A | B | C | D)
+ phase (received | normalized | triaged | queued | approved | promoted |
projected | reconciled | rejected | expired)
+ subject entity/event + connector/binding lineage + trace/correlation IDs
This is the requested operational record for system, connector, agent and
human activity. It is broader than a user action log and supports a complete
trace from external source to Workbench projection and back to a verified
outcome.
6. Promotion and sync rules
Operational to Fortress
- A connector, user action, page/canvas proposal, or agent produces an
operational candidate. - The candidate includes the scope envelope, evidence references, affected
entity IDs, source flow, trace/correlation IDs and proposed operation. - It is recorded in
spine_promotion_queue; raw content remains in R2 or its
bounded operational reference, never copied blindly into a truth table. - The policy determines the appropriate route:
- deterministic, low-risk Flow A data may be promoted by the governed
system route once schema and provenance are valid; - Flow B derived meaning, Flow C cognitive material, material record merges,
decisions, memory and consequential changes require the applicable human
approval; - a rejected or expired candidate never becomes canonical.
- deterministic, low-risk Flow A data may be promoted by the governed
- Only the Governed Spine Writer commits canonical entities, versions,
relationships, evidence links and audit records atomically.
No browser, page/canvas, Twin, connector runtime, MCP tool or operational D1
worker writes a Fortress entity table directly.
Fortress to operational
- A canonical commit creates
spine_canonical_change_outboxrecord and a
spine_flow_eventsentry. - Pipeline and the Projection Engine consume the outbox, invalidate affected
D1/KV keys and build fresh, RBAC-safe cache entries. - A cache receipt records the canonical entity version applied.
- The Workbench requests the projected shape through Gateway; it never reads
Fortress or a connector/provider model directly.
An operational cache miss is a partial-evidence/read-rebuild condition. It is
never permission to substitute seed data or to fabricate a new truth record.
7. Evidence, audit and lifecycle accountability
| Need | Canonical record |
|---|---|
| What happened and where in the route | spine_flow_events, spine_timeline_events |
| What durable entity changed | typed entity row + spine_entity_versions |
| Why it changed | spine_provenance, spine_evidence_links, source/evidence reference |
| Who/system made or requested it | actor_type, actor_id, connector and binding lineage in the flow event |
| Who authorized it | spine_decisions, spine_approvals, spine_audit_log |
| How an operational candidate became truth | spine_promotion_queue linked to decision/approval and target entity |
| How truth became a current view | spine_canonical_change_outbox plus operational sync receipt/cache version |
The required line of evidence is therefore:
source artifact or user/system action
→ Flow A/B/C/D event
→ candidate and evidence
→ promotion decision / approval where required
→ canonical entity version
→ outbox
→ operational projection cache
→ RBAC-safe Workbench view
8. Projection and RBAC
The Workbench receives a projection, never a raw table or a department schema.
The Projection Engine applies:
- resolved tenant, tenant account and Spine Network;
- authenticated user membership and permissions;
- workspace, object, relationship and context scope;
- entity visibility, field visibility and capability policy;
- role/department/industry only as view-composition inputs.
This makes cross-projections safe: the same canonical account can appear as a
renewal risk, an invoice context, a project dependency, a support incident
relationship or an executive outcome only when the reader's RBAC policy allows
it.
9. Implementation and enforcement sequence
039_tenant_network_scope_and_promotion_flow.sql establishes the root account
and network tables, the universal entity scope map, promotion queue, canonical
outbox and all-flow log. It also adds tenant_account_id and
spine_network_id to existing tenant-scoped rows without rewriting legacy
data. 040_scope_global_events_provenance_and_evidence.sql applies the same
envelope to the generic event, provenance and evidence logs that predate the
tenant-scoped model.
041_app_category_entity_domain_classification.sql adds the versioned
classification registries and entity classification record. It gives the
Projection Engine a domain filter and lifecycle routing key without turning
department into storage.
The companion D1 migration creates only rebuildable cache/staging/receipt
tables. It carries the same scope envelope but cannot become a source of
truth.
The safe cutover is:
- create and backfill tenant account/network records;
- attach scope rows to existing canonical entities and active connector
bindings; - make Gateway/Pipeline require the complete scope envelope on new writes;
- backfill/repair legacy rows conservatively;
- add validated
NOT NULL/foreign-key enforcement only after the migration
report has no unresolved active records; - switch operational cache readers and writers to the new scoped cache tables;
- prove isolation with cross-tenant, cross-account, cross-network,
cross-connector and RBAC projection tests.
No department migration is part of this sequence.
10. Closed four-flow lifecycle
The four flows operate through one closed lifecycle in Development, Customer
Zero and Customer Production. Flow D is the authority envelope for every Flow
A, B or C event; it is not a fourth business-data partition.
External source / Workbench / AI or MCP consumer
→ Gateway and Flow D authority binding
→ raw evidence preservation + immutable scoped event
→ Flow A deterministic normalization
or Flow B deterministic extraction/link preparation
or Flow C adaptive Triage
→ Operational Spine candidate/cache
→ promotion policy + required human approval
→ Governed Spine Writer
→ Neon Fortress
→ canonical change outbox
→ Operational Spine/search/projection rehydration
→ RBAC-scoped Workbench
→ contextual Silent Twin
→ Capability → Governance → approval token → Hermes
→ provider outcome
→ re-ingestion → verification → reconciliation
→ Governed Spine Writer → Neon Fortress
This sequence resolves several wording traps:
- Customer Zero is an operating tenant and isolated environment, not a
separate product, database model or control-surface application. - Twin is the AI Co-worker behavior. “Co-worker” is positioning for the
Twin when it accepts delegated work; it is not another runtime beside Twin. - Triage prepares and routes candidates. It does not approve its own
candidate and does not commit canonical truth. - A Projection is not a copy of truth. D1/KV projection state may be stale
or rebuilt; the versioned Neon entity remains authoritative. - Aging never causes truth promotion. Promotion is caused by evidence,
schema/provenance validity, policy and required authority.
11. OODA, search and context organization
The Four Buttons remain the exact user-facing OODA grammar:
| OODA | User control | Runtime responsibility |
|---|---|---|
| Observe | Store in Spine | Capture an observation through Gateway, evidence preservation and the governed write path. |
| Orient | Ask Your Twin | Assemble permitted context and retrieve/rank relevant entity, relationship, timeline, document, memory and evidence state. |
| Decide | Assign Your Twin | Create a bounded assignment, draft, proposal or immutable action plan. No external mutation occurs. |
| Act | Approve Twin's Action | Governance validates authority and issues the token used by Hermes for execution. |
Normalizer and Triage prepare material that can later be searched, but they are
not the whole search runtime:
Flow D tenant/RBAC binding
→ relational + relationship + timeline + full-text + vector retrieval
→ evidence/freshness/authority filtering
→ relevance and work-priority ranking
→ bounded Active Context
→ Projection Engine or Twin
Tenant and permission filtering occurs before ranking. Search indexes and
embeddings are derived structures; they never own truth. A material click may
refresh or reuse Active Context, but it does not automatically start expensive
model reasoning or open a permanent Twin panel.
Triage participates in context organization by classifying, linking,
deduplicating and prioritizing incoming unstructured/cognitive candidates.
Projection-time search participates by cumulatively retrieving the already
permitted material needed for the active work. These are complementary
responsibilities, not one combined authority.
12. Retention, aging and historical evidence
Retention is policy by material class and tenant. The values below are safe
defaults to validate, not a replacement for tenant, contractual, regulatory,
deletion or legal-hold policy.
| Data class | Authoritative store | Default operational posture | Aging effect |
|---|---|---|---|
| Sessions, temporary signals and transient context | D1/KV | Minutes to 7 days | Expire; reconstruct where possible. Never promote because of age. |
| Active operational projection/cache state | D1/KV | Up to 30 days by class | Rebuild from Fortress/outbox or expire when no longer active. |
| Candidate memory, knowledge, decisions and proposals | Operational staging + evidence reference | Until reviewed, rejected or policy-expired | Promotion requires the applicable policy and human authority. |
| Canonical entities, relationships, outcomes and audit | Neon Fortress | Tenant/record-class retention policy | Version, supersede, export or delete only through governed retention operations. |
| Raw artifacts and immutable evidence bytes | R2 | Evidence policy, lifecycle and legal hold | Transition storage class, retain or delete through explicit R2 policy; Spine retains governed metadata and lineage. |
| Embeddings and search indexes | Vector/search services | Same or shorter lifetime than their permitted source | Delete/rebuild when the source is deleted, revoked, reclassified or re-embedded. |
The long-horizon tier is a Historical Evidence/Analytics tier, not a second
canonical Spine. R2 lifecycle policies may transition evidence to lower-cost
storage classes, while bucket locks may enforce minimum retention. Neon remains
the authoritative metadata, policy, lineage and entity record. Tenant export,
right-to-delete, legal hold and residency requirements must be resolved before
any fixed production retention schedule is enabled.
13. Development, Customer Zero and Customer Production
All three environments run the same logical contracts and four flows. They do
not share data, credentials, queue state, cache state, evidence or deployment
authority.
| Environment | Data and purpose | Canonical truth | Operational state | Release rule |
|---|---|---|---|---|
| Development | Synthetic fixtures, approved redacted reproductions and test providers | Disposable Development Neon branch/database when persistence tests require it | Dedicated Development D1/KV/R2/queues/search | Code/configuration may be promoted after tests. Development data rows never promote. |
| Customer Zero | IntegrateWise's real internal operations | Dedicated Customer Zero Neon database/branch and credential boundary | Dedicated Customer Zero D1/KV/R2/queues/search and audit | Proves production behavior. Only reviewed code/configuration/policy may move toward Customer Production; internal memory/data never does. |
| Customer Production | External tenant data and customer-authorized providers | Production Neon with enforced tenant scope/RLS, or a dedicated customer cell where required | Production tenant-scoped D1/KV/R2/queues/search; dedicated resources for contractual isolation | Receives versioned releases only. No customer data flows into Customer Zero or another tenant. |
There is no per-department D1, Neon schema, Worker or Spine. Department,
industry and role remain projection dimensions. A dedicated tenant cell may be
selected for contractual isolation, residency, scale or regulatory reasons;
that is a deployment policy, not a different logical schema.
The default compute plane is the shared, stateless Cloudflare Platform services
with trusted tenant resolution at Gateway and tenant-aware bindings underneath.
Durable Objects may coordinate strongly consistent per-tenant or per-workspace
runtime state. Workers for Platforms is optional and is used only when
IntegrateWise must deploy and isolate customer-supplied or agent-generated code,
such as a governed coding-agent or extension runtime. Ordinary multi-tenant
Gateway, Pipeline, Projection, Governance and Hermes execution does not require
one Worker script per tenant.
Cloudflare Workers may connect to the Neon Fortress directly with the approved
driver or through Hyperdrive. This does not change storage authority: D1 remains
bounded operational state and Neon remains the Fortress.
Current Cloudflare implementation references:
- Workers for Platforms
and its
user-Worker deployment examples; - Neon from Cloudflare Workers;
- R2 object lifecycle policies
and R2 bucket locks.
14. Cross-environment release and replay
Only release artifacts cross environment boundaries automatically:
Development proof
→ reviewed code/schema/configuration/policy artifact
→ Customer Zero validation
→ reviewed production release
→ Customer Production
Data movement follows stricter rules:
- Customer Zero data and memory never seed Customer Production.
- Customer Production tenant data never enters Customer Zero or another
customer tenant. - A production incident may become a Development reproduction only after
authorization, redaction and synthetic reconstruction. It is a new
Development ingestion event, not a cross-environment Spine promotion. - Aggregated product telemetry may enter an internal observability scope only
under an explicit telemetry/privacy contract. It is not tenant continuity or
business truth. - Every replay is scoped, idempotent, auditable and prevented from performing
provider side effects unless its governed replay policy explicitly permits
them.
No dev=true, cz=true or prod=true row marker is an isolation boundary.
Isolation is enforced by environment-specific resources plus the complete
tenant/account/network authority envelope.