diff --git a/.github/workflows/factory.yml b/.github/workflows/factory.yml index 79baf622..aa2e74bb 100644 --- a/.github/workflows/factory.yml +++ b/.github/workflows/factory.yml @@ -8,7 +8,7 @@ name: factory on: workflow_run: - workflows: [bootstrap, SDK offline reproducibility, release] + workflows: [bootstrap, SDK offline reproducibility, release, pages client] types: [completed] permissions: diff --git a/.github/workflows/pages-client.yml b/.github/workflows/pages-client.yml new file mode 100644 index 00000000..0ad64145 --- /dev/null +++ b/.github/workflows/pages-client.yml @@ -0,0 +1,81 @@ +# UC-WEB-01: the Pages client, built as the release builds it, driven through +# every journey of its Prism product model (src/Uorc/Page.lex.tex) in headless +# Chrome by scripts/page-acceptance.mjs. +# +# A factory obligation (`pages` in factory/graph.json): its identity covers only +# what the page reads (the client set, the wasm crate, web/, the brand files and +# the two scripts), so a change elsewhere finds its receipt and skips the work. +# The release gate needs it, so no release ships a page that fails its model. +name: pages client + +on: + pull_request: + push: + branches: [main] + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: pages-client-${{ github.event.pull_request.number || github.sha }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + route: + name: pages client / factory route + runs-on: ubuntu-24.04 + timeout-minutes: 5 + outputs: + route: ${{ steps.route.outputs.route }} + identity: ${{ steps.route.outputs.identity }} + steps: + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 + with: + fetch-depth: 0 + persist-credentials: false + - name: Route the page acceptance by its own inputs + id: route + run: node scripts/factory.mjs route pages | tee -a "$GITHUB_OUTPUT" + + acceptance: + name: pages client / product model acceptance + needs: route + if: needs.route.outputs.route == 'observe' + runs-on: ubuntu-24.04 + timeout-minutes: 30 + steps: + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 + with: + fetch-depth: 0 + persist-credentials: false + - name: Build the site and walk every journey of the product model in Chrome + id: run + shell: bash + run: | + set -euo pipefail + cargo build --locked --release -p uorc-wasm --target wasm32-unknown-unknown + mkdir -p .tmp/bench + for f in bench.html bench.json bench.md; do printf 'benchmarks are published with each release\n' > ".tmp/bench/$f"; done + node scripts/site.mjs .tmp/site --wasm target/wasm32-unknown-unknown/release/uorc_wasm.wasm --version "$(git describe --tags --always)-dev" --bench .tmp/bench + node scripts/page-acceptance.mjs .tmp/site --chrome "$(command -v google-chrome)" --report .tmp/page-acceptance.json + - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 + if: always() + with: + name: page-acceptance + path: .tmp/page-acceptance.json + if-no-files-found: warn + retention-days: 30 + - name: Record the outcome + if: always() && (steps.run.outcome == 'success' || steps.run.outcome == 'failure') + env: + IDENTITY: ${{ needs.route.outputs.identity }} + OUTCOME: ${{ steps.run.outcome }} + run: node scripts/factory.mjs outcome pages "$IDENTITY" "$OUTCOME" .tmp/factory + - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 + if: always() && (steps.run.outcome == 'success' || steps.run.outcome == 'failure') + with: + name: factory-outcome-pages + path: .tmp/factory/ + if-no-files-found: error + retention-days: 3 diff --git a/CONFORMANCE.md b/CONFORMANCE.md index d1c3a099..3761858b 100644 --- a/CONFORMANCE.md +++ b/CONFORMANCE.md @@ -76,6 +76,12 @@ The three honesty levels (R2): | --- | --- | --- | | `UC-OBJ-01` | `build` | Archives of ordered objects preserve the exact object boundary vector, including zero objects and distinct zero-length objects. | +## pages-client + +| ID | Level | Statement | +| --- | --- | --- | +| `UC-WEB-01` | `build` | The Pages client is generated from and conforms to its Prism product model in Uorc.Page: stakeholders, features with their calls and acceptance cases, journeys, the page's UML state machine, operations, fields, controls, examples, error hints, sections, usage, links and quality measures. The generated page holds exactly the modeled elements, and a real browser walks every journey, takes every modeled transition, checks every control's enabled state in every state it reaches and holds every gated quality measure. | + ## product-interfaces | ID | Level | Statement | @@ -161,3 +167,4 @@ The three honesty levels (R2): | `UC-INT-04` | `build` | `build_evidence` | `not_measured` | Source-owned actual-call relations establish ordered hash admissions, drained selected-view EOF and checked cumulative basis/main work; composed generated-model controls reject failed-prefix resets and late corruption. Consumer snapshot preservation, canonical digest refinement and complete archive EOF remain separate obligations. | | `UC-INT-05` | `build` | `build_evidence` | `not_measured` | Source-owned completed-view and continuous publication proofs derive the actual chosen-profile digest and emitted-image reads, discharging canonical driver termination and OwnedHash control/cleanup lifetime for both explicit format identities and arbitrary finite source input. Initial source-layout correspondence and full product acceptance remain separate consumer obligations. | | `UC-NEU-01` | `build` | `kernel_theorem` | `not_measured` | The ncm coder's plasticity is stated as the Prism neuromorphic standard in Uorc.Neuromorphic, with kernel-checked bounds: every mixer weight stays within plus or minus 2^22 under the bounded Hebbian rule, potentiation never lowers and depression never raises a weight, the plasticity lies between 24 and 128 per 65536 (128 at the first byte, 24 in the limit), one bit's weight change is at most 16376 and every product fits a 32-bit lane, a context slot never steps past its gap to the coded bit and consolidates at count 127, and every probability-map point stays within 16 bits; the native coder reads the model's constants. | +| `UC-WEB-01` | `build` | `build_evidence` | `not_measured` | The Pages client is generated from and conforms to its Prism product model in Uorc.Page: stakeholders, features with their calls and acceptance cases, journeys, the page's UML state machine, operations, fields, controls, examples, error hints, sections, usage, links and quality measures. The generated page holds exactly the modeled elements, and a real browser walks every journey, takes every modeled transition, checks every control's enabled state in every state it reaches and holds every gated quality measure. | diff --git a/Justfile b/Justfile index e37efc6c..b145c419 100644 --- a/Justfile +++ b/Justfile @@ -28,14 +28,22 @@ model: # The hand-reviewed trust root is checked independently of generated project # content. PrismPM then validates the canonical contract and both locks. +# PrismPM's native regeneration runs model-write in a copy of the tree staged +# in the SDK's /tmp, a 2 GiB tmpfs of which CARGO_HOME already holds 1.1 GiB, +# with a cleared environment. The note .tmp/model-write-target travels with +# the copy and sends its build to a target directory of its own on this +# workspace's disk. It is not the workspace's target: a binary built from the +# copy carries the copy's paths, and cargo would take it as current here. template-check: cargo run --locked -q -p xtask -- audit-bootstrap + mkdir -p .tmp && printf '%s' "{{justfile_directory()}}/target/regeneration" > .tmp/model-write-target prismpm template check + rm -f .tmp/model-write-target prismpm lock check # Regenerate every model/document projection owned by the LexLean authority graph. model-write: - cargo run --locked -q -p xtask -- check-model --write + cargo run --locked -q -p xtask --target-dir "$(cat .tmp/model-write-target 2>/dev/null || echo target)" -- check-model --write # Direct R1 report: project prose cannot become a second UORC authority. source-authority: @@ -58,6 +66,15 @@ test: cargo test --locked --workspace --exclude xtask node --test scripts/site.test.mjs +# UC-WEB-01: build the Pages site as the release does (a stand-in benchmark +# page beside it) and walk every journey of the page's Prism product model in +# headless Chrome. CI runs the same steps in pages-client.yml. +pages: + cargo build --locked --release -p uorc-wasm --target wasm32-unknown-unknown + mkdir -p .tmp/bench && for f in bench.html bench.json bench.md; do printf 'benchmarks are published with each release\n' > .tmp/bench/$f; done + node scripts/site.mjs .tmp/site --wasm target/wasm32-unknown-unknown/release/uorc_wasm.wasm --version "$(git describe --tags --always)-dev" --bench .tmp/bench + node scripts/page-acceptance.mjs .tmp/site --report .tmp/page-acceptance.json + # The xtask suite: product-runtime, integrity, claims and offline harnesses. formal-tests: cargo test --locked -p xtask diff --git a/crates/model/src/authority.rs b/crates/model/src/authority.rs index b0dc7790..ce1a377d 100644 --- a/crates/model/src/authority.rs +++ b/crates/model/src/authority.rs @@ -137,6 +137,8 @@ pub struct AuthorityGraph { pub claim_policy: ClaimPolicy, /// Generated claim-disposition ledger. pub ledger: Ledger, + /// The Prism product model of the Pages client. + pub page: crate::page::PageModel, } impl AuthorityGraph { @@ -335,6 +337,7 @@ impl AuthorityGraph { spec: "template/1".to_string(), claim: claims, }, + page: crate::page::PageModel::load(root)?, }; graph.model().check()?; diff --git a/crates/model/src/codegen.rs b/crates/model/src/codegen.rs index 12d6b192..ab36f33c 100644 --- a/crates/model/src/codegen.rs +++ b/crates/model/src/codegen.rs @@ -53,6 +53,7 @@ pub fn render_all(graph: &AuthorityGraph) -> Vec<(String, String)> { ), ]; out.extend(render_feature_suites(graph)); + out.push((crate::page::PAGE_PATH.to_string(), graph.page.render())); out } diff --git a/crates/model/src/lib.rs b/crates/model/src/lib.rs index 329a2453..bb3469d2 100644 --- a/crates/model/src/lib.rs +++ b/crates/model/src/lib.rs @@ -13,6 +13,7 @@ pub mod authority; pub mod claims; pub mod codegen; +pub mod page; pub mod registry; pub mod varint; diff --git a/crates/model/src/page.rs b/crates/model/src/page.rs new file mode 100644 index 00000000..69a0187c --- /dev/null +++ b/crates/model/src/page.rs @@ -0,0 +1,833 @@ +//! The Prism product model of the Pages client: `src/Uorc/Page.lex.tex`. +//! +//! The module states the page in Prism's product-modeling vocabulary (PrismPM +//! `stdlib/src/Foundation/Arch.lex.tex` stakeholders, features, journeys and +//! UML state machines; `Foundation/Qual.lex.tex` quality requirements and +//! measures; `Foundation/View/Text/V3/Model.lex.tex` workbench operations, +//! fields, examples, error hints, sections, links and labels). The records +//! are declared locally because the page works on files, which the text/3 +//! workbench profile does not carry; each keeps the field names of its Prism +//! counterpart. +//! +//! [`PageModel::load`] reads every row, checks the model the way PrismPM checks +//! its own (PP2014 to PP2018 for features and journeys, one initial state and +//! closed references for the state machine, plus the page's own closed sets), +//! and [`PageModel::render`] generates `web/index.html`: the page's static +//! content and, embedded as JSON, the model `web/app.js` interprets. The page +//! therefore holds exactly what the model declares. + +use std::collections::{BTreeMap, BTreeSet}; +use std::fmt::Write as _; +use std::path::Path; + +use serde_json::{Map, Value}; + +use crate::ModelError; + +/// The LexLean module that owns the page's product model. +pub const PAGE_MODEL_PATH: &str = "src/Uorc/Page.lex.tex"; +/// The generated page. +pub const PAGE_PATH: &str = "web/index.html"; +const MODULE: &str = "Uorc.Page"; + +/// Every row type of the model, in the order the JSON projection lists them. +const ROW_TYPES: &[&str] = &[ + "Workbench", + "Labels", + "Stakeholder", + "Feature", + "Journey", + "UmlState", + "UmlTransition", + "Operation", + "Field", + "Control", + "Example", + "Column", + "ErrorHint", + "Section", + "Usage", + "Link", + "QualityRequirement", + "QualityMeasure", +]; + +/// The triggers `web/app.js` raises; a transition names one of them. +pub const TRIGGERS: &[&str] = &[ + "loaded", + "loadFailed", + "run", + "finished", + "failed", + "cancel", + "restarted", + "edit", +]; +/// The field kinds `web/app.js` renders. +pub const FIELD_KINDS: &[&str] = &["files", "folder", "archive", "file"]; +/// The example inputs `web/app.js` generates. +pub const EXAMPLE_INPUTS: &[&str] = &["text", "zeros", "counter", "random", "empty"]; +/// The operations the page's worker runs. +pub const OPERATIONS: &[&str] = &["compress", "decompress", "inspect", "verify"]; +/// The controls `web/app.js` enables by state. +pub const CONTROLS: &[&str] = &["run", "cancel", "operation", "field", "example"]; +/// The error codes the page's worker reports: the wasm client's four, a +/// stopped worker and a client that cannot load. +pub const ERROR_CODES: &[&str] = &[ + "budget", "overflow", "decode", "mismatch", "stopped", "load", +]; +/// The tables the page draws. +pub const TABLES: &[&str] = &["inspect", "examples"]; + +/// One row: the definition's name and its record's fields as JSON. +#[derive(Debug, Clone, PartialEq)] +pub struct Row { + /// The definition name; `Uorc.Page::` is its identifier. + pub name: String, + /// The record fields. + pub fields: Map, +} + +impl Row { + fn str(&self, field: &str) -> &str { + self.fields.get(field).and_then(Value::as_str).unwrap_or("") + } + fn strs(&self, field: &str) -> Vec<&str> { + self.fields + .get(field) + .and_then(Value::as_array) + .map(|values| values.iter().filter_map(Value::as_str).collect()) + .unwrap_or_default() + } + fn nat(&self, field: &str) -> u64 { + self.fields.get(field).and_then(Value::as_u64).unwrap_or(0) + } + fn bool(&self, field: &str) -> bool { + self.fields + .get(field) + .and_then(Value::as_bool) + .unwrap_or(false) + } +} + +/// The page's product model: every row, by type, in declaration order. +#[derive(Debug, Clone, PartialEq)] +pub struct PageModel { + /// Rows by record type. + pub rows: BTreeMap>, +} + +fn inconsistent(message: impl Into) -> ModelError { + ModelError::Inconsistent(format!("{PAGE_MODEL_PATH}: {}", message.into())) +} + +/// A record field value as JSON: strings, naturals, Booleans and lists of them. +fn value(data: &Value) -> Result { + match data.get("kind").and_then(Value::as_str) { + Some("string") => Ok(data.get("value").cloned().unwrap_or(Value::Null)), + Some("nat") => data + .get("value") + .and_then(Value::as_str) + .and_then(|n| n.parse::().ok()) + .map(Value::from) + .ok_or_else(|| inconsistent("a natural number does not fit in 64 bits")), + Some("bool") => Ok(data.get("value").cloned().unwrap_or(Value::Null)), + Some("cons" | "nil") => { + let mut items = Vec::new(); + let mut at = data; + while at.get("kind").and_then(Value::as_str) == Some("cons") { + items.push(value(at.get("head").unwrap_or(&Value::Null))?); + at = at.get("tail").unwrap_or(&Value::Null); + } + Ok(Value::Array(items)) + } + _ => Err(inconsistent(format!( + "a field value must be a string, natural, Boolean or list literal, not {data}" + ))), + } +} + +impl PageModel { + /// Read and check the model. + pub fn load(root: &Path) -> Result { + let declarations = + crate::authority::semantic_declarations(&root.join(PAGE_MODEL_PATH), MODULE)?; + let mut rows: BTreeMap> = BTreeMap::new(); + for declaration in &declarations { + if declaration.get("kind").and_then(Value::as_str) != Some("definition") { + continue; + } + let name = declaration + .get("name") + .and_then(Value::as_str) + .unwrap_or_default() + .to_string(); + let body = declaration.get("body").unwrap_or(&Value::Null); + let kind = body + .get("type") + .and_then(|t| t.get("name")) + .and_then(Value::as_str) + .filter(|_| body.get("kind").and_then(Value::as_str) == Some("record")) + .ok_or_else(|| inconsistent(format!("`{name}` is not a closed record literal")))?; + if !ROW_TYPES.contains(&kind) { + return Err(inconsistent(format!( + "`{name}` has unknown row type {kind}" + ))); + } + let mut fields = Map::new(); + for field in body + .get("fields") + .and_then(Value::as_array) + .into_iter() + .flatten() + { + let key = field + .get("field") + .and_then(Value::as_str) + .unwrap_or_default(); + fields.insert( + key.to_string(), + value(field.get("value").unwrap_or(&Value::Null))?, + ); + } + rows.entry(kind.to_string()) + .or_default() + .push(Row { name, fields }); + } + let model = PageModel { rows }; + model.check()?; + Ok(model) + } + + /// Rows of one type, in declaration order. + #[must_use] + pub fn of(&self, kind: &str) -> &[Row] { + self.rows.get(kind).map_or(&[], Vec::as_slice) + } + + fn sorted(&self, kind: &str) -> Vec<&Row> { + let mut rows: Vec<&Row> = self.of(kind).iter().collect(); + rows.sort_by_key(|row| row.nat("order")); + rows + } + + fn one(&self, kind: &str) -> &Row { + &self.of(kind)[0] + } + + /// The Prism checks: every feature is realized and accepted, journeys name + /// stakeholders and features, the state machine is closed and reachable, + /// and every reference and closed set holds. + pub fn check(&self) -> Result<(), ModelError> { + for kind in ROW_TYPES { + if self.of(kind).is_empty() { + return Err(inconsistent(format!("the model declares no {kind}"))); + } + } + for kind in ["Workbench", "Labels"] { + if self.of(kind).len() != 1 { + return Err(inconsistent(format!( + "the model declares exactly one {kind}" + ))); + } + } + let id = |row: &Row| format!("{MODULE}::{}", row.name); + let ids = |kind: &str| -> BTreeSet { self.of(kind).iter().map(id).collect() }; + let unique = |kind: &str, field: &str| -> Result, ModelError> { + let mut seen = BTreeSet::new(); + for row in self.of(kind) { + let key = row.str(field).to_string(); + if key.trim().is_empty() || !seen.insert(key.clone()) { + return Err(inconsistent(format!("{kind} `{key}` is blank or repeated"))); + } + } + Ok(seen) + }; + + // PP2014, PP2015: every feature is realized and accepted, once each. + let mut acceptance = BTreeSet::new(); + for feature in self.of("Feature") { + if feature.strs("calls").is_empty() { + return Err(inconsistent(format!( + "PP2014 feature `{}` is realized by no call", + feature.name + ))); + } + if feature.strs("acceptance").is_empty() { + return Err(inconsistent(format!( + "PP2015 feature `{}` is accepted by no row", + feature.name + ))); + } + for case in feature.strs("acceptance") { + if !acceptance.insert(case.to_string()) { + return Err(inconsistent(format!( + "acceptance case `{case}` is claimed twice" + ))); + } + } + } + // PP2016, PP2017: journeys name stakeholders and features; every + // feature is reached by a journey, which is how acceptance runs it. + let (features, stakeholders) = (ids("Feature"), ids("Stakeholder")); + let mut reached = BTreeSet::new(); + for journey in self.of("Journey") { + if !stakeholders.contains(journey.str("actor")) { + return Err(inconsistent(format!( + "PP2017 journey `{}` has no declared actor", + journey.name + ))); + } + for step in journey.strs("steps") { + if !features.contains(step) { + return Err(inconsistent(format!( + "PP2016 journey `{}` step `{step}` is not a feature", + journey.name + ))); + } + reached.insert(step.to_string()); + } + } + if let Some(missed) = features.difference(&reached).next() { + return Err(inconsistent(format!("feature `{missed}` is on no journey"))); + } + + // The state machine: one initial state, closed triggers, every state + // reachable from the initial one. + let states = unique("UmlState", "state")?; + let initial: Vec<&Row> = self + .of("UmlState") + .iter() + .filter(|s| s.bool("initial")) + .collect(); + if initial.len() != 1 { + return Err(inconsistent( + "the state machine needs exactly one initial state", + )); + } + let mut orders = BTreeSet::new(); + let mut pairs = BTreeSet::new(); + for t in self.of("UmlTransition") { + let (source, target, trigger) = (t.str("source"), t.str("target"), t.str("trigger")); + if !states.contains(source) || !states.contains(target) { + return Err(inconsistent(format!( + "transition `{}` names an undeclared state", + t.name + ))); + } + if !TRIGGERS.contains(&trigger) { + return Err(inconsistent(format!( + "transition `{}` has unknown trigger {trigger}", + t.name + ))); + } + if !orders.insert(t.nat("order")) + || !pairs.insert((source.to_string(), trigger.to_string())) + { + return Err(inconsistent(format!( + "transition `{}` repeats an order or a source and trigger", + t.name + ))); + } + } + let mut seen = BTreeSet::from([initial[0].str("state").to_string()]); + loop { + let next: BTreeSet = self + .of("UmlTransition") + .iter() + .filter(|t| seen.contains(t.str("source"))) + .map(|t| t.str("target").to_string()) + .collect(); + if next.is_subset(&seen) { + break; + } + seen.extend(next); + } + if seen != states { + return Err(inconsistent( + "a state is unreachable from the initial state", + )); + } + + // The workbench: operations, fields, controls, examples, columns, + // errors and links each use closed sets and resolve their references. + let fields = unique("Field", "id")?; + for field in self.of("Field") { + if !FIELD_KINDS.contains(&field.str("kind")) { + return Err(inconsistent(format!( + "field `{}` has unknown kind", + field.str("id") + ))); + } + let replaces = field.str("replaces"); + if !replaces.is_empty() && !fields.contains(replaces) { + return Err(inconsistent(format!( + "field `{}` replaces an undeclared field", + field.str("id") + ))); + } + } + let operations = unique("Operation", "id")?; + if operations != OPERATIONS.iter().map(ToString::to_string).collect() { + return Err(inconsistent(format!( + "the operations must be exactly {OPERATIONS:?}" + ))); + } + let mut used = BTreeSet::new(); + for op in self.of("Operation") { + if op.strs("fields").is_empty() { + return Err(inconsistent(format!( + "operation `{}` has no field", + op.str("id") + ))); + } + for field in op.strs("fields") { + if !fields.contains(field) { + return Err(inconsistent(format!( + "operation `{}` names undeclared field `{field}`", + op.str("id") + ))); + } + used.insert(field.to_string()); + } + } + if used != fields { + return Err(inconsistent("a field belongs to no operation")); + } + if !operations.contains(self.one("Workbench").str("initialOperation")) { + return Err(inconsistent("the initial operation is not declared")); + } + if unique("Control", "id")? != CONTROLS.iter().map(ToString::to_string).collect() { + return Err(inconsistent(format!( + "the controls must be exactly {CONTROLS:?}" + ))); + } + for control in self.of("Control") { + if !TRIGGERS.contains(&control.str("trigger")) { + return Err(inconsistent(format!( + "control `{}` raises an unknown trigger", + control.str("id") + ))); + } + for state in control.strs("enabledIn") { + if !states.contains(state) { + return Err(inconsistent(format!( + "control `{}` names undeclared state `{state}`", + control.str("id") + ))); + } + } + } + unique("Example", "id")?; + for example in self.of("Example") { + if !EXAMPLE_INPUTS.contains(&example.str("input")) { + return Err(inconsistent(format!( + "example `{}` has unknown input", + example.str("id") + ))); + } + } + for column in self.of("Column") { + if !TABLES.contains(&column.str("table")) { + return Err(inconsistent(format!( + "column `{}` is in an unknown table", + column.name + ))); + } + } + let codes = unique("ErrorHint", "code")?; + if codes != ERROR_CODES.iter().map(ToString::to_string).collect() { + return Err(inconsistent(format!( + "the error hints must cover exactly {ERROR_CODES:?}" + ))); + } + for hint in self.of("ErrorHint") { + for field in hint.strs("fields") { + if !fields.contains(field) { + return Err(inconsistent(format!( + "error `{}` names undeclared field `{field}`", + hint.str("code") + ))); + } + } + } + for link in self.of("Link") { + let href = link.str("href"); + let local = !href.contains(':') && !href.contains('/') && !href.is_empty(); + if !(href.starts_with("https://github.com/") || local) { + return Err(inconsistent(format!( + "link `{href}` is neither a GitHub page nor a site file" + ))); + } + } + let requirements = ids("QualityRequirement"); + for measure in self.of("QualityMeasure") { + if !requirements.contains(measure.str("requirement")) { + return Err(inconsistent(format!( + "measure `{}` names no requirement", + measure.name + ))); + } + if !["gate", "measured"].contains(&measure.str("disposition")) { + return Err(inconsistent(format!( + "measure `{}` is neither a gate nor measured", + measure.name + ))); + } + } + Ok(()) + } + + /// The model as JSON, by row type, each row with its `name`. + #[must_use] + pub fn json(&self) -> Value { + let mut out = Map::new(); + for kind in ROW_TYPES { + let rows = self + .of(kind) + .iter() + .map(|row| { + let mut fields = Map::new(); + fields.insert("name".to_string(), Value::from(row.name.clone())); + fields.extend(row.fields.clone()); + Value::Object(fields) + }) + .collect(); + out.insert((*kind).to_string(), Value::Array(rows)); + } + Value::Object(out) + } + + /// The generated page. + #[must_use] + pub fn render(&self) -> String { + let wb = self.one("Workbench"); + let labels = self.one("Labels"); + let initial_state = self + .of("UmlState") + .iter() + .find(|s| s.bool("initial")) + .expect("checked: one initial state"); + let mut h = String::new(); + let _ = write!( + h, + "\n\n\ + \n\n\n\ + \n\ + {}\n\n\ + \n\ + \ + \n\ + \n\n", + esc(wb.str("title")), + esc(wb.str("purpose")), + esc(initial_state.str("state")), + esc(wb.str("colorScheme")), + esc(wb.str("density")), + esc(wb.str("width")), + ); + let _ = write!( + h, + "{}\n
\n

