diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
new file mode 100644
index 0000000..3033516
--- /dev/null
+++ b/.github/workflows/pages.yml
@@ -0,0 +1,66 @@
+name: Deploy MachineOutcome live demo
+
+on:
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+concurrency:
+ group: pages
+ cancel-in-progress: false
+
+jobs:
+ verify-and-build:
+ runs-on: ubuntu-24.04
+ timeout-minutes: 8
+ steps:
+ - name: Checkout
+ uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+ with:
+ persist-credentials: false
+
+ - name: Setup Node
+ uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+ with:
+ node-version: "24"
+
+ - name: Verify reference and live demo
+ run: npm test
+
+ - name: Build minimal static artifact
+ run: |
+ set -euo pipefail
+ mkdir -p _site/src
+ cp index.html app.js styles.css _site/
+ cp src/reference-outcome-verifier.mjs src/demo-model.mjs _site/src/
+ test -s _site/index.html
+ test -s _site/app.js
+ test -s _site/styles.css
+ test -s _site/src/reference-outcome-verifier.mjs
+ test -s _site/src/demo-model.mjs
+
+ - name: Upload Pages artifact
+ uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b
+ with:
+ path: _site
+
+ deploy:
+ needs: verify-and-build
+ permissions:
+ pages: write
+ id-token: write
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+ runs-on: ubuntu-24.04
+ timeout-minutes: 8
+ steps:
+ - name: Configure Pages
+ uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b
+ with:
+ enablement: true
+
+ - name: Deploy Pages
+ id: deployment
+ uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e
diff --git a/README.md b/README.md
index 81faab8..abb431b 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,9 @@
# MachineOutcome - verify what actually happened before retrying
+[**Browser lab for this release →**](https://samct86.github.io/machineoutcome-case-study/)
+
+After the Pages deployment for this release completes, no install, account, credential or real external write is required. The browser lab uses the same bounded verifier exported by this repository and runs entirely on synthetic state.
+
[](https://github.com/SamCT86/machineoutcome-case-study/actions/workflows/verify-reference.yml)
MachineOutcome is about a simple but important failure mode in automation: an API call can time out even though the external system already changed.
@@ -36,6 +40,10 @@ Start with **2–3 sentences** describing what is slow, expensive or unreliable.
## Try it
+**Fastest path after the Pages deployment completes:** open the [browser lab](https://samct86.github.io/machineoutcome-case-study/) and run **Timeout, but change happened**. Then switch to **No readback** and **Wrong-attempt evidence** to see the safe action change.
+
+**Technical verification from a clean clone:**
+
```bash
git clone https://github.com/SamCT86/machineoutcome-case-study.git
cd machineoutcome-case-study
diff --git a/app.js b/app.js
new file mode 100644
index 0000000..bbd45bd
--- /dev/null
+++ b/app.js
@@ -0,0 +1,84 @@
+import { verifyMutationOutcome } from "./src/reference-outcome-verifier.mjs";
+import { SCENARIOS, escapeHtml, evaluateControls } from "./src/demo-model.mjs";
+
+const form = document.querySelector("#lab-form");
+const presets = document.querySelector("#presets");
+const result = document.querySelector("#result");
+const validation = document.querySelector("#validation");
+const resetButton = document.querySelector("[data-reset]");
+const guidedButton = document.querySelector("[data-run-guided]");
+let selected = "ambiguousVerified";
+
+function setControls(values) {
+ for (const [key, value] of Object.entries(values)) form.elements[key].value = value;
+}
+
+function readControls() {
+ return Object.fromEntries(["ack", "prestate", "readback", "poststate", "identity"].map((key) => [key, form.elements[key].value]));
+}
+
+function renderPresets() {
+ presets.innerHTML = "";
+ for (const [key, scenario] of Object.entries(SCENARIOS)) {
+ const button = document.createElement("button");
+ button.type = "button";
+ button.className = "preset";
+ button.dataset.scenario = key;
+ button.setAttribute("aria-pressed", String(key === selected));
+ button.innerHTML = '' + escapeHtml(scenario.title) + ' ' + escapeHtml(scenario.hint) + ' ';
+ button.addEventListener("click", () => {
+ selected = key;
+ setControls(scenario.controls);
+ validation.textContent = "";
+ renderPresets();
+ evaluate(scenario.controls);
+ });
+ presets.append(button);
+ }
+}
+
+function evaluate(controls) {
+ validation.textContent = "";
+ try {
+ const evaluation = evaluateControls(controls, verifyMutationOutcome);
+ result.innerHTML = evaluation.markup;
+ return evaluation.output;
+ } catch (error) {
+ validation.textContent = "VERIFIER_REFUSED_INPUT: " + (error instanceof Error ? error.message : String(error));
+ result.innerHTML = 'FAIL CLOSED
Invalid evidence contract. The public verifier rejected the input instead of guessing.
READY
Run an ambiguous action. You will get an outcome status, reason, safe retry decision, evidence trace and the exact verifier input/output.
MachineOutcome — Outcome Verification Lab
+ Skip to lab
+
+
+
+
+
+
OUTCOME VERIFICATION FOR AGENTIC SYSTEMS
+
A timeout is not a failure. Prove what happened before retrying.
+
MachineOutcome demonstrates one reliability rule: when an external action has an ambiguous result, read back the real state before success or retry is trusted.
+
+
+ ✓ no credentials
+ ✓ no network calls
+ ✓ no real writes
+ ✓ canonical public verifier
+
+
+ attempt / repo-change-001 synthetic
+
+ 01 MUTATION attempted 02 ACK timeout 03 READBACK expected state 04 OUTCOME verified 05 RETRY blocked
+ transport certainty: low verified by state
+
+
+
+
+
+
THE FAILURE MODE
+
+
1 Action leaves your process An agent asks another system to mutate something.
+
2 Acknowledgement disappears The request times out after the external system may already have changed.
+
3 Naive retry duplicates work Treating silence as failure can create a second write, deploy, payment or message.
+
4 Read reality first Observed post-state decides whether success or retry is safe.
+
+
+
+
+
+
+
TRY IT WITHOUT INSTALLING ANYTHING
+
Change the evidence. Watch the safe action change.
+
+
This lab calls the same bounded verifier exported by this public repository. It never contacts a provider and never performs a mutation.
+
+
+
+
+
+
+ READY
Run an ambiguous action. You will get an outcome status, reason, safe retry decision, evidence trace and the exact verifier input/output.
+
+
+
+
+
WHAT THIS PROVES
Small enough to inspect. Strict enough to fail closed.
+
The public lab demonstrates one invariant. It is not the private MachineOutcome runtime and it does not claim customer adoption, ROI or universal agent reliability.
+
+
01 Bind evidence Wrong-task and wrong-attempt evidence cannot prove the action.
+
02 Bind pre-state A stale starting state blocks the mutation boundary.
+
03 Read after ambiguity Transport timeout does not decide the real outcome.
+
04 Keep UNKNOWN Missing or ambiguous reality stays unresolved instead of being guessed into success or failure.
+
+
+
+
+
+
+
diff --git a/src/demo-model.mjs b/src/demo-model.mjs
new file mode 100644
index 0000000..a94c8c4
--- /dev/null
+++ b/src/demo-model.mjs
@@ -0,0 +1,120 @@
+export const BASE = Object.freeze({
+ taskId: "task:repo-change-001",
+ evidenceTaskId: "task:repo-change-001",
+ attemptId: "attempt:001",
+ evidenceAttemptId: "attempt:001",
+ expectedPreState: "repo@before",
+ expectedPostState: "repo@after",
+ observedPreState: "repo@before",
+ observedPostState: "repo@after",
+ readbackComplete: true,
+ providerAcknowledgement: "accepted",
+});
+
+export const SCENARIOS = Object.freeze({
+ ambiguousVerified: {
+ title: "Timeout, but change happened",
+ hint: "The acknowledgement disappears, but readback proves the expected state.",
+ controls: { ack: "ambiguous", prestate: "match", readback: "complete", poststate: "expected", identity: "exact" },
+ },
+ readbackMissing: {
+ title: "No readback",
+ hint: "Reality is unavailable, so retry remains blocked.",
+ controls: { ack: "ambiguous", prestate: "match", readback: "incomplete", poststate: "expected", identity: "exact" },
+ },
+ unchanged: {
+ title: "Timeout, state unchanged",
+ hint: "The provider is reachable, but the state still looks unchanged.",
+ controls: { ack: "ambiguous", prestate: "match", readback: "complete", poststate: "unchanged", identity: "exact" },
+ },
+ stalePrestate: {
+ title: "Stale starting state",
+ hint: "The action was prepared against an outdated state.",
+ controls: { ack: "accepted", prestate: "stale", readback: "complete", poststate: "expected", identity: "exact" },
+ },
+ wrongAttempt: {
+ title: "Wrong-attempt evidence",
+ hint: "The state looks right, but the evidence belongs to another attempt.",
+ controls: { ack: "accepted", prestate: "match", readback: "complete", poststate: "expected", identity: "wrong-attempt" },
+ },
+ wrongPost: {
+ title: "Unexpected post-state",
+ hint: "Readback is complete, but reality is not what the action was supposed to produce.",
+ controls: { ack: "accepted", prestate: "match", readback: "complete", poststate: "unexpected", identity: "exact" },
+ },
+});
+
+export function escapeHtml(value) {
+ return String(value)
+ .replaceAll("&", "&")
+ .replaceAll("<", "<")
+ .replaceAll(">", ">")
+ .replaceAll('"', """)
+ .replaceAll("'", "'");
+}
+
+export function toVerifierInput(c) {
+ const input = { ...BASE };
+ input.providerAcknowledgement = c.ack;
+ input.observedPreState = c.prestate === "match" ? BASE.expectedPreState : "repo@stale";
+ input.readbackComplete = c.readback === "complete";
+ input.observedPostState =
+ c.poststate === "expected" ? BASE.expectedPostState :
+ c.poststate === "unchanged" ? input.observedPreState :
+ "repo@unexpected";
+ if (!input.readbackComplete) input.observedPostState = null;
+ if (c.identity === "wrong-attempt") input.evidenceAttemptId = "attempt:other";
+ if (c.identity === "wrong-task") input.evidenceTaskId = "task:other";
+ return input;
+}
+
+export function explanation(out) {
+ const table = {
+ POSTSTATE_CONFIRMED: ["Observed state matches the expected result.", "Do not retry the mutation."],
+ PRESTATE_MISMATCH: ["The starting state changed before the action could be trusted.", "Do not mutate from this stale pre-state."],
+ READBACK_INCOMPLETE: ["The external reality is not established yet.", "Reconcile state before retrying."],
+ AMBIGUOUS_MUTATION_STATE: ["The acknowledgement was ambiguous and the observed state is still unchanged.", "Keep the outcome UNKNOWN and reconcile before retrying."],
+ EVIDENCE_ATTEMPT_MISMATCH: ["The readback belongs to a different attempt.", "Reject the evidence and do not retry from it."],
+ EVIDENCE_TASK_MISMATCH: ["The readback belongs to a different task.", "Reject the evidence and do not retry from it."],
+ POSTSTATE_MISMATCH: ["Readback is complete, but reality does not match the expected result.", "Treat the outcome as failed; do not blindly replay the mutation."],
+ };
+ return table[out.reason] ?? ["The verifier refused to infer a safe outcome.", out.retry.replaceAll("_", " ").toLowerCase() + "."];
+}
+
+export function naiveReaction(input) {
+ return input.providerAcknowledgement === "ambiguous"
+ ? "Treat the timeout as failure and immediately repeat the external action."
+ : "Trust the transport response without proving the downstream state.";
+}
+
+export function traceRows(input, out) {
+ return [
+ ["1", "IDENTITY", input.evidenceTaskId === input.taskId && input.evidenceAttemptId === input.attemptId ? "bound" : "mismatch", input.evidenceTaskId + " / " + input.evidenceAttemptId],
+ ["2", "PRE-STATE", input.observedPreState === input.expectedPreState ? "match" : "mismatch", "expected " + input.expectedPreState + " · observed " + input.observedPreState],
+ ["3", "ATTEMPT", "attempted", "provider acknowledgement: " + input.providerAcknowledgement],
+ ["4", "READBACK", input.readbackComplete ? "complete" : "incomplete", input.readbackComplete ? "observed " + input.observedPostState : "provider state not established"],
+ ["5", "OUTCOME", out.status.toLowerCase(), out.status + " · " + out.reason],
+ ["6", "RETRY", out.retry === "DO_NOT_RETRY" || out.retry === "DO_NOT_MUTATE" ? "blocked" : "hold", out.retry.replaceAll("_", " ")],
+ ];
+}
+
+export function renderResultMarkup(input, out) {
+ const [why, safe] = explanation(out);
+ const tone = out.status.toLowerCase();
+ const trace = traceRows(input, out)
+ .map(([n, stage, state, detail]) => '' + n + ' ' + stage + ' ' + escapeHtml(state) + ' ' + escapeHtml(detail) + '
OUTCOME
' + escapeHtml(out.status) + ' ' + escapeHtml(why) + '
' + escapeHtml(out.reason) + ' Safe next action ' + escapeHtml(safe) + '
',
+ 'Naive reaction ' + escapeHtml(naiveReaction(input)) + '
MachineOutcome reaction ' + escapeHtml(out.retry.replaceAll("_", " ")) + '
' + trace + '
',
+ 'Inspect exact verifier input and output ' + escapeHtml(JSON.stringify({ input, output: out }, null, 2)) + ' {
+ assert.match(app, /from "\.\/src\/reference-outcome-verifier\.mjs"/);
+ for (const primitive of [/\bfetch\s*\(/, /\bXMLHttpRequest\b/, /\bWebSocket\b/, /\bnavigator\.sendBeacon\b/]) assert.doesNotMatch(app, primitive);
+});
+
+test("preset selection immediately evaluates the selected scenario so stale results cannot remain visible", () => {
+ assert.match(app, /button\.addEventListener\("click",[\s\S]*evaluate\(scenario\.controls\)/);
+});
+
+test("manual select changes immediately reevaluate current controls so visible outcomes never stay stale", () => {
+ assert.match(app, /form\.addEventListener\("change",[\s\S]*HTMLSelectElement[\s\S]*evaluate\(readControls\(\)\)/);
+});
+
+test("guided ambiguous-success scenario is VERIFIED by the canonical verifier", () => {
+ assert.deepEqual(verifyMutationOutcome({
+ taskId:"task:repo-change-001",
+ evidenceTaskId:"task:repo-change-001",
+ attemptId:"attempt:001",
+ evidenceAttemptId:"attempt:001",
+ expectedPreState:"repo@before",
+ expectedPostState:"repo@after",
+ observedPreState:"repo@before",
+ observedPostState:"repo@after",
+ readbackComplete:true,
+ providerAcknowledgement:"ambiguous",
+ }), { status:"VERIFIED", reason:"POSTSTATE_CONFIRMED", retry:"DO_NOT_RETRY" });
+});
+
+test("demo exposes failure presets and explicit proof boundaries", () => {
+ for (const phrase of ["Timeout, but change happened","No readback","Timeout, state unchanged","Stale starting state","Wrong-attempt evidence","Unexpected post-state"]) assert.ok(model.includes(phrase), phrase);
+ assert.match(html, /not the private MachineOutcome runtime/i);
+ assert.match(html, /no credentials/i);
+ assert.match(html, /no network calls/i);
+});
+
+test("responsive stylesheet includes mobile and reduced-motion handling", () => {
+ assert.match(css, /@media\(max-width:580px\)/);
+ assert.match(css, /prefers-reduced-motion/);
+});