tmk241/hemx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(kanban): expose queued persistence state

Browse Source 
req: accessibility/004\nreq: client_local/013\nreq: performance/003
This commit is contained in:
slhx agent
2026-07-13 15:40:34 +02:00
parent 9b80444484
commit 978bf67a2c
3 changed files with 149 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
PLAN.md
+3 -3
View File
@@ -33,11 +33,11 @@ encryption, retention, backup, and deployment policy remain host concerns.
## Slice 3 — durable offline command log
- [ ] **User value:** an opted-in Kanban mutation remains available after network loss and browser reload without storing DOM patches as truth.
- **State:** In progress — the first app-owned `reorder_card` command is transactionally persisted with schema, actor, session, causal id, and app payload before projection; an app-owned service worker caches only the generated shell/resources, and reload restores the projection after the fixture server is stopped and proven unreachable. Native recovery controls export a versioned credential-free command envelope, delete queued commands while preserving actor/causal identity, and reset command data, identity, cache, and registration behind explicit confirmation. Unknown schemas stop with an explicit diagnostic. Transaction conflicts and injected quota exhaustion prove failed persistence neither projects nor emits a durability claim, expose stage/code without command payload, and remain recoverable through export/delete/reset. Malformed current-schema records are rejected field-specifically without partial projection while export/delete recovery remains available. Replay is preflighted before effects, capped by the app at 64 commands, measured against a 100 ms browser budget, and over-limit queues fail closed with export/delete recovery. Visible queued-status latency proof for `performance/006` remains.
- **State:** In progress — the first app-owned `reorder_card` command is transactionally persisted with schema, actor, session, causal id, and app payload before projection; an app-owned service worker caches only the generated shell/resources, and reload restores the projection after the fixture server is stopped and proven unreachable. Native recovery controls export a versioned credential-free command envelope, delete queued commands while preserving actor/causal identity, and reset command data, identity, cache, and registration behind explicit confirmation. Unknown schemas stop with an explicit diagnostic. Transaction conflicts and injected quota exhaustion prove failed persistence neither projects nor emits a durability claim, expose stage/code without command payload, and remain recoverable through export/delete/reset. Malformed current-schema records are rejected field-specifically without partial projection while export/delete recovery remains available. Replay is preflighted before effects, capped by the app at 64 commands, measured against a 100 ms browser budget, and over-limit queues fail closed with export/delete recovery. A programmatic queued/busy state appears within the 100 ms direct-interaction budget before blocked persistence completes, without claiming durability or projecting early. Optional-asset isolation for `performance/006` remains; that requirement is separate from interaction latency.
- **Build:** add an optional durable command-log adapter around platform transactional storage; persist versioned command ids and app payload before projection; restore projection after reload; expose queue state, export/delete/reset, quota/corruption failure, and migration refusal.
- **Refusals:** no server reconciliation, CRDT, mandatory IndexedDB, credential storage, or policy hidden in core.
- **Requirements:** `local/001-004`, `sync/009`, `sync/014-015`, `sync/020`, `security/007`, `performance/005-006`.
- **Proof:** `cargo test -p hemx-wasm --test browser kanban_command_persists_before_projection_and_restores_after_reload -- --exact` proves transactional persist-before-project ordering, app-owned shell caching, current-version replay after a real Firefox reload with the fixture server unreachable, stable identity metadata, and explicit unknown-schema refusal through real WASM. `cargo test -p hemx-wasm --test browser kanban_command_export_delete_and_reset_are_recoverable -- --exact` proves accessible export/delete/reset entry points, versioned credential-free export, confirmation before destructive actions, preserved identity after queue deletion, and fresh identity/baseline projection after reset. `cargo test -p hemx-wasm --test browser kanban_persistence_failure_does_not_project_and_recovers -- --exact` proves transactional failure does not project or emit `kanban:command-persisted`, reports non-payload stage/code diagnostics, and recovers through the ordinary deletion path. `cargo test -p hemx-wasm --test browser kanban_corrupt_command_refuses_projection_and_recovers -- --exact` proves strict current-schema validation, no partial projection, visible non-payload diagnostics, raw versioned export for recovery, and ordinary deletion recovery. `cargo test -p hemx-wasm --test browser kanban_replay_is_bounded_and_within_budget -- --exact` proves 64-command preflight/replay within the 100 ms browser budget, zero partial projection at 65 commands, and export/delete recovery. `cargo test -p hemx-wasm --test browser kanban_quota_failure_is_fail_closed_and_recoverable -- --exact` proves quota-specific fail-closed behavior, no false durability event, transactional metadata rollback, and export/delete/reset recovery. The completed slice proof must additionally show visible queued status within the `performance/006` latency budget.
- **Requirements:** `local/001-004`, `sync/009`, `sync/014-015`, `sync/020`, `security/007`, `accessibility/004`, `client_local/013`, `performance/003`, `performance/005-006`.
- **Proof:** `cargo test -p hemx-wasm --test browser kanban_command_persists_before_projection_and_restores_after_reload -- --exact` proves transactional persist-before-project ordering, app-owned shell caching, current-version replay after a real Firefox reload with the fixture server unreachable, stable identity metadata, and explicit unknown-schema refusal through real WASM. `cargo test -p hemx-wasm --test browser kanban_command_export_delete_and_reset_are_recoverable -- --exact` proves accessible export/delete/reset entry points, versioned credential-free export, confirmation before destructive actions, preserved identity after queue deletion, and fresh identity/baseline projection after reset. `cargo test -p hemx-wasm --test browser kanban_persistence_failure_does_not_project_and_recovers -- --exact` proves transactional failure does not project or emit `kanban:command-persisted`, reports non-payload stage/code diagnostics, and recovers through the ordinary deletion path. `cargo test -p hemx-wasm --test browser kanban_corrupt_command_refuses_projection_and_recovers -- --exact` proves strict current-schema validation, no partial projection, visible non-payload diagnostics, raw versioned export for recovery, and ordinary deletion recovery. `cargo test -p hemx-wasm --test browser kanban_replay_is_bounded_and_within_budget -- --exact` proves 64-command preflight/replay within the 100 ms browser budget, zero partial projection at 65 commands, and export/delete recovery. `cargo test -p hemx-wasm --test browser kanban_quota_failure_is_fail_closed_and_recoverable -- --exact` proves quota-specific fail-closed behavior, no false durability event, transactional metadata rollback, and export/delete/reset recovery. `cargo test -p hemx-wasm --test browser kanban_queued_status_precedes_durable_projection_within_budget -- --exact` proves queued/busy feedback within the `performance/003` and `client_local/013` 100 ms budget while persistence is blocked, followed by durable projection only after commit. The completed slice proof must additionally prove optional PWA/WASM assets do not load on the server-first path for `performance/006`.
## Slice 4 — authoritative reconnect and convergence
examples/kanban/static/command-log.js
+9
View File
@@ -168,6 +168,8 @@ async function project(root, wasmHandler, command) {
function report(root, stage, error) {
const code = error && typeof error.name === "string" ? error.name : "Error";
const message = error instanceof Error ? error.message : String(error);
root.setAttribute("data-kanban-command-phase", "failed");
root.removeAttribute("aria-busy");
root.setAttribute("data-kanban-command-error", `${stage}: ${message}`);
root.setAttribute("data-kanban-command-error-stage", stage);
root.setAttribute("data-kanban-command-error-code", code);
@@ -266,6 +268,11 @@ async function start() {
await clientReady(root);
let wasmHandler;
const durableHandler = async (...wire) => {
const queuedCard = String(wire[2] || "1");
root.setAttribute("data-kanban-command-phase", "queued");
root.setAttribute("aria-busy", "true");
announce(root, `Queued card ${queuedCard}; saving for offline use.`);
root.dispatchEvent(new CustomEvent("kanban:command-queued", { detail: { cardId: queuedCard } }));
let command;
let count;
try {
@@ -274,6 +281,8 @@ async function start() {
report(root, "persist", error);
throw error;
}
root.setAttribute("data-kanban-command-phase", "durable");
root.removeAttribute("aria-busy");
root.setAttribute("data-kanban-command-count", String(count));
root.dispatchEvent(new CustomEvent("kanban:command-persisted", {
detail: {
hemx-wasm/tests/browser.rs
+137
View File
@@ -528,6 +528,107 @@ async fn kanban_command_export_delete_and_reset_are_recoverable() -> WebDriverRe
result.and(quit)
}
#[tokio::test]
async fn kanban_queued_status_precedes_durable_projection_within_budget() -> WebDriverResult<()> {
// test req: accessibility/004 req: client_local/013 req: performance/003
const INTERACTION_BUDGET_MS: f64 = 100.0;
let workspace = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
.parent()
.expect("workspace root")
.to_owned();
let (package, bootstrap, rendered) = build_kanban_artifact(&workspace);
let runtime = workspace.join("hemx-js/runtime/hemx.js");
let server = StaticServer::start(
package,
runtime,
bootstrap,
rendered,
"kanban_client",
Some(kanban_app_assets(&workspace)),
);
let webdriver_port = available_port();
let webdriver_addr = format!("127.0.0.1:{webdriver_port}");
let mut webdriver = Command::new("geckodriver");
webdriver.arg("--port").arg(webdriver_port.to_string());
let _webdriver = ProcessGuard::start(webdriver, &webdriver_addr);
let mut caps = DesiredCapabilities::firefox();
caps.set_headless()?;
let driver = WebDriver::new(&format!("http://{webdriver_addr}"), caps).await?;
let result = async {
driver.goto(&server.url()).await?;
wait_until(
&driver,
"const root = document.querySelector('[data-hemx-root]'); return root.hasAttribute('data-kanban-command-ready') && root.hasAttribute('data-kanban-offline-ready')",
)
.await?;
hold_command_transaction(&driver).await?;
driver
.execute(
r#"
const root = document.querySelector('[data-hemx-root]');
window.__queuedTiming = { input: null, queued: null, persisted: false };
root.addEventListener('click', () => { window.__queuedTiming.input = performance.now(); }, { capture: true, once: true });
root.addEventListener('kanban:command-queued', () => { window.__queuedTiming.queued = performance.now(); }, { once: true });
root.addEventListener('kanban:command-persisted', () => { window.__queuedTiming.persisted = true; }, { once: true });
return true;
"#,
Vec::new(),
)
.await?;
driver.find(By::Css("[data-card-id='1']")).await?.click().await?;
wait_until(
&driver,
"return window.__queuedTiming.queued !== null && document.querySelector('[data-hemx-root]').getAttribute('data-kanban-command-phase') === 'queued'",
)
.await?;
let queued = driver
.execute(
"const root = document.querySelector('[data-hemx-root]'); return { latency: window.__queuedTiming.queued - window.__queuedTiming.input, persisted: window.__queuedTiming.persisted, phase: root.getAttribute('data-kanban-command-phase'), busy: root.getAttribute('aria-busy'), status: root.querySelector('[role=status]').textContent, order: [...root.querySelectorAll('[data-key]')].map((node) => node.dataset.key).join('|'), count: root.getAttribute('data-kanban-command-count') }",
Vec::new(),
)
.await?
.json()
.clone();
assert!(
queued["latency"]
.as_f64()
.is_some_and(|latency| latency <= INTERACTION_BUDGET_MS),
"queued status missed interaction budget: {queued}"
);
assert_eq!(queued["persisted"], false);
assert_eq!(queued["phase"], "queued");
assert_eq!(queued["busy"], "true");
assert_eq!(queued["status"], "Queued card 1; saving for offline use.");
assert_eq!(queued["order"], "1|2");
assert_eq!(queued["count"], "0");
release_command_transaction(&driver).await?;
wait_until(
&driver,
"const root = document.querySelector('[data-hemx-root]'); return window.__queuedTiming.persisted && root.getAttribute('data-kanban-command-phase') === 'durable' && [...root.querySelectorAll('[data-key]')].map((node) => node.dataset.key).join('|') === '2|1'",
)
.await?;
let durable = driver
.execute(
"const root = document.querySelector('[data-hemx-root]'); return { phase: root.getAttribute('data-kanban-command-phase'), busy: root.hasAttribute('aria-busy'), count: root.getAttribute('data-kanban-command-count'), status: root.querySelector('[role=status]').textContent }",
Vec::new(),
)
.await?
.json()
.clone();
assert_eq!(durable["phase"], "durable");
assert_eq!(durable["busy"], false);
assert_eq!(durable["count"], "1");
assert_eq!(durable["status"], "Moved 1 with click");
Ok(())
}
.await;
let quit = driver.quit().await;
result.and(quit)
}
#[tokio::test]
async fn kanban_quota_failure_is_fail_closed_and_recoverable() -> WebDriverResult<()> {
// test req: sync/015
@@ -1403,6 +1504,42 @@ fn fixture_html(rendered: &str, has_app_module: bool) -> String {
)
}
async fn hold_command_transaction(driver: &WebDriver) -> WebDriverResult<()> {
driver
.execute(
r#"
window.__releaseCommandTransaction = false;
window.__commandTransactionHeld = false;
const open = indexedDB.open('hemx-kanban-v1', 1);
open.onsuccess = () => {
const tx = open.result.transaction('commands', 'readwrite');
const commands = tx.objectStore('commands');
window.__commandTransactionHeld = true;
const keepAlive = () => {
if (window.__releaseCommandTransaction) return;
const request = commands.count();
request.onsuccess = keepAlive;
};
keepAlive();
};
return true;
"#,
Vec::new(),
)
.await?;
wait_until(driver, "return window.__commandTransactionHeld === true").await
}
async fn release_command_transaction(driver: &WebDriver) -> WebDriverResult<()> {
driver
.execute(
"window.__releaseCommandTransaction = true; return true;",
Vec::new(),
)
.await?;
Ok(())
}
async fn inject_quota_failure(driver: &WebDriver) -> WebDriverResult<()> {
let injected = driver
.execute(