iterate-kernel 0.1.1 → 0.1.2

package/README.md

@@ -90,6 +90,21 @@ as `unplanned` — a reporter that quietly dropped it would be the failure this
 consumer depends on, so a change to either is a minor-version change at minimum, and the
 fixtures in `fixtures/` are the executable statement of what the contract means.
 
+## The fixtures are the portable half of the contract
+
+`schemas/` and `fixtures/` ship in the tarball — `test/packaging.test.mjs` packs locally and
+refuses a corpus that did not make it into the artifact. Each fixture states its own rules in
+its `comment`, written so a second implementation can be coded from the file without reading the
+TypeScript. That is the only way this contract reaches the consumers that cannot import it:
+`iterate-harness` is Python and `glasspaned` is Swift.
+
+Those consumers do not read this package at runtime. They vendor a copy of the corpus pinned by
+sha256 — `iterate-harness/tests/kernel_fixtures/`, checked by its `scripts/check_kernel_fixtures.py`
+(`--source kernel/fixtures` inside the monorepo, registry mode in the split repo). Moving a fixture
+therefore means re-recording that pin in the same change, and the check fails in whichever
+direction the bytes disagree. A cross-implementation comparison that can be skipped silently is
+not a contract; it is a note nobody reads.
+
 ## Consumers
 
 Vendored or installed, a consumer's kernel is one of two things, and the difference is a

package/fixtures/decision-log-chain.ok-01.json

@@ -0,0 +1,13 @@
+{
+  "comment": "Cross-implementation anchor for the decision log chain (kernel/src/decision-log.ts). A line's bytes ARE canonicalJson(entry) — keys sorted by UTF-16 code unit, no insignificant whitespace — so prevEntryHash of line i+1 equals sha256_hex of line i, and genesis carries an empty prevEntryHash. Any language that can sort keys and sha256 can verify this file; the kernel test recomputes the hashes with an external tool (shasum/openssl), so a TypeScript-only chain cannot pass silently.",
+  "lines": [
+    "{\"createdAt\":\"2026-09-25T04:00:00.000Z\",\"entryId\":\"dl_01K2ABCDEFGHJKMNPQRSTVWXZ0\",\"outcome\":\"pass\",\"prevEntryHash\":\"\",\"sequence\":0,\"summary\":\"attach Finder; window matched the attached pid\"}",
+    "{\"createdAt\":\"2026-09-25T04:00:01.000Z\",\"entryId\":\"dl_01K2ABCDEFGHJKMNPQRSTVWXZ1\",\"operationId\":\"op_01K2ABCDEFGHJKMNPQRSTVWXZ9\",\"outcome\":\"fail\",\"prevEntryHash\":\"f7c3b4198c27ad0e5947efd2d50dedced3e02f0171411fbf6c67f07e22d13d4d\",\"sequence\":1,\"summary\":\"act set-value refused: element not focusable\"}",
+    "{\"createdAt\":\"2026-09-25T04:00:02.000Z\",\"entryId\":\"dl_01K2ABCDEFGHJKMNPQRSTVWXZ2\",\"outcome\":\"inconclusive\",\"prevEntryHash\":\"db250a8182952a7ceb4240bcfcc48f639d452514e6ee9e8401111a57127f69c3\",\"sequence\":2,\"summary\":\"observe timed out while the app was modal\"}"
+  ],
+  "hashes": [
+    "f7c3b4198c27ad0e5947efd2d50dedced3e02f0171411fbf6c67f07e22d13d4d",
+    "db250a8182952a7ceb4240bcfcc48f639d452514e6ee9e8401111a57127f69c3",
+    "7b89c488c39f680343eec27cee805092140a43ef50e15f25a81133c1f154076b"
+  ]
+}

package/fixtures/decision-log-entry.ok-01.json

@@ -0,0 +1,9 @@
+{
+  "entryId": "dl_0123456789ABCDEFGHJKMNPQRS",
+  "sequence": 0,
+  "prevEntryHash": "",
+  "operationId": "op_0123456789ABCDEFGHJKMNPQRS",
+  "summary": "act press on button 'Submit' (op_0123456789ABCDEFGHJKMNPQRS): actConfirmed=true, axChanged=true, assertion enabled=true passed",
+  "outcome": "pass",
+  "createdAt": "2026-09-14T12:34:56.789Z"
+}

package/fixtures/dimension-context.ok-01.json

