Index And Kukulkan Real Production Rewrite Roadmap

This roadmap is the implementation plan for rewriting Index and Kukulkan as

real production 0x0 applications.

It starts after the repository-level replacement foundation is present. The

existing docs/index-kukulkan-production-roadmap.html created workspace,

runtime-boundary, release, cutover, and safety scaffolding. This roadmap is

stricter: a milestone is not complete because a surface exists, a schema exists,

a fixed fixture passes, or a host script simulates behavior. Completion requires

production behavior exercised by production-shaped gates.

Non-Negotiable Scope

In scope:

• replace Index app logic with app-owned .0x0 source;
• replace Kukulkan app package logic with app-owned .0x0 source;
• replace Python release probes with production release artifacts generated from

the 0x0 app build path;

• replace fixed-response runtime probes with real request handling and real

error behavior;

• replace fake persistence, auth, object-store, search, email, observability,

and deployment behavior with production implementations plus isolated test

adapters;

• migrate accepted behavioral tests from the source applications into this repo;
• make the normal production path independent from the old jmp0x1b source and

runner;

• keep every default gate resource-safe for the user session.

Out of scope:

• adding new placeholder packages;
• treating constructor-only modules as complete domain rewrites;
• treating static Docker, Helm, or systemd files as deployment readiness without

build and smoke gates;

• keeping old source as a production fallback;
• running unsafe broad gates by default.

Disallowed Done Signals

These are useful during bring-up, but they do not complete a milestone:

• a function that only returns a tagged list;
• a route that returns a fixed fixture regardless of input;
• a release executable whose production app logic is implemented in Python;
• a checker that duplicates app behavior instead of testing the .0x0 app;
• a fake adapter used as the only passing path;
• a generated manifest with no install, run, rollback, and hash verification;
• a browser, database, cluster, or deploy claim without an executable gate.

Test fakes are allowed only when a matching production adapter exists and the

fake is clearly scoped to deterministic tests.

Session Safety Rules

The default rewrite path must not repeat known session-breaking behavior.

• Do not run make docs-check as part of this roadmap's default gates.
• Do not run broad compiler sweeps or parallel compilers by default.
• Default gates must be single-job, timeout-bounded, and explicit about process

cleanup.

• Browser, Docker, Helm, kubectl, k3s, load, and external service gates stay

opt-in until resource budgets are recorded.

• Runtime gates must write PID files and have stop and force-stop paths before

joining a parent gate.

• Every milestone must have at least one dedicated commit.

Production Definition

Index is production-ready only when:

• its command implementation is .0x0 app logic;
• accepted CLI commands run through the same release artifact operators install;
• file, config, cache, shelf, capture, network, browser, auth assist,

compatibility pack, and artifact-inspection behavior are implemented rather

than simulated;

• failures have stable diagnostics and nonzero exits where appropriate;
• package hashes, rollback metadata, and install smoke tests are reproducible;
• the old source is used only as archived parity evidence.

Kukulkan is production-ready only when:

• app-owned packages contain real .0x0 domain and runtime logic;
• HTTP, routing, WebSocket/LiveView, auth, sessions, tenant/workspace checks,

idempotency, database workflows, background jobs, object store, search, email,

observability, backup, restore, and deployment paths are executable;

• API and UI release artifacts are built from the 0x0 app path;
• browser, accessibility, load, security, container, Kubernetes, and remote

deploy gates are available with documented resource modes;

• rollback and operational runbooks have been proven by smoke tests.

Milestone 0: Production Gap Inventory

Status: done.

Goal: replace "we have a surface" with an exact list of behavior that still has

to become production implementation.

Required work:

