[K2B] External operation journal, outbox, and artifact durability #13

New issue

Closed

opened 2026-09-24 19:35:19 +00:00 by kilo · 1 comment

kilo commented

2026-09-24 19:35:19 +00:00

Member

Goal

Durably journal external-operation intent, delivery and observations, and finalize immutable content-addressed artifact references without implementing any live external provider.

Why

A local commit cannot make an external effect exactly-once. A restart-safe journal must preserve intent, distinguish delivery from domain acknowledgement and terminal outcomes, and reconcile uncertainty before retrying.

Scope

In scope

Stable Operation identity and canonical request digest.
Separate identities for domain-command admission deduplication, logical-effect deduplication, and inbound-observation deduplication. The command-admission identity uses K2A's command deduplication; logical-effect and inbound-observation identities remain distinct from it and from each other.
Durable INTENT and transactional outbox committed before any external delivery attempt.
Delivery-attempt records; distinct domain acknowledgement and rejection; running, waiting, terminal, and unknown observations.
Leases and fencing for single-controller/local delivery ownership; stale callbacks and stale fences are rejected.
Crash uncertainty, reconciliation before retry, and retry only for the same proven-safe original logical effect.
Content-addressed artifact storage and finalization, with immutable artifact references.
Backup, restore/restart, and recovery behavior for Operation, outbox, observation, fence, and artifact records.
Synthetic/fake external-effect seam and deterministic fault injection only. No live external provider or network service.

Out of scope

K3 Runtime/Workspace and worker implementation; K4 verification, AcceptedResult, and remediation; Forgejo, Codex, M5-B, Prefect, and Scarcity Router; usage/outcome accounting; real network I/O; distributed delivery ownership; and automatic merge or deployment.

Acceptance Criteria

Operations have stable identity and a versioned/canonical request digest; command-admission, logical-effect, and inbound-observation deduplication are distinct and independently tested.
INTENT and its outbox entry commit before a fake external effect can be attempted; no external I/O occurs inside a database transaction.
Delivery attempts, domain acknowledgement/rejection, and running/waiting/terminal/unknown observations remain distinct durable facts; observations are deduplicated by inbound-observation identity.
Leases/fences prevent concurrent local delivery ownership; stale callback/fence publication is rejected without rewriting history.
A crash after possible external effect but before local acknowledgement preserves uncertainty; recovery reconciles before retry and never advances from intent or delivery alone.
Artifact bytes are content-addressed and finalized before an immutable reference is published; reopen and backup/restore preserve verified references.
Named synthetic fault-injection regressions cover: B, review intent confused with dispatch (persist intent, crash/restart, and prove there is no accepted-review wait or WorkUnit advance; delivery attempt and semantic receipt remain distinct); D, transport succeeded but domain rejected (the fake reports transport success with rejected/invalid domain status, which remains a persisted rejection, not acknowledged execution); and E, waited for review never accepted (missing, rejected, accepted, and uncertain receipts remain distinct; wait requires a durable matching acceptance reference; reconcile and redispatch only the same proven-safe original operation).
Tests use only the synthetic/fake effect seam and require no network service, Forgejo, Runtime, Codex, M5-B, Prefect, or cloud service.

Constraints

Direct prerequisite: issue #5 (K2A). Direct dependent: issue #6 (K3).
Preserve ADR 0003 and the journal, outbox, and reconciliation contracts; at-least-once delivery is not exactly-once external execution.
Do not introduce provider integrations, public arbitrary state restoration, usage accounting, or a distributed worker system.

Links

Parent: issue #3 #3
Direct prerequisite: issue #5 #5
Direct dependent: issue #6 #6
Architecture: docs/adr/0003-durability-and-effects.md, docs/architecture/contracts.md, docs/architecture/threat-model.md, docs/architecture/successor.md