{}

\n

{}

\n\ +

{}

\n

\n
\n
\n", + esc(labels.str("skipToWorkbench")), + esc(wb.str("heading")), + esc(wb.str("purpose")), + esc(wb.str("privacy")), + esc(labels.str("version")), + ); + + // The workbench. + let _ = write!( + h, + "
\n

{}

\n
    \n", + esc(labels.str("workbench")) + ); + for step in wb.strs("guidance") { + let _ = writeln!(h, "
  1. {}
  2. ", esc(step)); + } + let _ = write!( + h, + "
\n\n
\n", + esc(labels.str("noscript")), + esc(labels.str("operations")) + ); + let initial = wb.str("initialOperation"); + for op in self.sorted("Operation") { + let on = op.str("id") == initial; + let _ = writeln!( + h, + "", + esc(op.str("id")), + on, + if on { "0" } else { "-1" }, + esc(op.str("label")) + ); + } + let _ = write!( + h, + "
\n
\n", + esc(initial) + ); + for op in self.sorted("Operation") { + let _ = writeln!( + h, + "

{}

{}

", + esc(op.str("id")), + if op.str("id") == initial { "" } else { " hidden" }, + esc(op.str("summary")), + esc(op.str("help")) + ); + } + let initial_fields: BTreeSet<&str> = self + .of("Operation") + .iter() + .find(|op| op.str("id") == initial) + .map(|op| op.strs("fields").into_iter().collect()) + .unwrap_or_default(); + for field in self.of("Field") { + let id = field.str("id"); + let attrs = match field.str("kind") { + "files" => " multiple", + "folder" => " webkitdirectory", + "archive" => " accept=\".uorc,application/octet-stream\"", + _ => "", + }; + let _ = writeln!( + h, + "
\ + \ +

{4}

", + esc(id), + if initial_fields.contains(id) { "" } else { " hidden" }, + esc(field.str("label")), + attrs, + esc(field.str("help")) + ); + } + let run_label = self + .of("Operation") + .iter() + .find(|op| op.str("id") == initial) + .map_or("", |op| op.str("runLabel")); + let cancel = self + .of("Control") + .iter() + .find(|c| c.str("id") == "cancel") + .map_or("", |c| c.str("label")); + let _ = write!( + h, + "
\ +
\n\ + \n\ +

{}

\n\ + \n\ + \n
\n
\n", + esc(run_label), + esc(cancel), + esc(labels.str("progress")), + esc(initial_state.str("status")) + ); + + // Examples. + let _ = write!( + h, + "
\n

{}

\n

{}

\n
\n", + esc(labels.str("examples")), + esc(labels.str("examplesHelp")) + ); + for example in self.sorted("Example") { + let _ = writeln!( + h, + "", + esc(example.str("id")), + esc(example.str("label")) + ); + } + h.push_str("
\n
    \n"); + for example in self.sorted("Example") { + let _ = writeln!( + h, + "
  • {}: {} ({} bytes)
  • ", + esc(example.str("id")), + esc(example.str("label")), + esc(example.str("description")), + example.nat("bytes") + ); + } + h.push_str("
\n
"); + for column in self + .sorted("Column") + .into_iter() + .filter(|c| c.str("table") == "examples") + { + let _ = write!(h, "", esc(column.str("label"))); + } + h.push_str("
{}
\n
\n"); + + // What the page does, and usage elsewhere. + for section in self.sorted("Section") { + let _ = write!( + h, + "
\n

{1}

\n", + esc(section.str("id")), + esc(section.str("title")) + ); + for paragraph in section.strs("paragraphs") { + let _ = writeln!(h, "

{}

", esc(paragraph)); + } + h.push_str("
\n"); + } + let _ = write!( + h, + "
\n

{}

\n", + esc(labels.str("usage")) + ); + for usage in self.sorted("Usage") { + let _ = write!( + h, + "

{}

\n
{}
\n", + esc(usage.str("title")), + esc(usage.str("language")), + esc(&usage.strs("code").join("\n")) + ); + } + let _ = write!( + h, + "
\n
\n\n
    \n", + esc(labels.str("links")) + ); + for link in self.sorted("Link") { + let _ = writeln!( + h, + "
  • {}
  • ", + esc(link.str("href")), + esc(link.str("label")) + ); + } + h.push_str("
\n
\n
\n"); + let json = serde_json::to_string(&self.json()) + .expect("serializable page model") + .replace("{json}\n\ + \n\n\n" + ); + h + } +} + +/// HTML text and attribute escaping. +fn esc(text: &str) -> String { + let mut out = String::with_capacity(text.len()); + for c in text.chars() { + match c { + '&' => out.push_str("&"), + '<' => out.push_str("<"), + '>' => out.push_str(">"), + '"' => out.push_str("""), + _ => out.push(c), + } + } + out +} + +#[cfg(test)] +mod tests { + use super::*; + + fn root() -> std::path::PathBuf { + crate::repo_root() + } + + /// The model loads, passes the Prism checks, and the generated page holds + /// every operation, field, example, error hint, usage block and link. + #[test] + fn the_page_model_checks_and_renders_every_element_uc_web_01() { + let model = PageModel::load(&root()).expect("the page model checks"); + let page = model.render(); + for op in model.of("Operation") { + assert!(page.contains(&format!("id=\"tab-{}\"", op.str("id")))); + } + for field in model.of("Field") { + assert!(page.contains(&format!("id=\"field-{}\"", field.str("id")))); + } + for example in model.of("Example") { + assert!(page.contains(&format!("data-example=\"{}\"", example.str("id")))); + } + for link in model.of("Link") { + assert!(page.contains(&format!("href=\"{}\"", esc(link.str("href"))))); + } + assert_eq!(page.matches("role=\"status\"").count(), 1); + assert!(page.contains("id=\"page-model\"")); + } + + /// Each Prism check rejects its planted defect. + #[test] + fn planted_model_defects_are_rejected_uc_web_01() { + let good = PageModel::load(&root()).expect("the page model checks"); + type Plant = fn(&mut PageModel); + fn set(m: &mut PageModel, kind: &str, i: usize, field: &str, v: Value) { + m.rows.get_mut(kind).expect("rows")[i] + .fields + .insert(field.to_string(), v); + } + let plants: Vec<(&str, Plant)> = vec![ + ("PP2014", |m| { + set(m, "Feature", 0, "calls", Value::Array(vec![])) + }), + ("PP2015", |m| { + set(m, "Feature", 0, "acceptance", Value::Array(vec![])) + }), + ("PP2016", |m| { + set( + m, + "Journey", + 0, + "steps", + serde_json::json!(["Uorc.Page::nothing"]), + ) + }), + ("PP2017", |m| { + set(m, "Journey", 0, "actor", Value::from("Uorc.Page::nobody")) + }), + ("two initial states", |m| { + set(m, "UmlState", 1, "initial", Value::from(true)) + }), + ("unknown trigger", |m| { + set(m, "UmlTransition", 0, "trigger", Value::from("teleport")) + }), + ("unreachable state", |m| { + m.rows + .get_mut("UmlTransition") + .expect("rows") + .retain(|t| t.str("target") != "unavailable"); + }), + ("unknown field", |m| { + set(m, "Operation", 0, "fields", serde_json::json!(["nowhere"])) + }), + ("uncovered error", |m| { + m.rows.get_mut("ErrorHint").expect("rows").pop(); + }), + ("remote link", |m| { + set(m, "Link", 0, "href", Value::from("https://example.com/")) + }), + ("orphan measure", |m| { + set( + m, + "QualityMeasure", + 0, + "requirement", + Value::from("Uorc.Page::none"), + ) + }), + ]; + for (label, plant) in plants { + let mut bad = good.clone(); + plant(&mut bad); + assert!(bad.check().is_err(), "{label} must be rejected"); + } + } +} diff --git a/crates/uorc-wasm/src/lib.rs b/crates/uorc-wasm/src/lib.rs index 1515f756..9e673eab 100644 --- a/crates/uorc-wasm/src/lib.rs +++ b/crates/uorc-wasm/src/lib.rs @@ -285,6 +285,84 @@ pub extern "C" fn decompress_tree() -> i32 { })) } +/// Start a file tree streamed through the frame operations: the input +/// buffer lists its entries as `u32 count` then, per entry, `u8 kind`, +/// `u32 pathLength`, path, `u64 length` (zero for a directory). The output is +/// the manifest, the first object; push it, then every regular file's bytes +/// in listing order, with [`compress_frame`], then [`compress_end`]. +#[no_mangle] +pub extern "C" fn tree_start() -> i32 { + finish(INPUT.with(|input| { + let listing = read_listing(&input.borrow())?; + let layout = uorc::tree::layout(listing.iter().map(|(p, k, n)| (p.as_str(), *k, *n)))?; + ENCODER + .with(|encoder| *encoder.borrow_mut() = uorc::FrameEncoder::objects(&layout.lengths)); + Ok(layout.manifest) + })) +} + +fn read_listing(bytes: &[u8]) -> Result, uorc::Error> { + use uorc::tree::Kind; + let mut at = 0usize; + let mut take = |n: usize| -> Result<&[u8], uorc::Error> { + let end = at.checked_add(n).ok_or(uorc::Error::Decode)?; + let out = bytes.get(at..end).ok_or(uorc::Error::Decode)?; + at = end; + Ok(out) + }; + let word = |b: &[u8]| u32::from_le_bytes(b.try_into().expect("4 bytes")) as usize; + let count = word(take(4)?); + let mut out = Vec::new(); + for _ in 0..count { + let kind = match take(1)?[0] { + 0 => Kind::File, + 1 => Kind::Executable, + 2 => Kind::Directory, + _ => return Err(uorc::Error::Decode), + }; + let len = word(take(4)?); + let path = std::str::from_utf8(take(len)?) + .map_err(|_| uorc::Error::Decode)? + .to_owned(); + let length = u64::from_le_bytes(take(8)?.try_into().expect("8 bytes")); + out.push((path, kind, if kind == Kind::Directory { 0 } else { length })); + } + if at != bytes.len() { + return Err(uorc::Error::Decode); + } + Ok(out) +} + +/// The lengths of the object pieces the archive in the input buffer holds, +/// as a JSON array: its output splits at them, and every frame's first piece +/// after the first frame continues the object before. +#[no_mangle] +pub extern "C" fn frame_objects() -> i32 { + finish(INPUT.with(|input| { + let lengths = uorc::object_lengths(&input.borrow())?; + let all: Vec = lengths.iter().map(u64::to_string).collect(); + Ok(format!("[{}]", all.join(",")).into_bytes()) + })) +} + +/// The entries a tree manifest in the input buffer lists, with every path +/// checked, in the [`read_entries`] layout with empty data. +#[no_mangle] +pub extern "C" fn tree_manifest() -> i32 { + finish(INPUT.with(|input| { + let listed = uorc::tree::read_manifest(&input.borrow())?; + let entries: Vec = listed + .into_iter() + .map(|(path, kind)| uorc::tree::Entry { + path, + kind, + data: Vec::new(), + }) + .collect(); + Ok(write_entries(&entries)) + })) +} + #[cfg(test)] mod tests { use super::*; @@ -373,4 +451,106 @@ mod tests { } assert!(back == input); } + + /// A tree streamed a piece at a time writes the library's bytes, and its + /// frames split back into the same files. + #[test] + fn tree_exports_stream_the_library_tree() { + use uorc::tree::{Entry, Kind}; + let big: Vec = (0..uorc::FRAME + 70_000) + .map(|i| (i * 7 % 251) as u8) + .collect(); + let entries = vec![ + Entry { + path: "d".into(), + kind: Kind::Directory, + data: vec![], + }, + Entry { + path: "d/a.txt".into(), + kind: Kind::File, + data: b"alpha".to_vec(), + }, + Entry { + path: "d/big".into(), + kind: Kind::Executable, + data: big, + }, + Entry { + path: "d/empty".into(), + kind: Kind::File, + data: vec![], + }, + ]; + let mut listing = (entries.len() as u32).to_le_bytes().to_vec(); + for e in &entries { + listing.push(match e.kind { + Kind::File => 0, + Kind::Executable => 1, + Kind::Directory => 2, + }); + listing.extend((e.path.len() as u32).to_le_bytes()); + listing.extend(e.path.as_bytes()); + listing.extend((e.data.len() as u64).to_le_bytes()); + } + window_reset(); + let (code, manifest) = run(&listing, || tree_start()); + assert_eq!(code, OK); + let mut stream = run(&manifest, || compress_frame(0)).1; + for e in &entries { + for piece in e.data.chunks(1_000_000) { + let (code, archives) = run(piece, || compress_frame(0)); + assert_eq!(code, OK); + stream.extend(archives); + } + } + stream.extend(run(&[], || compress_end(0)).1); + assert_eq!( + stream, + uorc::compress_tree(&entries, 0).expect("library tree") + ); + + window_reset(); + let mut objects: Vec> = Vec::new(); + for (frame, archive) in uorc::frames(&stream) + .expect("frames") + .into_iter() + .enumerate() + { + let (_, lengths) = run(archive, || frame_objects()); + let lengths: Vec = String::from_utf8(lengths) + .expect("json") + .trim_matches(|c| c == '[' || c == ']') + .split(',') + .filter(|n| !n.is_empty()) + .map(|n| n.parse().expect("length")) + .collect(); + let (code, output) = run(archive, || decompress_frame()); + assert_eq!(code, OK); + let mut rest = &output[..]; + for (i, n) in lengths.into_iter().enumerate() { + let (piece, tail) = rest.split_at(n); + rest = tail; + if frame > 0 && i == 0 { + objects + .last_mut() + .expect("an object to continue") + .extend(piece); + } else { + objects.push(piece.to_vec()); + } + } + } + let (code, listed) = run(&objects[0], || tree_manifest()); + assert_eq!(code, OK); + let listed = read_entries(&listed).expect("listing"); + let mut files = objects.into_iter().skip(1); + for (want, got) in entries.iter().zip(&listed) { + assert_eq!((&want.path, want.kind), (&got.path, got.kind)); + if want.kind != Kind::Directory { + assert_eq!(files.next().expect("file"), want.data); + } + } + assert!(files.next().is_none()); + } } diff --git a/crates/uorc/src/lib.rs b/crates/uorc/src/lib.rs index 481e7896..ca8161b1 100644 --- a/crates/uorc/src/lib.rs +++ b/crates/uorc/src/lib.rs @@ -944,7 +944,24 @@ fn decode_stream( let store = store::Shared::new(scan(&mut reader)?); let store = &store; - let threads = threads.max(1); + if threads <= 1 { + // One core decodes in stream order with no worker thread, which is + // also the only schedule a host without threads (WebAssembly) can run. + let (mut totals, mut carry, mut window) = (Totals::default(), Vec::new(), Vec::new()); + while let Some(archive) = next_archive(&mut reader, &mut carry)? { + totals.read += archive.len() as u64; + on_archive(&archive)?; + let lengths = object_lengths(&archive)?; + let output = decode_into(&mut window, &archive, totals.frames as usize, store, work)?; + totals.written += output.len() as u64; + totals.frames += 1; + on_output(&lengths, output)?; + } + if totals.frames == 0 { + return Err(Error::Decode.into()); + } + return Ok(totals); + } // Output bytes of frames sent to the decoders and not yet handed on. let limit = threads * BLOCK * FRAME; // Cores decoding coded frames: a block whose reference frame waits for a @@ -1168,6 +1185,16 @@ impl FrameEncoder { } } + /// A new stream of ordered objects of `lengths`, whose bytes are pushed + /// back to back (a file tree's [`tree::Layout`]): the archives are the + /// stream [`compress_objects_stream`] writes for the same objects. + pub fn objects(lengths: &[u64]) -> Self { + FrameEncoder { + framer: chunk::Framer::objects(lengths), + before: Vec::new(), + } + } + /// The next piece of input: returns the archives of the frames it /// completes, back to back (none until more than a frame is pending). pub fn push(&mut self, input: &[u8], steps: u64) -> Result, Error> { diff --git a/docs/verification/pages-client.md b/docs/verification/pages-client.md new file mode 100644 index 00000000..cb7c1cef --- /dev/null +++ b/docs/verification/pages-client.md @@ -0,0 +1,82 @@ + +# Pages client against its product model (UC-WEB-01) + +`src/Uorc/Page.lex.tex` is the authority. This file records what was found on +the v0.3 page, the evidence the gate produces and the planted defects that show +each gate can fail. + +## The v0.3 page, driven in headless Chromium + +Measured on main `a4e2222` plus PR #129, with real files and CLI-written archives. + +| Control | Result | +| --- | --- | +| Verify, with or without an original | WebAssembly trap (`unreachable`) | +| Every example button | trap: each example decompresses in memory | +| Decompress of a folder or multi-file archive | trap | +| Any action after a trap | trap: the module's state stays poisoned until reload | +| Compress of an 18 MB file | correct bytes, 90 s with the page frozen between 8 MiB frames, no cancel | +| A file and a folder both chosen | the file is silently ignored | +| "Extra program-search steps" | no effect a visitor can see | + +Cause of the traps: in-memory decoding ran `decode_stream`, which always spawned +worker threads, and `wasm32-unknown-unknown` has none. One core now decodes in +stream order with no thread (`threads <= 1`, which is what a WebAssembly host +reports), the same schedule `FrameDecoder` runs. + +## Gates + +- `cargo xtask check-model`: the model loads, passes the Prism checks (PP2014 to + PP2017 for features and journeys, one initial state, closed triggers, every + state reachable, closed operations, controls, field kinds, error codes and + tables, links to GitHub or the site only, measures naming requirements) and + `web/index.html` equals its rendering. +- `planted_model_defects_are_rejected_uc_web_01`: eleven planted model defects, + each rejected by its check. +- `scripts/page-acceptance.mjs` (CI: `pages-client.yml`; local: `just pages`): + walks the three journeys in fresh pages, runs the 17 acceptance cases, records + every state change and checks every control against `enabledIn` at each one, + and holds the gated measures. + +## Planted defects in the browser gate + +| Plant | Command | Diagnostic | +| --- | --- | --- | +| Cancel enabled in `done` (built `app.js` edited) | `node scripts/page-acceptance.mjs ` | `done: cancel is enabled` | +| The v0.3 wasm (threaded decode) beside the new page | same | `decompress folder: The browser stopped the operation.` and `example text: The browser stopped the operation.` | + +Restored: the unmodified site passes, `17 cases, 11 transitions, 8 measures`. + +The acceptance also requires every `uorc.*` call a feature names to be defined +in the shipped `uorc.js`. + +## Folders stream like files + +Folders and multi-file archives go through the frame operations +(`compressTreeBlob`, `decompressTreeBlob`). The page reads each file a frame at +a time and splits each decoded frame at its object lengths. +`tree_exports_stream_the_library_tree` (uorc-wasm) checks that a tree pushed a +piece at a time writes the library's `compress_tree` bytes and restores the same +entries. In Node, a folder holding a 24 MiB file round-trips with 217 MiB of +WebAssembly memory to compress and 189 MiB to decompress. + +Planting the v0.3 wasm first showed a page defect: an async trap in the worker +raised no `error` event, so the page stayed in `running`. The worker now reports +any non-uorc failure as `stopped` and closes, and the page starts a new one. + +## Measured (4 vCPU cloud VM, headless Chromium, SIMD128 build) + +| Measure | Value | Gate | +| --- | --- | --- | +| Longest page task while an operation runs | 0 ms (4 long tasks seen outside operations) | ≤ 200 ms | +| Cancel to ready | 112 ms | ≤ 3000 ms | +| Navigation to ready | 225 ms | ≤ 5000 ms | +| Page archives differing from the library's | 0 | 0 | +| WebAssembly memory after a 3-frame (24 MiB) stream | 179 MiB | ≤ 256 MiB | +| Controls without an accessible name | 0 | 0 | +| Compress, generated prose | 409 KB/s | measured | +| Decompress, generated prose | 439 KB/s | measured | + +Node (same V8) on 2 MB of repository text: 0.21 MB/s both ways without SIMD128, +0.29 MB/s with it, against 0.53 MB/s for one native core. Random input +compresses at 0.18 MB/s before being stored raw. diff --git a/factory/README.md b/factory/README.md index acb987a3..51e587a9 100644 --- a/factory/README.md +++ b/factory/README.md @@ -8,7 +8,7 @@ identity text (`prism-factory/obligation/1`), receipts on a `factory-receipts` branch, refutation of hermetic failures, retried fetches, and a 16-level weight that orders remaining work. Here the decisions are a small Node host (`scripts/factory.mjs`, tests in `scripts/factory.test.mjs`) over the graph in -`graph.json`, not a kernel-checked model: uorc's graph is fifteen rows. +`graph.json`, not a kernel-checked model: uorc's graph is sixteen rows. ## The graph @@ -21,7 +21,8 @@ that orders remaining work. Here the decisions are a small Node host | `claims`, `reproducibility` | hermetic | the formal set | bootstrap `template-gate` | | `offline` | fetch | the formal set | offline-validation | | `export` | fetch, host | the import closure of `Uorc.Client` (client/src over src), the LexLean project files, the export scripts | `node scripts/client-export.mjs` on a workstation | -| `gate` | gate | the identities of the seven bootstrap legs | proved when all seven are | +| `pages` | fetch | the client set, `crates/uorc-wasm/`, `web/`, the brand files, `scripts/site.mjs`, `scripts/page-acceptance.mjs`, its workflow | pages-client `acceptance` (UC-WEB-01) | +| `gate` | gate | the identities of the seven bootstrap legs and `pages` | proved when all eight are | | `native-` (2), `wasm` | fetch | the client set (+ `crates/uorc-wasm/`) | release `native`, `wasm` | | `bench` | fetch | `scripts/bench.mjs`, release.yml, `native-x86_64` | release `bench` | | `publish` | fetch | everything, `@mode`, `@run` | release `publish`, `pages` | diff --git a/factory/graph.json b/factory/graph.json index 6eaff621..898aa4d1 100644 --- a/factory/graph.json +++ b/factory/graph.json @@ -1,10 +1,10 @@ { "schema": "uorc/factory-graph/1", "sets": { - "formal": ["", "!client/", "!crates/uorc/", "!crates/uorc-wasm/", "!generated/", "!web/", "!vendor/hologram-brand/", "!scripts/site.", "!scripts/bench.mjs", "!scripts/client-export.mjs", "!factory/", "!scripts/factory.", "!.github/workflows/release.yml", "!.github/workflows/pages.yml", "!.github/workflows/factory.yml", "manifest:crates/conformance/Cargo.toml", "manifest:crates/uorc/Cargo.toml", "manifest:crates/uorc-wasm/Cargo.toml", "manifest:generated/rust/uorc_compress/Cargo.toml", "manifest:generated/rust/uorc_decompress/Cargo.toml"], + "formal": ["", "!client/", "!crates/uorc/", "!crates/uorc-wasm/", "!generated/", "!web/", "web/index.html", "!vendor/hologram-brand/", "!scripts/site.", "!scripts/page-acceptance.mjs", "!.github/workflows/pages-client.yml", "!scripts/bench.mjs", "!scripts/client-export.mjs", "!factory/", "!scripts/factory.", "!.github/workflows/release.yml", "!.github/workflows/pages.yml", "!.github/workflows/factory.yml", "manifest:crates/conformance/Cargo.toml", "manifest:crates/uorc/Cargo.toml", "manifest:crates/uorc-wasm/Cargo.toml", "manifest:generated/rust/uorc_compress/Cargo.toml", "manifest:generated/rust/uorc_decompress/Cargo.toml"], "lexlean": ["lexlean.toml", "lexlean.lock", "lakefile.toml", "lake-manifest.json", "lean-toolchain", "prismpm.lock", "Justfile", ".github/workflows/bootstrap.yml", "validation/lexlean-verify-hints.json"], "xtask": ["Cargo.toml", "Cargo.lock", "rust-toolchain.toml", ".cargo/", "xtask/", "crates/model/", "manifest:crates/conformance/Cargo.toml", "manifest:crates/uorc/Cargo.toml", "manifest:crates/uorc-wasm/Cargo.toml", "manifest:generated/rust/uorc_compress/Cargo.toml", "manifest:generated/rust/uorc_decompress/Cargo.toml"], - "scripts": ["scripts/", "!scripts/factory.", "!scripts/site.", "!scripts/bench.mjs", "!scripts/client-export.mjs"], + "scripts": ["scripts/", "!scripts/factory.", "!scripts/site.", "!scripts/page-acceptance.mjs", "!scripts/bench.mjs", "!scripts/client-export.mjs"], "client": ["Cargo.toml", "Cargo.lock", "rust-toolchain.toml", ".cargo/", "crates/uorc/", "generated/rust/", ".github/workflows/release.yml"] }, "obligations": [ @@ -17,7 +17,8 @@ {"name": "integrity-ubuntu-24.04", "kind": "hermetic", "environment": "ubuntu-24.04", "run": "just integrity", "inputs": ["&lexlean", "&xtask", "&scripts", "closure:Uorc.Integrity.*,Uorc.Wire.ArchiveIntegrity,Uorc.Wire.OwnedRead", "validation/integrity/", "standards/", "standards.lock"], "needs": [], "workflow": "bootstrap.yml", "job": "template-gate"}, {"name": "offline", "kind": "fetch", "environment": "ubuntu-24.04", "run": "node scripts/offline-validation.mjs acquire, isolated first and second-distinct-root, compare-offline", "inputs": ["&formal"], "needs": [], "workflow": "offline-validation.yml", "job": "offline-compare"}, {"name": "export", "kind": "fetch", "environment": "host", "run": "node scripts/client-export.mjs", "inputs": ["closure:Uorc.Client@client/src,src", "lexlean.toml", "lakefile.toml", "lake-manifest.json", "lean-toolchain", "scripts/client-export.mjs", "scripts/semantic-source.mjs"], "needs": [], "record": "generated/rust/factory.identity"}, - {"name": "gate", "kind": "gate", "environment": "-", "run": "-", "inputs": [], "needs": ["rest-ubuntu-24.04", "rest-ubuntu-24.04-arm", "artifacts-ubuntu-24.04", "claims-ubuntu-24.04", "varint-ubuntu-24.04", "reproducibility-ubuntu-24.04", "integrity-ubuntu-24.04"], "workflow": "release.yml", "job": "factory"}, + {"name": "pages", "kind": "fetch", "environment": "ubuntu-24.04", "run": "cargo build --locked --release -p uorc-wasm --target wasm32-unknown-unknown && node scripts/site.mjs && node scripts/page-acceptance.mjs", "inputs": ["&client", "crates/uorc-wasm/", "web/", "vendor/hologram-brand/", "scripts/site.mjs", "scripts/page-acceptance.mjs", ".github/workflows/pages-client.yml"], "needs": [], "workflow": "pages-client.yml", "job": "acceptance"}, + {"name": "gate", "kind": "gate", "environment": "-", "run": "-", "inputs": [], "needs": ["rest-ubuntu-24.04", "rest-ubuntu-24.04-arm", "artifacts-ubuntu-24.04", "claims-ubuntu-24.04", "varint-ubuntu-24.04", "reproducibility-ubuntu-24.04", "integrity-ubuntu-24.04", "pages"], "workflow": "release.yml", "job": "factory"}, {"name": "native-x86_64-unknown-linux-gnu", "kind": "fetch", "environment": "ubuntu-24.04", "run": "cargo test --locked --release -p uorc && cargo build --locked --release -p uorc --target x86_64-unknown-linux-gnu", "inputs": ["&client"], "needs": [], "workflow": "release.yml", "job": "native", "evidence": "factory-native-x86_64-unknown-linux-gnu"}, {"name": "native-aarch64-unknown-linux-gnu", "kind": "fetch", "environment": "ubuntu-24.04-arm", "run": "cargo test --locked --release -p uorc && cargo build --locked --release -p uorc --target aarch64-unknown-linux-gnu", "inputs": ["&client"], "needs": [], "workflow": "release.yml", "job": "native", "evidence": "factory-native-aarch64-unknown-linux-gnu"}, {"name": "wasm", "kind": "fetch", "environment": "ubuntu-24.04", "run": "cargo build --locked --release -p uorc-wasm --target wasm32-unknown-unknown", "inputs": ["&client", "crates/uorc-wasm/"], "needs": [], "workflow": "release.yml", "job": "wasm", "evidence": "factory-wasm"}, diff --git a/features/suites/pages-client.feature b/features/suites/pages-client.feature new file mode 100644 index 00000000..4eec5bb7 --- /dev/null +++ b/features/suites/pages-client.feature @@ -0,0 +1,8 @@ +# @generated from src/Uorc/Registry.lex.tex by `cargo xtask check-model --write`. +Feature: pages-client + + @UC-WEB-01 @build + Scenario: The Pages client is generated from and conforms to its Prism product model in Uorc.Page: stakeholders, features with their calls and acceptance cases, journeys, the page's UML state machine, operations, fields, controls, examples, error hints, sections, usage, links and quality measures. The generated page holds exactly the modeled elements, and a real browser walks every journey, takes every modeled transition, checks every control's enabled state in every state it reaches and holds every gated quality measure. + Given the Uorc.Page module, the generated web/index.html and the site built from the release wasm + When the model gate checks and renders the model and the browser acceptance drives the built site in headless Chromium + Then every Prism check holds, the committed page equals the rendered model, every acceptance case passes, every transition is taken and every gated measure is within its threshold diff --git a/model/ids.toml b/model/ids.toml index b6a17d04..10eea1b3 100644 --- a/model/ids.toml +++ b/model/ids.toml @@ -170,3 +170,9 @@ id = "UC-NEU-01" level = "build" suite = "neuromorphic-standard" statement = "The ncm coder's plasticity is stated as the Prism neuromorphic standard in Uorc.Neuromorphic, with kernel-checked bounds: every mixer weight stays within plus or minus 2^22 under the bounded Hebbian rule, potentiation never lowers and depression never raises a weight, the plasticity lies between 24 and 128 per 65536 (128 at the first byte, 24 in the limit), one bit's weight change is at most 16376 and every product fits a 32-bit lane, a context slot never steps past its gap to the coded bit and consolidates at count 127, and every probability-map point stays within 16 bits; the native coder reads the model's constants." + +[[id]] +id = "UC-WEB-01" +level = "build" +suite = "pages-client" +statement = "The Pages client is generated from and conforms to its Prism product model in Uorc.Page: stakeholders, features with their calls and acceptance cases, journeys, the page's UML state machine, operations, fields, controls, examples, error hints, sections, usage, links and quality measures. The generated page holds exactly the modeled elements, and a real browser walks every journey, takes every modeled transition, checks every control's enabled state in every state it reaches and holds every gated quality measure." diff --git a/model/ledger.toml b/model/ledger.toml index cf47135b..df968db3 100644 --- a/model/ledger.toml +++ b/model/ledger.toml @@ -228,3 +228,11 @@ statement = "The ncm coder's plasticity is stated as the Prism neuromorphic stan evidence_kind = "kernel_theorem" research_disposition = "not_measured" feature = "features/suites/neuromorphic-standard.feature" + +[[claim]] +id = "UC-WEB-01" +level = "build" +statement = "The Pages client is generated from and conforms to its Prism product model in Uorc.Page: stakeholders, features with their calls and acceptance cases, journeys, the page's UML state machine, operations, fields, controls, examples, error hints, sections, usage, links and quality measures. The generated page holds exactly the modeled elements, and a real browser walks every journey, takes every modeled transition, checks every control's enabled state in every state it reaches and holds every gated quality measure." +evidence_kind = "build_evidence" +research_disposition = "not_measured" +feature = "features/suites/pages-client.feature" diff --git a/scripts/page-acceptance.mjs b/scripts/page-acceptance.mjs new file mode 100644 index 00000000..69178ca3 --- /dev/null +++ b/scripts/page-acceptance.mjs @@ -0,0 +1,459 @@ +#!/usr/bin/env node +// UC-WEB-01: the browser acceptance of the Pages client against its Prism +// product model (src/Uorc/Page.lex.tex, carried as JSON by the built page). +// +// It serves a built site, drives headless Chromium over the DevTools protocol +// (no dependency beyond Node), walks every journey of the model in a fresh +// page, runs each feature's acceptance cases, records every state transition +// and checks every control's enabled state in every state reached, and holds +// every gated quality measure to its threshold. Measured-only measures are +// reported. Any failure exits 1. +// +// node scripts/page-acceptance.mjs [--chrome ] [--report ] +import { spawn } from 'node:child_process'; +import crypto from 'node:crypto'; +import fs from 'node:fs'; +import http from 'node:http'; +import os from 'node:os'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const [site, ...rest] = process.argv.slice(2); +const opt = (key) => { const i = rest.indexOf(key); return i < 0 ? undefined : rest[i + 1]; }; +if (!site) { console.error('usage: node scripts/page-acceptance.mjs [--chrome ] [--report ]'); process.exit(2); } +const chrome = opt('--chrome') ?? process.env.CHROME ?? ['/usr/bin/google-chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser', '/opt/pw-browsers/chromium'].find((p) => fs.existsSync(p)); +if (!chrome) { console.error('page acceptance: no Chrome or Chromium found; pass --chrome'); process.exit(2); } + +const html = fs.readFileSync(path.join(site, 'index.html'), 'utf8'); +const model = JSON.parse(html.match(/ diff --git a/web/uorc.js b/web/uorc.js index 2e831e28..16be7302 100644 --- a/web/uorc.js +++ b/web/uorc.js @@ -1,8 +1,13 @@ -// Thin loader for the uorc WebAssembly client (crates/uorc-wasm). +// Thin loader for the uorc WebAssembly client (crates/uorc-wasm). Loaded as a +// module worker, it is also the page's worker: see `serve` at the end. const ERRORS = ["", "no checked archive was found within the step budget", "a natural-number operation overflowed 64 bits", "input is not a decodable stream of self-contained UORC archives", "the archive does not decode to the given original"]; +// The code of each failure, as the page's product model names them. +export const CODES = ["", "budget", "overflow", "decode", "mismatch"]; +const failure = (code) => Object.assign(new Error(ERRORS[code] ?? `uorc error ${code}`), { code: CODES[code] ?? "decode" }); const KINDS = ["file", "executable", "directory"]; +const fail = () => { throw failure(3); }; // Entries cross into wasm as u32 count, then per entry u8 kind, u32 path length, // path, u32 data length, data (little-endian). @@ -23,6 +28,23 @@ function packEntries(entries) { return out; } +// A tree's listing crosses as u32 count, then per entry u8 kind, u32 path +// length, path, u64 length (little-endian): no file bytes. +function packListing(items) { + const enc = new TextEncoder(); + const paths = items.map((e) => enc.encode(e.path)); + const out = new Uint8Array(4 + items.reduce((n, e, i) => n + 13 + paths[i].length, 0)); + const view = new DataView(out.buffer); + let at = 0; + view.setUint32(at, items.length, true); at += 4; + items.forEach((e, i) => { + out[at++] = Math.max(0, KINDS.indexOf(e.kind ?? "file")); + view.setUint32(at, paths[i].length, true); at += 4; out.set(paths[i], at); at += paths[i].length; + view.setBigUint64(at, BigInt(e.blob?.size ?? 0), true); at += 8; + }); + return out; +} + function unpackEntries(bytes) { const dec = new TextDecoder(); const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength); @@ -50,7 +72,7 @@ export async function load(url) { const call = (bytes, op) => { put(x.input_buffer, bytes); const code = op(); - if (code !== 0) throw new Error(ERRORS[code] ?? `uorc error ${code}`); + if (code !== 0) throw failure(code); return new Uint8Array(x.memory.buffer, x.output_ptr(), x.output_len()).slice(); }; const json = (bytes) => JSON.parse(new TextDecoder().decode(bytes)); @@ -63,7 +85,20 @@ export async function load(url) { put(x.input_buffer, head); const length = x.frame_length(); if (length >= 0 && at + length <= blob.size) return length; - if (length === -1 || head.length < want) throw new Error(ERRORS[3]); + if (length === -1 || head.length < want) throw failure(3); + } + }; + // Start decoding a stream: read the headers first and note every reference + // frame, so the decoder keeps the frames they name (and only those). + const begin = async (blob) => { + x.window_reset(); + for (let at = 0; at < blob.size;) { + const length = await archiveLength(blob, at); + if (x.may_be_reference()) { + put(x.input_buffer, await bytesOf(blob.slice(at, at + length))); + x.note_frame(); + } + at += length; } }; return { @@ -89,17 +124,7 @@ export async function load(url) { }, async decompressBlob(blob, progress = () => {}) { const parts = []; - x.window_reset(); - // Headers first: note every reference frame, so the decoder keeps the - // frames they name (and only those). - for (let at = 0; at < blob.size;) { - const length = await archiveLength(blob, at); - if (x.may_be_reference()) { - put(x.input_buffer, await bytesOf(blob.slice(at, at + length))); - x.note_frame(); - } - at += length; - } + await begin(blob); for (let at = 0; at < blob.size || parts.length === 0;) { const length = await archiveLength(blob, at); parts.push(call(await bytesOf(blob.slice(at, at + length)), () => x.decompress_frame())); @@ -117,5 +142,151 @@ export async function load(url) { // entries: [{ path: "dir/a.txt", kind: "file" | "executable" | "directory", data: Uint8Array }] compressFiles: (entries, steps = 0n) => call(packEntries(entries), () => x.compress_tree(BigInt(steps))), decompressFiles: (archive) => unpackEntries(call(archive, () => x.decompress_tree())), + // Stream a file tree of any size: items are [{ path, kind, blob }] (no + // blob for a directory). Each file is read a frame at a time; the result + // is a Blob of the same bytes compressFiles writes. + async compressTreeBlob(items, steps = 0n, progress = () => {}) { + x.window_reset(); + const manifest = call(packListing(items), () => x.tree_start()); + const parts = [call(manifest, () => x.compress_frame(BigInt(steps)))]; + const total = items.reduce((n, e) => n + (e.blob?.size ?? 0), 0); + let done = 0; + for (const { blob } of items) { + for (let at = 0; blob && at < blob.size; at += frame) { + const piece = await bytesOf(blob.slice(at, at + frame)); + parts.push(call(piece, () => x.compress_frame(BigInt(steps)))); + done += piece.length; + progress(done, total); + } + } + parts.push(call(new Uint8Array(0), () => x.compress_end(BigInt(steps)))); + progress(total, total); + return new Blob(parts); + }, + // Restore a tree archive a frame at a time: [{ path, kind, blob }], with + // no blob for a directory. A one-object archive is not a tree. + async decompressTreeBlob(blob, progress = () => {}) { + await begin(blob); + const objects = []; + for (let at = 0, frames = 0; at < blob.size || frames === 0; frames++) { + const length = await archiveLength(blob, at); + const archive = await bytesOf(blob.slice(at, at + length)); + const lengths = json(call(archive, () => x.frame_objects())); + const output = call(archive, () => x.decompress_frame()); + let from = 0; + lengths.forEach((n, i) => { + const piece = output.subarray(from, from + n); + from += n; + if (frames > 0 && i === 0) { + if (!objects.length) throw failure(3); + objects.at(-1).push(piece); + } else objects.push([piece]); + }); + at += length; + progress(at, blob.size); + } + if (objects.length < 2) throw failure(3); + const manifest = new Uint8Array(await new Blob(objects[0]).arrayBuffer()); + const listed = unpackEntries(call(manifest, () => x.tree_manifest())); + const files = objects.slice(1); + const entries = listed.map(({ path, kind }) => (kind === "directory" ? { path, kind } : { path, kind, blob: new Blob(files.shift() ?? fail()) })); + if (files.length > 1 || (files.length === 1 && (entries.some((e) => e.blob) || files[0].some((p) => p.length)))) throw failure(3); + return entries; + }, + // How many objects the stream's first archive holds: one for a file, more + // for an archive of several files or a folder. + async objects(blob) { + const length = await archiveLength(blob, 0); + const [info] = json(call(await bytesOf(blob.slice(0, length)), () => x.inspect())); + return info.objects; + }, + // Bytes of WebAssembly memory the client holds now. + memoryBytes: () => x.memory.buffer.byteLength, + }; +} + +// The page's worker: one operation at a time on File objects, answering with +// progress, then the result or the failure's code. The page ends a running +// operation by terminating the worker. +const inWorker = typeof WorkerGlobalScope !== "undefined" && self instanceof WorkerGlobalScope; + +const EXAMPLES = { + text: (n, seed) => { const t = new TextEncoder().encode(seed); return Uint8Array.from({ length: n }, (_, i) => t[i % t.length]); }, + zeros: (n) => new Uint8Array(n), + counter: (n) => Uint8Array.from({ length: n }, (_, i) => i & 255), + random: (n) => { const out = new Uint8Array(n); for (let at = 0; at < n; at += 65536) crypto.getRandomValues(out.subarray(at, Math.min(n, at + 65536))); return out; }, + empty: () => new Uint8Array(0), +}; + +async function serve() { + let uorc; + try { + uorc = await load("./uorc_bg.wasm"); + } catch (error) { + self.postMessage({ type: "loadFailed", message: String(error?.message ?? error) }); + return; + } + const bytesOf = async (file) => new Uint8Array(await file.arrayBuffer()); + const progress = (done, total) => self.postMessage({ type: "progress", done, total }); + const run = { + async compress({ files }) { + const tree = files.length > 1 || files.some((f) => f.webkitRelativePath); + if (!tree) { + const [file] = files; + const archive = await uorc.compressBlob(file, 0n, progress); + return { kind: "archive", input: file.size, files: [{ path: `${file.name}.uorc`, blob: archive }] }; + } + const dirs = new Set(); + const entries = files.map((file) => { + const path = file.webkitRelativePath || file.name; + const parts = path.split("/"); + for (let i = 1; i < parts.length; i++) dirs.add(parts.slice(0, i).join("/")); + return { path, kind: "file", blob: file }; + }); + const total = files.reduce((n, f) => n + f.size, 0); + const all = [...[...dirs].sort().map((path) => ({ path, kind: "directory" })), ...entries]; + const root = files[0].webkitRelativePath ? files[0].webkitRelativePath.split("/")[0] : "files"; + const archive = await uorc.compressTreeBlob(all, 0n, progress); + return { kind: "archive", input: total, count: entries.length, files: [{ path: `${root}.uorc`, blob: archive }] }; + }, + async decompress({ archive }) { + if ((await uorc.objects(archive)) === 1) { + const blob = await uorc.decompressBlob(archive, progress); + const name = archive.name.endsWith(".uorc") && archive.name.length > 5 ? archive.name.slice(0, -5) : `${archive.name}.out`; + return { kind: "files", input: archive.size, files: [{ path: name, blob }] }; + } + const entries = await uorc.decompressTreeBlob(archive, progress); + const files = entries.filter((e) => e.blob).map((e) => ({ path: e.path, blob: e.blob })); + return { kind: "files", input: archive.size, files }; + }, + async inspect({ archive }) { + return { kind: "table", input: archive.size, rows: uorc.inspect(await bytesOf(archive)) }; + }, + async verify({ archive, original }) { + const rows = uorc.verify(await bytesOf(archive), original ? await bytesOf(original) : undefined); + return { kind: "verified", input: archive.size, compared: Boolean(original), rows }; + }, + async example({ input, bytes, seed }) { + const data = EXAMPLES[input](bytes, seed); + const started = performance.now(); + const archive = uorc.compress(data); + const back = uorc.decompress(archive); + const same = back.length === data.length && back.every((b, i) => b === data[i]); + return { kind: "example", bytes: data.length, archive: archive.length, same, seconds: (performance.now() - started) / 1000 }; + }, }; + self.onmessage = async ({ data }) => { + try { + const result = await run[data.op](data); + self.postMessage({ type: "done", result: { ...result, memory: uorc.memoryBytes() } }); + } catch (error) { + // Anything but a uorc failure (a trap, exhausted memory) leaves the + // module unusable: report the stop and let the page start a new worker. + self.postMessage({ type: "failed", code: error?.code ?? "stopped", message: String(error?.message ?? error) }); + if (!error?.code) self.close(); + } + }; + self.postMessage({ type: "ready" }); } + +if (inWorker) serve();