@hassangameryt/freeflow 0.2.0 → 0.3.0

package/evals/reports/runtime/quickjs-script-derive-execution-1-report.md

@@ -0,0 +1,159 @@
+# QuickJS Script Derive Execution Report 1
+
+> **Date:** 2026-06-24
+> **Status:** Passed QuickJS-only execution smoke
+> **Scope:** Partial Slice 17 execution engine. JavaScript can execute only through an explicitly registered/provided QuickJS adapter; script derive remains disabled by default.
+
+## What Changed
+
+- Added dependency-free QuickJS adapter support in router core.
+- Adapter loading is explicit. The Pi adapter discovers QuickJS only when `FREEFLOW_QUICKJS_WASI_ROOT` points to an installed `quickjs-wasi` package root.
+- No `package.json` dependency was added.
+- No runtime artifact is downloaded by Freeflow.
+- Python remains unavailable.
+- jq remains proof-backed but not product-enabled in this slice.
+
+## Execution Boundary
+
+QuickJS exposes only these host APIs to guest JavaScript:
+
+- `readText(alias)` — reads copied vault-source input by alias.
+- `writeText(text)` — writes to captured stdout.
+- `console.log(...)` — writes bounded stdout.
+- `console.error(...)` — writes bounded stderr.
+
+The adapter does not expose `process`, `require`, host filesystem APIs, `fetch`, package loading, repo paths, vault paths, or home paths.
+
+## Verification Evidence
+
+### Product-path smoke
+
+A local smoke used the temp-installed package root:
+
+```text
+/tmp/freeflow-sandbox-candidates-xVAJBl/node_modules/quickjs-wasi
+```
+
+It executed `freeflowDerive` with:
+
+- `scriptDerive.enabled=true`,
+- `languages=["javascript"]`,
+- `network="off"`,
+- one vault source alias `log`,
+- a JavaScript script that filtered source lines containing `ERROR`.
+
+Result excerpt:
+
+```json
+{
+  "toolStatus": "ok",
+  "outputId": "ffout_1b9511127021d96d579578b7",
+  "summary": "Script derive javascript completed with 10 stdout bytes and 0 stderr bytes.",
+  "operation": {
+    "kind": "script",
+    "language": "javascript",
+    "codeSha256": "sha256_c5834b4ad4d0974718d47258aa6bf8fc633d08c45433f65a936b15986076226b"
+  }
+}
+DERIVED="ERROR beta"
+```
+
+Raw script text was not persisted in the routed result; the operation records only `codeSha256`.
+
+### Output cap regression smoke
+
+A real QuickJS product-path smoke used a configured adapter proof cap of `4096` bytes and a per-call `limits.maxOutputBytes=10` with:
+
+```js
+writeText('x'.repeat(100));
+```
+
+Result excerpt:
+
+```json
+{
+  "toolStatus": "ok",
+  "failure": {
+    "kind": "derive_execution_failure",
+    "message": "Script derive javascript failed. QuickJS execution exceeded maxOutputBytes. stdoutBytes=10 stderrBytes=0."
+  },
+  "deriveExecution": {
+    "status": "failed",
+    "failureKind": "derive_execution_failure"
+  },
+  "persistence": {
+    "status": "not_persisted",
+    "recoverability": "none"
+  }
+}
+```
+
+This confirms truncated output is not persisted as a successful exact result.
+
+### Pi status smoke
+
+With `FREEFLOW_QUICKJS_WASI_ROOT=/tmp/freeflow-sandbox-candidates-xVAJBl/node_modules/quickjs-wasi`, `buildFreeflowStatusReport` reports:
+
+```json
+{
+  "enabled": false,
+  "adapterAvailable": true,
+  "adapterStatus": "available",
+  "availableLanguages": ["javascript"],
+  "registeredAdapters": [{ "id": "quickjs-wasi", "version": "3.0.1", "languages": ["javascript"] }],
+  "executionStatus": "disabled"
+}
+```
+
+This proves explicit adapter discovery does not enable script execution while `scriptDerive.enabled` remains false.
+
+### Targeted tests
+
+```text
+npm run build:router && node --test router/tests/derive.test.js router/tests/script-sandbox.test.js
+```
+
+Result:
+
+```text
+29 targeted tests passed
+```
+
+Coverage added:
+
+- script derive remains disabled by default,
+- source resolution still returns adapter unavailable without a registered adapter,
+- a proof-backed registered adapter can execute and persist exact derived stdout,
+- adapter timeout/failure returns structured `derive_execution_failure`,
+- output-limit failures return structured `derive_execution_failure` without exact recovery,
+- proof fixture coverage remains complete,
+- invalid `FREEFLOW_QUICKJS_WASI_ROOT` fails closed as adapter unavailable.
+
+### Full router suite
+
+```text
+npm run test:router
+```
+
+Result:
+
+```text
+273 tests passed
+```
+
+## Current Availability
+
+| Language | Status |
+| --- | --- |
+| JavaScript | Product execution path implemented for explicitly registered/provided QuickJS adapter roots; disabled by default. |
+| Python | Unavailable. Eryx candidate blocked before proofs. |
+| jq | Proof-backed candidate only; not product-enabled in this slice. |
+
+## Remaining Gates
+
+Before public docs can present script derive as generally available:
+
+1. Add durable setup/config UX for optional adapter installation if desired.
+2. Run full router suite and focused review for this implementation slice.
+3. Decide whether to product-enable jq after separate security review of the Worker-boundary large-output caveat.
+4. Find or fix a Python WASM candidate.

