Index And Kukulkan Production Replacement Roadmap

This roadmap defines the work needed before index and kukulkan can be

rewritten and operated as production 0x0 applications.

The target is full application replacement, not source translation alone. A

milestone is complete only when the repository contains the 0x0 source, the

runtime implementation needed by that source, resource-safe gates, migrated

tests, release packaging, and a rollback path.

Scope

In scope:

• rewrite /home/n0um3n4/repositories/index as a 0x0 application;
• rewrite /home/n0um3n4/repositories/kukulkan as a 0x0 application suite;
• keep the migrated external libraries under libs/ as the shared dependency

base;

• add missing 0x0 package/workspace features needed by multi-package apps;
• replace compatibility-only host surfaces with real runtime behavior where the

applications need it;

• create resource-safe gates that do not break the user session;
• produce release packages and deployment artifacts that do not require the

jmp0x1b runner in the normal path.

Out of scope:

• reintroducing /home/n0um3n4/repositories/libs as a dependency;
• keeping jmp0x1b source as the production implementation after cutover;
• claiming browser, network, database, subprocess, or deployment readiness

before a real executable gate proves it.

External tools such as cc, curl, docker, helm, kubectl, node,

playwright, and PostgreSQL may remain deployment or validation dependencies

when the application contract requires them. They must be called through an

explicit 0x0 runtime boundary or an explicitly documented host-side release

gate.

Current Baseline

index:

• branch: main;
• source scale: 16 .jmp0x1b files and about 12k non-dist source lines;
• current app entry points: src/lib.jmp0x1b, src/main.jmp0x1b;
• manifest dependencies are present under libs/;
• production behavior depends on file IO, local config/cache/state paths, HTTP

fetches, browser snapshots, terminal rendering, capture artifacts, shelf

persistence, compatibility packs, auth assist, and command packaging.

kukulkan:

• branch: master;
• source scale: 26 .jmp0x1b files and about 46k source lines;
• current package set:

- jmp0x1b_kukulkan_api_contract;

- jmp0x1b_kukulkan_client;

- jmp0x1b_kukulkan_events;

- kukulkan_compliance_domain;

- kukulkan_geospatial_domain;

- kukulkan_service_stack;

- kukulkan_saas_orchestration;

- kukulkan_api_runtime;

- kukulkan_web_ui;

• external library dependencies are present under libs/;
• missing dependency names are app-owned packages that must be rewritten;
• production behavior depends on HTTP listeners, routing, WebSocket/LiveView,

subprocess/env access, Postgres, OIDC, object store/search/email/observability

adapters, browser e2e, WCAG/perf/security gates, Docker, Helm, Kubernetes,

and remote deployment scripts.

0x0:

• package support exists, but it is a first local package slice, not a

workspace, registry, or solver;

• libs/ contains standalone library packages with smoke tests;
• core host builtins are narrow: file read/write, stdin, stdout, argv, env,

print, and panic;

• several high-level app dependencies are currently compatibility surfaces that

construct values rather than perform real effects, including web.listen,

web.accept, web.execute-text-request, cli.exec-subprocess, and

jmp0x1b-shaped fs.read-text / fs.write-text.

Replacement Definition

index is replaced when:

• the production app source lives in the 0x0 repository or a declared 0x0 app

workspace;

• all app-owned logic is written in .0x0;
• app tests run through the 0x0 toolchain;
• the normal CLI binary does not invoke jmp0x1b;
• local files, config/cache/state paths, network fetches, browser snapshots,

capture artifacts, shelf storage, and compatibility packs work through real

0x0 runtime boundaries;

• command outputs match the accepted parity corpus or intentionally documented

0x0 replacements;

• the release package can be installed and run from a clean checkout.

kukulkan is replaced when:

• all app-owned packages are .0x0 packages;
• API and UI binaries run without the jmp0x1b runner;
• HTTP server, request routing, WebSocket/LiveView, auth, domain mutations,

runtime metrics, and database-backed workflows are exercised by 0x0-owned

app gates;

• browser e2e, WCAG, load/perf, security, Docker dependency, Helm, Kubernetes,

and deployment gates are either 0x0-owned or explicit host-side release gates;

• the cutover package has rollback, runtime health probes, and deployment docs.

Session Safety Rules

The project has already hit user-session breaks from heavy documentation and

