[EPIC] Universal causal effect journal and cross-capability undo #343

New issue

Open

opened 2026-09-08 02:03:35 +00:00 by nsaspy · 0 comments

nsaspy commented

2026-09-08 02:03:35 +00:00

Owner

Parent architecture: #624
Depends on: #625 conversational transactions; typed capability/tool lifecycle from #150/#159 and canonical cancellation.

Goal

Make every Zara side effect attributable, explainable and—where technically possible—reversible through a causal effect journal.

Target interactions:

undo everything you did since I started lunch;
why did that happen?;
roll back everything downstream of that mistake.

This is broader than undoing a user-command definition in #151. It applies across calendar, communications, files, SmartThings, tasks, settings, device actions, plugins and future providers.

Effect contract

Research and freeze a durable typed record equivalent to:

effect(
  id,
  principal,
  transaction,
  cause,
  capability,
  provider,
  resource,
  before,
  intended_after,
  observed_after,
  reversible,
  compensation,
  timestamp
).

The exact persisted representation is design-owned, but it must distinguish intended state, provider acknowledgement and independently observed state where available.

Causality

Represent causal edges between:

user intent transaction;
policy/rule decision;
tool/provider action;
resulting state observation;
subsequent actions triggered by that state.

Correlation IDs alone are insufficient: Zara must be able to identify the downstream effect subgraph of a specific decision/effect.

Undo semantics

reversible effects define a typed compensating operation or explicit not_reversible reason;
compensation is a new authorized transaction, never hidden mutation of history;
before compensating, verify current resource state to detect third-party/user changes;
conflicts produce a plan/clarification instead of blindly overwriting newer state;
partial rollback reports exactly what was and was not restored;
irreversible operations remain visible in the causal graph.

Never promise ACID rollback for third-party systems that cannot provide it.

Security / privacy

Effect records are principal-scoped and bounded. Do not persist secret bodies merely to make undo possible when provider-native IDs/versioning or encrypted private state can support compensation. Guest/public principals follow their constrained capability profile.

Tests

Use deterministic fake providers to prove multi-effect rollback, branching causal graphs, partial reversibility, state drift/conflict, duplicate compensation, cancellation races, cross-principal isolation, restart persistence and stale runtime generations. Add real provider adapters only with safe sandbox fixtures.

Acceptance

For supported reversible capabilities, Zara can show the causal chain from intent to observed effect and perform a policy-authorized compensating rollback without corrupting newer state. Unsupported/irreversible effects are reported precisely rather than faked.

Parent architecture: #624 Depends on: #625 conversational transactions; typed capability/tool lifecycle from #150/#159 and canonical cancellation. ## Goal Make every Zara side effect attributable, explainable and—where technically possible—reversible through a **causal effect journal**. Target interactions: - `undo everything you did since I started lunch`; - `why did that happen?`; - `roll back everything downstream of that mistake`. This is broader than undoing a user-command definition in #151. It applies across calendar, communications, files, SmartThings, tasks, settings, device actions, plugins and future providers. ## Effect contract Research and freeze a durable typed record equivalent to: ```text effect( id, principal, transaction, cause, capability, provider, resource, before, intended_after, observed_after, reversible, compensation, timestamp ). ``` The exact persisted representation is design-owned, but it must distinguish intended state, provider acknowledgement and independently observed state where available. ## Causality Represent causal edges between: - user intent transaction; - policy/rule decision; - tool/provider action; - resulting state observation; - subsequent actions triggered by that state. Correlation IDs alone are insufficient: Zara must be able to identify the downstream effect subgraph of a specific decision/effect. ## Undo semantics - reversible effects define a typed compensating operation or explicit `not_reversible` reason; - compensation is a **new authorized transaction**, never hidden mutation of history; - before compensating, verify current resource state to detect third-party/user changes; - conflicts produce a plan/clarification instead of blindly overwriting newer state; - partial rollback reports exactly what was and was not restored; - irreversible operations remain visible in the causal graph. Never promise ACID rollback for third-party systems that cannot provide it. ## Security / privacy Effect records are principal-scoped and bounded. Do not persist secret bodies merely to make undo possible when provider-native IDs/versioning or encrypted private state can support compensation. Guest/public principals follow their constrained capability profile. ## Tests Use deterministic fake providers to prove multi-effect rollback, branching causal graphs, partial reversibility, state drift/conflict, duplicate compensation, cancellation races, cross-principal isolation, restart persistence and stale runtime generations. Add real provider adapters only with safe sandbox fixtures. ## Acceptance For supported reversible capabilities, Zara can show the causal chain from intent to observed effect and perform a policy-authorized compensating rollback without corrupting newer state. Unsupported/irreversible effects are reported precisely rather than faked.