package/evals/reports/runtime/quickjs-wasi-proof-spike-1-report.md

@@ -0,0 +1,55 @@
+# QuickJS WASI Sandbox Proof Spike Report
+
+> **Date:** 2026-06-24
+> **Status:** Passed proof spike for JavaScript candidate
+> **Scope:** Proof-only evaluation. No Freeflow script execution path is enabled.
+
+## Candidate
+
+- Package: `quickjs-wasi@3.0.1`
+- License: MIT
+- Package root: `/tmp/freeflow-sandbox-candidates-xVAJBl/node_modules/quickjs-wasi`
+- WASM bytes: 1587119
+- WASM SHA-256: `66629761271fe05c63622c15c7169e2d386985db43cb3917fca4bd43caffdc84`
+- Timeout: 250ms
+- Memory limit: 8388608 bytes
+- Output cap: 4096 bytes
+
+## Positive API Probe
+
+- Status: success
+- Output: `INFO setup\nERROR target\n`
+- Error: none
+
+## Required Proof Results
+
+| Proof | Result | Evidence |
+| --- | --- | --- |
+| env_access_denied | pass | ambient environment was not exposed; status=success; durationMs=2; outputBytes=0; stdoutBytes=0; stderrBytes=0; truncated=false |
+| home_access_denied | pass | home/secret paths were not exposed; status=success; durationMs=1; outputBytes=14; stdoutBytes=14; stderrBytes=0; truncated=false |
+| repo_access_denied | pass | repo files were not exposed; status=success; durationMs=3; outputBytes=14; stdoutBytes=14; stderrBytes=0; truncated=false |
+| vault_access_denied | pass | vault records were not exposed; status=success; durationMs=2; outputBytes=14; stdoutBytes=14; stderrBytes=0; truncated=false |
+| network_access_denied | pass | network/fetch capability was absent; status=success; durationMs=2; outputBytes=17; stdoutBytes=17; stderrBytes=0; truncated=false |
+| input_read_only | pass | input mutation was not possible through host filesystem APIs; status=success; durationMs=1; outputBytes=14; stdoutBytes=14; stderrBytes=0; truncated=false |
+| output_escape_denied | pass | output symlink/file escape was not possible through host filesystem APIs; status=success; durationMs=2; outputBytes=14; stdoutBytes=14; stderrBytes=0; truncated=false |
+| stdout_stderr_bounded | pass | stdout and stderr flood capture was truncated within the cap; status=timed_out; durationMs=253; outputBytes=4096; stdoutBytes=2076; stderrBytes=2020; truncated=true; error=interrupted |
+| timeout_enforced | pass | infinite loop was interrupted by runtime timeout; status=timed_out; durationMs=251; outputBytes=0; stdoutBytes=0; stderrBytes=0; truncated=false; error=interrupted |
+
+## Notes
+
+- This proof runner uses a temporary installed `quickjs-wasi` package root passed explicitly by the caller.
+- It does not add repo dependencies and does not wire the adapter into `freeflow_derive` execution.
+- Passing this spike only supports JavaScript adapter feasibility; Python and jq remain unavailable until their own proof slices pass.
+- Before product execution, this must still go through implementation/security review and source-plan update.
+
+## Required Proof Set
+
+- env_access_denied
+- home_access_denied
+- repo_access_denied
+- vault_access_denied
+- network_access_denied
+- input_read_only
+- output_escape_denied
+- stdout_stderr_bounded
+- timeout_enforced

package/evals/reports/runtime/render-format-row-protocol-1-report.md

