kcode-kmap-command-lane 0.1.0

Restart-safe durable command lane for administrator Kmap mutations
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

# kcode-kmap-command-lane 0.1.0

This library is the single restart-safe submission lane for administrator Kmap
commands. SQLite is authoritative for command lifecycle state; an in-memory
notification only wakes the supervised runtime promptly.

## Public API

`open(database_path, manager)` opens or creates the command table, recovers
every `Applying` record to `Queued`, and returns `(CommandLane,
CommandRuntime)`. `CommandRuntime` implements `Future<Output = Result<()>>` and
must be supervised after Kweb Manager readiness.

`CommandLane::submit(submission)` validates canonical durable identifiers,
serializes the typed decoded Kennedy operation, and commits a `Queued` record
before notifying the runtime. An exact repeated ID returns the original record;
reuse for different input returns `Error::Conflict`.

`CommandLane::snapshot()` returns every durable record in submission order.
The HTTP owner may select one record or serialize the collection without a
second status store.

`Submission` contains a 32-character lowercase hexadecimal `idempotency_id`,
one `DecodedKwebTool`, and expected visible transaction IDs keyed by canonical
node ID. Pending identifiers are invalid at this administrator boundary.

`Record` exposes the original submission, `State`, submission time, attempt
count, next attempt time, transaction ID, created node ID, and terminal error.
`State` is `Queued`, `Applying`, `Committed`, or `Failed`. `Error` is the public
enum `InvalidInput`, `Conflict`, or `Internal`.

## Lifecycle

The runtime processes records in durable submission order. It marks a record
`Applying`, calls Kweb Manager on a blocking task, and then records the signed
transaction outcome. Manager recovery checks exact command provenance in Kweb
history first, so a crash after Kweb commit but before the SQLite status update
does not apply the command twice.

Writer unavailability returns the record to `Queued` with exponential backoff
bounded at 60 seconds. Invalid input, missing nodes, and stale revisions become
terminal `Failed` records and do not block later commands. Runtime SQLite or
task failures terminate the future for application supervision.

Committed Kweb history is the authoritative replay record. The lane retains
workflow receipts for inspection but does not batch commands, open Kweb,
authorize users, decode HTTP, or render UI.