Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .tours/03-debug-and-recovery.tour
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@
"line": 36,
"pattern": "Smoke render",
"title": "12 — Gate 3: CI actually renders",
"description": "npm ci, npm run check, then a real Remotion render of frames 0-30 asserted to produce a non-empty MP4. This is the only automated check that executes application code. It deliberately excludes the Playwright capture step, which needs a live app CI does not have."
"description": "npm ci, npm run check, then a real Remotion render of frames 0-30 asserted to produce a non-empty MP4. The render step imports the composition code; the appended bridge scenarios execute the local evidence protocol and proof checks committed output without writing. Neither verifies a fresh product workflow. The Playwright capture step still needs a live app CI does not have."
}
]
}
20 changes: 17 additions & 3 deletions HANDOFF.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,11 +70,25 @@ The accepted framing makes the selected control/result and both client labels re

The default `npm run render:example` still renders historical WT-NodeRoom inputs and retains a separate output-quality hold. LiveSync acceptance does not certify other examples, responsive browser behavior, physical devices, provider behavior or production. The earlier install reported 12 affected packages (2 low, 10 high). The normal installed-tree audit for the exact Remotion 4.0.479 lock reported zero on September 7, 2026. That is a dated dependency result, not a full security assessment. Full criterion and overall grades remain null.

Verify the packet and its selected current source bindings from the repository root:
Verify the retained packet from the repository root. Check its selected historical source bindings only against the matching retained source checkout:

```sh
python promotion/evidence/local-livesync-handoff-20260907/verify.py
python promotion/evidence/local-livesync-handoff-20260907/verify.py --source-root .
python promotion/evidence/local-livesync-handoff-20260907/verify.py --source-root "<matching-historical-checkout>"
```

The first command checks exact packet bytes. The optional source check accepts only each row's demonstrated Git checkout newline transformation; it does not rerun capture/render or certify the whole repository. The evidence index records raw versus minimized receipts and which historical artifacts remain operator-local.
The first command checks exact packet bytes. The optional source check compares its original selected snapshot, allowing only each row's demonstrated Git checkout newline transformation. Use the checkout matching those recorded bindings; later code or documentation changes do not re-certify that snapshot. It does not rerun capture/render or certify the whole repository. The evidence index records raw versus minimized receipts and which historical artifacts remain operator-local.

## Local evidence bridge

For a Change Story or deck, use the [NodeKit Present evidence bridge](docs/NODEKIT_PRESENT_EVIDENCE.md)
for its commands, actual baseline/new comparison and declared limits. It projects
selected historical media as `observed`, with `productWorkflowProof: not-certified`
and `releaseReady: false`. Receipt references and retained supporting-file byte
guards do not establish passing outcomes or capture provenance. This local protocol
adds no new capture, render, provider, production or visual-quality certification.
## Local presentation-file proof update (2026-10-08)

The no-key bridge's named proof is `CURRENT-GATES-RETAINED-EVIDENCE-OBSERVED-DRIFT-REJECTED-01`. Unchanged main passed 43 parses, 36 tour assertions, 34 prose citations and three render records. The candidate passed 45 parses (two protocol files added), the same 36/34/3 assertions and 20 local scenarios with no failures or skips. The preserved old 13-scenario suite had passed while labelling a schema-only receipt verified; the corrected scenario returns observed, including failed and unbound references. These are different suites, not a speed comparison.

The actual projection contains three observed historical assets and zero workflow receipt references, with not-certified/releaseReady false. Stale proof did not rewrite outputs; redirected directory/file outputs were rejected with foreign files unchanged; eight repeated rounds and two simultaneous disjoint fixture jobs passed. The [bridge update log](docs/NODEKIT_PRESENT_EVIDENCE.md) records the source/claim boundaries and preserved Windows launcher failure. No capture/render, provider, production, physical-device or pixel result was added by this work.
36 changes: 36 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -1468,3 +1468,39 @@ the whole pipeline: write a spec, capture, render, and embed the GIFs for you.
## License