@@ -0,0 +1,58 @@
+# Render Format Row Protocol Benchmark 1
+
+Date: 2026-06-27
+
+Purpose: decide whether Pi model-visible Freeflow output should move from compact prose to a deterministic row protocol before continuing later runtime slices.
+
+Committed regression benchmark: `router/tests/benchmarks/render-format-benchmark.test.js` gates bytes, visible fact preservation, per-sample validity, row shape, and visible recovery rows for future renderer changes.
+
+Scope:
+
+- `freeflow_run`
+- `freeflow_retrieve`
+- `freeflow_derive`
+- `freeflow_batch`
+
+Gate:
+
+- Use bytes, not tokenizer-specific counts.
+- A candidate renderer is valid only when every sample preserves at least the current visible fact coverage.
+- `details.result` JSON remains unchanged.
+- TUI rendering remains human-readable.
+
+Best valid candidate selected: `line:shortHeader`.
+
+| renderer | bytes | visible facts | valid samples | byte change |
+| --- | ---: | ---: | ---: | ---: |
+| current compact prose | 14,049 | 41/50 | 14/14 | baseline |
+| line:noRecovery | 8,331 | 41/50 | 14/14 | 40.70% saved |
+| line:shortHeader | 10,600 | 41/50 | 14/14 | 24.55% saved |
+| jsonMin | 67,456 | 50/50 | 14/14 | 380.15% larger |
+
+Decision:
+
+Use a readable row protocol with short recovery rows, not `noRecovery`, because Freeflow should keep recovery visible while reducing model-visible bytes.
+
+Selected row shape examples:
+
+```text
+freeflow_run|success|exit=0|route=routed|parser=test-output|raw=ffout_...
+s|test-output summary...
+p|stdout:1-4
+>|tests: 4 failed, 108 passed, (112)
+rec|vault|ffout_...|stdout|1-4
+details|details.result
+```
+
+```text
+freeflow_batch|routed|steps=3|ok=3|failed=0|c=3
+q|answered|failed test files and counts|...
+step|1|tests|run|ok|...
+details|details.result steps+queries
+```
+
+Notes:
+
+- TSV was also viable, but line protocol was chosen for readability and easier visual inspection.
+- Minified JSON preserves the most facts but is much larger, confirming JSON is unsuitable for model-visible output.
+- The `line:noRecovery` variant saved more bytes, but was rejected because recovery visibility is part of Freeflow's product value.

package/evals/reports/runtime/script-sandbox-adapter-selection-review-1-report.md

@@ -0,0 +1,84 @@
+# Script Sandbox Adapter Selection Review 1
+
+> **Date:** 2026-06-24
+> **Status:** Conditional pass for adapter-family selection; execution remains blocked
+> **Scope:** Artifact/security gate after JavaScript, Python, and jq sandbox proof spikes. No Freeflow script execution path is enabled.
+
+## Decision Summary
+
+Select the optional pinned **WASM/WASI adapter family** as the current script-sandbox direction.
+
+Proof-backed partial candidates:
+
+| Language | Candidate | Gate result | Current availability decision |
+| --- | --- | --- | --- |
+| JavaScript | `quickjs-wasi@3.0.1` | Required proof fixtures passed 9/9. | Candidate can proceed to adapter implementation planning after owner approval for optional package addition. |
+| jq | `jq-wasm@1.2.0-jq-1.8.2` | Required proof fixtures passed 9/9 using Worker termination and bounded Worker-to-host output. | Candidate can proceed to adapter implementation planning after owner approval for optional package addition and security review of the in-Worker large-output caveat. |
+| Python | `@bsull/eryx@0.5.0` | Blocked before Python execution by package/transitive compatibility. Proofs not run. | Unavailable. Do not add dependency until a compatible Eryx set or alternate Python WASM candidate passes proofs. |
+
+This is not approval to wire execution into `freeflow_derive`. Slice 17 remains blocked until the owner explicitly approves the runtime package additions and the implementation/security review accepts the adapter boundaries.
+
+## Source Evidence
+
+- JavaScript proof report: `evals/reports/runtime/quickjs-wasi-proof-spike-1-report.md`
+  - `quickjs-wasi@3.0.1`
+  - proofs passed 9/9
+  - no repo dependency added
+  - no script execution path enabled
+- Python proof report: `evals/reports/runtime/eryx-python-proof-spike-1-report.md`
+  - `@bsull/eryx@0.5.0`
+  - failed before Python execution because `@bytecodealliance/preview2-shim/filesystem` did not export `_setFileData`
+  - proofs not run
+- jq proof report: `evals/reports/runtime/jq-wasm-proof-spike-1-report.md`
+  - `jq-wasm@1.2.0-jq-1.8.2`
+  - proofs passed 9/9
+  - timeout proof uses Worker termination
+  - output proof caps stdout/stderr before Worker result crosses to host
+  - residual caveat: jq can generate large in-Worker strings before wrapper truncation
+
+## Security Review Notes
+
+### Accepted Direction
+
+- Keep the public surface as `freeflow_derive operation.kind="script"` only.
+- Keep script derive disabled by default.
+- Keep no unsandboxed fallback.
+- Keep runtime packages optional and pinned; Freeflow core should not add heavyweight runtime dependencies silently.
+- Keep JavaScript, Python, and jq as the target language set. JavaScript and jq can become partial availability states, not a narrowed product direction.
+
+### Required Before Execution Implementation
+
+Before Slice 17 can enable any real adapter execution, the owner must decide:
+
+1. Whether to add optional pinned adapter package support for `quickjs-wasi`.
+2. Whether to add optional pinned adapter package support for `jq-wasm`.
+3. Whether `jq-wasm`'s Worker boundary is acceptable even though jq can allocate large strings inside the Worker before wrapper truncation.
+4. Whether Slice 17 should implement JavaScript first, jq first, or JavaScript and jq in one execution slice.
+
+### Must Remain Blocked
+
+- Python script derive remains unavailable.
+- `@bsull/eryx` must not be added as a dependency yet.
+- No script code may execute through Freeflow until an approved adapter implementation passes the proof-backed availability checks inside product code.
+- No runtime artifacts may be downloaded during script execution.
+- Raw script text must not be persisted.
+
+## Recommended Slice 17 Entry
+
+If the owner approves dependency/security decisions, execute Slice 17 as a narrow partial-availability implementation:
+
+1. Add optional adapter discovery for approved package roots or installed optional dependencies.
+2. Register only proof-backed languages.
+3. Keep unsupported languages returning structured unavailable.
+4. Preserve current disabled-by-default behavior.
+5. Implement one adapter at a time unless the owner explicitly approves bundling JavaScript and jq.
+6. Re-run adversarial proofs against the actual product adapter, not only the proof runner.
+7. Keep exact recovery false for truncated script output.
+
+## Current Gate State
+
+- Adapter family selected: WASM/WASI with optional pinned adapters.
+- JavaScript: proof-backed candidate, not product-enabled.
+- jq: proof-backed candidate with security caveat, not product-enabled.
+- Python: unavailable.
+- Slice 17: still blocked pending explicit owner dependency/security approval.