compiler runs. Until a gate is proven safe, roadmap work must follow these

rules:

• Do not run make docs-check as an exploratory command. First create a

smaller resource-safe docs gate and use it for this roadmap work.

• Do not run broad compiler sweeps with parallel jobs by default.
• Keep library and app compile gates single-job unless the user explicitly asks

for parallel execution.

• Prefer targeted per-package gates while implementing a milestone.
• Any new long-running gate must support:

- single-job mode;

- timeout;

- peak-RSS capture;

- resumable package list;

- clear log output under build/ or .runtime/;

- no uncontrolled background processes.

• Runtime-start gates must write PID files and have reliable stop/force-stop

targets before they are allowed into a parent milestone gate.

• Full release, browser, Docker, Kubernetes, and deployment gates must be opt-in

until their resource budgets are recorded and accepted.

Standing Gates

These gates apply to every milestone once they exist:

make package-check
make libs-check
git diff --check

Resource-safe application gates must be added before broad checks:

make apps-check
make index-check
make kukulkan-check

Heavy gates must stay opt-in until they have resource budgets:

make apps-full-check
make index-full-check
make kukulkan-full-check
make kukulkan-browser-check
make kukulkan-deploy-check

No milestone may require make docs-check until Milestone 3 replaces or fixes

the behavior that breaks the user session.

Commit And Submilestone Policy

• Every milestone must land in at least one dedicated commit.
• Every submilestone must land in at least one dedicated commit when it changes

code, tests, docs, or generated release metadata.

• A submilestone is not a placeholder. It must add a real artifact, a real gate,

or a real app rewrite slice.

• A parent milestone is complete only when all of its submilestones pass and the

parent exit gate passes.

• App parity changes must include a fixture, a test, and a documented decision

about whether the output is exact parity or intentional 0x0 behavior.

Milestone 0: Replacement Inventory And Acceptance Baseline

Status: done.

Goal: convert the audit into machine-checkable inventories so no runtime or app

dependency is discovered late during the rewrite.

Submilestones:

0.1 Source Inventory

Artifacts:

• apps/index/PORTING.html or docs/apps/index-inventory.html;
• apps/kukulkan/PORTING.html or docs/apps/kukulkan-inventory.html;
• generated file lists for source, fixtures, scripts, docs, static assets, and

release files.

Required behavior:

• excludes generated dist/, .runtime/, caches, and node modules;
• records source line counts and package ownership;
• records current branch and commit for each source repository;
• records every app-owned package that must become .0x0.

Exit gate:

make apps-inventory-check

0.2 Dependency And Runtime Matrix

Artifacts:

• docs/apps/index-dependency-matrix.html;
• docs/apps/kukulkan-dependency-matrix.html.

Required behavior:

• maps every import to one of:

- existing 0x0 library;

- app-owned package to rewrite;

- host runtime capability to implement;

- release/deploy-only host tool;

• records whether each dependency is pure, file, process, network, database,

browser, deployment, or security-sensitive.

Exit gate:

make apps-dependency-matrix-check

0.3 Acceptance Corpus

Artifacts:

• apps/index/fixtures/parity/;
• apps/kukulkan/fixtures/parity/;
• command-output manifests for current accepted behavior.

Required behavior:

• captures CLI command outputs for stable Index commands;
• captures Kukulkan package test expectations and route/API response contracts;
• stores sensitive values only as redacted fixtures;
• records commands that are intentionally not reproduced exactly.

Exit gate:

make apps-parity-corpus-check

Parent exit gate:

make apps-readiness-baseline-check

Milestone 1: 0x0 Application Workspace

Status: done.

Goal: give production applications a first-class location, dependency model,

test model, and release model in the 0x0 repository.

Submilestones:

1.1 App Directory Contract

Required layout:

apps/
  index/
    0x0.pkg
    src/
    tests/
    fixtures/
    release/
  kukulkan/
    0x0.workspace
    packages/
    tests/
    fixtures/
    deploy/
    release/

Required behavior:

• app sources do not live under libs/;
• app-owned packages can depend on shared libs/;
• generated build output stays under build/apps/;
• runtime state stays under .runtime/ or an app-configured directory.

Exit gate:

make apps-layout-check

1.2 Workspace Manifest And Lockfile

Required artifacts:

