Build closed-loop operations, replanning orchestration, and deployment freshness metadata

[recklessnode]

Objective

Build the ATOS closed-loop operations layer that connects deterministic dispatch planning to simulation execution and routes execution failures, delays, and resource changes back into explicit replanning cycles.

This issue also adds a persistent deployment footer across the web app so users can immediately tell which build they are viewing and whether it may be stale.

Part of #2. Implementation is gated on both #12 and #13 being merged.

Dependency rule

This issue may be refined now, but implementation must not begin until the final dispatch APIs from #12 and simulation/replanning APIs from #13 are merged into main.

Do not invent parallel mission, reservation, runtime-state, event, or replanning-request types.

Why this comes next

ATOS needs an explicit operating loop:

Open chits
  -> dispatch plan
  -> mission execution
  -> runtime events
  -> deficiency or replanning request
  -> revised plan
  -> continued execution

The system must preserve separation of concerns:

• dispatch decides what should happen;
• simulation records what actually happens;
• operations orchestration decides when replanning is warranted and which state crosses the boundary;
• no package silently mutates another package's state.

Required reading

Before implementation, read:

• AGENTS.md
• all accepted ADRs in docs/adr/
• docs/architecture/web-prototyping-environment.md
• docs/provenance/README.md
• Issues Epic: Build the ATOS web prototyping environment #2, Build the ATOS distributed DC power-integrity simulator and Power workspace #8, Build the ATOS interactive layout editor and recommendation preview workflow #9, Build the ATOS universal chit, asset, worker, and deterministic dispatch-planning core #12, and Build the ATOS simulation clock, mission execution engine, and event-log workspace #13
• final merged packages/dispatch
• final merged packages/simulation
• packages/scenario
• packages/power

Scope

1. Add a React-free operations package

Create a framework-independent package, preferably:

packages/operations/

Suggested modules:

packages/operations/src/
  types.ts
  replanning-policy.ts
  state-projection.ts
  orchestration.ts
  plan-diff.ts
  reservation-reconciliation.ts
  incident-correlation.ts
  metrics.ts
  fixtures.ts
  index.ts

2. Closed-loop orchestration state

Represent a deterministic operations session containing:

• scenario identity and schema version;
• planning generation number;
• current dispatch result;
• current simulation runtime state;
• active and completed missions;
• pending replanning requests;
• retained, released, superseded, and newly created reservations;
• unresolved deficiencies;
• incident/event correlation;
• operations metrics;
• stable session ID.

3. Replanning policy

Implement explicit deterministic rules for when replanning occurs.

Support triggers such as:

• mission failure;
• route blockage;
• reservation conflict;
• asset failure;
• battery reserve violation;
• power launch failure;
• station or service outage;
• missed hard deadline;
• material queue growth;
• released high-priority asset;
• operator-requested replan.

Policy output must distinguish:

• no replan;
• defer until current mission boundary;
• partial replan of affected missions/chits;
• full replan of the open queue.

4. Runtime-to-planner state projection

Build a clean adapter that converts simulation runtime state into a new dispatch input.

It must project:

• asset location;
• asset availability;
• asset health;
• battery SoC;
• current consist membership;
• active reservations;
• completed and partially fulfilled chits;
• unavailable guideway or service resources;
• current simulation time;
• current power constraints.

Do not mutate the original scenario or historical mission plans.

5. Reservation reconciliation

When replanning:

• retain reservations still valid and required;
• release reservations made obsolete by failed or superseded missions;
• prevent duplicate reservation ownership;
• preserve active in-transit occupancy;
• distinguish immutable historical reservations from current active reservations;
• emit structured reconciliation results.

6. Plan diff

Compare the previous and revised dispatch plans.

Expose:

• unchanged missions;
• delayed missions;
• cancelled missions;
• replacement missions;
• changed consist membership;
• changed route;
• changed reservations;
• newly satisfied chits;
• newly unsatisfied chits;
• score and deadline impact;
• power and energy impact;
• plain-language rationale.

7. Deficiency carry-forward

Carry unresolved deficiencies between planning generations and detect whether they are:

• resolved;
• worsened;
• unchanged;
• superseded;
• transformed into a different gate.

Aggregate recurring deficiencies into persistent infrastructure findings.

8. Incident correlation

Correlate simulation events, faults, replanning requests, plan changes, and final outcomes using stable IDs.

An incident should include:

• incident ID;
• triggering event IDs;
• affected mission/chit/asset/resource IDs;
• planning generation before and after;
• deficiency IDs;
• resolution state;
• operator-visible summary.

9. Operations metrics

Calculate deterministic metrics such as:

• replans per simulated hour;
• mission completion rate;
• on-time completion rate;
• average queue wait;
• average passenger wait;
• average cargo lateness;
• asset utilization;
• empty/repositioning movement share;
• reservation conflict rate;
• energy-related delay count;
• mission failures by cause;
• deficiency recurrence;
• planning churn.

10. Operations workspace

Add a real Operations workspace showing:

• current planning generation;
• active execution state;
• pending replanning requests;
• policy decision;
• previous-versus-revised plan diff;
• reservation reconciliation;
• incidents;
• unresolved deficiencies;
• operations metrics;
• controls to trigger a deterministic manual replan;
• map highlighting for affected missions, assets, resources, and deficiencies.

