From 8c9ed840a3f4dce83ddebecd48db6c3e9880da1f Mon Sep 17 00:00:00 2001 From: Mikhail Date: Sun, 16 Aug 2026 16:01:55 +0300 Subject: [PATCH] docs: propose durable Continuity action envelope --- ...1-continuity-action-envelope-proposal.json | 16 ++++ docs/CONTINUITY_ACTION_ENVELOPE_PROPOSAL.md | 90 +++++++++++++++++++ 2 files changed, 106 insertions(+) create mode 100644 dev/tasks/ARCH-000001-continuity-action-envelope-proposal.json create mode 100644 docs/CONTINUITY_ACTION_ENVELOPE_PROPOSAL.md diff --git a/dev/tasks/ARCH-000001-continuity-action-envelope-proposal.json b/dev/tasks/ARCH-000001-continuity-action-envelope-proposal.json new file mode 100644 index 0000000..10ea88d --- /dev/null +++ b/dev/tasks/ARCH-000001-continuity-action-envelope-proposal.json @@ -0,0 +1,16 @@ +{ + "task_id": "ARCH-000001", + "task_revision": 1, + "architecture_revision": "bootstrap-1", + "base_repo_revision": "543b93105bacc8617ece73d9879410ffb4d1d586", + "risk_tier": "E", + "intent": "Produce a proposal-only resolution for the missing durable typed action envelope and owner transition contract required before Creator can mutate Continuity through Authority, Commit, Executor, and reconciliation.", + "allowed_change_scope": {"paths": ["docs/CONTINUITY_ACTION_ENVELOPE_PROPOSAL.md", "dev/tasks/ARCH-000001-continuity-action-envelope-proposal.json"]}, + "forbidden_change_scope": {"paths": ["architecture/**", "security/**", "database/**", "modules/**", "contracts/**", "adapters/**", "cmd/**", "deploy/**", "tests/**"]}, + "allowed_architecture_delta": {"new_cross_module_dependencies": 0, "new_canonical_owners": 0, "new_privileges": 0}, + "semantic_owner": "proposal-only", + "assumptions": ["No Continuity mutation is safe until an accepted architecture decision defines a typed durable command and reconciliation semantics"], + "acceptance_scenarios": ["proposal identifies every observed blocking gap", "proposal preserves Continuity ownership and Commit isolation", "proposal defines crash, retry, idempotency, revision and reconciliation requirements", "no protected architecture or implementation file is modified"], + "required_tests": ["architecture preflight", "diff-scope review"], + "terminal_gap_states": ["BLOCKED_BY_ARCHITECTURE_GAP", "BLOCKED_BY_SPEC_GAP"] +} diff --git a/docs/CONTINUITY_ACTION_ENVELOPE_PROPOSAL.md b/docs/CONTINUITY_ACTION_ENVELOPE_PROPOSAL.md new file mode 100644 index 0000000..744f627 --- /dev/null +++ b/docs/CONTINUITY_ACTION_ENVELOPE_PROPOSAL.md @@ -0,0 +1,90 @@ +# Continuity Action Envelope Proposal + +Status: **PROPOSED — not architecture authority** +Task: `ARCH-000001`, revision 1 +Base: `543b93105bacc8617ece73d9879410ffb4d1d586` + +## Objective + +Enable one explicit Creator-initiated Continuity state transition without allowing the UI, gateway, Commit Runtime, or another module to write Continuity canonical storage directly. + +Required path: + +`Creator session → owner validation → live Authority validation → durable Commit → Executor → Continuity owner CAS → durable attempt/outcome → reconciliation` + +## Observed architecture gaps + +1. `commit.ActionProposal.Target` is only a `work.TaskTarget`. It can express the live Work justification but cannot identify a Continuity subject, expected Prospective revision, or requested transition without conflating semantic identifiers. +2. `commit.authorized_actions` persists only action ID, intent ID, state, and revision. The immutable proposal, grant/scope evidence, operation subject, expected revision, and operation parameters are lost after restart. +3. Commit Runtime exposes authorization and terminal-attempt insertion, but no execution endpoint invokes `commitdomain.Execute` with a production Executor. +4. The only Executor is the deterministic test adapter. There is no remote Continuity executor with idempotent delivery and read-only reconciliation. +5. Continuity persistence uses an upsert. A mutation command needs an owner-local atomic compare-and-swap on ID, owner Principal, current state, and expected revision. +6. Creator authentication is not consumed by Commit Runtime. Actor, Principal, and Grant must be constructed from a validated session/server policy, not accepted as trusted browser fields. +7. Authority V1 validates an active grant and scope but does not constrain `CapabilityID + Operation`. A non-empty arbitrary operation currently passes domain validation. +8. V1 does not specify which Prospective transition a Creator may request, what evidence is required, or whether the command changes only Prospective state or also Commitment state. + +## Proposed minimum contracts + +### Durable authorized envelope + +Persist an immutable envelope before execution with: + +- `AuthorizedActionID`, `ActionIntentID`, Actor, Principal; +- Authority grant ID and revision, Scope ID; +- Work justification target: Task ID, Goal ID, Scope ID, revision; +- operation capability and typed operation name; +- typed operation subject: `ProspectiveItemID` and expected Prospective revision; +- requested target state and optional evidence reference; +- authorization time and envelope revision. + +The Work target remains justification. The ProspectiveItem remains the operation subject. They must not reuse one identifier field. + +### Continuity owner command + +Continuity Runtime should accept only an internal typed executor request containing the committed envelope identity and operation subject. The owner must: + +- validate the permitted state transition in Continuity domain code; +- atomically update with `WHERE id = ? AND owner_principal_id = ? AND state = ? AND revision = ?`; +- increment revision exactly once; +- record or return an idempotency receipt keyed by `ActionIntentID`; +- return conflict for stale state/revision without mutation. + +### Executor and reconciliation + +The isolated Commit Runtime owns a Continuity HTTP Executor adapter. A timeout records `UNKNOWN_OUTCOME`; it never blindly retries. Reconciliation performs a read-only receipt/result query by `ActionIntentID` and creates a new attempt record. + +### Creator command boundary + +The public Creator command endpoint must: + +- validate the bounded Creator session through Identity; +- derive Actor and Principal server-side; +- use a server-selected Grant policy; +- require an explicit Work justification target and its current revision; +- require the selected ProspectiveItem and current revision; +- never accept arbitrary capability or operation strings from the browser; +- return committed action/attempt identities and outcome state. + +## Required decisions before implementation + +1. **First allowed transition.** Choose exactly one: + - `DELIVERED → SATISFIED` with an evidence reference (recommended); + - `ARMED → SUPPRESSED` with a cancellation reason, which requires new lifecycle semantics; + - another explicitly specified transition. +2. **Commit durability shape.** Approve a migration storing the full immutable authorized envelope and operation subject. +3. **Idempotency receipt ownership.** Approve a Continuity-owned receipt keyed by `ActionIntentID`, or specify another rebuild/reconciliation source. +4. **Operation authorization.** Define the allowed mapping between Creator grant class, capability, operation, and scope. +5. **Commitment interaction.** State whether the first transition changes only `ProspectiveItem` or also its parent Commitment. Cross-owner or multi-aggregate atomicity must not be implied. + +## Proposed implementation slices after acceptance + +1. Accepted ADR/registry-compatible contract decision and Tier E guardrail review. +2. Commit envelope contract plus Commit-owned migration and restart recovery tests. +3. Continuity transition command, CAS persistence, idempotency receipt, and owner tests. +4. Commit Executor/reconciler adapter with injected timeout and no-blind-retry tests. +5. Session-authenticated Creator command orchestration with revoked/stale/adversarial tests. +6. Gateway allowlist and explicit confirmation UI. + +## Current terminal state + +`BLOCKED_BY_ARCHITECTURE_GAP` for implementation of Creator mutation. Read-only Creator APIs and the deployed console remain valid and operational.