Skip to main content

​
Notebook Launch Runbook

Follow this runbook in order. A later phase does not authorize an earlier blocked phase, and a green local prototype does not authorize a hosted migration, provider call, schedule, merge, or production release.
Current posture: customer Report V2 writes, research-revision writes, customer update requests, companion executors, and automatic research schedules are off. No hosted research migration has been applied. Keep this posture until every preceding gate below is complete and explicitly approved.

​
Phase 0: Review the stack

  • Review the notebook roadmap and dependency order in draft PR #1253.
  • Review progress UX in #1254.
  • Review the local Studio and shared engine in #1255.
  • Review unresolved-order preservation in #1256.
  • Review immutable publications and update/history UX in #1257.
  • Review guarded research revisions and coordinators in #1259.
  • Confirm every PR still points at the reviewed head and has no unresolved base conflict.
  • Keep all PRs draft until the stack is reconciled into one launch candidate.
Do not merge individual stacked branches in an arbitrary order. Reconcile their semantic dependencies and rerun the combined gates first.

​
Phase 1: Approve the product in Studio

Start the local browser Studio:
Use Notebook Studio to review:
  • Known order happy path
  • Known plus unknown order
  • All-unknown order
  • Alias, ambiguous, placeholder, and duplicate lines
  • Missing price and dispensary
  • Fresh, stale, conflicting, no-data, failed, and timed-out research
  • Update available, updating, promoted, failed, canceled, retry, and history
  • Cancel at preparing, researching, generating, and finalizing
  • Cancel-too-late and superseded attempts
  • Close, background, reopen, and readable-current behavior
  • Free preview and paid entitlement
  • 32-line order and payload pressure
  • Evidence, privacy, accessibility, and media-blocking checks
Record accepted deep links or exported synthetic fixtures. Never use production customer data in Studio.

​
Phase 2: Run deterministic gates

Build shared packages before checking apps:
Then run:
Expected posture while no approved database URL is present: the static migration lane passes and the explicitly database-backed race cases skip. The guarded local PostgreSQL 17 lane can prove lock ordering, but it is not the canonical Plan 066 bootstrap or full pgTAP proof.

​
Phase 3: Complete Plan 066 database baseline

  • Reconcile the canonical Supabase migration history.
  • Produce a reproducible disposable database from that baseline.
  • Apply the proposed research revision migration only to the approved disposable target.
  • Run full pgTAP state-transition, authorization, replay, and publication tests.
  • Rerun the two-session concurrency tests.
  • Verify service-role-only RPC access and rejected anon/authenticated access.
  • Verify forward migration audit checksums.
  • Record the exact PostgreSQL/Supabase versions and test output.
The existing local runner rejects non-loopback hosts, non-test database names, nonempty schemas, and non-PostgreSQL-17 targets. Do not weaken those guards to make a test easier to run.

​
Phase 4: Finish research engine integration behind hard-off flags

Before wiring a live task, define and test:
  • Retry exhaustion before terminal failure settlement
  • Leased, cooldown, fresh-skip, and duplicate dispositions without premature success callbacks
  • Revision-aware behavior for the legacy catalog-exists shortcut
  • Stable subject identity across reordered/partial batches
  • Recovery for partial begin and abandoned leases
  • Exactly one terminal settlement per subject
  • Direct, Batch API, bulk, and scheduled parity
  • Exact source/retrieval binding and no cross-subject publication
Import the tested coordinators only after these contracts exist. Keep STRAIN_RESEARCH_REVISION_WRITES literally false throughout implementation and review. Disabled-path tests must prove that no Supabase client, revision adapter, or revision builder is constructed or evaluated.

​
Phase 5: Reconcile one staging candidate

  • Create one integration branch containing the approved order, Studio, progress, publication, research, and docs work.
  • Resolve conflicts semantically; do not choose one side mechanically.
  • Rerun every Phase 2 gate on the combined branch.
  • Repeat the full Studio pairwise review.
  • Confirm NotebookLM is absent from deployable customer runtimes and provider manifests.
  • Confirm all companion executor selections remain empty and execution remains off.

​
Phase 6: Stage the database and write path

This phase requires an explicit migration/staging approval.
1

Apply the reviewed migration to staging

Capture migration output and verify tables, functions, grants, and indexes against the approved manifest.
2

Verify read contracts first

Exercise service-role ordered source-batch reads with known, unknown, stale, failed, and mixed subjects. Confirm exactly one result per requested subject in requested order.
3

Enable one bounded write cohort

Flip the research write boundary only in a separately reviewed staging change. Keep schedules unattached and use controlled synthetic subjects.
4

Observe every terminal outcome

Prove success, no-data, failure, cancellation, duplicate replay, cooldown, lease expiry, and forced refresh.
5

Enable Report V2 staging writes

Only after source revisions are trustworthy, enable bounded notebook attempts for controlled test accounts. Verify immutable publications and history.
Rollback order:
  1. turn the write/execution boundary off;
  2. stop starting new attempts;
  3. leave current readable publications untouched;
  4. allow owned attempts to settle or expire according to the reviewed policy;
  5. inspect and reconcile before retrying;
  6. never “roll back” by mutating or deleting immutable publications.

​
Phase 7: Certify native user flows

Browser Studio does not replace device testing. Using Argent/Revyl and manual device QA, certify:
  • Order review to notebook start
  • Research-waiting presentation
  • Bottom progress accessory above every relevant tab layout
  • Open, minimize, swipe-down, dismiss accessory, and reopen
  • Confirmed cancellation and every cancellation result
  • App background/foreground and cold reopen
  • Keep reading current while update runs
  • Update comparison, request, failure, cancellation, promotion, and history navigation
  • Small and large iPhone layouts
  • Dynamic Type, VoiceOver labels, reduced motion, and 44-point targets
  • Network loss, delayed callbacks, and stale local cache recovery
  • Free, Pro, lapsed, and restore states
Capture screenshots, flow results, build identifier, account fixture, and any server run IDs needed for private debugging. Do not put sensitive identifiers in public docs.

​
Phase 8: Evaluate optional providers

The readable notebook must launch without generated media. Provider selection is per capability—not one vendor for the whole notebook. Use a provider-neutral job contract with idempotency key, capability, model/executor snapshot, safe input hash, cost ceiling, timeout, cancel handle, retention policy, and normalized result.

​
Provider scorecard

Score each candidate using the same synthetic evaluation pack: For a prototype broker, evaluate fal Model APIs and Replicate predictions. For direct video quality, evaluate candidates such as Runway and Luma. Kling can remain a candidate only after its direct or brokered commercial terms, privacy posture, and cancellation semantics pass the same review. Do not send raw orders or user profiles to a media provider. Derive a minimized safe creative brief from the validated publication.

​
Phase 9: Paid-beta decision

The notebook is ready for paid beta only when:
  • The reconciled branch and database gates are green.
  • The complete native flow is certified on the release candidate.
  • Free/Pro/lapsed access matches pricing and documentation.
  • A readable notebook provides enough value with every companion disabled.
  • Unknown, stale, failed, canceled, and update states are understandable without support intervention.
  • Monitoring, cost ceilings, support recovery, data export, and account deletion include notebook records.
  • Public help copy matches the actual enabled capability profile.
  • John explicitly approves the staging/launch transition.

​
Evidence package

For each candidate, retain:
  • commit and build identifiers;
  • feature/capability profile;
  • automated test outputs;
  • migration/pgTAP evidence where applicable;
  • Studio deep links and reviewed fixtures;
  • device flow screenshots/results;
  • provider scorecards and measured costs if any provider is selected;
  • known limitations and rollback steps;
  • final public-promise review.