• app package manifests;
• workspace manifest for Kukulkan multi-package layout;
• generated app lockfiles.

Required behavior:

• supports local path dependencies outside root package sources;
• prevents parent traversal and absolute paths;
• supports pkg: imports for app-owned packages and shared libraries;
• reports missing, duplicate, or cyclic dependencies deterministically.

Exit gate:

make apps-package-check

1.3 App Test Discovery

Required behavior:

• discovers package-local smoke tests;
• discovers app parity tests;
• supports targeted package runs;
• supports single-job mode by default;
• writes a deterministic test manifest.

Exit gate:

make apps-test-manifest-check

Parent exit gate:

make apps-check

Milestone 2: Source Rewrite Foundation

Status: done.

Goal: make manual and mechanical rewrites reliable before touching large app

sources.

Submilestones:

2.1 0x0 App Style Guide

Artifacts:

• docs/apps/porting-style.html;
• examples for type constructors, fallible results, capability annotations,

module imports, CLI dispatchers, and runtime boundaries.

Required behavior:

• standardizes kebab-case function names;
• standardizes app-owned module names;
• defines how jmp0x1b tagged unions map to 0x0 constructors;
• defines how effects map to 0x0 cap annotations;
• defines how compatibility outputs are represented during migration.

Exit gate:

make app-style-check

2.2 Porting Harness

Artifacts:

• source scanner for unsupported jmp0x1b syntax;
• fixture converter for tests where conversion is mechanical;
• parity runner that compares current accepted output with 0x0 output.

Required behavior:

• never rewrites source silently;
• reports every unsupported language construct;
• supports file-by-file conversion tracking;
• produces reviewable diffs.

Exit gate:

make app-porting-harness-check

2.3 App Lint Rules

Required behavior:

• rejects snake_case function names in app and library sources except for

imported compatibility names that are deliberately wrapped;

• rejects accidental translated, migration, or legacy source comments in

production app code;

• rejects hidden /home/n0um3n4/repositories/libs references;
• rejects jmp0x1b runner calls in production 0x0 app paths.

Exit gate:

make apps-lint

Parent exit gate:

make source-rewrite-foundation-check

Milestone 3: Resource-Safe Gate Infrastructure

Status: done.

Goal: prevent roadmap work from breaking the user session.

Submilestones:

3.1 Safe Docs Gate

Required behavior:

• replaces exploratory make docs-check usage with a targeted docs gate;
• can check one doc file;
• records elapsed time and peak RSS;
• has a timeout;
• produces compact output.

Exit gate:

make docs-safe-check DOC=docs/index-kukulkan-production-roadmap.md

3.2 Single-Job App Compiler Gates

Required behavior:

• all app compile/test runners default to one compiler process;
• parallelism requires an explicit environment variable;
• each runner prints the package currently being checked;
• failed package runs can be resumed.

Exit gate:

make apps-compile-check

3.3 Runtime Process Hygiene

Required behavior:

• runtime-start targets write PID files;
• runtime-stop targets terminate app-owned processes;
• runtime-stop-force cleans orphan listeners on app-owned ports;
• checks fail if a port is owned by an unmanaged process.

Exit gate:

make apps-runtime-hygiene-check

Parent exit gate:

make resource-safe-gates-check

Milestone 4: Host Runtime Capability Model

Status: done.

Goal: define the real runtime boundary that app code can depend on.

Submilestones:

4.1 Capability Taxonomy

Required artifacts:

• docs/runtime-capabilities.html;
• capability names for pure, io, file, process, network, browser, database,

crypto, time, state, deploy, and test.

Required behavior:

• every host effect has a documented capability;
• pure code cannot call effectful functions;
• compatibility constructors are separated from real runtime effects;
• failure values use stable result/error shapes.

Exit gate:

make runtime-capability-check

4.2 Runtime ABI

Required behavior:

• app runtime calls can be compiled through the production compiler path;
• host calls have stable names, argument shapes, and error shapes;
• native, object, and linked executable paths agree on supported runtime calls;
• unsupported runtime calls fail at compile time or startup, not silently.

Exit gate:

make runtime-abi-check

4.3 Runtime Test Adapter

Required behavior:

• app tests can inject fake file, process, network, browser, and database

runtimes;

• fake runtimes are deterministic;
• production runtime and fake runtime share the same 0x0-facing contract.

Exit gate:

make runtime-test-adapter-check

Parent exit gate:

make host-runtime-boundary-check

Milestone 5: File, Environment, And Process Runtime

Status: done.

Goal: replace compatibility-only file/process surfaces with real behavior.

Submilestones:

5.1 Filesystem Runtime

Required behavior:

• read text;
• write text;
• atomic write;
• temp/config/cache/home directory discovery;
• permissions check;
• lock/unlock;
• directory walk;
• local artifact and capture storage;
• safe path normalization.

Index needs this for capture, shelf, compatibility packs, auth assist, save,

batch extraction, and diagnostics.

Kukulkan needs this for reports, runtime PID/log files, deploy artifacts, and

package fixtures.

Exit gate:

make runtime-fs-check

5.2 Environment And CLI Runtime

Required behavior:

• argv;
• env lookup;
• stdout/stderr;
• exit code policy;
• stable command error reporting.

Exit gate:

make runtime-cli-check

5.3 Subprocess Runtime

Required behavior:

• execute command with argv, cwd, env, timeout, and stdin policy;
• capture stdout, stderr, exit code, elapsed time, and timeout status;
• kill timed-out process trees;
• prevent shell injection in structured command paths;
• keep shell execution explicit when a shell is required.

Kukulkan needs this for current env probes, Postgres/psql metrics, Docker

fallbacks, OIDC helper scripts, and deployment checks.

Exit gate:

make runtime-process-check

Parent exit gate:

make runtime-local-effects-check

Milestone 6: HTTP Client And Browser Runtime

Status: done.

Goal: support Index live browsing/capture behavior and Kukulkan browser-facing

checks without relying on jmp0x1b host behavior.

Submilestones:

6.1 HTTP Client Runtime

Required behavior:

• GET and POST text requests;
• request headers;
• response status, headers, content type, body, and timing;
• timeout and retry policy;
• local cache policy;
• TLS failure reporting;
• redirect policy;
• deterministic fake client for tests.

Index needs this for URL fetch and cache-backed document loading.

Kukulkan needs this for internal runtime probes and external provider

integration tests.

Exit gate:

make runtime-http-client-check

6.2 Browser Snapshot Runtime

Required behavior:

• browser snapshot request contract;
• artifact root contract;
• timeout handling;
• page HTML/text capture;
• screenshot or metadata hooks where needed;
• redaction policy;
• deterministic fake browser for tests.

Index needs this for browser_snapshot and capture diagnostics.

Kukulkan needs this for browser e2e validation and OIDC browser PKCE flows.

Exit gate:

make runtime-browser-check

6.3 Capture And Redaction Security Gate

Required behavior:

• URL query secret redaction;
• form/token/cookie redaction;
• artifact validation;
• no leaked credential-shaped values in previews or reports.

Exit gate:

make runtime-capture-security-check

Parent exit gate:

make runtime-fetch-browser-check

Milestone 7: HTTP Server, Routing, WebSocket, And Live Runtime

Status: done.

Goal: support Kukulkan API/UI runtime and any future Index service mode.

Submilestones:

7.1 HTTP Server Runtime

Required behavior:

• bind/listen on configured host and port;
• accept requests with timeout/cancel behavior;
• respond with status, headers, and body;
• close listener;
• report bind, accept, parse, write, and timeout failures;
• expose test listener mode without opening public ports.

Exit gate:

make runtime-http-server-check

7.2 Router And API Contract Runtime

Required behavior:

• route matching;
• method checks;
• request body limits;
• JSON/text request decoding;
• response encoding;
• route-level error conversion;
• API contract snapshots for app tests.

Exit gate:

make runtime-router-check

7.3 WebSocket Runtime

Required behavior:

• HTTP upgrade;
• accept-key calculation;
• protocol negotiation;
• text frame send/receive;
• close/ping/pong;
• malformed upgrade rejection;
• deterministic frame probe.

Exit gate:

make runtime-websocket-check

7.4 LiveView-Compatible Runtime

Required behavior:

• live route document generation;
• mount payload;
• event dispatch;
• diff generation;
• heartbeat;
• reconnect state;
• backpressure policy;
• browser client assets.

Exit gate:

make runtime-live-check

Parent exit gate:

make runtime-web-check

Milestone 8: Persistence And Service Adapter Runtime

Status: done.