• audit every apps/index/src/*.0x0 function and mark it as:

- production implementation;

- partial implementation;

- constructor-only scaffold;

- obsolete scaffold to delete;

• audit every Kukulkan package function with the same classification;
• audit every release executable and identify app logic implemented outside

.0x0;

• audit every checker and separate test-only logic from production app logic;
• produce a source-to-target behavior map for Index and every Kukulkan package;
• mark all fake adapters and fixed-response routes with their replacement

milestone.

Artifacts:

• apps/real-rewrite-gap.tsv;
• docs/apps-real-production-gap.html;
• updated apps/production-acceptance.tsv with only production-ready gates.

Exit gate:

make apps-real-rewrite-gap-check

Completion rule: the gate must fail if any constructor-only scaffold is listed

as production-ready.

Milestone 1: Production 0x0 App Build Path

Status: done.

Goal: make production app artifacts come from the 0x0 build path, not Python

probes or checker-side behavior.

Required work:

• define app build targets for Index, Kukulkan API, and Kukulkan UI;
• decide the production artifact format for app executables:

- compiled native executable when supported;

- or a supported 0x0 runtime launcher with app bytecode/source package;

• make release manifests distinguish production artifacts from test harnesses;
• move checker-only Python scripts out of the production runtime path;
• add hash verification for source, lockfiles, runtime libraries, and binaries;
• add install, upgrade, and rollback smoke tests for built app artifacts.

Artifacts:

• apps/build-manifest.tsv;
• apps/index/release/production-manifest.tsv;
• apps/kukulkan/release/production-manifest.tsv;
• production artifact hashes under app release directories.

Exit gate:

make apps-production-build-check

Completion rule: the gate must fail if production app behavior depends on a

Python release shim.

Milestone 2: Runtime Capability Implementations

Status: done.

Goal: replace capability declarations with production runtime implementations

that app code can actually call.

Submilestones:

2.1 Local Runtime

Required behavior:

• filesystem read/write/stat/list/copy/move/delete;
• config/cache/state path resolution;
• environment and argv handling;
• subprocess execution with timeout, stdout/stderr capture, exit code, and

process cleanup;

• structured diagnostics for permission, missing file, invalid path, and timeout

failures.

Exit gate:

make runtime-local-production-check

2.2 Network And Browser Runtime

Required behavior:

• HTTP client with method, headers, body, redirect policy, timeout, TLS errors,

and stable failure diagnostics;

• browser snapshot runtime with HTML capture, DOM text extraction, screenshot or

artifact metadata, timeout, and redaction;

• capture artifact format with validation and hash verification.

Exit gate:

make runtime-network-browser-production-check

2.3 Server And Live Runtime

Required behavior:

• HTTP server request accept loop;
• routing by method/path;
• JSON request/response handling;
• static asset serving;
• WebSocket upgrade and frame handling;
• LiveView-compatible mount, join, event, diff, heartbeat, reconnect, and reject

behavior.

Exit gate:

make runtime-server-live-production-check

2.4 Service Runtime

Required behavior:

• Postgres connection, query, transaction, migration, and retry behavior;
• OIDC authorization-code flow and fail-closed token exchange;
• object-store put/get/list/delete;
• search indexing/querying;
• email notification;
• metrics, logs, traces, health checks;
• backup and restore adapters;
• background job queue and scheduler.

Exit gate:

make runtime-service-production-check

Parent gate:

make runtime-production-capabilities-check

Completion rule: each production adapter must have at least one deterministic

test adapter and one production-shaped smoke path.

Milestone 3: Accepted Test Corpus Migration

Status: done.

Goal: migrate behavior tests from the source applications into this repo so the

rewrite is judged by real behavior, not handpicked examples.

Required work:

• migrate Index CLI, parser, capture, shelf, auth assist, compatibility pack,

adapter, and browser snapshot tests;

• migrate Kukulkan package tests for API schema behavior, client behavior,

events, compliance, geospatial, service stack, orchestration, API runtime, and

UI runtime;

• convert fixture data to neutral production fixtures, not old source snippets;
• classify every parity change as exact behavior or intentional 0x0 behavior;
• remove pending-0x0-output status from accepted production corpus rows;
• add failure-case fixtures for malformed inputs, auth failure, unavailable

dependencies, and timeout behavior.

Artifacts:

• apps/index/tests/*.0x0;
• apps/kukulkan/packages/*/tests/*.0x0;
• apps/accepted-behavior-corpus.tsv;
• apps/intentional-behavior-differences.html.

Exit gate:

make apps-accepted-corpus-check

Completion rule: a behavior is not accepted unless a migrated test executes

against the production app path.

Milestone 4: Index Core Rewrite

Status: done.

Goal: implement Index's pure application logic in .0x0.

Required behavior:

• document model with source metadata, headings, blocks, links, citations,

sections, actions, and diagnostics;

• HTML parser behavior required by the accepted corpus;
• Markdown parser and renderer behavior;
• feed parser behavior;
• terminal/plain/JSON/Markdown renderers;
• command parser and normalized command model;
• stable diagnostics for malformed documents and invalid command combinations;
• no checker-side parser duplication as the production implementation.

Artifacts:

• production implementations in apps/index/src/*.0x0;
• Index core tests in apps/index/tests/;
• fixtures under apps/index/fixtures/production/.

Exit gate:

make index-core-production-check

Completion rule: the gate must run app code, not reimplement parsing in Python.

Milestone 5: Index State, Capture, And Local Effects Rewrite

Status: done.

Goal: implement Index behavior that touches local state and local artifacts.

Required behavior:

• config/cache/state path discovery;
• shelf save/list/show/search;
• save-to-file commands;
• capture artifact creation, preview, validation, and inspection;
• redaction policy for URLs, headers, cookies, tokens, and local secrets;
• artifact hash and provenance metadata;
• local failure diagnostics for permission and missing path errors.

Artifacts:

• state/capture modules in apps/index/src/;
• production fixture artifacts;
• shelf/capture acceptance tests.

Exit gate:

make index-local-effects-production-check

Completion rule: the gate must create and validate real files in a temporary

state directory and leave no untracked runtime state.

Milestone 6: Index Network, Browser, Auth, And Compatibility Rewrite

Status: done.

Goal: implement Index features that interact with network and browser-facing

workflows.

Required behavior:

• HTTP fetch command path with timeout and error diagnostics;
• browser snapshot command path;
• auth assist import/inspect/export;
• challenge diagnosis;
• compatibility pack install/update/list/verify;
• adapter check/scaffold/diff;
• IDX lint and recovery behavior;
• benchmark command with bounded resource reporting.

Artifacts:

• production Index modules for network, browser, auth assist, compatibility

packs, adapters, IDX, and benchmark behavior;

• deterministic local HTTP/browser fixtures;
• accepted network/browser corpus tests.

Exit gate:

make index-network-production-check

Completion rule: no external network is required by default, but the code path

must use the same runtime interface that production uses.

Milestone 7: Index Production Release

Status: done.

Goal: make Index installable and supportable as a real production CLI.

Required behavior:

• production index artifact built from the 0x0 app path;
• package layout with source, lockfile, binary/runtime artifact, docs, fixtures,

hashes, and rollback metadata;

• install and upgrade smoke tests;
• CLI corpus run against the release artifact;
• version, help, doctor, paths, and diagnostics stable for operators;
• no old source or runner in the normal package path.

Artifacts:

• apps/index/release/production-manifest.tsv;
• apps/index/release/SHA256SUMS;
• apps/index/release/rollback.tsv;
• operator-facing Index documentation.

Exit gate:

make index-production-release-check

Parent gate:

make index-real-production-check

Completion rule: Index is complete only when the release artifact passes the

accepted CLI corpus from a clean checkout.

Milestone 8: Kukulkan Shared Package Rewrite

Status: done.

Goal: implement the shared Kukulkan packages as real app logic.

Required behavior:

• API schema validation for requests, responses, errors, and versioning;
• client request construction with retries, idempotency, auth headers, and error

normalization;

• event envelopes, append/read behavior, serialization, ordering, and

deduplication;

• compatibility snapshots produced from real schemas and event definitions;
• package tests that execute .0x0 package code.

Artifacts:

• production code in:

- jmp0x1b_kukulkan_api_contract/src/lib.0x0;

- jmp0x1b_kukulkan_client/src/lib.0x0;

- jmp0x1b_kukulkan_events/src/lib.0x0;

• migrated tests and fixtures for each package.

Exit gate:

make kukulkan-shared-packages-production-check

Completion rule: tagged constructors are insufficient; validation and

serialization behavior must run.

Milestone 9: Kukulkan Compliance Domain Rewrite

Status: done.

Goal: implement supplier compliance behavior as production domain logic.

Required behavior:

• supplier lifecycle and compliance status model;
• audit records and audit history;
• QMS controls and evidence linkage;
• requirement traceability;
• evidence ingestion, hash, media-type, retention, and validation;
• NCR/CAPA workflow;
• document-control workflow;
• onboarding decisions and rejection reasons;
• deterministic error model for missing, conflicting, expired, and invalid

evidence.

Artifacts:

• production compliance modules;
• migrated compliance tests;
• production fixtures for suppliers, requirements, evidence, audits, and CAPA.

Exit gate:

make kukulkan-compliance-production-check

Completion rule: every state transition must be tested with accepted valid and

invalid inputs.

Milestone 10: Kukulkan Geospatial Domain Rewrite

Status: done.

Goal: implement geospatial behavior as production domain logic.

Required behavior:

• AOI geometry validation and CRS handling;
• raster and vector metadata validation;
• STAC item validation;
• EO ingest planning and checksum validation;
• hydromet series handling;
• risk model input validation and scoring;
• alert generation and severity rules;
• drone artifact metadata;
• change detection;
• geostats;
• timeseries aggregation;
• provider-independent fixtures and deterministic provider test adapters.

Artifacts:

• production geospatial modules;
• migrated geospatial tests;
• local provider fixtures for EO, hydromet, drone, raster, vector, and STAC.

Exit gate:

make kukulkan-geospatial-production-check

Completion rule: no provider network call is required by default, but provider

adapter boundaries must be the production boundaries.

Milestone 11: Kukulkan Service And SaaS Rewrite

Status: done.

Goal: implement service orchestration and tenant/workspace behavior.

Required behavior:

• auth and role model;
• tenant, workspace, membership, and invitation model;
• workflow engine behavior;
• event bus integration;
• rate limiting;
• TLS posture configuration;
• metrics/logging/tracing plan execution;
• health readiness and liveness behavior;
• scheduler and retry behavior;
• provenance and secret reference handling;
• object-store/search/notify/job/backup/restore orchestration.

Artifacts:

• production service-stack and SaaS modules;
• migrated orchestration tests;
• deterministic service adapter tests and production adapter smoke tests.

Exit gate:

make kukulkan-service-saas-production-check

Completion rule: tenant isolation and authorization failures must be tested

before this milestone can pass.

Milestone 12: Kukulkan API Production Runtime

Status: done.

Goal: replace the API runtime probe with a production API process.

Required behavior:

• config loading with validation and redacted diagnostics;
• HTTP listener using the production server runtime;
• route table for health, readiness, API root, auth, compliance, onboarding,

geospatial, dashboard, history, and admin surfaces;

• JSON parsing, validation, and stable error responses;
• OIDC fail-closed exchange;
• session envelope, role checks, tenant/workspace membership checks, and

idempotency policy;

• database-backed metrics, mutations, provider sync, audit, and provenance;
• unavailable dependency fallback behavior;
• migration and seed gate;
• start, stop, restart, and readiness probes with PID/log cleanup.

Artifacts:

• production API runtime .0x0 source;
• API release artifact generated from the 0x0 app build path;
• API runtime tests and fixtures.

Exit gate:

make kukulkan-api-production-check

Completion rule: fixed JSON responses are insufficient; routes must execute the

domain, auth, and persistence code paths.

Milestone 13: Kukulkan UI And Live Runtime

Status: done.

Goal: replace the UI runtime probe with a production UI process.

Required behavior:

• production HTML shell templates and static assets;
• dashboard, lane, onboarding, operations, audit, and readiness fragments;
• API client binding and browser runtime configuration;
• OIDC browser callback path;
• event stream and polling fallback;
• LiveView-compatible mount, join, event dispatch, diff response, heartbeat,

reconnect, and malformed WebSocket rejection;

• browser-visible auth and session state;
• accessibility-safe markup and security headers.

Artifacts:

• production UI .0x0 source;
• UI release artifact generated from the 0x0 app build path;
• UI, LiveView, browser bridge, and accessibility tests.

Exit gate:

make kukulkan-ui-production-check

Completion rule: static strings do not pass unless they are rendered through the

production template and runtime path.

Milestone 14: Kukulkan Production Integrations

Status: done.

Goal: make external integrations real and operable.

Required behavior:

• Postgres migrations, seeds, transactions, backups, and restores;
• Keycloak or OIDC provider setup and local valid/fail-closed probes;
• object-store bucket setup and object lifecycle tests;
• search index setup, indexing, and query tests;
• email delivery adapter with local and production profiles;
• tracing and metrics export;
• job runtime with retry, dead-letter, and idempotency behavior;
• dependency profile matrix for local process, Docker Compose, and external

managed services;

• resource reports for every heavy integration gate.

Artifacts:

• integration modules and adapter configs;
• Docker Compose integration profile;
• migration and seed files;
• backup/restore fixtures;
• resource budget reports.

Exit gate:

make kukulkan-integrations-production-check

Completion rule: every fake adapter must have a production adapter and a smoke

gate, even if the production gate remains opt-in by default.

Milestone 15: Kukulkan Deployment Productionization

Status: done.

Goal: make Kukulkan deployable through production artifacts, not static plans.

Required behavior:

• API and UI image builds with hashes and labels;
• image smoke tests that run health and readiness probes;
• Helm lint/template for dev, staging, and prod;
• Kubernetes objects for Deployment, Service, NetworkPolicy, HPA, ConfigMap,

Secret references, readiness probes, and liveness probes;

• optional k3s/kubectl smoke path with resource budget;
• remote dry-run, deploy, probe, and rollback;
• systemd service installation and restart behavior;
• deployment docs with exact operator commands.

Artifacts:

• built image hash reports;
• Helm render reports;
• remote deploy smoke reports;
• updated operator runbook.

Exit gate:

make kukulkan-deployment-production-check

Completion rule: a static YAML file is insufficient; build/render/smoke gates

must prove the artifact path.

Milestone 16: Security, Reliability, And Performance Hardening

Status: done.

Goal: prove the rewritten apps can survive production failure modes.

Required behavior:

• threat model for Index and Kukulkan;
• secret redaction across logs, captures, artifacts, and diagnostics;
• auth and authorization negative tests;
• dependency outage tests;
• retry and timeout tests;
• malformed input tests;
• load/performance budgets;
• browser accessibility and security report generation;
• data retention and cleanup policies;
• crash/restart and rollback drills.

Artifacts:

• docs/security/index-kukulkan-threat-model.html;
• .runtime/reports/ generation targets;
• committed resource budget baselines;
• production incident drill checklist.

Exit gate:

make apps-security-reliability-production-check

Completion rule: all high-severity findings must be fixed or explicitly

accepted with mitigation before release.

Milestone 17: Final Production Cutover

Status: done.

Goal: make the real rewrite the only normal path.

Required behavior:

• Index production package passes the accepted CLI corpus;
• Kukulkan production package passes package, API, UI, integration, deployment,

browser, accessibility, load, and security gates;

• no production Make target or release package invokes old source or old runner;
• release candidate includes source, lockfiles, binaries/runtime artifacts,

fixtures, report hashes, image hashes, deployment artifacts, and rollback

metadata;

• operator runbook has startup, stop, backup, restore, logs, probes, rollback,

dependency profile, and incident drill sections;

• archived parity manifests remain read-only evidence only.

Artifacts:

• final release-candidate manifest and hashes;
• production acceptance report;
• updated runbook;
• final cutover matrix.

Exit gate:

make apps-real-production-rewrite-check

Completion rule: the repository must be able to prove production readiness from

a clean checkout using only documented gates and documented opt-in heavy gates.

Recommended Execution Order

1. Milestone 0: expose every scaffold and fake that must disappear.

2. Milestones 1-3: make the build path, runtime capabilities, and accepted

corpus real enough to judge implementation work.

3. Milestones 4-7: finish Index end to end.

4. Milestones 8-11: finish Kukulkan package and domain logic.

5. Milestones 12-15: finish Kukulkan runtime, integrations, and deployment.

6. Milestone 16: harden security, reliability, and performance.

7. Milestone 17: cut over only after all production gates pass.

Completion Signal

The rewrite is complete when:

• all milestones are Status: done;
• every milestone has at least one dedicated commit;
• make index-real-production-check passes;
• make kukulkan-production-check passes;
• make apps-real-production-rewrite-check passes;
• no production artifact depends on old app source or a compatibility runner;
• the operator runbooks describe only the production 0x0 path, with old source

mentioned only as archived parity evidence.