Check OPFS capabilities only for default storage

.github/ISSUE_SPECS/101-delegate-session-pcm-prefill-proof-to-the-sdk-runway-helper.md

@@ -0,0 +1,65 @@
+# Delegate session PCM prefill proof to the SDK runway helper
+
+Depends on misofm/engine#797 and a published SDK containing its
+`waitForPcmRunway` contract for final package acceptance. Independent of adapter
+misofm/engine-web-adapter#95, misofm/engine-web-adapter#102 and app misofm/app#210; never hold their delivery for this work.
+
+## Smallest outcome and facts
+
+Dense and sparse session opening/seek use the SDK's generic PCM runway proof,
+leaving this adapter responsible for its producer and aggregate choreography.
+Current source baseline is main
+`f833303f146de7cbe1705fe88ae68a6d6e0d4e45`; refresh before implementation.
+`src/feed.ts`, `src/scratch.ts` and `src/stems/ring.ts` already delegate to SDK
+primitives. Only `src/session.ts::waitForRunway` duplicates the generic generation,
+contiguity and ring-capacity proof. This is source-level ownership evidence.
+
+## Required change
+
+1. Replace that algorithm with SDK `waitForPcmRunway`. Opening supplies existing
+   source totals/rings, frame 0, generation 1 and the current two-second timeout;
+   seek supplies its acknowledged target/full generation and the same deadline.
+   Omit `minimumFrames` to retain today's full-capacity/EOF-clamped policy.
+2. Keep source `pump.seekFrames`, feed attachment/`prepareSeek`, context-state
+   checks, suspension/resumption, serialized transport, producer/refill work and
+   terminal cleanup exactly at their current composition seam. The helper never
+   grants permission to skip these steps or resumes audio itself.
+3. Remove now-unused per-prefill observer construction and direct protocol
+   checks. Keep the existing diagnostic/source-observation objects because they
+   have independent callers. Do not alter ring/read cursor behavior or prefetch.
+4. Translate `PcmRunwayError` into existing `session.open`/`session.seek` failures,
+   preserving source ID, cause and timeout/mismatch distinction in details.
+   Preserve abort/close semantics and meaningful SDK usage errors. No second
+   fallback algorithm or copy retained after migration.
+5. Preserve dense/sparse canonical BLAKE3/count checks, warm/cold worker limits,
+   512 KiB reads, 128 KiB ingest bounds, 64 KiB zero checkpoints, source-specific
+   cleanup/locks, current diagnostics and all playback behavior. No codec,
+   storage framework, source-policy expansion or transport rewrite.
+
+## Focused proof and delivery
+
+Files: `src/session.ts`, an existing error translation seam only if needed,
+`tests/session.test.ts`, README and package/provenance pins when adopting the
+published SDK. Reuse existing opening, suspended/running seek and failure tests:
+full current-generation prefill before success, wrong generation/contiguity,
+EOF, timeout/cancellation, close during seek, and restore-running only after
+successful proof. Assert consumer preparation precedes the SDK call and a
+failure still completes aggregate cleanup. SDK owns detailed ring unit cases;
+do not duplicate its matrix or add an engine factory just for testing.
+
+Root commits one focused-green implementation tranche. Run `npm run check`;
+for a released candidate run existing packed-browser/publish-dry-run gates and
+fresh-consumer dependency checks once. Package with another coherent adapter
+release when available; do not delay misofm/engine-web-adapter#95/app plotting to manufacture batching.
+Final published adoption needs exact SDK/adapter versions, merged source SHAs,
+registry integrities and existing provenance/attestation checks. If it cannot
+share misofm/engine-web-adapter#95's cut, use a stateless ordinary release issue for publication and
+record that dependency explicitly; source availability is never registry proof.
+
+Luna XHIGH implements; a fresh Astra MEDIUM independently verifies and fixes
+concrete in-scope bugs only; coordinator is a separate fresh Astra MEDIUM.
+Maximum five coherent attempts with one verdict each; preserve evidence and
+rebrief after five failures. Root synchronizes numbered local/GitHub evidence,
+integrates latest main, and closes after PASS, merged delivery, required CI and
+the published adoption evidence; verify remote CLOSED. No new results claimed
+by this scope-only brief.

.github/ISSUE_SPECS/102-apply-opfs-capability-requirements-only-to-the-selected-storage-path.md