package/evals/reports/runtime/script-sandbox-probe-resource-hardening-1-report.md

@@ -0,0 +1,51 @@
+# Script Sandbox Probe Resource Hardening Report 1
+
+> **Date:** 2026-06-24
+> **Status:** Passed targeted verification
+> **Scope:** Follow-up hardening after QuickJS and jq script-derive execution slices.
+
+## Trigger
+
+During implementation and proof smokes, repeated full router suites plus sandbox proof runs caused high local CPU load. The jq adapter caveat also exposed a related risk: output is capped before crossing the Worker boundary, but jq can still allocate inside the Worker before wrapper truncation.
+
+## Root Cause / Risk
+
+Two resource costs were unnecessarily high:
+
+1. The shared `stdout_stderr_bounded` proof fixtures used runaway loop counts (`1000000` for JavaScript/Python and `100000` for jq). The adapters stop or truncate, but the fixture text encouraged far more output generation than needed to prove cap enforcement.
+2. Adapter proof probes could rerun repeatedly in the same Pi process. `freeflow_status` and script adapter selection both need proof-backed availability, but repeating adversarial proofs for the same adapter binary/hash and probe limits wastes CPU.
+
+## Changes
+
+- Reduced `stdout_stderr_bounded` proof fixture loops to `1000` iterations for JavaScript, Python, and jq.
+  - This still exceeds normal proof output caps.
+  - It avoids multi-megabyte raw jq stdout/stderr generation during proof runs.
+- Lowered jq probe timeout from `500ms` to `250ms`.
+  - Product execution still uses configured/per-call script limits.
+  - The proof only needs to show the adapter can terminate runaway jq execution.
+- Added per-process proof-result caches:
+  - QuickJS cache key: package version, WASM hash, probe timeout, probe output cap, network mode.
+  - jq cache key: package version, entrypoint hash, probe timeout, probe output cap, network mode.
+- Added a regression test that rejects future `stdout_stderr_bounded` fixtures containing five-or-more-digit loop counts.
+- Fixed a flaky Pi status test that assumed the default user vault index was empty. The default vault is user-global, so tests now assert the index shape rather than `entryCount === 0`.
+
+## Preserved Safety Properties
+
+- Script derive remains disabled by default.
+- No unsandboxed fallback was added.
+- Adapter availability still requires every required proof to pass.
+- Caches are keyed by adapter content hash and probe limits, not just package root strings.
+- Output-limit failures remain structured failures with no exact recovery.
+- Python remains unavailable.
+
+## Verification
+
+Targeted check passed:
+
+```text
+npm run build && node --test router/tests/script-sandbox.test.js router/tests/derive.test.js router/tests/pi-extension.test.js
+```
+
+Result: 62/62 targeted tests passed.
+
+Additional note: the earlier temporary optional adapter package roots under `/tmp/freeflow-sandbox-candidates-xVAJBl` had been cleaned up before this follow-up, so this report does not claim a fresh real QuickJS/jq package-root smoke after hardening. The product execution smokes from the immediately preceding QuickJS and jq reports remain the adapter proof/execution evidence; this slice reduces repeat probe cost and guards against runaway fixture sizes.