The workspace must remain usable on phone-sized layouts.

11. Deployment freshness footer

Add a persistent footer across the entire web application.

The footer must display:

• a link to the repository: https://github.com/recklessnode/ATOS;
• the deployed commit date in a readable, unambiguous format;
• a version string;
• the short commit SHA when available;
• a clear label such as ATOS build or Deployed version.

Recommended display:

ATOS v0.5.0 · commit b0928ac · 2026-07-11 · GitHub

Requirements:

• version and build metadata must be injected at build time, not manually duplicated in React components;
• support local development with truthful fallbacks such as dev, unknown, or package version;
• use environment variables or generated build metadata compatible with Vite and GitHub Pages;
• the GitHub link must open the repository page;
• the footer must appear in every workspace and remain readable on mobile;
• build metadata must be accessible to screen readers;
• do not expose secrets or private environment values;
• tests must verify rendering and fallback behavior.

The commit date should represent the commit/build being deployed, not the user's browser date.

12. Versioning policy

Document a lightweight version policy for the prototype.

At minimum:

• use the root package version or a dedicated build-version constant;
• define when minor/patch versions advance;
• keep the visible version deterministic for a given build;
• record the version in provenance and PR descriptions;
• avoid claiming semantic-version stability guarantees until the public API is mature.

13. Provenance

Follow docs/provenance/README.md.

For each commit:

• use truthful AI provenance trailers;
• append valid NDJSON records;
• record conceptual role separately from actual observable model;
• never invent model identifiers;
• do not add source-file authorship headers.

14. Screenshot policy

Screenshots remain optional.

Attempt automated capture at most once. If it is not promptly useful, document the limitation and continue.

Required tests

Add deterministic tests for at least:

• each replanning policy trigger;
• no-replan and deferred-replan behavior;
• runtime-state projection;
• partial versus full replan;
• reservation retention and release;
• active occupancy preservation;
• plan diff classification;
• deficiency carry-forward;
• incident correlation;
• deterministic repeated orchestration;
• metrics calculation;
• manual replan action;
• Operations workspace rendering;
• phone-width behavior;
• footer repository link;
• footer version string;
• footer commit date;
• footer commit SHA;
• local-development fallback metadata;
• no React imports in packages/operations.

Acceptance criteria

• Implementation begins only after Build the ATOS universal chit, asset, worker, and deterministic dispatch-planning core #12 and Build the ATOS simulation clock, mission execution engine, and event-log workspace #13 are merged.
• A React-free operations package exists.
• Simulation replanning requests can be converted into new dispatch inputs.
• Replanning policy is explicit and deterministic.
• Reservations are reconciled without losing active occupancy.
• Previous and revised plans can be compared meaningfully.
• Deficiencies persist across planning generations with status changes.
• Incidents correlate events, plans, assets, resources, and outcomes.
• Operations metrics are exposed.
• The Operations workspace provides closed-loop visibility and manual replan controls.
• Every page displays the deployment freshness footer.
• The footer links to the ATOS GitHub repository.
• The footer shows a truthful commit date, version string, and short SHA or explicit fallback.
• Build metadata is injected safely at build time.
• npm test, npm run lint, npm run build, and VITE_BASE_PATH=/ATOS/ npm run build pass.
• GitHub Pages remains functional.
• Provenance records are present and truthful.

Non-goals

• hidden replanning inside simulation;
• continuous physics;
• real hardware control;
• PostgreSQL persistence;
• authentication;
• multiplayer operations;
• automatic physical layout mutation;
• globally optimal scheduling guarantees;
• real-time operational guarantees;
• telemetry ingestion from physical devices.

PR expectations

Open a focused PR referencing this issue, #12, #13, and #2.

The PR description must include:

• operations architecture;
• replanning policy;
• runtime-to-planner projection;
• reservation reconciliation;
• plan-diff semantics;
• incident and deficiency carry-forward model;
• operations metrics;
• footer/build-metadata implementation;
• versioning policy;
• provenance summary;
• tests and results;
• known limitations;
• confirmation that /ATOS/ Pages build succeeds;
• explicit confirmation that no hardware control, backend, hidden replanning, or continuous-physics engine was added.

Do not merge the PR automatically.

[recklessnode]

Codex implementation prompt

This issue is gated on Issues #12 and #13 being merged.

When implementation begins:

• start from the latest main;
• read the merged implementations of dependency issues, not only their issue text;
• reuse existing packages and types rather than creating parallel abstractions;
• treat this issue body as the implementation contract;
• keep all orchestration logic React-free in packages/operations;
• maintain deterministic behavior and stable IDs throughout;
• perform a self-audit against every acceptance criterion before opening the PR;
• include an acceptance checklist in the PR description;
• explicitly document any intentional deviations or tradeoffs;
• run npm test, npm run lint, npm run build, and VITE_BASE_PATH=/ATOS/ npm run build before opening the PR;
• follow docs/provenance/README.md exactly, recording truthful runtime provenance and conceptual model roles separately;
• avoid repeated screenshot attempts; one attempt is sufficient if the environment supports it;
• do not merge automatically.

The final PR should include:

• architecture summary;
• package-boundary summary;
• deterministic-behavior summary;
• provenance summary;
• test results;
• Pages build confirmation;
• explicit confirmation that all non-goals remain out of scope.