@@ -0,0 +1,50 @@
+{
+  "comment": "Cross-implementation anchor for dimensionContext (kernel/src/dimension-context.ts). The rules a second implementation must reproduce, written so it can be coded from this file without reading the TypeScript: (1) planned entries keep the caller's order; status is `verified` iff recorded[id].decisions >= 1, else `unverified`, and an absent id is the same as a recorded zero — `{decisions: 0}`. (2) A recorded id absent from the plan becomes one `unplanned` entry, sorted by id ascending in UTF-16 code unit order. (3) totals.decisions sums planned and unplanned alike, each decision counted once; verified + unverified === planned always. (4) A duplicate planned id throws KERNEL_E_DIMENSION_DUPLICATE rather than collapsing. The ids here are the nine the iterate config owns (config/config.schema.json $defs.dimension.enum); the kernel validates their *shape* and never enumerates them, which is why this fixture may name them without the kernel knowing they exist.",
+  "input": {
+    "planned": [
+      { "id": "correctness", "label": "正确性", "focus": "Crash risks, logic errors, concurrency." },
+      { "id": "security" },
+      { "id": "performance" },
+      { "id": "architecture" },
+      { "id": "style-tests" },
+      { "id": "tech-debt" },
+      { "id": "spec-compliance" },
+      { "id": "frontend-backend" },
+      { "id": "ui-ux", "label": "UI/UX" }
+    ],
+    "recorded": {
+      "correctness": { "decisions": 6, "operationIds": ["op_01K2ABCDEFGHJKMNPQRSTVWXZ9"] },
+      "security": { "decisions": 3 },
+      "performance": { "decisions": 0 },
+      "architecture": { "decisions": 2 },
+      "style-tests": { "decisions": 1 },
+      "tech-debt": { "decisions": 1 },
+      "spec-compliance": { "decisions": 0 },
+      "frontend-backend": { "decisions": 4 },
+      "ui-ux": { "decisions": 1 },
+      "concurrency": { "decisions": 2 }
+    }
+  },
+  "expected": {
+    "planned": [
+      {
+        "id": "correctness",
+        "status": "verified",
+        "label": "正确性",
+        "focus": "Crash risks, logic errors, concurrency.",
+        "evidence": { "decisions": 6, "operationIds": ["op_01K2ABCDEFGHJKMNPQRSTVWXZ9"] }
+      },
+      { "id": "security", "status": "verified", "evidence": { "decisions": 3 } },
+      { "id": "performance", "status": "unverified", "evidence": { "decisions": 0 } },
+      { "id": "architecture", "status": "verified", "evidence": { "decisions": 2 } },
+      { "id": "style-tests", "status": "verified", "evidence": { "decisions": 1 } },
+      { "id": "tech-debt", "status": "verified", "evidence": { "decisions": 1 } },
+      { "id": "spec-compliance", "status": "unverified", "evidence": { "decisions": 0 } },
+      { "id": "frontend-backend", "status": "verified", "evidence": { "decisions": 4 } },
+      { "id": "ui-ux", "status": "verified", "label": "UI/UX", "evidence": { "decisions": 1 } }
+    ],
+    "unplanned": [{ "id": "concurrency", "status": "unplanned", "evidence": { "decisions": 2 } }],
+    "totals": { "planned": 9, "verified": 7, "unverified": 2, "unplanned": 1, "decisions": 20 }
+  },
+  "expectedLine": "7/9 dimensions verified, 2 unverified (performance, spec-compliance), 1 unplanned (concurrency), 20 decisions"
+}

package/fixtures/evidence-pack.ok-01.json

@@ -0,0 +1,69 @@
+{
+  "schemaVersion": "glasspane.evidence/0.1",
+  "operationId": "op_0123456789ABCDEFGHJKMNPQRS",
+  "createdAt": "2026-09-14T12:34:56.789Z",
+  "attribution": {
+    "level": "soft",
+    "contaminated": false
+  },
+  "circuitBreaker": {
+    "level": 0
+  },
+  "signals": {
+    "act": {
+      "selector": {
+        "role": "button",
+        "title": "Submit"
+      },
+      "action": "press",
+      "actConfirmed": true
+    },
+    "axEvent": {
+      "treeDigestBefore": "00112233445566778899aabbccddeeff",
+      "treeDigestAfter": "ffeeddccbbaa99887766554433221100",
+      "nodeCount": 128,
+      "axChanged": true,
+      "latencyMs": 42
+    },
+    "handlerProbe": null,
+    "stateDiff": null,
+    "pixelDiff": {
+      "changedPixelRatio": 0.023,
+      "bounds": {
+        "x": 100,
+        "y": 200,
+        "width": 80,
+        "height": 28
+      },
+      "windowId": 12
+    },
+    "responsiveness": {
+      "responsive": true,
+      "pingMs": 3
+    },
+    "crash": {
+      "processAliveBefore": true,
+      "processAliveAfter": true
+    }
+  },
+  "assertion": {
+    "kind": "element_property",
+    "selector": {
+      "role": "button",
+      "title": "Submit"
+    },
+    "property": "enabled",
+    "expected": true,
+    "actual": true,
+    "passed": true
+  },
+  "diagnosis": {
+    "class": "NO_ANOMALY",
+    "report": {
+      "path": "act.press -> ax-confirm -> tree-digest -> pixel-diff",
+      "anomaly": "none: operation confirmed, AX tree changed, pixels changed",
+      "evidence": "op_0123456789ABCDEFGHJKMNPQRS soft attribution; axChanged=true (digest 00112233445566778899aabbccddeeff -> ffeeddccbbaa99887766554433221100); changedPixelRatio=0.023; pingMs=3",
+      "next": "no action required; assertion passed"
+    }
+  }
+}