package/evals/reports/runtime/storage-policy-benchmark-1-report.md

@@ -0,0 +1,176 @@
+# Storage Policy Benchmark Report - Iteration 1
+
+Date: 2026-06-28
+
+## Scope
+
+Benchmark-only experiment for Freeflow vault storage policies. This report does not change runtime defaults or repo config. It compares exact storage, threshold storage, hybrid metadata/exact storage, and duplicate-output dedupe using deterministic command-output fixtures.
+
+## Summary
+
+- Fixtures: 9
+- Policies: 5
+- Safe candidates for further evaluation: store-everything, metadata-small-exact-large-hybrid, duplicate-output-dedupe, hybrid-dedupe
+- Disqualified by exact-recovery safety: threshold-exact
+- Runtime default changed: no
+
+## Policy Results
+
+| Policy | Exact-sensitive recovery | Storage bytes | Index bytes | Exact stored bytes | Storage reduction | Token-surface reduction | Privacy surface | Metadata-only | Duplicate metadata | Latency p50/p95 | Notes |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | --- |
+| Store everything exactly | 8/8 | 490785 | 185735 | 121022 | 0.00% | 0.00% | 100.00% | 0 | 0 | 1.58/2.76 |  |
+| Threshold exact storage | 0/8 | 466984 | 185391 | 120120 | 0.75% | 0.75% | 99.25% | 14 | 0 | 1.21/1.78 | disqualified: exactness-sensitive failure/verification output would lose exact recovery threshold-only policy is unsafe without an exactness-sensitive override |
+| Metadata-small / exact-large hybrid | 8/8 | 483256 | 186749 | 120884 | 0.11% | 0.12% | 99.89% | 6 | 0 | 1.32/1.74 | hybrid preserved exact recovery for sensitive fixtures while reducing exact raw storage |
+| Duplicate output dedupe | 8/8 | 172791 | 66691 | 30335 | 74.93% | 74.93% | 25.07% | 12 | 12 | 1.04/1.43 | duplicates kept metadata pointers to prior exact output |
+| Hybrid exactness + duplicate dedupe | 8/8 | 168371 | 66134 | 30299 | 74.96% | 74.96% | 25.04% | 14 | 8 | 1.02/1.35 | hybrid+dedupe preserved exact-sensitive recovery while metadata-only small output and duplicate pointers reduced exact raw storage |
+
+## Candidate Notes
+
+### Store everything exactly
+
+Current baseline: every command output is vaulted exactly, so recovery is maximally useful and storage/privacy surface is largest.
+
+- Exactness-sensitive recovery: pass
+- Metadata-only recovery labeled: yes
+- Repeated outputs deduped: no
+
+| Fixture | Iteration | Record | Recovery | Exact bytes | Notes |
+| --- | ---: | --- | --- | ---: | --- |
+| small-success | 1 | command/exact | exact | 3 | exact combined recovery passed |
+| small-failure | 1 | command/exact | exact | 104 | exact combined recovery passed |
+| verification-output | 1 | command/exact | exact | 52 | exact combined recovery passed |
+| large-log | 1 | command/exact | exact | 30030 | exact combined recovery passed |
+| large-log-repeat | 1 | command/exact | exact | 30030 | exact combined recovery passed |
+| repeated-failure-a | 1 | command/exact | exact | 113 | exact combined recovery passed |
+| repeated-failure-b | 1 | command/exact | exact | 113 | exact combined recovery passed |
+| repeat-a | 1 | command/exact | exact | 33 | exact combined recovery passed |
+| repeat-b | 1 | command/exact | exact | 33 | exact combined recovery passed |
+| small-success | 2 | command/exact | exact | 3 | exact combined recovery passed |
+| small-failure | 2 | command/exact | exact | 104 | exact combined recovery passed |
+| verification-output | 2 | command/exact | exact | 52 | exact combined recovery passed |
+| large-log | 2 | command/exact | exact | 30030 | exact combined recovery passed |
+| large-log-repeat | 2 | command/exact | exact | 30030 | exact combined recovery passed |
+| repeated-failure-a | 2 | command/exact | exact | 113 | exact combined recovery passed |
+| repeated-failure-b | 2 | command/exact | exact | 113 | exact combined recovery passed |
+| repeat-a | 2 | command/exact | exact | 33 | exact combined recovery passed |
+| repeat-b | 2 | command/exact | exact | 33 | exact combined recovery passed |
+
+### Threshold exact storage
+
+Exact storage only when combined output is at least 8192 bytes; smaller outputs are metadata-only. This intentionally tests whether a threshold alone would drop exact failure/verification recovery.
+
+- Exactness-sensitive recovery: fail
+- Metadata-only recovery labeled: yes
+- Repeated outputs deduped: no
+
+| Fixture | Iteration | Record | Recovery | Exact bytes | Notes |
+| --- | ---: | --- | --- | ---: | --- |
+| small-success | 1 | metadata/metadata_only | metadata-only | 0 | metadata-only record intentionally has no raw exact recovery |
+| small-failure | 1 | metadata/metadata_only | metadata-only | 0 | metadata-only record intentionally has no raw exact recovery |
+| verification-output | 1 | metadata/metadata_only | metadata-only | 0 | metadata-only record intentionally has no raw exact recovery |
+| large-log | 1 | command/exact | exact | 30030 | exact combined recovery passed |
+| large-log-repeat | 1 | command/exact | exact | 30030 | exact combined recovery passed |
+| repeated-failure-a | 1 | metadata/metadata_only | metadata-only | 0 | metadata-only record intentionally has no raw exact recovery |
+| repeated-failure-b | 1 | metadata/metadata_only | metadata-only | 0 | metadata-only record intentionally has no raw exact recovery |
+| repeat-a | 1 | metadata/metadata_only | metadata-only | 0 | metadata-only record intentionally has no raw exact recovery |
+| repeat-b | 1 | metadata/metadata_only | metadata-only | 0 | metadata-only record intentionally has no raw exact recovery |
+| small-success | 2 | metadata/metadata_only | metadata-only | 0 | metadata-only record intentionally has no raw exact recovery |
+| small-failure | 2 | metadata/metadata_only | metadata-only | 0 | metadata-only record intentionally has no raw exact recovery |
+| verification-output | 2 | metadata/metadata_only | metadata-only | 0 | metadata-only record intentionally has no raw exact recovery |
+| large-log | 2 | command/exact | exact | 30030 | exact combined recovery passed |
+| large-log-repeat | 2 | command/exact | exact | 30030 | exact combined recovery passed |
+| repeated-failure-a | 2 | metadata/metadata_only | metadata-only | 0 | metadata-only record intentionally has no raw exact recovery |
+| repeated-failure-b | 2 | metadata/metadata_only | metadata-only | 0 | metadata-only record intentionally has no raw exact recovery |
+| repeat-a | 2 | metadata/metadata_only | metadata-only | 0 | metadata-only record intentionally has no raw exact recovery |
+| repeat-b | 2 | metadata/metadata_only | metadata-only | 0 | metadata-only record intentionally has no raw exact recovery |
+
+### Metadata-small / exact-large hybrid
+
+Small non-sensitive outputs become metadata-only; exactness-sensitive or >= 8192 byte outputs remain exactly recoverable.
+
+- Exactness-sensitive recovery: pass
+- Metadata-only recovery labeled: yes
+- Repeated outputs deduped: no
+
+| Fixture | Iteration | Record | Recovery | Exact bytes | Notes |
+| --- | ---: | --- | --- | ---: | --- |
+| small-success | 1 | metadata/metadata_only | metadata-only | 0 | metadata-only record intentionally has no raw exact recovery |
+| small-failure | 1 | command/exact | exact | 104 | exact combined recovery passed |
+| verification-output | 1 | command/exact | exact | 52 | exact combined recovery passed |
+| large-log | 1 | command/exact | exact | 30030 | exact combined recovery passed |
+| large-log-repeat | 1 | command/exact | exact | 30030 | exact combined recovery passed |
+| repeated-failure-a | 1 | command/exact | exact | 113 | exact combined recovery passed |
+| repeated-failure-b | 1 | command/exact | exact | 113 | exact combined recovery passed |
+| repeat-a | 1 | metadata/metadata_only | metadata-only | 0 | metadata-only record intentionally has no raw exact recovery |
+| repeat-b | 1 | metadata/metadata_only | metadata-only | 0 | metadata-only record intentionally has no raw exact recovery |
+| small-success | 2 | metadata/metadata_only | metadata-only | 0 | metadata-only record intentionally has no raw exact recovery |
+| small-failure | 2 | command/exact | exact | 104 | exact combined recovery passed |
+| verification-output | 2 | command/exact | exact | 52 | exact combined recovery passed |
+| large-log | 2 | command/exact | exact | 30030 | exact combined recovery passed |
+| large-log-repeat | 2 | command/exact | exact | 30030 | exact combined recovery passed |
+| repeated-failure-a | 2 | command/exact | exact | 113 | exact combined recovery passed |
+| repeated-failure-b | 2 | command/exact | exact | 113 | exact combined recovery passed |
+| repeat-a | 2 | metadata/metadata_only | metadata-only | 0 | metadata-only record intentionally has no raw exact recovery |
+| repeat-b | 2 | metadata/metadata_only | metadata-only | 0 | metadata-only record intentionally has no raw exact recovery |
+
+### Duplicate output dedupe
+
+First occurrence is stored exactly; exact duplicates become metadata-only records that point at the prior exact output.
+
+- Exactness-sensitive recovery: pass
+- Metadata-only recovery labeled: yes
+- Repeated outputs deduped: yes
+
+| Fixture | Iteration | Record | Recovery | Exact bytes | Notes |
+| --- | ---: | --- | --- | ---: | --- |
+| small-success | 1 | command/exact | exact | 3 | exact combined recovery passed |
+| small-failure | 1 | command/exact | exact | 104 | exact combined recovery passed |
+| verification-output | 1 | command/exact | exact | 52 | exact combined recovery passed |
+| large-log | 1 | command/exact | exact | 30030 | exact combined recovery passed |
+| large-log-repeat | 1 | metadata/metadata_only | duplicate-ref | 0 | metadata duplicate points to exact outputId=ffout_a7c4a56fb1bc488dc03fa0ef |
+| repeated-failure-a | 1 | command/exact | exact | 113 | exact combined recovery passed |
+| repeated-failure-b | 1 | metadata/metadata_only | duplicate-ref | 0 | metadata duplicate points to exact outputId=ffout_8e9758900243b59ade59cc2b |
+| repeat-a | 1 | command/exact | exact | 33 | exact combined recovery passed |
+| repeat-b | 1 | metadata/metadata_only | duplicate-ref | 0 | metadata duplicate points to exact outputId=ffout_a29dfa4bd5a569d730e6cee3 |
+| small-success | 2 | metadata/metadata_only | duplicate-ref | 0 | metadata duplicate points to exact outputId=ffout_4e210a9b34da56ca40514bd6 |
+| small-failure | 2 | metadata/metadata_only | duplicate-ref | 0 | metadata duplicate points to exact outputId=ffout_a4991d68dddc508bd8043e65 |
+| verification-output | 2 | metadata/metadata_only | duplicate-ref | 0 | metadata duplicate points to exact outputId=ffout_57eddf9b12365d59cb7ba3ce |
+| large-log | 2 | metadata/metadata_only | duplicate-ref | 0 | metadata duplicate points to exact outputId=ffout_a7c4a56fb1bc488dc03fa0ef |
+| large-log-repeat | 2 | metadata/metadata_only | duplicate-ref | 0 | metadata duplicate points to exact outputId=ffout_a7c4a56fb1bc488dc03fa0ef |
+| repeated-failure-a | 2 | metadata/metadata_only | duplicate-ref | 0 | metadata duplicate points to exact outputId=ffout_8e9758900243b59ade59cc2b |
+| repeated-failure-b | 2 | metadata/metadata_only | duplicate-ref | 0 | metadata duplicate points to exact outputId=ffout_8e9758900243b59ade59cc2b |
+| repeat-a | 2 | metadata/metadata_only | duplicate-ref | 0 | metadata duplicate points to exact outputId=ffout_a29dfa4bd5a569d730e6cee3 |
+| repeat-b | 2 | metadata/metadata_only | duplicate-ref | 0 | metadata duplicate points to exact outputId=ffout_a29dfa4bd5a569d730e6cee3 |
+
+### Hybrid exactness + duplicate dedupe
+
+Exactness-sensitive or >= 8192 byte outputs stay exactly recoverable; exact duplicates of those outputs become metadata pointers; small non-sensitive outputs are metadata-only.
+
+- Exactness-sensitive recovery: pass
+- Metadata-only recovery labeled: yes
+- Repeated outputs deduped: yes
+
+| Fixture | Iteration | Record | Recovery | Exact bytes | Notes |
+| --- | ---: | --- | --- | ---: | --- |
+| small-success | 1 | metadata/metadata_only | metadata-only | 0 | metadata-only record intentionally has no raw exact recovery |
+| small-failure | 1 | command/exact | exact | 104 | exact combined recovery passed |
+| verification-output | 1 | command/exact | exact | 52 | exact combined recovery passed |
+| large-log | 1 | command/exact | exact | 30030 | exact combined recovery passed |
+| large-log-repeat | 1 | metadata/metadata_only | duplicate-ref | 0 | metadata duplicate points to exact outputId=ffout_5153e748859b1faf49211433 |
+| repeated-failure-a | 1 | command/exact | exact | 113 | exact combined recovery passed |
+| repeated-failure-b | 1 | metadata/metadata_only | duplicate-ref | 0 | metadata duplicate points to exact outputId=ffout_78ba156d8ff23576c596ff12 |
+| repeat-a | 1 | metadata/metadata_only | metadata-only | 0 | metadata-only record intentionally has no raw exact recovery |
+| repeat-b | 1 | metadata/metadata_only | metadata-only | 0 | metadata-only record intentionally has no raw exact recovery |
+| small-success | 2 | metadata/metadata_only | metadata-only | 0 | metadata-only record intentionally has no raw exact recovery |
+| small-failure | 2 | metadata/metadata_only | duplicate-ref | 0 | metadata duplicate points to exact outputId=ffout_97633d780c13e9c3385a6196 |
+| verification-output | 2 | metadata/metadata_only | duplicate-ref | 0 | metadata duplicate points to exact outputId=ffout_1e58e267e9ad6f288c56c3d7 |
+| large-log | 2 | metadata/metadata_only | duplicate-ref | 0 | metadata duplicate points to exact outputId=ffout_5153e748859b1faf49211433 |
+| large-log-repeat | 2 | metadata/metadata_only | duplicate-ref | 0 | metadata duplicate points to exact outputId=ffout_5153e748859b1faf49211433 |
+| repeated-failure-a | 2 | metadata/metadata_only | duplicate-ref | 0 | metadata duplicate points to exact outputId=ffout_78ba156d8ff23576c596ff12 |
+| repeated-failure-b | 2 | metadata/metadata_only | duplicate-ref | 0 | metadata duplicate points to exact outputId=ffout_78ba156d8ff23576c596ff12 |
+| repeat-a | 2 | metadata/metadata_only | metadata-only | 0 | metadata-only record intentionally has no raw exact recovery |
+| repeat-b | 2 | metadata/metadata_only | metadata-only | 0 | metadata-only record intentionally has no raw exact recovery |
+
+## Decision Boundary
+
+This benchmark intentionally stops before changing defaults. Any storage default change still needs a product/safety decision because metadata-only storage changes exact recovery semantics and privacy surface.