[MIT](LICENSE) © Homen Shum

## NodeKit Present: local evidence bridge

A developer preparing a Change Story or deck can use checked-in media as supporting
material without claiming that the pictured workflow passed. The authored
`evidence/nodekit-present.manifest.json` selects three historical assets and their
declared provenance; it does not trigger a new capture or render.

Run from this reviewed checkout's root:

```sh
npm run evidence:check
npm run evidence:project
npm run proof
npm run check
```

`evidence:project` explicitly writes `proof/nodekit-present.evidence-index.json` and
`proof/featureclip-evidence.receipt.json`. `proof` recomputes those outputs without
writing and fails if they are missing or stale. `check` retains the existing syntax,
citation and render-byte checks, then runs the local bridge scenarios and proof.

Projected media stays `observed`; the receipt keeps
`productWorkflowProof: not-certified` and `releaseReady: false`. A tracked, matching
receipt reference is a declared link, counted as `workflowReceiptReferences`, not
a certificate of passing outcomes, target binding, freshness or judge quality.
Source-truth fields remain declared historical provenance. Active basis entries
guard retained supporting driver/state-file bytes; they do not establish capture-time
or current application behavior. Original changed README/NODE-LOOPS hashes remain
historical limitations rather than being rebound to today's documentation.

This is a trusted local, single-writer file workflow. Capture, rendering, provider
judging and production verification remain separate. Read the
[bridge contract, actual comparison results and limits](docs/NODEKIT_PRESENT_EVIDENCE.md)
before consuming its output; these commands do not grant new visual or readiness
grades.
114 changes: 114 additions & 0 deletions docs/NODEKIT_PRESENT_EVIDENCE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
# NodeKit Present evidence bridge

A developer preparing a deck can reuse a tracked screenshot or clip without
mistaking it for proof that the pictured workflow passed. This local bridge checks
the selected repository files and produces a content-addressed evidence index.
Matching receipt references remain references; every projected asset is observed.

## Commands and checked inputs

Run from the repository root with Node 20 or newer. These commands require no
dependency installation, browser, network or provider key:

```sh
npm run evidence:check
npm run evidence:project
npm run proof
npm run check
```

The authored input is `evidence/nodekit-present.manifest.json`. The verifier checks
its exact field shape, Git tracking, contained regular-file paths, unique IDs and
paths, declared GIF/PNG signatures, header dimensions, byte sizes and SHA-256
digests. It compares declared size before reading media bytes. Retained supporting
text hashes normalize newline differences. JSON contract hashes sort object keys.

Capture environment and representation are **declared metadata**. Matching bytes
do not independently validate those declarations, decode every image, establish
visual quality or prove capture-time/current application behavior. Synthetic test
PNG headers exercise the metadata protocol, not rendered pixels.

`evidence:project` explicitly writes two deterministic files:

- `proof/nodekit-present.evidence-index.json`, a `nodekit.evidence-index/v1` index;
- `proof/featureclip-evidence.receipt.json`, the checked inputs and claim boundary.

`proof` recomputes and compares both on-disk outputs without writing. Missing,
invalid or stale outputs fail with a nonzero exit. These outputs can be reviewed
before committing; their presence alone does not prove the verifier's code or CI.

The fixed output parent and existing output files reuse containment checks and
reject directory/file redirects before output read/write. Per-file atomic writes
do not make the two-file pair transactional. This is a trusted local single-writer
tool; it is not a filesystem sandbox and does not guarantee safety against a
concurrent adversary changing paths or against writers sharing an output pair.
Input-sized collections and local synchronous reads have no global hard caps.

## Status and receipt fields

All matching media project as `observed`. The manifest's
`sourceTruth.workflowVerification` names a declared reference kind;
`verificationReceipt` is its optional path/digest/schema-name pointer. The bridge
checks that pointer's tracked bytes and schema name, **not** its outcome, target
binding, freshness or judge quality. Schema-only, failed and unrelated references
therefore remain observed.

