Blinkin Legacy Docs Docs
Porting · porting/2026-05-05-local-full-stack-evidence.md Docs Home

Local Full-Stack Evidence

Date: 2026-05-05

Objective

Make the "first rebuild it local" requirement explicit.

The existing local smoke proves the non-Python platform surfaces can run together. This evidence contract is stricter: the local rebuild is not complete until the Python Query Engine, the Ingestion Worker, and one Agent/AI runtime response are observed with the rebuilt Studio API, Picasso, and Zweistein services.

What Was Added

  • scripts/local-full-stack-evidence.mjs Live-probe evidence collector and contract checker for the local full-stack rebuild.
  • package.json scripts:
    • local:full-stack:plan
    • local:full-stack:doctor
    • local:full-stack:probe
    • local:full-stack:template
    • local:full-stack:collect
    • local:full-stack:check
  • port:completion:* now includes local-full-stack-evidence as a hard completion criterion.

Safety Rules

  • It does not start servers.
  • It does not build Docker images.
  • It does not run migrations.
  • It does not read or print env values.
  • local:full-stack:doctor is read-only and reports disk, Docker, Docker Compose, artifacts, Python runtime directories, Query Engine torch import, Ingestion Worker redis import, HTTP probes, and observation flags.
  • local:full-stack:probe is read-only and only reports current live state.
  • local:full-stack:collect writes evidence only when every live HTTP probe passes and the verifier explicitly confirms the manual observations.
  • It intentionally fails until real local full-stack evidence exists.

Commands

Print the evidence plan:

npm run local:full-stack:plan

Show the current blockers before attempting a local full-stack evidence run:

npm run local:full-stack:doctor

Probe the currently running local stack without writing evidence:

npm run local:full-stack:probe

Print a pending evidence template:

npm run local:full-stack:template

Write complete evidence only after live probes pass and the worker plus Agent/AI behavior were observed:

LOCAL_FULL_STACK_VERIFIER="Your Name" \
LOCAL_FULL_STACK_EVIDENCE_CONFIRM=1 \
LOCAL_INGESTION_WORKER_OBSERVED=1 \
LOCAL_AGENT_AI_OBSERVED=1 \
  npm run local:full-stack:collect

Fail until a completed evidence file exists:

npm run local:full-stack:check

Evidence Contract

The completed evidence must live in a file named like:

docs/evidence/<timestamp>-local-full-stack.md

It must include:

# Local Full-Stack Runtime Verification
Status: complete
Target: local
Verifier:
Studio API HTTP 200: yes
Zweistein Server HTTP 200: yes
Zweistein Admin HTTP 200: yes
Zweistein Embedding Widget HTTP 200: yes
Picasso Houston HTTP 200: yes
Picasso Editor HTTP 200: yes
Picasso Widget HTTP 200: yes
Query Engine HTTP 200: yes
Ingestion Worker observed: yes
Agent/AI response observed: yes
Runtime status command: npm run legacy:runtime:status
Evidence collector command: npm run local:full-stack:collect
Live probe source: scripts/local-full-stack-evidence.mjs

Current Local Verification Evidence

  • npm run legacy:runtime:smoke:non-python proves the seven non-Python services can run together.
  • npm run local:full-stack:plan prints the stricter full-stack evidence workflow.
  • npm run local:full-stack:doctor now combines local disk readiness, Docker CLI, Docker Compose, rebuilt artifacts, Python runtime directories, Query Engine torch import, Ingestion Worker redis import, live HTTP probes, and manual observation flags into one read-only readiness check.
  • npm run local:full-stack:probe now performs live HTTP checks for the seven non-Python URLs plus the Query Engine URL and fails while they are not all responding.
  • npm run local:full-stack:template prints a pending template and does not create a fake evidence file.
  • npm run local:full-stack:collect refuses to write evidence unless all live probes pass, LOCAL_FULL_STACK_VERIFIER is set, LOCAL_FULL_STACK_EVIDENCE_CONFIRM=1 is set, and both manual observation flags are set.
  • npm run local:full-stack:check fails locally as expected while Python runtime and Agent/AI evidence are missing.
  • After the real Query Engine Docker build attempt, npm run local:full-stack:doctor reports 13 blocker(s): the current Mac is below the 20 GiB Python Docker build disk guard, Query Engine torch import still fails, Ingestion Worker redis import still fails, the app HTTP probes are stopped, Query Engine HTTP is not responding, and the worker/Agent observation flags are not set.

Current Boundary

This does not replace the Hetzner Python gate.

It makes the local boundary honest: the local rebuild has strong non-Python proof, but the full local platform is still incomplete until the Python services and an Agent/AI response are observed in the same local rebuild context.