package/evals/reports/runtime/vault-index-storage-spike-1-report.md

@@ -0,0 +1,39 @@
+# Vault Index Storage Spike Report - Iteration 1
+
+Date: 2026-06-24
+
+## Scope
+
+Slice 11/12 storage-interface and write-path spike for the Freeflow vault index. The benchmark checks that a fresh index starts empty, persisted appends become queryable incrementally through automatic write-through indexing, metadata-only records do not index raw content, and the selected storage engine stays hidden behind the vault-index interface.
+
+## Command
+
+```sh
+npm run bench:router:vault-index
+```
+
+## Summary
+
+- Fixtures per iteration: 3
+- Iterations: 3
+- Selected engine: local-json-sidecar
+- Selected reason: Portable deterministic sidecar files satisfy automatic incremental write-through semantics without adding a native dependency.
+- Local sidecar passed: yes
+- Scanner baseline passed: yes
+- SQLite FTS status: not-run
+- Local append p50/p95: 1.34/3.31 ms
+- Local query p50/p95: 0.34/5.16 ms
+- Scan query p50/p95: 0.20/0.38 ms
+- Local query result reduction: -8.32%
+
+## Candidates
+
+| candidate | status | adopted | append p50/p95 ms | query p50/p95 ms | raw/result bytes | reduction | checks | notes |
+| --- | --- | --- | ---: | ---: | ---: | ---: | --- | --- |
+| local-json-sidecar | pass | yes | 1.34/3.31 | 0.34/5.16 | 15681/16986 | -8.32% | fresh index starts empty; each persisted append is queryable immediately; metadata-only raw content is not indexed; no native dependency | Selected for the Slice 11 interface and exercised through the Slice 12 write path because it is portable and dependency-free. |
+| vault-session-scan-baseline | pass | no | - | 0.20/0.38 | - | - | finds fixture evidence by reading vault records directly | Baseline remains source-truth fallback but query cost grows with vaulted text. |
+| sqlite-fts | not-run | no | - | - | - | - | not introduced during Slice 11 | Deferred: adding a native dependency or relying on experimental runtime SQLite needs explicit owner approval. |
+
+## Decision
+
+Use the deterministic local JSON sidecar behind the vault-index interface for the next slices. Do not adopt SQLite/FTS in this slice because introducing a native dependency or relying on experimental runtime SQLite needs separate owner approval. The vault remains source truth; the index is a rebuildable sidecar.