Unclassified

Life Cycles

Derived from actual source code only. No documentation used.

1. Entity/Object Life Cycle

Code: apps/web/src/lib/workspace/workspace-config.ts, apps/web/src/lib/workspace/business-object.ts

Objects are created or imported as canonical Business Objects and then move through department-defined stages.

Create/Seed: department-seed.ts defines DeptSeed.projection and DeptSeed.entities. Hooks useSpineEntities / useSpineEntitiesBatch fetch entities or fall back to these seeded rows.
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.
Field origin: FieldOrigin.spine | memory | hybrid in BusinessObjectField. Fields can originate from Spine truth, Twin memory, or hybrid.
Close/Archive: Operations like close in operation-registry.ts represent terminal transitions. UI quick actions in entity-detail.tsx include Archive and Delete.

2. Attention State Life Cycle

Code: apps/web/src/lib/workspace/business-object.ts:228

Every object carries an ambient attention state with a strict state machine:

observe → assist when event is twin_discovers
assist → execute when event is human_approves
execute → observe when event is execution_complete

Visual indicators: ○ observe, ◐ assist, ● execute. Labels: Watching → Needs Judgment → Executing.

3. Operation Life Cycle

Code: apps/web/src/components/l1/workbench/operations-bar.tsx, apps/web/src/lib/operations/operation-registry.ts

Operations are first-class verbs attached to objects.

Idle → Preparing: User selects an operation. OperationsBar indicates intent without execution.
Preparing → Ready: Input fields validated; capability resolved via capabilityPattern.
Ready → Approving: If requiresApproval is true, operation enters approval gate.
Approving → Executed: Human approves; execution commits via Execution layer.
Execution complete: Object’s attention state returns to observe; outcome becomes a timeline entry.

Operation families: communication, collaboration, productivity, documents, business, ai. Entity-specific operation sets are defined in ENTITY_OPERATION_MAP.

4. Decision Life Cycle

Code: apps/web/src/lib/workspace/business-object.ts:124, apps/web/src/components/l1/workbench/decision-rail.tsx

Decisions are pending judgments attached to objects.

Pending: Created by Twin or user; shown in DecisionRail.
Approved/Declined: Human responds via DecisionRail actions.
Expired: Time-bound decisions reach expiresAt without response.
Proposed operation: Each decision can carry a proposedOperation that executes on approval.

5. Data/Projection Life Cycle

Code: apps/web/src/hooks/use-spine-entities.ts, apps/web/src/lib/api-client.ts, apps/web/src/lib/spine/department-seed.ts

Entity data flows through a fail-open pipeline so UI never surfaces raw backend failures.

UI requests data via useSpineEntities or useSpineEntitiesBatch.
Hooks call /api/v1/pipeline/entities or /batch through apiFetch.
On failure, catch block falls back to DEPARTMENT_SEED rows collected across all departments.
Seeded shapes match exact field names/KPIs read by domain views.
UI renders with realistic data whether API succeeds or fails.

6. Integration/Sync Life Cycle

Code: apps/web/src/lib/workspace/business-object.ts:204, services/gateway/src/workspace-spine.ts:1022

External providers are invisible infrastructure. Each provider mapping has a lifecycle:

synced: Provider data matches Spine truth.
syncing: Ongoing reconciliation.
stale: Provider data diverged; refresh needed.
error: Sync failed; surface remains usable via fallback data.

getConnectorCatalog() now sources from internal catalog (getSerializableCatalog()) rather than Nango API, maps metadata including supportedEntities, authType, mcpTools, and returns source: "integratewise-connectors".

7. Field Confidence Life Cycle

Code: apps/web/src/lib/workspace/business-object.ts:88

Fields carry confidence: number | null:

Spine fields: confidence = null, treated as canonical truth.
Memory fields: confidence between 0–100, generated by Twin/intelligence.
Hybrid fields: blend of spine + memory with explicit confidence.

As Twin learns or human edits, field confidence and provenance can update without changing the object’s attention state unless a Twin discovery occurs.

8. Onboarding/Activation Life Cycle

Code: apps/web/src/components/activation/onboarding/role-domain/, apps/web/src/lib/workspace/workspace-config.ts

User selects role/domain during onboarding. That department maps to a WorkspaceConfig that determines:

objectType
Fields, stages, views
Available operation families
Related types

This seeds the initial workspace surface and data scope.

9. Twin Interaction Life Cycle

Code: apps/web/src/lib/workspace/business-object.ts:175, apps/web/src/components/l1/workbench/entity-detail.tsx:351

Twin operates as an embedded overlay inside objects, not a sidebar:

Observation: Twin adds observations to TwinContext.observations.
Recommendation: Twin populates TwinContext.recommendations.
Proposal: Twin creates a Decision with recommendation, evidence, and optional proposedOperation.
Judgment: Human reviews via DecisionRail; approves or declines.
Execution: Approved proposals execute; results written to timeline.
Learning: Outcome feeds back into Twin memory/intelligence via action-loop/memory-writeback paths in services/intelligence.

10. Service/Test Life Cycle

Code: services/gateway/src/gateway.test.ts, services/intelligence/src/dispatch.test.ts, services/billing/src/lib/__tests__/webhook-idempotency.test.ts

Non-UI services verify their own life cycles:

Gateway: request → auth/routing → projection/catalog response.
Intelligence dispatch: event → tenant class lookup → s11_native or handoff_layer decision → log.
Billing webhook: signature verification → idempotency check → process or skip payment → entitlement enforcement with fail-open in dev, fail-closed in prod.