Implementation Handover

This is the consolidated handover for Phases 0 through 6 of the MORK and Surface delivery plan. It is the starting point for a coding agent, maintainer, or network-enabled validation environment. The canonical phase plan remains plan-morkSurfaceImplementation.prompt.md.

Status [DEAD]

Phases 0 through 6 are authoring complete. Their source, contracts, tests, CI wiring, ADRs, architecture documentation, and phase handoffs exist. None is validated complete. This authoring host could run JSON parsing, editor diagnostics, Markdown-link checks, and git diff --check, but did not have Java 21, Maven, a usable Python interpreter, Docker on PATH, resolved Yarn dependencies, Playwright browsers, or network access.

This handover has been sidelined in favour of re-architecting the platform layers now.

Reading Order

1. Read the canonical plan for scope, completion criteria, and phase order.
2. Read the toolchain guide, Windows and WSL guidance, and offline handoff procedure.
3. Read the architecture map, then the phase architecture guides listed below.
4. Read the relevant ADRs before changing a boundary. The complete catalogue is ADR README.
5. Run one phase handoff at a time in a network-enabled environment. Do not regenerate lockfiles, images, or generated assets without reporting the resulting changes.

Core Boundaries

Ontology and compiler sources
  -> immutable graph references
  -> policy, revision, and review control planes
  -> RabbitMQ worker boundaries
  -> immutable outputs and MORK staging graphs
  -> semantic release intent
  -> external release stack

RDF remains the semantic source of truth. PostgreSQL holds operational state. RabbitMQ carries graph-reference jobs and results, never RDF payloads, credentials, browser tokens, or executable commands. The control plane authorizes tenant and project scope before resolving a graph. The worker materializes canonical graph bytes and verifies the referenced hash before invoking a compiler.

Phase 0 and 1

Purpose: repository foundation and shared semantic platform.

The Phase 1 deployment gaps are PostgreSQL-backed outbox validation, Testcontainers, and an end-to-end Java to RabbitMQ to Python worker retry test.

Phase 2

Purpose: Surface Promotion and Index lifecycle, graph-family ownership, worker execution, and authoring UI.

Normative Surface semantics remain in ontology/surface/README.md. Existing Promotion, Index, parity, invalidation, and lowering algorithms remain in tools/surface. The control plane must not reimplement them.

Phase 3

Purpose: release-stack-neutral semantic release integration and OCI reference implementation.

LATTICE creates and verifies semantic intent. The release stack packages, signs, stores, promotes, restores, and retains artifacts. A valid signature does not prove semantic validity, and passed semantic gates do not prove release-stack provenance.

Phase 4

Purpose: deterministic Surface Projection lowering to immutable MORK staging.

All Projection policies are deterministic-only and prohibit LLM completion. Lowering accepts only graph references and a staging namespace. It rejects active mapping targets. MORK governance, not Surface, owns activation.

Phase 5

Purpose: immutable MORK review snapshots, six decision semantics, role-safe evidence, and the Review Bench.

Domain Stewards can receive only review-safe evidence projections. They must not receive MCN, lint diagnostics, pack internals, MORK syntax, or cross-tenant content. RESHAPE produces structural feedback and must never change projection statistics.

Phase 6

Purpose: replayable review queue, calibration-gated bulk action, governance ledger, and safe Atlas, Boundary, Ledger, and Pack fixtures.

Queue ordering is replayable. Bulk confirmation requires a passing calibration gate for the exact pack, profile, and model. Named ontology axioms reopen affected approvals without deleting prior history. Template exceptions require engineering review. Pack Studio and Domain Steward projections must not expose source syntax or technical internals.

Validation Sequence

Run the phase handoffs in order. The current codebase has a generated or placeholder Yarn lockfile that must be regenerated and reviewed with the committed package manifests before frontend validation. Do not claim a lockfile is valid until that occurs.

mise install
mise run bootstrap
mise run check
mise run test

mvn -f platform/pom.xml verify
python -m pytest workers/tests
python -m unittest surface.test_surface mork_compilers.test_mork_compilers -v
python -m tools.phase8_conformance

yarn install
yarn check
yarn build
yarn playwright install --with-deps chromium
yarn test

Apply these migrations to the reference PostgreSQL database before integration tests:

platform/surface-workflow/src/main/resources/db/migration/V1__surface_revision_ledger.sql
platform/surface-workflow/src/main/resources/db/migration/V2__surface_graph_artifact_registry.sql
platform/release-integration/src/main/resources/db/migration/V1__release_ledger.sql
workers/sql/V1__processed_surface_jobs.sql
workers/sql/V2__mork_review_ledger.sql

Start reference services using mise run services:up. Exercise Fuseki graph materialization, RabbitMQ acknowledgement, retry and dead-letter behavior, PostgreSQL persistence, OCI registry packaging and restore, and role-restricted review projections. Stop services with mise run services:down and use the phase handoffs for fixture and cleanup specifics.

Validation Evidence and Gaps

Validation evidence belongs in CI or release records, not this document. The expected offsite acceptance conditions are:

• Existing Surface parity and Phase 8 conformance pass through the worker path.
• Stale Surface revisions and MORK review snapshots conflict safely.
• Surface output, MORK staging, and release artifacts are immutable and digest-addressed.
• The OCI reference signs, publishes, verifies, exports, restores, and records a receipt by digest.
• Projection lowering cannot write active MORK mappings.
• Domain Steward, Pack Studio, and review APIs do not leak restricted technical content.
• Queue order is replayable, and bulk confirmation remains blocked without matching calibration.

Do Not Break

• Do not move or rewrite normative ontology directories. Layer READMEs remain normative.
• Do not replace native package managers with mise.
• Do not place RDF, credentials, browser tokens, file paths, shell commands, or mutable tags in worker or release contracts.
• Do not write an active MORK mapping from Surface or expose mapping activation in Surface-facing UI.
• Do not let RESHAPE alter projection statistics.
• Do not allow evidence projections for Domain Stewards to return MCN, syntax, lint diagnostics, pack internals, or cross-tenant data.
• Do not state that builds, tests, container pulls, registry operations, signing, or CI passed until evidence exists in the network-enabled environment.

Next Phase

Phase 7 begins only after validation feedback is triaged. Its scope is compiler breadth and SPC readiness: adapter conformance, MORK-to-SPC bridge contracts with isolated RabbitMQ exchanges, and independently deployable SPC behavior. Read the Phase 7 section of the canonical plan before changing its boundary.