package/fixtures/evidence-pack.ok-02.json

@@ -0,0 +1,34 @@
+{
+  "schemaVersion": "glasspane.evidence/0.1",
+  "operationId": "op_112233445566778899AABBCCDD",
+  "createdAt": "2026-09-14T12:35:00.001Z",
+  "attribution": {
+    "level": "soft",
+    "contaminated": false
+  },
+  "circuitBreaker": {
+    "level": 1,
+    "reason": "screen-recording-denied"
+  },
+  "signals": {
+    "act": {
+      "selector": {
+        "role": "checkBox",
+        "identifier": "agree-checkbox"
+      },
+      "action": "confirm",
+      "actConfirmed": true
+    },
+    "axEvent": {
+      "treeDigestBefore": "00000000000000000000000000000001",
+      "treeDigestAfter": "00000000000000000000000000000002",
+      "nodeCount": 57,
+      "axChanged": true,
+      "latencyMs": 12.5
+    },
+    "handlerProbe": null,
+    "stateDiff": null
+  },
+  "assertion": null,
+  "diagnosis": null
+}

package/fixtures/evidence-pack.ok-03.json

@@ -0,0 +1,69 @@
+{
+  "schemaVersion": "glasspane.evidence/0.1",
+  "operationId": "op_0PAAAABBBBCCCCDDDDEEEEFFFF",
+  "createdAt": "2026-09-19T09:41:02.500Z",
+  "attribution": {
+    "level": "strong",
+    "contaminated": false
+  },
+  "circuitBreaker": {
+    "level": 0
+  },
+  "signals": {
+    "act": {
+      "selector": {
+        "role": "AXButton",
+        "title": "OK Press",
+        "identifier": "ok-press"
+      },
+      "action": "press",
+      "actConfirmed": true
+    },
+    "axEvent": {
+      "treeDigestBefore": "0f1e2d3c4b5a69788796a5b4c3d2e1f0",
+      "treeDigestAfter": "00112233445566778899aabbccddeeff",
+      "nodeCount": 24,
+      "axChanged": true,
+      "latencyMs": 21.4
+    },
+    "handlerProbe": {
+      "probeVersion": "gp-probe/0.1.0",
+      "hitCount": 3,
+      "handlers": [
+        { "file": "probe-demo/ProbeDemoApp.swift", "line": 64 },
+        { "file": "probe-demo/ProbeDemoApp.swift", "line": 65 }
+      ],
+      "lateCount": 0
+    },
+    "stateDiff": {
+      "source": "z3-kvc",
+      "changed": true,
+      "entries": [
+        { "key": "demo.count", "before": "0", "after": "1" }
+      ]
+    },
+    "pixelDiff": {
+      "changedPixelRatio": 0.014,
+      "bounds": { "x": 12, "y": 34, "width": 96, "height": 28 },
+      "windowId": 4210
+    },
+    "responsiveness": {
+      "responsive": true,
+      "pingMs": 2.1
+    },
+    "crash": {
+      "processAliveBefore": true,
+      "processAliveAfter": true
+    }
+  },
+  "assertion": null,
+  "diagnosis": {
+    "class": "NO_ANOMALY",
+    "report": {
+      "path": "act.press -> probe-window -> handler/state -> ax-digest -> pixel-diff",
+      "anomaly": "none: operation confirmed, AX tree changed and pixels changed",
+      "evidence": "op_0PAAAABBBBCCCCDDDDEEEEFFFF strong attribution; actConfirmed=true",
+      "next": "no action required; continue the recipe"
+    }
+  }
+}

package/fixtures/evidence-pack.ok-04-legacy-draft.json

