# 4A — Ordered commands and recorded results

Site Coordination stores the instructions that Runtime will execute and records
their results. Execution Core retains the Run and its Attempts. The future Run
Supervisor decides which instruction is needed and calls Site Coordination's port.

## Baseline and adaptation

The baseline is architecture-reset `48e60e542`, especially
`contexts/site-coordination/adaptors/postgres/src/protocol/site-protocol-store.ts`,
`contexts/site-coordination/domain/src/site-cursor.aggregate.ts` and migration
`0011_site_command_stream.sql`.

Keep its ordered streams, saved results and transactional acknowledgement progress.
Our configured destinations are `k8s` and `slurm`, with one Site for each. Each
therefore owns one stream identified by its environment. Commands retain canonical
Run, Attempt, member and Project UUIDs. The stream's internal canonical UUID is a
storage identity and adds no Site identifier to requests.

Adapt the old shared `platform.*` tables to the skeleton's private
`pharos_site_coordination` database and restricted runtime role. Use the existing
aggregate writer, version checks and receipts. The stream is the aggregate root.
Its commands and outcomes have no independent write repository.

Identical command retries return the original command and sequence. Conflicting
input fails. Pull results are explicitly sorted, including when several writers
append concurrently.

## Flow

1. A caller supplies a command draft using the existing 1C execution fields,
   without a sequence number.
2. Site Coordination validates the draft and assigns the next sequence in its
   environment's stream. It saves the command, stream state and receipt together.
3. A caller reads commands in sequence through the query port. Pagination uses a
   read cursor and never changes acknowledgement progress.
4. The Runtime caller supplies a typed success or failure result for one command.
5. Site Coordination verifies the environment, command, sequence, operation and
   Run/Attempt/member/Project identity. It records the result, receipt and next
   acknowledgement position in one transaction.
6. The supervisor caller can read the recorded result and continue the Run's
   lifecycle in its own context.

A result acknowledges handling the command. A successful start returns the native
execution reference. It does not mean the workload has finished. Lifecycle
observation and usage belong to 4D.

## Storage

All tables below belong to `pharos_site_coordination`.

| Table | Contents |
| --- | --- |
| `pharos.aggregates`, kind `site_stream` | Environment, sequence allocation and acknowledged position. |
| `pharos.aggregates`, kind `site_progress` | Why the next command waits: its ID, sequence, code and since when (#1053). |
| `pharos.site_commands` | Immutable numbered commands, IDs and execution data. |
| `pharos.site_command_outcomes` | The recorded result for each handled command. |
| `pharos.command_receipts` | Original outcomes of stream mutations for safe replay. |

Saving a command and advancing its stream commit together. Recording a result and
advancing acknowledgement also commit together. A failed write leaves neither a
partial command nor a falsely advanced cursor. These operations emit no browser
updates. The stream has an explicit disabled projection registration.

## Protocol rules

- Commands use the six existing 1C start/cancel operations. The additional draft,
  pull and result schemas are generated with the same pinned tooling and checked
  for drift. Provider-independent application types stay separate from generated
  transport models.
- Command IDs cannot be reassigned to another environment or execution. Repeated
  identical commands retain their original sequence.
- Results must match the saved command. Repeating the same result is safe and a
  changed result is rejected.
- Acknowledgements are consecutive. A later command cannot advance progress past
  an earlier unhandled command. Rejected out-of-order results can be retried once
  the earlier result is recorded.
- Pull queries are read-only and ordered. Their pagination cursor is distinct
  from the authoritative acknowledgement position.
- Restored state and stored command/result data are validated. Corrupt identities,
  positions or envelopes fail explicitly.
- Database credentials belong only to Site Coordination. Runtime will access its
  HTTPS API through the authentication work in 4B.

## Verification evidence

Verified on 11 October 2026:

| Lane | Result |
| --- | --- |
| `pnpm verify` | Passed, including 521 Metallo unit tests, strict Mypy, Ruff, architecture, both generated-contract drift checks, Go tests/builds and deployment renders. |
| `pnpm test:integration` | Passed with 116 PostgreSQL tests, including 21 Site Coordination cases, plus RabbitMQ, all service images, sessions and the browser test. |
| Isolated dev-box k3s Job | Passed with 617 tests covering the existing Execution Core cases and the new protocol unit/PostgreSQL cases. |

The PostgreSQL cases include the complete accepted-launch to worker/planner to
saved Run to command to recorded result path for both environments. They also
exercise all six command kinds, simultaneous writers, reuse of one ID across
environments, pagination/restart, retry after a sequence gap, conflicting results,
rollback after root/receipt and child writes, corrupt saved evidence, denied DDL
and denial of cross-context database connections.

The dev-box harness created namespace `metallo-identity-dev-dkats-e658294f18a4`,
with separate context databases, restricted runtime roles and NetworkPolicies.
The test image's 132 source files were checked against this checkout. Dependency
files matched the previously qualified image and only new image layers were
transferred. The harness removed its temporary namespace after the test.

The private test report is under
`.local/metallo/identity-tests/dev-dkats/identity/metallo-identity-dev-dkats-e658294f18a4/report.json`.
Local verification logs are `/tmp/metallo-4a-verify.log`,
`/tmp/metallo-4a-integration.log` and `/tmp/metallo-4a-devbox.log`.

The 4A end-to-end lane starts with a saved Run, constructs a production 1C command,
appends and reads it through Site Coordination, records a simulated Runtime result
and reloads that result. PostgreSQL and production codecs are real. Supervisor
and Runtime callers are test fixtures. Workload, provisioning, permission and
credential owners used by existing execution tests remain test doubles.

Real Runtime authentication and HTTPS delivery belong to 4B, Runtime journals and
restart recovery to 4C, execution lifecycle and supervision to 4D/4E, and native
Kubernetes and Slurm execution to Tasks 5/6.