{"slug":"business/LIFE_CYCLES","title":"Life Cycles","section":"business","sectionLabel":"Business","status":"unclassified","type":"document","path":"business/LIFE_CYCLES.mdx","bytes":6500,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n> Derived from actual source code only. No documentation used.\n\n## 1. Entity/Object Life Cycle\n\n**Code:** `apps/web/src/lib/workspace/workspace-config.ts`, `apps/web/src/lib/workspace/business-object.ts`\n\nObjects are created or imported as canonical Business Objects and then move through department-defined stages.\n\n- **Create/Seed:** `department-seed.ts` defines `DeptSeed.projection` and `DeptSeed.entities`. Hooks `useSpineEntities` / `useSpineEntitiesBatch` fetch entities or fall back to these seeded rows.\n- **Stage progression:** `workspace-config.ts` defines `WorkspaceStage[]` per department. Sales uses `prospect → qualify → proposal → negotiate → closed-won/closed-lost`. Services uses `open → in_progress → pending → resolved → closed`.\n- **Field origin:** `FieldOrigin.spine | memory | hybrid` in `BusinessObjectField`. Fields can originate from Spine truth, Twin memory, or hybrid.\n- **Close/Archive:** Operations like `close` in `operation-registry.ts` represent terminal transitions. UI quick actions in `entity-detail.tsx` include Archive and Delete.\n\n## 2. Attention State Life Cycle\n\n**Code:** `apps/web/src/lib/workspace/business-object.ts:228`\n\nEvery object carries an ambient attention state with a strict state machine:\n\n- `observe` → `assist` when event is `twin_discovers`\n- `assist` → `execute` when event is `human_approves`\n- `execute` → `observe` when event is `execution_complete`\n\nVisual indicators: `○` observe, `◐` assist, `●` execute. Labels: Watching → Needs Judgment → Executing.\n\n## 3. Operation Life Cycle\n\n**Code:** `apps/web/src/components/l1/workbench/operations-bar.tsx`, `apps/web/src/lib/operations/operation-registry.ts`\n\nOperations are first-class verbs attached to objects.\n\n- **Idle → Preparing:** User selects an operation. `OperationsBar` indicates intent without execution.\n- **Preparing → Ready:** Input fields validated; capability resolved via `capabilityPattern`.\n- **Ready → Approving:** If `requiresApproval` is true, operation enters approval gate.\n- **Approving → Executed:** Human approves; execution commits via Execution layer.\n- **Execution complete:** Object’s attention state returns to `observe`; outcome becomes a timeline entry.\n\nOperation families: communication, collaboration, productivity, documents, business, ai. Entity-specific operation sets are defined in `ENTITY_OPERATION_MAP`.\n\n## 4. Decision Life Cycle\n\n**Code:** `apps/web/src/lib/workspace/business-object.ts:124`, `apps/web/src/components/l1/workbench/decision-rail.tsx`\n\nDecisions are pending judgments attached to objects.\n\n- **Pending:** Created by Twin or user; shown in DecisionRail.\n- **Approved/Declined:** Human responds via DecisionRail actions.\n- **Expired:** Time-bound decisions reach `expiresAt` without response.\n- **Proposed operation:** Each decision can carry a `proposedOperation` that executes on approval.\n\n## 5. Data/Projection Life Cycle\n\n**Code:** `apps/web/src/hooks/use-spine-entities.ts`, `apps/web/src/lib/api-client.ts`, `apps/web/src/lib/spine/department-seed.ts`\n\nEntity data flows through a fail-open pipeline so UI never surfaces raw backend failures.\n\n1. UI requests data via `useSpineEntities` or `useSpineEntitiesBatch`.\n2. Hooks call `/api/v1/pipeline/entities` or `/batch` through `apiFetch`.\n3. On failure, catch block falls back to `DEPARTMENT_SEED` rows collected across all departments.\n4. Seeded shapes match exact field names/KPIs read by domain views.\n5. UI renders with realistic data whether API succeeds or fails.\n\n## 6. Integration/Sync Life Cycle\n\n**Code:** `apps/web/src/lib/workspace/business-object.ts:204`, `services/gateway/src/workspace-spine.ts:1022`\n\nExternal providers are invisible infrastructure. Each provider mapping has a lifecycle:\n\n- **synced:** Provider data matches Spine truth.\n- **syncing:** Ongoing reconciliation.\n- **stale:** Provider data diverged; refresh needed.\n- **error:** Sync failed; surface remains usable via fallback data.\n\n`getConnectorCatalog()` now sources from internal catalog (`getSerializableCatalog()`) rather than Nango API, maps metadata including `supportedEntities`, `authType`, `mcpTools`, and returns `source: \"integratewise-connectors\"`.\n\n## 7. Field Confidence Life Cycle\n\n**Code:** `apps/web/src/lib/workspace/business-object.ts:88`\n\nFields carry `confidence: number | null`:\n\n- Spine fields: `confidence = null`, treated as canonical truth.\n- Memory fields: `confidence` between 0–100, generated by Twin/intelligence.\n- Hybrid fields: blend of spine + memory with explicit confidence.\n\nAs Twin learns or human edits, field confidence and provenance can update without changing the object’s attention state unless a Twin discovery occurs.\n\n## 8. Onboarding/Activation Life Cycle\n\n**Code:** `apps/web/src/components/activation/onboarding/role-domain/`, `apps/web/src/lib/workspace/workspace-config.ts`\n\nUser selects role/domain during onboarding. That department maps to a `WorkspaceConfig` that determines:\n\n- `objectType`\n- Fields, stages, views\n- Available operation families\n- Related types\n\nThis seeds the initial workspace surface and data scope.\n\n## 9. Twin Interaction Life Cycle\n\n**Code:** `apps/web/src/lib/workspace/business-object.ts:175`, `apps/web/src/components/l1/workbench/entity-detail.tsx:351`\n\nTwin operates as an embedded overlay inside objects, not a sidebar:\n\n1. **Observation:** Twin adds observations to `TwinContext.observations`.\n2. **Recommendation:** Twin populates `TwinContext.recommendations`.\n3. **Proposal:** Twin creates a `Decision` with recommendation, evidence, and optional `proposedOperation`.\n4. **Judgment:** Human reviews via DecisionRail; approves or declines.\n5. **Execution:** Approved proposals execute; results written to timeline.\n6. **Learning:** Outcome feeds back into Twin memory/intelligence via action-loop/memory-writeback paths in `services/intelligence`.\n\n## 10. Service/Test Life Cycle\n\n**Code:** `services/gateway/src/gateway.test.ts`, `services/intelligence/src/dispatch.test.ts`, `services/billing/src/lib/__tests__/webhook-idempotency.test.ts`\n\nNon-UI services verify their own life cycles:\n\n- **Gateway:** request → auth/routing → projection/catalog response.\n- **Intelligence dispatch:** event → tenant class lookup → s11_native or handoff_layer decision → log.\n- **Billing webhook:** signature verification → idempotency check → process or skip payment → entitlement enforcement with fail-open in dev, fail-closed in prod.\n"}