@@ -0,0 +1,59 @@
+{
+  "schemaVersion": "glasspane.evidence/0.1-draft",
+  "operationId": "op_04DRAFTPACK000000000000000",
+  "createdAt": "2026-09-17T13:33:39.275Z",
+  "attribution": {
+    "level": "soft",
+    "contaminated": false
+  },
+  "circuitBreaker": {
+    "level": 0
+  },
+  "signals": {
+    "act": {
+      "selector": {
+        "role": "AXButton",
+        "title": "Submit"
+      },
+      "action": "press",
+      "actConfirmed": true
+    },
+    "axEvent": {
+      "treeDigestBefore": "f84988c2d9a2edf3972aa9a247279fce",
+      "treeDigestAfter": "0b7d3f1a5c8e2946d1a70c5e8b342f61",
+      "nodeCount": 4,
+      "axChanged": true,
+      "latencyMs": 18.7
+    },
+    "handlerProbe": null,
+    "stateDiff": null,
+    "pixelDiff": {
+      "changedPixelRatio": 0.018,
+      "bounds": {
+        "x": 512,
+        "y": 344,
+        "width": 168,
+        "height": 32
+      },
+      "windowId": 12
+    },
+    "responsiveness": {
+      "responsive": true,
+      "pingMs": 3
+    },
+    "crash": {
+      "processAliveBefore": true,
+      "processAliveAfter": true
+    }
+  },
+  "assertion": null,
+  "diagnosis": {
+    "class": "NO_ANOMALY",
+    "report": {
+      "path": "act.press -> ax-digest -> pixel-diff",
+      "anomaly": "none: operation confirmed, AX tree changed, pixels changed",
+      "evidence": "op_04DRAFTPACK000000000000000 soft attribution; axChanged=true; changedPixelRatio=0.018; pingMs=3",
+      "next": "no action required; continue the recipe"
+    }
+  }
+}

package/fixtures/evidence-pack.ok-05-pixelbounds-null.json

@@ -0,0 +1,53 @@
+{
+  "schemaVersion": "glasspane.evidence/0.1",
+  "operationId": "op_05AXTREEMAP000000000000000",
+  "createdAt": "2026-09-21T07:12:44.500Z",
+  "attribution": {
+    "level": "strong",
+    "contaminated": false
+  },
+  "circuitBreaker": {
+    "level": 0
+  },
+  "signals": {
+    "act": {
+      "selector": {
+        "role": "AXButton",
+        "title": "Toggle"
+      },
+      "action": "press",
+      "actConfirmed": true
+    },
+    "axEvent": {
+      "treeDigestBefore": "9f2c6a04d81b3e57c206af9d4b7e1358",
+      "treeDigestAfter": "9f2c6a04d81b3e57c206af9d4b7e1358",
+      "nodeCount": 6,
+      "axChanged": false,
+      "latencyMs": 2.4
+    },
+    "handlerProbe": null,
+    "stateDiff": null,
+    "pixelDiff": {
+      "changedPixelRatio": 0,
+      "windowId": 12
+    },
+    "responsiveness": {
+      "responsive": true,
+      "pingMs": 4
+    },
+    "crash": {
+      "processAliveBefore": true,
+      "processAliveAfter": true
+    }
+  },
+  "assertion": null,
+  "diagnosis": {
+    "class": "T2",
+    "report": {
+      "path": "act.press -> ax-digest -> pixel-diff",
+      "anomaly": "act confirmed but neither the AX tree nor the pixels changed",
+      "evidence": "op_05AXTREEMAP000000000000000 strong attribution; axChanged=false; changedPixelRatio=0",
+      "next": "verify the selector targets a live element; run observe before retrying"
+    }
+  }
+}

package/fixtures/recipe-config.ok-01.json

@@ -0,0 +1,37 @@
+{
+  "schemaVersion": "glasspane.recipe/0.1-draft",
+  "name": "smoke-check-submit",
+  "steps": [
+    {
+      "kind": "act",
+      "params": {
+        "selector": {
+          "role": "button",
+          "title": "Submit"
+        },
+        "action": "press"
+      }
+    },
+    {
+      "kind": "observe",
+      "params": {
+        "maxDepth": 4
+      }
+    },
+    {
+      "kind": "assert",
+      "params": {
+        "selector": {
+          "role": "button",
+          "title": "Submit"
+        },
+        "property": "enabled",
+        "expected": true
+      }
+    },
+    {
+      "kind": "diagnose",
+      "params": {}
+    }
+  ]
+}

package/fixtures/report.ok-01.html