## Goal Durably journal external-operation intent, delivery and observations, and finalize immutable content-addressed artifact references without implementing any live external provider. ## Why A local commit cannot make an external effect exactly-once. A restart-safe journal must preserve intent, distinguish delivery from domain acknowledgement and terminal outcomes, and reconcile uncertainty before retrying. ## Scope ### In scope - Stable Operation identity and canonical request digest. - Separate identities for domain-command admission deduplication, logical-effect deduplication, and inbound-observation deduplication. The command-admission identity uses K2A's command deduplication; logical-effect and inbound-observation identities remain distinct from it and from each other. - Durable INTENT and transactional outbox committed before any external delivery attempt. - Delivery-attempt records; distinct domain acknowledgement and rejection; running, waiting, terminal, and unknown observations. - Leases and fencing for single-controller/local delivery ownership; stale callbacks and stale fences are rejected. - Crash uncertainty, reconciliation before retry, and retry only for the same proven-safe original logical effect. - Content-addressed artifact storage and finalization, with immutable artifact references. - Backup, restore/restart, and recovery behavior for Operation, outbox, observation, fence, and artifact records. - Synthetic/fake external-effect seam and deterministic fault injection only. No live external provider or network service. ### Out of scope K3 Runtime/Workspace and worker implementation; K4 verification, AcceptedResult, and remediation; Forgejo, Codex, M5-B, Prefect, and Scarcity Router; usage/outcome accounting; real network I/O; distributed delivery ownership; and automatic merge or deployment. ## Acceptance Criteria - [ ] Operations have stable identity and a versioned/canonical request digest; command-admission, logical-effect, and inbound-observation deduplication are distinct and independently tested. - [ ] INTENT and its outbox entry commit before a fake external effect can be attempted; no external I/O occurs inside a database transaction. - [ ] Delivery attempts, domain acknowledgement/rejection, and running/waiting/terminal/unknown observations remain distinct durable facts; observations are deduplicated by inbound-observation identity. - [ ] Leases/fences prevent concurrent local delivery ownership; stale callback/fence publication is rejected without rewriting history. - [ ] A crash after possible external effect but before local acknowledgement preserves uncertainty; recovery reconciles before retry and never advances from intent or delivery alone. - [ ] Artifact bytes are content-addressed and finalized before an immutable reference is published; reopen and backup/restore preserve verified references. - [ ] Named synthetic fault-injection regressions cover: **B, review intent confused with dispatch** (persist intent, crash/restart, and prove there is no accepted-review wait or WorkUnit advance; delivery attempt and semantic receipt remain distinct); **D, transport succeeded but domain rejected** (the fake reports transport success with rejected/invalid domain status, which remains a persisted rejection, not acknowledged execution); and **E, waited for review never accepted** (missing, rejected, accepted, and uncertain receipts remain distinct; wait requires a durable matching acceptance reference; reconcile and redispatch only the same proven-safe original operation). - [ ] Tests use only the synthetic/fake effect seam and require no network service, Forgejo, Runtime, Codex, M5-B, Prefect, or cloud service. ## Constraints - Direct prerequisite: issue #5 (K2A). Direct dependent: issue #6 (K3). - Preserve ADR 0003 and the journal, outbox, and reconciliation contracts; at-least-once delivery is not exactly-once external execution. - Do not introduce provider integrations, public arbitrary state restoration, usage accounting, or a distributed worker system. ## Links - Parent: issue #3 https://forgejo.creatidy.com/Creatidy/creatidy-kernel/issues/3 - Direct prerequisite: issue #5 https://forgejo.creatidy.com/Creatidy/creatidy-kernel/issues/5 - Direct dependent: issue #6 https://forgejo.creatidy.com/Creatidy/creatidy-kernel/issues/6 - Architecture: `docs/adr/0003-durability-and-effects.md`, `docs/architecture/contracts.md`, `docs/architecture/threat-model.md`, `docs/architecture/successor.md`

kilo referenced this issue

2026-09-24 19:36:40 +00:00

[Kernel v0] First useful vertical slice #3

kilo referenced this issue

2026-09-24 19:36:40 +00:00

[K2A] Durable SQLite history and projections #5

kilo referenced this issue

2026-09-24 19:36:40 +00:00

[K3] Synthetic execution, workspace, and authority enforcement #6

kilo referenced this issue

2026-09-25 20:54:42 +00:00

[K2B] Journal external operations and durable artifacts #17

kilo commented

2026-09-25 20:55:10 +00:00

Author

Member