Goal: implement the runtime adapters Kukulkan needs for production workflows.

Submilestones:

8.1 Database Runtime

Required behavior:

• database connection config;
• query execution;
• transaction boundary;
• migrations or schema setup hooks;
• typed query result decoding;
• timeout and retry policy;
• deterministic fake database for tests.

Exit gate:

make runtime-db-check

8.2 Auth And OIDC Runtime

Required behavior:

• OIDC discovery document handling;
• PKCE state/challenge handling;
• token exchange contract;
• JWT verification boundary;
• fail-closed auth errors;
• session envelope validation.

Exit gate:

make runtime-auth-check

8.3 Object Store, Search, Email, And Observability

Required behavior:

• S3/object-store request contract;
• search indexing/query contract;
• email notification contract;
• OTLP/logging/metrics contract;
• fake adapters for package tests;
• production adapter probes behind opt-in gates.

Exit gate:

make runtime-service-adapters-check

8.4 Backup, Restore, And Job Runtime

Required behavior:

• backup artifact manifest;
• restore plan and validation;
• background job request model;
• job status and retry policy;
• audit/provenance records.

Exit gate:

make runtime-operations-adapters-check

Parent exit gate:

make runtime-service-boundary-check

Milestone 9: Index Pure Rewrite

Status: done.

Goal: rewrite Index's deterministic app logic in 0x0 before enabling live

effects.

Submilestones:

9.1 Index Document Model

Required behavior:

• semantic document model;
• source metadata;
• headings, links, citations, sections, text blocks, and action hints;
• stable JSON/text rendering for tests.

Exit gate:

make index-document-model-check

9.2 Parsers And Extractors

Required behavior:

• HTML fixture parsing for accepted corpus;
• Markdown fixture parsing;
• RSS or feed-shaped fixture parsing if still in accepted behavior;
• link, markdown, JSON, citation, and section extraction;
• malformed input diagnostics.

Exit gate:

make index-extraction-check

9.3 Terminal Rendering And TUI Command Model

Required behavior:

• plain rendering;
• profile rendering;
• TUI command parser;
• interaction command output for capture preview/save and extraction actions;
• no terminal escape behavior without tests.

Exit gate:

make index-render-check

9.4 Compatibility Pack, Auth Assist, Challenge, Adapter, And IDX Logic

Required behavior:

• compatibility-pack parse/lint/sign/verify/install/update/list/remove/rollback

logic with fake file runtime;

• auth cookie bundle import/export/inspect/diagnose logic;
• challenge diagnostics;
• IDX lint;
• adapter check/scaffold/diff.

Exit gate:

make index-policy-tools-check

Parent exit gate:

make index-pure-check

Milestone 10: Index Runtime Replacement

Status: done.

Goal: make the Index CLI production-ready in 0x0.

Submilestones:

10.1 Index CLI Binary

Required behavior:

• argv dispatch;
• stdout/stderr/exit codes;
• help/version/quickstart/doctor/paths;
• exact or documented parity for accepted command corpus.

Exit gate:

make index-cli-check

10.2 File-Backed Commands

Required behavior:

• local file transform;
• save markdown/json;
• batch extraction;
• capture redact/preview/validate/catalog;
• shelf save/list/show/tag/note/search;
• artifact inspect.

Exit gate:

make index-file-runtime-check

10.3 Network And Browser Commands

Required behavior:

• URL fetch through 0x0 HTTP client runtime;
• cache behavior;
• browser snapshot through 0x0 browser runtime boundary;
• timeout and failure diagnostics.

Exit gate:

make index-network-runtime-check

10.4 Index Package And Release

Required behavior:

• installable native binary;
• app source package;
• vendored library lockfile;
• release manifest and hashes;
• no jmp0x1b runner in normal path;
• rollback to previous Index package.

Exit gate:

make index-release-check

Parent exit gate:

make index-full-check

Milestone 11: Kukulkan Pure Package Rewrite

Status: done.

Goal: rewrite Kukulkan app-owned packages that do not require live runtime

effects first.

Submilestones:

11.1 API Contract, Client, And Events

Required behavior:

• route contract models;
• request/response schemas;
• client request construction;
• event envelope construction;
• serde round trips;
• compatibility snapshots.

Exit gate:

make kukulkan-contracts-check

11.2 Compliance Domain

Required behavior:

• supplier compliance model;
• audit, QMS, requirement trace, evidence, NCR/CAPA, document-control, and

onboarding rules;

• deterministic fixtures and error tests.

Exit gate:

make kukulkan-compliance-check

11.3 Geospatial Domain

Required behavior:

• AOI, raster, vector, STAC, EO ingest, hydromet, risk models, alerts, drone

artifact, change detection, geostats, and timeseries contracts;

• deterministic domain fixtures;
• no provider network calls in pure tests.

Exit gate:

make kukulkan-geospatial-check

11.4 Service Stack And SaaS Orchestration

Required behavior:

• auth, workflow, events, rate limit, TLS posture, metrics, logging, health,

scheduler, retry, provenance, secrets, tracing, OIDC, object store, search,

notify, job runtime, observability, and backup/restore plans;

• fake adapters for pure package gates;
• tenant/workspace orchestration rules.

Exit gate:

make kukulkan-service-core-check

Parent exit gate:

make kukulkan-pure-check

Milestone 12: Kukulkan API Runtime Replacement

Status: done.

Goal: replace kukulkan_api_runtime with a 0x0 production API process.

Submilestones:

12.1 API Config And Boot

Required behavior:

• environment/config loading;
• bind/TLS/backlog settings;
• tenant/workspace boot state;
• runtime startup diagnostics;
• managed PID/log behavior.

Exit gate:

make kukulkan-api-boot-check

12.2 API Routing And Responses

Required behavior:

• /healthz;
• /readyz;
• /api/v1;
• auth routes;
• compliance action routes;
• onboarding routes;
• geospatial ingest and alert routes;
• dashboard/history routes;
• stable JSON responses.

Exit gate:

make kukulkan-api-routes-check

12.3 Auth, Authorization, And Session Runtime

Required behavior:

• OIDC fail-closed exchange;
• valid local OIDC probe;
• session envelope;
• role checks;
• tenant/workspace membership checks;
• idempotency key policy.

Exit gate:

make kukulkan-api-auth-check

12.4 Database-Backed Workflows

Required behavior:

• Postgres-backed metrics;
• compliance mutations;
• geospatial provider sync;
• audit/provenance rows;
• fallback behavior when database is unavailable;
• migration/seed gate.

Exit gate:

make kukulkan-api-db-check

12.5 API Runtime Probes

Required behavior:

• start/stop/force-stop;
• HTTP readiness probes;
• restart continuity;
• Docker dependency seed path;
• single-job default and timeout budgets.

Exit gate:

make kukulkan-api-runtime-check

Parent exit gate:

make kukulkan-api-full-check

Milestone 13: Kukulkan UI, LiveView, And Browser Runtime Replacement

Status: done.

Goal: replace kukulkan_web_ui with a 0x0 production UI process.

Submilestones:

13.1 UI Static And Template Runtime

Required behavior:

• HTML shell templates;
• lane cards, onboarding rows, operations rows, and dashboard fragments;
• asset manifest;
• route continuity with API contracts.

Exit gate:

make kukulkan-ui-template-check

13.2 LiveView Runtime

Required behavior:

• /live/readiness.json;
• /live document;
• /live/websocket;
• mount/join;
• event dispatch;
• diff response;
• heartbeat/reconnect;
• malformed WebSocket rejection.

Exit gate:

make kukulkan-live-check

13.3 Browser Runtime Bridge

Required behavior:

• browser runtime client profile;
• API URL binding;
• OIDC browser callback path;
• event stream path;
• polling fallback;
• browser-visible auth/session state.

Exit gate:

make kukulkan-browser-runtime-bridge-check

13.4 Browser, WCAG, Load, And Security Gates

Required behavior:

• Playwright browser e2e remains opt-in until resource budgeted;
• Axe/WCAG report generation;
• load/perf probe;
• security review report;
• all reports written under .runtime/reports/ and copied to docs only by an

explicit update target.

Exit gate:

make kukulkan-browser-quality-check

Parent exit gate:

make kukulkan-ui-full-check

Milestone 14: Kukulkan Deployment And Operations Replacement

Status: done.

Goal: package and deploy Kukulkan from the 0x0 app artifacts.

Submilestones:

14.1 Dependency Runtime Profiles

Required behavior:

• local process mode;
• Docker Compose integration mode;
• external managed service mode;
• clear profile matrix for Postgres, Keycloak, MinIO, Meilisearch, Mailpit,

Jaeger, object store, and search.

Exit gate:

make kukulkan-dependency-profile-check

14.2 Container And Image Build

Required behavior:

• API image;
• UI image;
• release labels and hashes;
• no jmp0x1b runner in production image;
• healthcheck command.

Exit gate:

make kukulkan-image-check

14.3 Helm And Kubernetes

Required behavior:

• Helm lint/template for dev, staging, and prod;
• Deployment, Service, NetworkPolicy, HPA, ConfigMap, Secret reference, and

readiness/liveness probes;

• k3s/kubectl probe remains opt-in until resource budgeted.

Exit gate:

make kukulkan-k8s-check

14.4 Remote App Deployment

Required behavior:

• dry-run deploy;
• rsync/ssh deploy with explicit excludes;
• systemd service update;
• app probe;
• rollback to previous release.

Exit gate:

make kukulkan-app-deploy-check

Parent exit gate:

make kukulkan-deploy-check

Milestone 15: Final Cutover And Legacy Removal

Status: done.

Goal: make the 0x0 applications the normal production path and remove legacy

runtime assumptions.

Submilestones:

15.1 Production Cutover Matrix

Required behavior:

• exact list of commands and routes switched to 0x0;
• exact list of host tools still required;
• exact rollback command;
• exact acceptance artifacts and hashes.

Exit gate:

make apps-cutover-matrix-check

15.2 Legacy Runner Removal From Normal Path

Required behavior:

• no production Make target invokes jmp0x1b for Index or Kukulkan;
• no app release package contains jmp0x1b source as the runtime implementation;
• legacy source references are retained only in archived parity manifests.

Exit gate:

make apps-legacy-runner-check

15.3 Release Candidate

Required behavior:

• Index release candidate;
• Kukulkan release candidate;
• source, binary, lockfile, fixture, report, and image hashes;
• install/upgrade/rollback smoke tests;
• resource reports for heavy gates.

Exit gate:

make apps-release-candidate-check

15.4 Production Acceptance

Required behavior:

• Index production package runs the accepted CLI corpus;
• Kukulkan production package passes API, UI, browser, quality, dependency, and

deploy acceptance gates;

• docs describe the 0x0-only normal path;
• operator runbook covers startup, stop, backup, restore, logs, probes,

rollback, and known external dependencies.

Exit gate:

make apps-production-acceptance-check

Parent exit gate:

make apps-production-replacement-check

Recommended Implementation Order

1. Milestone 0: make the current app behavior measurable.

2. Milestone 1: create the app workspace so source has a stable home.

3. Milestone 3: add safe gates before any large compile or docs work.

4. Milestone 2: establish source rewrite conventions and lint rules.

5. Milestones 4 through 8: implement the runtime boundary needed by apps.

6. Milestones 9 and 10: rewrite and ship Index.

7. Milestones 11 through 14: rewrite and ship Kukulkan.

8. Milestone 15: cut over and remove legacy runtime assumptions.

Index should go first because it is smaller and exercises file, CLI, HTTP

client, browser snapshot, and local persistence without requiring the full

Kukulkan service stack. Kukulkan should follow once HTTP server, WebSocket,

database, subprocess, and deployment boundaries are proven.

Blockers To Resolve Before Full Rewrite

• Package/workspace support is not yet enough for Kukulkan's multi-package app.
• web, cli, and jmp0x1b-shaped fs libraries expose compatibility

constructors where the applications need real effects.

• HTTP client, HTTP server, WebSocket, subprocess, browser, database, and

deployment adapters need real runtime implementations.

• App tests need resource-safe runners before large packages are ported.
• make docs-check must not be part of the default workflow until the session

break is fixed or replaced by a safe targeted docs gate.

• Heavy browser, Docker, Kubernetes, and release gates need timeouts and

resource budgets before they become standing gates.

Completion Signal

This roadmap is complete when:

• make apps-production-replacement-check passes;
• Index and Kukulkan release artifacts are produced from 0x0 source;
• normal Index and Kukulkan runtime paths do not invoke jmp0x1b;
• accepted command, route, browser, deployment, and rollback behavior is covered

by executable gates;

• the user can continue development with targeted, resource-safe commands rather

than risky full sweeps.