@@ -0,0 +1,33 @@
+<div class="gp-evidence" id="op_0PAAAABBBBCCCCDDDDEEEEFFFF">
+<h1>op_0PAAAABBBBCCCCDDDDEEEEFFFF · NO_ANOMALY · normal</h1>
+<dl class="gp-summary">
+<dt>operationId</dt><dd>op_0PAAAABBBBCCCCDDDDEEEEFFFF</dd>
+<dt>createdAt</dt><dd>2026-09-19T09:41:02.500Z</dd>
+<dt>schemaVersion</dt><dd>glasspane.evidence/0.1</dd>
+<dt class="gp-line">·</dt><dd>attribution: strong | contaminated=false</dd>
+<dt class="gp-line">·</dt><dd>circuitBreaker: level 0 (normal)</dd>
+<dt class="gp-line">·</dt><dd>act press AXButton &quot;OK Press&quot; #ok-press: confirmed</dd>
+<dt class="gp-line">·</dt><dd>axEvent: changed=true nodes=24 latencyMs=1234.57</dd>
+<dt class="gp-line">·</dt><dd>handlerProbe: probeVersion=gp-probe/0.1.0 hitCount=3 late=1 handlers=[probe-demo/ProbeDemoApp.swift:64, probe-demo/ProbeDemoApp.swift:65]</dd>
+<dt class="gp-line">·</dt><dd>stateDiff: source=z3-kvc changed=true entries=[demo.count &quot;0&quot; -&gt; &quot;1&quot;, demo.label &quot;idle&quot; -&gt; &quot;pressed&quot;]</dd>
+<dt class="gp-line">·</dt><dd>pixelDiff: changedRatio=0.123457 windowId=4210 bounds=12,34,96,28</dd>
+<dt class="gp-line">·</dt><dd>responsiveness: responsive=true pingMs=2.1</dd>
+<dt class="gp-line">·</dt><dd>crash: aliveBefore=true aliveAfter=true</dd>
+</dl>
+<section class="gp-section">
+<h2>PATH</h2>
+<p>act.press -&gt; probe-window -&gt; handler/state -&gt; ax-digest -&gt; pixel-diff</p>
+</section>
+<section class="gp-section">
+<h2>ANOMALY</h2>
+<p>none: operation confirmed, AX tree changed and pixels changed</p>
+</section>
+<section class="gp-section">
+<h2>EVIDENCE</h2>
+<p>op_0PAAAABBBBCCCCDDDDEEEEFFFF strong attribution; actConfirmed=true</p>
+</section>
+<section class="gp-section">
+<h2>NEXT</h2>
+<p>no action required; continue the recipe</p>
+</section>
+</div>

package/fixtures/report.ok-01.md

@@ -0,0 +1,30 @@
+# op_0PAAAABBBBCCCCDDDDEEEEFFFF · NO_ANOMALY · normal
+
+**operationId**: op_0PAAAABBBBCCCCDDDDEEEEFFFF
+**createdAt**: 2026-09-19T09:41:02.500Z
+**schemaVersion**: glasspane.evidence/0.1
+* attribution: strong | contaminated=false
+* circuitBreaker: level 0 (normal)
+* act press AXButton "OK Press" #ok-press: confirmed
+* axEvent: changed=true nodes=24 latencyMs=1234.57
+* handlerProbe: probeVersion=gp-probe/0.1.0 hitCount=3 late=1 handlers=[probe-demo/ProbeDemoApp.swift:64, probe-demo/ProbeDemoApp.swift:65]
+* stateDiff: source=z3-kvc changed=true entries=[demo.count "0" -> "1", demo.label "idle" -> "pressed"]
+* pixelDiff: changedRatio=0.123457 windowId=4210 bounds=12,34,96,28
+* responsiveness: responsive=true pingMs=2.1
+* crash: aliveBefore=true aliveAfter=true
+
+## PATH
+
+act.press -> probe-window -> handler/state -> ax-digest -> pixel-diff
+
+## ANOMALY
+
+none: operation confirmed, AX tree changed and pixels changed
+
+## EVIDENCE
+
+op_0PAAAABBBBCCCCDDDDEEEEFFFF strong attribution; actConfirmed=true
+
+## NEXT
+
+no action required; continue the recipe

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iterate-kernel",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "private": false,
   "description": "iterate ecosystem shared kernel: schemas, the evidence->decision transcription, the decision-log audit chain and public validators. Verification reasoning stays in the engine; this layer transcribes.",
   "type": "module",
@@ -62,6 +62,7 @@
   "files": [
     "dist",
     "schemas",
+    "fixtures",
     "README.md"
   ],
   "scripts": {