@@ -0,0 +1,122 @@
+# Apply OPFS capability requirements only to the selected storage path
+
+Independent of adapter misofm/engine-web-adapter#95/misofm/engine-web-adapter#101 and engine/app analysis work.
+This issue does not implement IndexedDB, WAVPACK or another backend.
+
+## Outcome and source evidence
+
+A caller supplying an existing custom dense or sparse store can open a session
+without unrelated OPFS/Web Locks browser APIs. Default OPFS sessions retain
+their current early, typed capability refusals and Worker-side write probe.
+
+At adapter main `f833303f146de7cbe1705fe88ae68a6d6e0d4e45`,
+`src/session.ts::openSessionCommon` unconditionally calls
+`assertEngineWebCapabilities` before selecting a store. That checker in
+`src/capabilities.ts` requires `navigator.storage.getDirectory`,
+`FileSystemFileHandle` and Web Locks even when `options.store` supplies the
+whole storage service. `OpfsStorageBackend.open()` in `src/stems/storage.ts`
+already probes actual Worker-only write support before source resolution.
+This establishes an unnecessary source-level gate, not a demonstrated production
+incident. Refresh latest main and read its AGENTS before implementing.
+
+## Frozen correction
+
+1. Separate the existing runtime predicates (cross-origin isolation, SAB,
+   Worker, AudioContext/AudioWorklet and Wasm SIMD128) from OPFS persistence
+   predicates in `src/capabilities.ts`. Reuse existing errors/remedies.
+2. Preserve the existing module-level `assertEngineWebCapabilities(scope?)` as the comprehensive
+   default-FLAC/OPFS preflight for compatibility. Use two small internal/exported
+   module helpers, `assertEngineRuntimeCapabilities(scope?)` and
+   `assertOpfsStorageCapabilities(scope?)`, to compose its existing behavior.
+   Export from the package only if a current public use requires it; no new
+   capability registry, backend descriptor or plug-in protocol.
+3. Both open entry points snapshot whether a store was supplied before awaiting
+   work. `openSessionCommon` always runs runtime checks; run OPFS checks only
+   for the default store path, before creating it or invoking resolver/network
+   work. Sparse opening currently removes `store` from `commonOptions`, so pass
+   the selected-path fact explicitly; do not accidentally treat it as default.
+4. A supplied store owns its persistence/locking requirements. Do not inspect
+   its class name, assume all custom stores use OPFS, or disable actual backend
+   errors. Injected OPFS still executes its own `open()`/Worker support checks.
+   Default OPFS retains window-visible file handles/getDirectory and Web Locks
+   checks, Worker write handshake and existing typed failures/remedies.
+5. Preserve source validation/admission ordering, BLAKE3/count verification,
+   current locking and cleanup contracts, warm/cold paths and output behavior.
+   There is no promise that a custom store is safe on multiple tabs without its
+   own coordination. Do not modify locks, storage algorithms or source policy.
+
+## Small proof and completion
+
+Change `src/capabilities.ts`, the common-open selected-path argument and focused
+`tests/session.test.ts` cases plus concise API docs. Existing memory/custom-store
+fixtures must reach normal opening for dense and sparse paths with valid runtime
+capabilities but no OPFS/file handles/Web Locks. Missing runtime requirements
+must still refuse before store/resolver work. Default-store cases must still
+refuse missing persistence APIs before source work and retain the existing
+Worker write-support failure/cleanup case. A supplied store's own failure must
+propagate. Reuse the existing default OPFS packed smoke; no new browser/backend
+matrix or IndexedDB test framework.
+
+Run focused tests and `npm run check`, then current required CI. One coherent
+checkpoint should suffice; root commits focused-green exact paths before more
+implementation. Luna XHIGH implements, a fresh Astra MEDIUM verifies and may
+fix concrete in-scope bugs only, and a separate fresh Astra MEDIUM coordinates.
+At most five coherent attempts/one verdict each; after five failures stop and
+rebrief. Root records the source/evidence and closes local/GitHub state after
+independent PASS, merged delivery and required CI; verify remote CLOSED.
+If package publication is deferred, explicitly record the ordinary release
+successor and do not claim registry availability. It may share a ready adapter
+release cut, but misofm/engine-web-adapter#95 and app misofm/app#210 do not wait for this independent correction.
+
+Decision record: scope-only; no implementation or fresh runtime result yet.
+
+
+## Implementation checkpoint
+
+Luna XHIGH implemented the frozen selected-path correction in isolated
+`codex/backend-capabilities`: runtime and OPFS preflights compose the existing
+comprehensive checker; dense and sparse opens snapshot whether a store was
+supplied and skip persistence predicates only for that selected custom path.
+Default-store refusal order and actual backend failures remain intact.
+Implementer reports focused session 45/45, full `npm run check` 367/367 with
+package policy, and whitespace checks PASS. Root checkpoints the four intended
+source/test/README paths; no release pins changed. Independent fresh Astra
+MEDIUM verification and required merged CI remain pending. This is attempt 1;
+no published capability or final acceptance is claimed yet.
+
+
+## Independent attempt 1 review — 2026-09-14
+
+Fresh Astra MEDIUM adversarial review of implementation
+`6616d01b7560d35975ad0b9733f97e7f76cfe708`: **PASS for the frozen correction**.
+No production or test fixes were needed. Both entry points retain their supplied
+store and selected-path fact before awaiting work; runtime predicates always
+run, default persistence predicates precede scratch/source work, and supplied
+stores retain their actual backend checks and error propagation. The helpers
+remain module exports, without a new package API or backend protocol.
+
+Independent local evidence, Node 22.23.2/npm 10.9.8:
+
+- Focused session tests: 45/45 PASS.
+- `npm run check`: 367/367 PASS, including reproducible SHA256 Wasm,
+  source/decoder/package policies and type checks.
+- Fourteen review probes: all six runtime refusals precede scratch/store work
+  for both entry points; mutating `options.store` during deferred scratch work
+  preserves the original supplied store and its exact typed backend refusal.
+- Existing packed default browser fixture: PASS on Chromium 151.0.7922.34,
+  including cold/warm ingestion, Worker/AudioWorklet assets and no console or
+  request failures.
+- Existing packed OPFS gate: Chromium PASS (65,536 cold bytes, warm reuse,
+  sparse verification and cleanup). Linux Playwright WebKit 26.5 is an
+  environment blocker: its fixture throws `ReferenceError` for the absent
+  `FileSystemFileHandle`. A separate blank localhost page, secure and
+  cross-origin isolated, confirms both `FileSystemFileHandle` and
+  `navigator.storage.getDirectory` are undefined without loading the adapter.
+  This is **not a passing WebKit gate**; required macOS OPFS CI remains pending.
+- Implementation whitespace check: PASS.
+
+Raw logs and the repeatable review probe are preserved outside this worktree in
+`/tmp/miso-796-audit/adapter102-{focused,check,adversarial,packed-browser,packed-opfs,webkit-environment}.log`
+and `adapter102-adversarial.mjs`. The coordinator owns evidence checkpointing,
+merged required CI, GitHub synchronization and ordinary package release. This
+review does not claim merged delivery, issue completion or registry availability.