The receipt's former `checks.independentWorkflowReceipts` field is corrected to
`checks.workflowReceiptReferences`, with no alias. It counts resolved tracked
digest/schema-matched references, not passed workflows. The schema and output
always require `productWorkflowProof: "not-certified"` and `releaseReady: false`.
Generated illustrations retain their explicit unknown-capture boundary.

The selected initial three historical assets have zero receipt references.
Other repository examples have their own historical judge files; this bridge
does not certify them or assert that the whole repository has no receipts.

## Historical supporting files

The three original media bytes are retained. Active basis guards use only the
unchanged walkthrough scripts and Room OS state file. Original README/NODE-LOOPS
digests from PR #4 head `36dd7741e53a6cc66e4ea0eac48d8717fa60ee69` remain in
limitations and the preserved original manifest. They are not replaced by current
document digests. Supporting-file matches do not establish that an old capture
was made from today's app.

Consumers must retain the observed status, content-addressed location and summary
boundary. A presentation clip must not be relabelled as fresh browser proof,
passing workflow evidence or release certification.

## Update log and before/new proof

Named proof: `CURRENT-GATES-RETAINED-EVIDENCE-OBSERVED-DRIFT-REJECTED-01`.

The current source/citation/render-byte gate remains `node check.mjs`.
`npm run check` appends local evidence scenarios and read-only projection proof.
The existing Remotion wrapper, lock, dependency versions, CI render command,
captured media and source anchors are retained. NodeKit's finite proof command
now uses this local bridge; its preview/partial/migration-planned disclosures stay.

On 2026-10-08, unchanged main `b06ab1890b0a44634151e170a626d804c8098e9a` passed
43 JavaScript parses, 36 tour assertions, 34 prose citations and three render
records locally. The preserved PR module passed its 13 original scenarios while
actually reporting a schema-only browser receipt as verified. Only fixture
cleanup guards and an output diagnostic changed in that baseline harness; its
module and assertions remained unchanged.

The candidate's explicit projection and expanded check both exited zero:

| Evidence | Before | Candidate |
|---|---|---|
| Current source gate | 43 parses / 36 tours / 34 citations / 3 render records | 45 parses / same 36 / 34 / 3; two protocol files added |
| Local evidence scenarios | Original PR module: 13/13 passed, accepting the false promotion | 20/20 passed, no skips; 13 retained intents corrected plus seven scenarios |
| Schema-only receipt | Actual status verified | Actual status observed; failed and unbound references also observed |
| Output redirection | Source defect; before exploit not executed | Directory and file redirects rejected for project/proof; foreign files unchanged |
| Stale projection/receipt | No before CLI scenario | Exit 1 without rewriting either output |
| Repeated/disjoint handoffs | Not run before | Eight deterministic rounds; two simultaneous disjoint jobs passed |
| Selected media | Historical manifest declarations | Three actual byte/header metadata matches, three observed entries, zero receipt references |

The counts describe different scenario suites, not a matched performance score.
The first candidate npm launch failed before adapter work because the process-only
Windows ComSpec path used forward slashes. Its failure was preserved; the same
npm launcher succeeded with the native backslash path. No product source changed
to bypass that failure. Generated receipts remain not-certified/releaseReady false.
No new render, provider, production, physical-device or visual-quality result is
claimed. The existing normal CI render baseline is a separate historical result.
36 changes: 25 additions & 11 deletions docs/START_HERE.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,7 @@ command. `npm run` is the discovery surface: the list below *is* the API.
"studio": "node run-remotion.mjs studio src/index.js",
"render:example": "node run-remotion.mjs render src/index.js WT-NodeRoom out/example.mp4 --concurrency=2",
"clip": "node clip.mjs",
"check": "node check.mjs",
"check": "node check.mjs && npm run test:evidence && npm run proof",
"probe:opening": "node probe-opening-frame.mjs",
"probe:maxpath": "node probe-max-path.mjs"
```
Expand Down Expand Up @@ -166,8 +166,8 @@ logged, and the spec is retried in a brand-new page if `retries` was set. See St
**Why this exists**
A spec is plain data — `{ act: "click", sel: "btn:Approve" }`. Something has to turn
`"btn:Approve"` into a real element and reject anything it does not understand. This is
that boundary, and it is the closest thing this repository has to schema validation.
There is no Zod, no JSON Schema, no type checker: the validation is a throw.
that boundary, and it is the validation seam on this capture path.
This capture path uses no Zod, JSON Schema or type checker: invalid ops throw.

**Core code**
```js
Expand Down Expand Up @@ -403,23 +403,23 @@ stage**: every stage's output is a file, so nothing is lost by starting over.

