Port to .NET

Status: draft v2, restructured on 2026-11-07. The Python implementation is frozen on the python-archive branch. Next session: S23 (docs port, parity acceptance, release); S08 to S22a and S27 are done.

How to use these files

Rationale

Main drivers for doing this now, before investing more in the Python implementation:

1. OPC UA .NET stack 2.0 (What's new). Direct model generation for standard companion specs (plus the generator itself), and the ISA-95 libraries abstract Job Control V1/V2 (ISA95 guide). V1 has been ignored so far. MIT licensed since v2 (D-21).
2. MQTT library risk. aiomqtt is maintained by a single developer, development looks stalled, and the OpenTelemetry instrumentation for it would have to be maintained here (today a git-pinned fork, see review.md).
3. More protocols than MQTT. Northbound: NATS and AMQP. Southbound: Zenoh.
4. Drop MessagePack-RPC (transport, sidecar protocol and the msgpack serialization path).
5. Performance and strong typing. .NET Native AOT, span-based/low-allocation code paths where they matter.
6. Fully open-source components. Replace Redis with Valkey. The Linux Foundation maintains the valkey-bundle image, which pre-packages valkey-json, valkey-search and valkey-bloom.
7. HTTP endpoints in-process (health, metrics, query API) instead of the sidecar approach that works around Python shortcomings.

Planned libraries

Porting baseline

Size of the Python implementation on python-archive (about 11.4k lines of Python in src/microdcs):

Decisions

Full text in decisions.md. Status: decided, proposal (direction agreed, details open), revised (decided, replaced an earlier version).

| D-50 | decided | Machinery Jobs processor: V2 commands only, wire shapes in the extension NodeSet, responses with their own type id, recipe start atomic with the order on every entry into AllowedToStart | | D-51 | decided | Job order publisher: separate Deployment by role, poller hand-off, lease as a guard, order topic without state, ids limited to the segment rule, rebuild from documents | | D-52 | revised | SFC host: own project, job order transitions as work entries, Abort and Stop end the recipe, Pause and Resume hold and release it (S20a), equipment hold in D-57 (S27) | | D-53 | decided | SFC pull events: Selector field, waits index oldest first, one event one job; the recovery scan resends nothing with a deadline; replica tests with real containers | | D-54 | decided | HTTP surface and telemetry: OTLP only, producer and SFC spans, readiness checks for transports and Valkey, read-only /api/v1/jobs off by default | | D-55 | decided | Image publishing to GHCR from main and v* tags, cosign keyless signatures and two CycloneDX SBOM attestations per platform, manifest by role with kustomize pin, kind test in CI, Valkey island ACL user | | D-56 | decided | CI path rules in scripts/ci-changes, skips that keep required checks reportable, docs-only PRs build and analyse only, arm64 and kind on main and daily, kind reuses the x64 image | | D-57 | decided | SFC equipment hold: recipe v1.1.0 with per-action Hold and Restart, hold answered held ends the attempt and the restart completes the action, anything else falls back to S20a, restart once with its own timeout, capability EquipmentHold |

Next free id: D-58.

Open questions

Each question ends in a decision or a finding recorded by its owner session. Answered questions are kept struck through with the decision id.

Sessions

Each session fits one Claude Code session. Sessions marked "parallel" can run in any order after their prerequisites. Details in sessions.md.

Session ids were renumbered on 2026-11-07; the mapping from the old ids is in the log.

Working rules for every session

• Size rule: one coherent area, roughly up to 1.5k lines of new code including tests, or a spike whose output is only findings. If a session turns out too large, stop at a clean boundary and write the remainder into the handoff.
• Branches and PRs (D-22): one milestone is one GitHub stack (gh stack); each session is one PR in that stack, on a branch named after the session (for example s04-library-spike), with the session id in the PR title. A PR targets the branch of the PR below it; the bottom PR targets main. Merge bottom-up with squash, as soon as a session is done and its checks are green, so main gets one commit per session and the stack stays short. Parallel sessions go into the stack in the order they are started. A session that needs a second PR adds it to the stack on top of its first one. The session's log.md entry and status change are part of its own PR. Each PR is also assigned to the GitHub milestone (M0 to M3) for the progress view.
• Start: read this file, the own block in sessions.md, the last log.md entry, and the research files and decisions the block links to. CLAUDE.md and the path rules load by themselves. Do not re-research settled decisions; if one is wrong, record the change as a revision in decisions.md instead of silently deviating.
• Definition of done (code sessions): build with zero warnings (warnings as errors), unit tests green, AOT publish without IL2xxx/IL3xxx warnings for the touched projects, compose integration tests green for touched transports, public API has XML docs, no secrets or payloads in logs; once S03 exists the scanners are green (Gitleaks clean, Trivy without fixable HIGH/CRITICAL, Sonar quality gate on new code; waivers only with reason and expiry, D-20); every new stateful component ships its read-only inspector (D-19, S11 is done); maintenance tools of a component follow D-45. Code sessions also pass /code-review high on their diff before the PR is opened, with confirmed findings fixed in the same PR (/session-end).
• End (mandatory, last task of every session): append a log.md entry (with "Post-merge checks" that the next session verifies; no follow-up PR), set the session's status in the table above, update the affected decisions and open questions, and write the "Next session pickup" so that a fresh session needs nothing from chat history.
• Python cross-check (design and port sessions): before replacing Python behaviour, read the matching sources and tests on python-archive and keep a parity list (behaviour, file, disposition kept/changed/dropped/open) in the session's research file. No row stays open at the end of the session; the plan documents and memory are not a substitute for reading the code. The session blocks name the files, and /session-start and /session-end check it.
• Decisions: new ones take the next free id (above) and get a full entry in decisions.md plus a row here. A revision keeps the id and adds a dated "Revised" line.
• Keep the plan small: log entries stay short (about 15 lines); findings and analysis go to research/ or the regular docs.

Out of scope for porting / later

• Job spec client: southbound implementation of the Job Control spec. Use the OPC UA library's server example as the integration-test partner.
• Tightening client (IJT).