Delivery ledger (issue #13)

PR: #17; feature HEAD a7035f31c36c9a19d7c3a24c96abbced6ac80116; base develop at 2fa51e965748279d843e8be1190003b4738b7e3b. Owner merged PR #17 into develop on 2026-09-25T21:47:35Z as commit 059482d045bd8e772005c9fbc1a9b89ce64ce26f; no promotion to main.
max_remediation_cycles = 10; remediation_used = 0 / 10. No K2B changes after original feature commit. Two invalid_request routing attempts were invalid diagnostics, not review cycles; installed Router policy version 6 lacked repository_review, then owner updated it to version 8.
Acceptance evidence: independent full review #600 maps all eight issue #13 criteria to code and synthetic tests B/D/E, with no blockers. No live provider/network, K3/K4, or automatic merge. Exact-feature-HEAD local checks make check (152 passed), make package-check, make audit (no known vulnerabilities), git diff --check passed; make check and make package-check reran successfully after review. Exact-feature-HEAD Forgejo PR CI #1944 succeeded.

Full independent review cycle 1: exact reviewed HEAD a7035f31c36c9a19d7c3a24c96abbced6ac80116, base develop at 2fa51e965748279d843e8be1190003b4738b7e3b; profile repository_review, monotone task floor L4, minima reasoning=5,coding=5,tool_use=5, requires_tool_use=true, requires_reasoning_mode=true (known numeric author floor unavailable). Valid Router selection at 2026-09-25T21:22:46Z: router_selected=zai/glm-5.3/max, dispatched=zai-coding-plan/GLM-5.3/max via documented provider adapter, routing_result=ROUTER_SELECTED; catalog v4, profile policy v8, resource policy v1, degraded=false. Agent Manager request am-1790371388993-7emwfr; independent read-only reviewer session ses_f258ca123ffeg2RLzMN8vVC9B4; REQUESTED=YES, DISPATCH_VERIFIED=YES by explicit Resolved models: GLM-5.3 (zai-coding-plan) · max; session completed. Full review #600, exact commit ID, non-stale: substantive reviewer verdict APPROVE; blocker IDs/titles: none; non-blocking suggestions in review; remediation none; resulting feature HEAD unchanged; remediation_used=0 / 10.

Review recording caveat: Forgejo stored review #600 as COMMENT, not formal APPROVED, because its MCP identity kilo was also PR author and Forgejo forbids self-approval. The distinct read-only reviewer session's complete review text concludes APPROVE with no blockers. This is a substantive independent verdict, not a Forgejo-recorded approval; owner exercised merge authority separately.

Completion: integrated into develop by owner merge commit 059482d045bd8e772005c9fbc1a9b89ce64ce26f. Local develop fast-forwarded and clean; merged local feature branch and its stale tracking ref removed. The separate detached .kilo/worktrees/fuchsia-nymphea worktree was not part of issue #13 and was left untouched. Issue can be closed; this does not release or promote main.

## Delivery ledger (issue #13) - PR: https://forgejo.creatidy.com/Creatidy/creatidy-kernel/pulls/17; feature HEAD `a7035f31c36c9a19d7c3a24c96abbced6ac80116`; base `develop` at `2fa51e965748279d843e8be1190003b4738b7e3b`. Owner merged PR #17 into `develop` on 2026-09-25T21:47:35Z as commit `059482d045bd8e772005c9fbc1a9b89ce64ce26f`; no promotion to `main`. - `max_remediation_cycles = 10`; `remediation_used = 0 / 10`. No K2B changes after original feature commit. Two `invalid_request` routing attempts were invalid diagnostics, not review cycles; installed Router policy version 6 lacked `repository_review`, then owner updated it to version 8. - Acceptance evidence: independent full review [#600](https://forgejo.creatidy.com/Creatidy/creatidy-kernel/pulls/17#issuecomment-11673) maps all eight issue #13 criteria to code and synthetic tests B/D/E, with no blockers. No live provider/network, K3/K4, or automatic merge. Exact-feature-HEAD local checks `make check` (152 passed), `make package-check`, `make audit` (no known vulnerabilities), `git diff --check` passed; `make check` and `make package-check` reran successfully after review. Exact-feature-HEAD [Forgejo PR CI #1944](https://forgejo.creatidy.com/Creatidy/creatidy-kernel/actions/runs/30) succeeded. 1. Full independent review cycle 1: exact reviewed HEAD `a7035f31c36c9a19d7c3a24c96abbced6ac80116`, base `develop` at `2fa51e965748279d843e8be1190003b4738b7e3b`; profile `repository_review`, monotone task floor `L4`, minima `reasoning=5,coding=5,tool_use=5`, `requires_tool_use=true`, `requires_reasoning_mode=true` (known numeric author floor unavailable). Valid Router selection at 2026-09-25T21:22:46Z: `router_selected=zai/glm-5.3/max`, `dispatched=zai-coding-plan/GLM-5.3/max` via documented provider adapter, `routing_result=ROUTER_SELECTED`; catalog v4, profile policy v8, resource policy v1, `degraded=false`. Agent Manager request `am-1790371388993-7emwfr`; independent read-only reviewer session `ses_f258ca123ffeg2RLzMN8vVC9B4`; `REQUESTED=YES`, `DISPATCH_VERIFIED=YES` by explicit `Resolved models: GLM-5.3 (zai-coding-plan) · max`; session completed. [Full review #600](https://forgejo.creatidy.com/Creatidy/creatidy-kernel/pulls/17#issuecomment-11673), exact commit ID, non-stale: substantive reviewer verdict **APPROVE**; blocker IDs/titles: none; non-blocking suggestions in review; remediation `none`; resulting feature HEAD unchanged; `remediation_used=0 / 10`. Review recording caveat: Forgejo stored review #600 as `COMMENT`, not formal `APPROVED`, because its MCP identity `kilo` was also PR author and Forgejo forbids self-approval. The distinct read-only reviewer session's complete review text concludes `APPROVE` with no blockers. This is a substantive independent verdict, not a Forgejo-recorded approval; owner exercised merge authority separately. **Completion: integrated into `develop`** by owner merge commit `059482d045bd8e772005c9fbc1a9b89ce64ce26f`. Local `develop` fast-forwarded and clean; merged local feature branch and its stale tracking ref removed. The separate detached `.kilo/worktrees/fuchsia-nymphea` worktree was not part of issue #13 and was left untouched. Issue can be closed; this does not release or promote `main`.