## Step 9 — The tests that prove the flow

There is no unit-test suite and no `npm test`. Saying otherwise would be the easiest
lie in this document. There are three real gates, in ascending order of what they
prove:
Local evidence-bridge scenarios run with `npm run test:evidence`; there is no
`npm test` alias. Separate source validation, local protocol execution and
rendered-output checks by what each one proves:

**1. `npm run check` → `check.mjs`** — two halves, and it prints how much of each it
**1. `npm run check`** starts with `node check.mjs`; this source gate prints how much it
did, so it cannot silently shrink (the fifteen-file hand-kept list it replaced had
drifted to covering a third of the repository). On 2026-08-13 it said:

```
[check] parsed 36/36 JavaScript files; 36/36 tour steps and 34/34 prose citations name a line that matches
```

The first half runs `node --check` on every `.mjs`/`.js` file the package ships. Green
Its syntax pass runs `node --check` on every `.mjs`/`.js` file the package ships. Green
means every file is syntactically valid JavaScript and **nothing more**: `--check`
parses, it does not import, execute, or resolve a dependency.

The second half is the reason you can trust the numbers in this document. Every
Its citation pass checks the source references in this document. Every
`file:line` written here or in a `.tours/*.tour` step has to carry the text it expects
to find, and the gate opens the file and compares. Until 2026-08-13 it asserted only
that the number was within the file's length, which proves an anchor is *stable* and
Expand All @@ -428,6 +428,19 @@ all 36 tour steps still passed while every one of them pointed at the wrong symb
A citation written in a form the gate cannot read is reported as a problem rather
than skipped, because a citation that looks checked and is not is how this came back.

The same source gate also checks each committed `render.json` against its GIF,
named judge-run bytes and kept-run hash. These are byte bindings, not a new
judgment or a test that a depicted workflow passed.

After that unchanged gate, `npm run check` runs `npm run test:evidence`, then
`npm run proof`. The scenarios execute the local evidence protocol; proof
recomputes its two committed outputs without writing and rejects missing or
stale files. The bridge checks declared bytes and references while keeping
media `observed`, `productWorkflowProof: not-certified` and `releaseReady: false`.
A matching receipt reference does not certify its outcome or target binding;
a retained supporting-file basis guard does not prove capture provenance.
See [the scoped bridge contract and comparison](NODEKIT_PRESENT_EVIDENCE.md).

**2. `npm run probe:opening` → `probe-opening-frame.mjs`** — the only committed gate
that *runs the renderers and fails on a property of the rendered output*. It renders
frame 0 and frame 4 of one composition per renderer, decodes both PNGs through ffmpeg,
Expand All @@ -447,8 +460,9 @@ back.

**3. `.github/workflows/ci.yml`** — on every push and pull request: `npm ci`,
`npm run check`, then a real Remotion render of frames 0–30 of `WT-NodeRoom`, and it
asserts the MP4 exists and is non-empty. This is the only automated check that
executes application code. It deliberately excludes the Playwright capture step, which
asserts the MP4 exists and is non-empty. This step imports and renders the
composition code; the appended bridge scenarios execute the local protocol.
It deliberately excludes the Playwright capture step, which
needs a live app that CI does not have.

**What none of them prove:** that a capture against a real application produces correct
Expand Down
Loading
Loading