Phase 0 WP-0.10–0.12: Host skeleton, options classes, sample configs, and execution framework
- WP-0.10: Role-based Host startup (Central=WebApplication, Site=generic Host), 15 component AddXxx() extension methods, MapCentralUI/MapInboundAPI stubs - WP-0.11: 12 per-component options classes with config binding - WP-0.12: Sample appsettings for central and site topologies - Add execution procedure and checklist template to generate_plans.md - Add phase-0-checklist.md for execution tracking - Resolve all 21 open questions from plan generation - Update IDataConnection with batch ops and IAsyncDisposable 57 tests pass, zero warnings.
This commit is contained in:
Joseph Doherty
@@ -530,21 +530,206 @@ Ask Codex: *"Review this implementation plan against the provided requirements,
|
||||
|
||||
---
|
||||
|
||||
## Phase Execution Procedure
|
||||
|
||||
This section governs how implementation plans are executed. The goal is autonomous execution with built-in compliance checks — no user input required between starting a phase and completing it.
|
||||
|
||||
### Principles
|
||||
|
||||
1. **Work packages are executed in dependency order** — respect `blockedBy` relationships within the phase. Independent WPs may be parallelized.
|
||||
2. **Each WP is self-verifying** — acceptance criteria are checked before moving on. A WP is not complete until all its criteria pass.
|
||||
3. **Tests are written alongside code, not after** — unit tests for a WP are part of that WP, not a separate step.
|
||||
4. **Commit at WP boundaries** — each completed WP (or logical group of small WPs) gets its own commit with a message referencing the WP number and phase.
|
||||
5. **Questions are logged, not blocking** — if an ambiguity is discovered during implementation, log it to `questions.md`, make the best judgment, and continue. Do not stop for user input.
|
||||
6. **Codex MCP is best-effort** — if unavailable during verification steps, note the skip and continue.
|
||||
|
||||
### Per-Work-Package Execution
|
||||
|
||||
For each work package, follow this sequence:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ 1. READ the WP description and acceptance criteria │
|
||||
│ 2. READ all traced requirements (HLR bullets, KDD, │
|
||||
│ CD constraints) to understand intent │
|
||||
│ 3. IMPLEMENT the WP │
|
||||
│ - Write code │
|
||||
│ - Write unit tests for acceptance criteria │
|
||||
│ - Write negative tests for prohibition criteria │
|
||||
│ 4. VERIFY acceptance criteria │
|
||||
│ - Run tests: all must pass │
|
||||
│ - Walk each acceptance criterion line by line │
|
||||
│ - If a criterion cannot be verified yet (depends │
|
||||
│ on a later WP), note it as "deferred to WP-N" │
|
||||
│ 5. UPDATE the phase execution checklist │
|
||||
│ - Mark WP as complete with date │
|
||||
│ - Note any deferred criteria │
|
||||
│ - Note any questions logged │
|
||||
│ 6. COMMIT with message: "Phase N WP-M: <summary>" │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Mid-Phase Compliance Check
|
||||
|
||||
After completing approximately half of a phase's work packages (or at any natural milestone), perform a lightweight compliance check:
|
||||
|
||||
1. **Build check**: The solution compiles with zero warnings (treat warnings as errors).
|
||||
2. **Test check**: All tests written so far pass.
|
||||
3. **Deferred criteria review**: Check if any previously deferred acceptance criteria can now be verified. If so, verify them and update the checklist.
|
||||
4. **Traceability spot-check**: Pick 3 random requirements from the Requirements Checklist. Verify they have corresponding code and tests.
|
||||
|
||||
If any check fails, fix the issue before proceeding to the next WP.
|
||||
|
||||
### Phase Completion Gate
|
||||
|
||||
After all work packages are complete, execute the verification gate from the plan document:
|
||||
|
||||
1. **Run the full test suite** — all unit, integration, negative, and failover tests must pass.
|
||||
2. **Walk the verification gate checklist** — each item in the plan's "Verification Gate" section must pass. Record pass/fail per item.
|
||||
3. **Walk the Requirements Checklist** — confirm every bullet has been implemented and tested. Check off each item.
|
||||
4. **Walk the Design Constraints Checklist** — confirm every constraint has been respected. Check off each item.
|
||||
5. **Check deferred criteria** — all previously deferred acceptance criteria must now be resolvable. Verify them.
|
||||
6. **Run the phase execution checklist** — all WPs must be marked complete with no open items.
|
||||
|
||||
### Post-Phase Codex MCP Review
|
||||
|
||||
After the completion gate passes, submit the implementation for external review:
|
||||
|
||||
**Step 1 — Implementation vs. Plan review**: Submit to Codex (model: `gpt-5.4`):
|
||||
- The phase plan document
|
||||
- A summary of what was implemented (file list, key decisions made)
|
||||
- The phase execution checklist (showing all WPs complete)
|
||||
- Any test output or coverage summary
|
||||
|
||||
Ask Codex: *"Review this implementation against the plan. For each work package, verify that the acceptance criteria described in the plan are reflected in the implementation summary. Identify: (1) any acceptance criterion that appears unimplemented, (2) any implementation that contradicts the plan, (3) any requirement from the plan's Requirements Checklist that lacks corresponding code or tests. List each finding with the specific plan text and what is missing."*
|
||||
|
||||
**Step 2 — Code quality review**: Ask Codex: *"Review the implementation for: (1) security vulnerabilities (OWASP top 10), (2) race conditions or thread safety issues, (3) missing error handling at system boundaries, (4) violations of the project's architectural constraints (no business logic in Commons, no EF in consuming components, Tell for hot-path/Ask for boundaries). List each finding with file and line reference."*
|
||||
|
||||
**Handling findings**: Fix valid findings. Dismiss false positives with rationale. Record the review outcome in the execution checklist.
|
||||
|
||||
### Final Steps
|
||||
|
||||
1. **Commit** any fixes from the post-phase review.
|
||||
2. **Update `requirements-traceability.md`** — change status from "Plan generated" to "Implemented" for all sections, REQ-* IDs, and KDD/CD constraints covered by this phase.
|
||||
3. **Push** to remote.
|
||||
4. **Report** — output a summary of what was implemented, tests passing, and any questions logged.
|
||||
|
||||
---
|
||||
|
||||
## Phase Execution Checklist Template
|
||||
|
||||
Each phase creates a checklist file at `docs/plans/phase-N-checklist.md` when execution begins. This file tracks compliance as work packages are completed.
|
||||
|
||||
```markdown
|
||||
# Phase N Execution Checklist
|
||||
|
||||
**Phase**: [phase name]
|
||||
**Started**: [date]
|
||||
**Completed**: [date or "in progress"]
|
||||
|
||||
---
|
||||
|
||||
## Work Package Status
|
||||
|
||||
| WP | Description | Status | Date | Deferred Criteria | Notes |
|
||||
|----|-------------|--------|------|-------------------|-------|
|
||||
| WP-1 | [description] | [ ] Pending | | | |
|
||||
| WP-2 | [description] | [ ] Pending | | | |
|
||||
| ... | | | | | |
|
||||
|
||||
## Mid-Phase Compliance Checks
|
||||
|
||||
| Check | Date | Result | Notes |
|
||||
|-------|------|--------|-------|
|
||||
| Build (zero warnings) | | [ ] Pass / [ ] Fail | |
|
||||
| All tests pass | | [ ] Pass / [ ] Fail | |
|
||||
| Deferred criteria review | | [ ] Pass / [ ] N/A | |
|
||||
| Traceability spot-check (3 random) | | [ ] Pass / [ ] Fail | |
|
||||
|
||||
## Verification Gate
|
||||
|
||||
| # | Gate Criterion | Pass | Notes |
|
||||
|---|---------------|------|-------|
|
||||
| 1 | [from plan] | [ ] | |
|
||||
| 2 | [from plan] | [ ] | |
|
||||
| ... | | | |
|
||||
|
||||
## Requirements Checklist Verification
|
||||
|
||||
| ID | Requirement | Implemented | Tested | Notes |
|
||||
|----|------------|-------------|--------|-------|
|
||||
| [3.1-1] | [requirement text] | [ ] | [ ] | |
|
||||
| [3.1-2] | [requirement text] | [ ] | [ ] | |
|
||||
| ... | | | | |
|
||||
|
||||
## Design Constraints Checklist Verification
|
||||
|
||||
| ID | Constraint | Respected | Notes |
|
||||
|----|-----------|-----------|-------|
|
||||
| KDD-xxx-N | [constraint] | [ ] | |
|
||||
| CD-xxx-N | [constraint] | [ ] | |
|
||||
| ... | | | |
|
||||
|
||||
## Post-Phase Review
|
||||
|
||||
| Review Step | Date | Result | Findings |
|
||||
|------------|------|--------|----------|
|
||||
| Codex: Implementation vs. Plan | | [ ] Pass / [ ] Pass with corrections / [ ] Skipped | |
|
||||
| Codex: Code quality | | [ ] Pass / [ ] Pass with corrections / [ ] Skipped | |
|
||||
|
||||
## Questions Logged During Execution
|
||||
|
||||
| # | Question | Logged to questions.md | Resolution |
|
||||
|---|----------|----------------------|------------|
|
||||
| | | | |
|
||||
|
||||
## Summary
|
||||
|
||||
- **Total WPs**: N
|
||||
- **Tests written**: N unit, N integration, N negative
|
||||
- **Tests passing**: N/N
|
||||
- **Requirements verified**: N/N
|
||||
- **Design constraints verified**: N/N
|
||||
- **Questions logged**: N
|
||||
- **Codex review**: [outcome]
|
||||
```
|
||||
|
||||
When starting a phase, the executor:
|
||||
1. Creates the checklist file from this template, populated with the phase's actual WPs, gate criteria, requirements, and constraints.
|
||||
2. Updates the checklist as each WP is completed.
|
||||
3. Fills in the verification sections during the completion gate.
|
||||
4. Commits the final checklist alongside the last phase commit.
|
||||
|
||||
---
|
||||
|
||||
## File Index
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `docs/plans/generate_plans.md` | This document — master plan for generating implementation plans |
|
||||
| `docs/plans/generate_plans.md` | This document — master plan, generation procedure, and execution procedure |
|
||||
| `docs/plans/requirements-traceability.md` | Matrix linking every requirement to its implementation phase |
|
||||
| `docs/plans/questions.md` | Questions requiring follow-up before or during implementation |
|
||||
| `docs/plans/phase-0-solution-skeleton.md` | (To be generated) |
|
||||
| `docs/plans/phase-1-central-foundations.md` | (To be generated) |
|
||||
| `docs/plans/phase-2-modeling-validation.md` | (To be generated) |
|
||||
| `docs/plans/phase-3a-runtime-foundation.md` | (To be generated) |
|
||||
| `docs/plans/phase-3b-site-io-observability.md` | (To be generated) |
|
||||
| `docs/plans/phase-3c-deployment-store-forward.md` | (To be generated) |
|
||||
| `docs/plans/phase-4-operator-ui.md` | (To be generated) |
|
||||
| `docs/plans/phase-5-authoring-ui.md` | (To be generated) |
|
||||
| `docs/plans/phase-6-deployment-ops-ui.md` | (To be generated) |
|
||||
| `docs/plans/phase-7-integrations.md` | (To be generated) |
|
||||
| `docs/plans/phase-8-production-readiness.md` | (To be generated) |
|
||||
| **Implementation Plans** | |
|
||||
| `docs/plans/phase-0-solution-skeleton.md` | Generated |
|
||||
| `docs/plans/phase-1-central-foundations.md` | Generated |
|
||||
| `docs/plans/phase-2-modeling-validation.md` | Generated |
|
||||
| `docs/plans/phase-3a-runtime-foundation.md` | Generated |
|
||||
| `docs/plans/phase-3b-site-io-observability.md` | Generated |
|
||||
| `docs/plans/phase-3c-deployment-store-forward.md` | Generated |
|
||||
| `docs/plans/phase-4-operator-ui.md` | Generated |
|
||||
| `docs/plans/phase-5-authoring-ui.md` | Generated |
|
||||
| `docs/plans/phase-6-deployment-ops-ui.md` | Generated |
|
||||
| `docs/plans/phase-7-integrations.md` | Generated |
|
||||
| `docs/plans/phase-8-production-readiness.md` | Generated |
|
||||
| **Execution Checklists** (created when each phase begins) | |
|
||||
| `docs/plans/phase-0-checklist.md` | Phase 0 execution tracking |
|
||||
| `docs/plans/phase-1-checklist.md` | Phase 1 execution tracking |
|
||||
| `docs/plans/phase-2-checklist.md` | Phase 2 execution tracking |
|
||||
| `docs/plans/phase-3a-checklist.md` | Phase 3A execution tracking |
|
||||
| `docs/plans/phase-3b-checklist.md` | Phase 3B execution tracking |
|
||||
| `docs/plans/phase-3c-checklist.md` | Phase 3C execution tracking |
|
||||
| `docs/plans/phase-4-checklist.md` | Phase 4 execution tracking |
|
||||
| `docs/plans/phase-5-checklist.md` | Phase 5 execution tracking |
|
||||
| `docs/plans/phase-6-checklist.md` | Phase 6 execution tracking |
|
||||
| `docs/plans/phase-7-checklist.md` | Phase 7 execution tracking |
|
||||
| `docs/plans/phase-8-checklist.md` | Phase 8 execution tracking |
|
||||
|
||||
113
docs/plans/phase-0-checklist.md
Normal file
113
docs/plans/phase-0-checklist.md
Normal file
@@ -0,0 +1,113 @@
|
||||
# Phase 0 Execution Checklist
|
||||
|
||||
**Phase**: Solution Skeleton & Delivery Guardrails
|
||||
**Started**: 2026-03-16
|
||||
**Completed**: in progress
|
||||
|
||||
---
|
||||
|
||||
## Work Package Status
|
||||
|
||||
| WP | Description | Status | Date | Deferred Criteria | Notes |
|
||||
|----|-------------|--------|------|-------------------|-------|
|
||||
| WP-0.1 | Solution Structure | [ ] Pending | | | |
|
||||
| WP-0.2 | Commons Namespace & Folder Skeleton | [ ] Pending | | | |
|
||||
| WP-0.3 | Commons Shared Data Types | [ ] Pending | | | |
|
||||
| WP-0.4 | Commons Domain Entity POCOs | [ ] Pending | | | |
|
||||
| WP-0.5 | Commons Repository Interfaces | [ ] Pending | | | |
|
||||
| WP-0.6 | Commons Cross-Cutting Service Interfaces | [ ] Pending | | | |
|
||||
| WP-0.7 | Commons Message Contracts | [ ] Pending | | | |
|
||||
| WP-0.8 | Commons Protocol Abstraction | [ ] Pending | | | |
|
||||
| WP-0.9 | Commons Architectural Constraint Enforcement | [ ] Pending | | | |
|
||||
| WP-0.10 | Host Skeleton with Role-Based Startup | [ ] Pending | | | |
|
||||
| WP-0.11 | Per-Component Options Classes | [ ] Pending | | | |
|
||||
| WP-0.12 | Local Dev Topology & Sample Config | [ ] Pending | | | |
|
||||
|
||||
## Mid-Phase Compliance Checks
|
||||
|
||||
| Check | Date | Result | Notes |
|
||||
|-------|------|--------|-------|
|
||||
| Build (zero warnings) | | [ ] Pass / [ ] Fail | |
|
||||
| All tests pass | | [ ] Pass / [ ] Fail | |
|
||||
| Deferred criteria review | | [ ] Pass / [ ] N/A | |
|
||||
| Traceability spot-check (3 random) | | [ ] Pass / [ ] Fail | |
|
||||
|
||||
## Verification Gate
|
||||
|
||||
| # | Gate Criterion | Pass | Notes |
|
||||
|---|---------------|------|-------|
|
||||
| 1 | `dotnet build ScadaLink.slnx` zero errors, zero warnings | [ ] | |
|
||||
| 2 | `dotnet test ScadaLink.slnx` all tests pass | [ ] | |
|
||||
| 3 | Host boots in central role from appsettings.Central.json | [ ] | |
|
||||
| 4 | Host boots in site role from appsettings.Site.json | [ ] | |
|
||||
| 5 | Site-role Host does not open any network port | [ ] | |
|
||||
| 6 | All 17 component projects compile with correct Commons references | [ ] | |
|
||||
| 7 | Commons has zero non-core-NET package references | [ ] | |
|
||||
| 8 | All architectural constraint tests pass (no EF, Akka, ASP.NET in Commons) | [ ] | |
|
||||
| 9 | All entity POCOs use DateTimeOffset for timestamp fields | [ ] | |
|
||||
| 10 | All message contracts are record types | [ ] | |
|
||||
| 11 | Every Requirements/Design Constraints checklist item maps to a WP | [ ] | |
|
||||
|
||||
## Requirements Checklist Verification
|
||||
|
||||
Verified when all WPs complete — see phase plan Section 3 for full list.
|
||||
|
||||
| Req Group | Count | Implemented | Tested |
|
||||
|-----------|-------|-------------|--------|
|
||||
| 13.1 Timestamps | 3 | [ ] | [ ] |
|
||||
| REQ-COM-1 Shared Types | 12 | [ ] | [ ] |
|
||||
| REQ-COM-2 Protocol Abstraction | 3 | [ ] | [ ] |
|
||||
| REQ-COM-3 Entity POCOs | 13 | [ ] | [ ] |
|
||||
| REQ-COM-4 Repository Interfaces | 10 | [ ] | [ ] |
|
||||
| REQ-COM-4a Cross-Cutting Interfaces | 2 | [ ] | [ ] |
|
||||
| REQ-COM-5 Message Contracts | 10 | [ ] | [ ] |
|
||||
| REQ-COM-5a Versioning | 4 | [ ] | [ ] |
|
||||
| REQ-COM-5b Namespace Convention | 12 | [ ] | [ ] |
|
||||
| REQ-COM-6 No Business Logic | 3 | [ ] | [ ] |
|
||||
| REQ-COM-7 Minimal Dependencies | 5 | [ ] | [ ] |
|
||||
| REQ-HOST-1 Single Binary | 3 | [ ] | [ ] |
|
||||
| REQ-HOST-2 Role Registration | 6 | [ ] | [ ] |
|
||||
| REQ-HOST-3 Config Binding | 6 | [ ] | [ ] |
|
||||
| REQ-HOST-7 ASP.NET vs Generic Host | 3 | [ ] | [ ] |
|
||||
| REQ-HOST-10 Extension Methods | 5 | [ ] | [ ] |
|
||||
|
||||
## Design Constraints Checklist Verification
|
||||
|
||||
| ID | Constraint | Respected | Notes |
|
||||
|----|-----------|-----------|-------|
|
||||
| KDD-data-6 | All timestamps UTC | [ ] | |
|
||||
| KDD-code-1 | POCOs in Commons, EF in ConfigDB | [ ] | |
|
||||
| KDD-code-2 | Repo interfaces in Commons | [ ] | |
|
||||
| KDD-code-3 | Commons namespace hierarchy | [ ] | |
|
||||
| KDD-code-4 | Additive-only message evolution | [ ] | |
|
||||
| KDD-code-5 | Options pattern config binding | [ ] | |
|
||||
| KDD-code-6 | Options classes in component projects | [ ] | |
|
||||
| CD-Commons-1 | All components reference Commons | [ ] | |
|
||||
| CD-Commons-2 | No EF annotations on POCOs | [ ] | |
|
||||
| CD-Commons-3 | Interface contract for ConfigDB | [ ] | |
|
||||
| CD-Host-1 | Host references all components | [ ] | |
|
||||
| CD-Host-2 | ConfigDB in Host AddXxx chain | [ ] | |
|
||||
| CD-Host-3 | Component registration matrix | [ ] | |
|
||||
|
||||
## Post-Phase Review
|
||||
|
||||
| Review Step | Date | Result | Findings |
|
||||
|------------|------|--------|----------|
|
||||
| Codex: Implementation vs. Plan | | [ ] Pass / [ ] Pass with corrections / [ ] Skipped | |
|
||||
| Codex: Code quality | | [ ] Pass / [ ] Pass with corrections / [ ] Skipped | |
|
||||
|
||||
## Questions Logged During Execution
|
||||
|
||||
| # | Question | Logged to questions.md | Resolution |
|
||||
|---|----------|----------------------|------------|
|
||||
| | | | |
|
||||
|
||||
## Summary
|
||||
|
||||
- **Total WPs**: 12
|
||||
- **Tests written**: TBD
|
||||
- **Tests passing**: TBD
|
||||
- **Requirements verified**: 0/100
|
||||
- **Design constraints verified**: 0/13
|
||||
- **Questions logged**: 0
|
||||
- **Codex review**: pending
|
||||
@@ -6,63 +6,6 @@
|
||||
|
||||
## Open Questions
|
||||
|
||||
### Phase 0: Solution Skeleton
|
||||
|
||||
| # | Question | Context | Impact | Status |
|
||||
|---|----------|---------|--------|--------|
|
||||
| Q16 | Should `Result<T>` use a OneOf-style library or be hand-rolled? | Affects COM-7-1 (minimal dependencies). A hand-rolled `Result<T>` keeps zero external dependencies. | Phase 0. | Recommend hand-rolled to maintain zero-dependency constraint. |
|
||||
| Q17 | Should entity POCO properties be required (init-only) or settable? | EF Core Fluent API mapping may need settable properties. POCOs must be persistence-ignorant but still mappable by Phase 1. | Phase 0 / Phase 1 boundary. | Recommend `{ get; set; }` for EF compatibility, with constructor invariants for required fields. |
|
||||
| Q18 | What `QualityCode` values should the protocol abstraction define? | OPC UA has a rich quality model (Good, Uncertain, Bad with subtypes). Need to decide on a simplified shared set. | Phase 0. | Recommend: Good, Bad, Uncertain as the minimal set, with room to extend. |
|
||||
| Q19 | Should `IDataConnection` be `IAsyncDisposable` for connection cleanup? | Affects DCL connection actor lifecycle. | Phase 0 / Phase 3B boundary. | Recommend yes — add `IAsyncDisposable` to support proper cleanup. |
|
||||
|
||||
### Phase 1: Central Platform Foundations
|
||||
|
||||
| # | Question | Context | Impact | Status |
|
||||
|---|----------|---------|--------|--------|
|
||||
| Q-P1-1 | Should Data Protection keys be stored in the configuration database (via EF Core Data Protection key store) or on a shared filesystem path? | WP-10 requires both central nodes share Data Protection keys. DB storage is more portable; filesystem requires shared mount. | Implementation detail for WP-10. Either approach works. | Open — decide during implementation. Default to DB storage. |
|
||||
|
||||
### Phase 2: Core Modeling, Validation & Deployment Contract
|
||||
|
||||
| # | Question | Context | Impact | Status |
|
||||
|---|----------|---------|--------|--------|
|
||||
| Q-P2-1 | What hashing algorithm should be used for revision hashes? | SHA-256 is likely choice for determinism and collision resistance. | WP-16. Low risk — algorithm can be changed without API impact. | Open — proceed with SHA-256 as default. |
|
||||
| Q-P2-2 | What serialization format for the deployment package contract? | JSON is most natural for .NET; MessagePack is more compact. Decision affects Site Runtime deserialization. | WP-17. Medium — format must be stable once sites consume it. | Open — recommend JSON for debuggability; can add binary format later. |
|
||||
| Q-P2-3 | How should script pre-compilation handle references to runtime APIs (GetAttribute, SetAttribute, etc.) that don't exist at compile time on central? | Scripts reference runtime APIs only available at site. Central needs stubs. | WP-18, WP-19. Must be addressed before script compilation validation works. | Open — implement compilation against a stub ScriptApi assembly. |
|
||||
| Q-P2-4 | Should semantic validation for CallShared resolve against shared script library at validation time, or deployed version at target site? | Shared scripts may be modified between validation and deployment. | WP-19. Low risk if validation re-runs before deployment. | Open — validate against current library; document re-validation on deploy. |
|
||||
|
||||
### Phase 3A: Runtime Foundation
|
||||
|
||||
| # | Question | Context | Impact | Status |
|
||||
|---|----------|---------|--------|--------|
|
||||
| Q-P3A-1 | What is the optimal batch size and delay for staggered Instance Actor startup? | Component-SiteRuntime.md suggests 20 with a "short delay." Actual values depend on OPC UA server capacity. | Performance tuning. Default to 20/100ms, make configurable. | Deferred — tune during Phase 3B when DCL is integrated. |
|
||||
| Q-P3A-2 | Should the SQLite schema use a single database file or separate files per concern (configs, overrides, S&F, events)? | Single file is simpler. Separate files isolate concerns and allow independent backup/maintenance. | Schema design. | Recommend single file with separate tables. Simpler transaction management. Final decision during implementation. |
|
||||
| Q-P3A-3 | Should Akka.Persistence (event sourcing / snapshotting) be used for the Deployment Manager singleton, or is direct SQLite access sufficient? | Akka.Persistence adds complexity (journal, snapshots) but provides built-in recovery. Direct SQLite is simpler for this use case. | Architecture. | Recommend direct SQLite — Deployment Manager recovery is a full read-all-configs-and-rebuild pattern, not event replay. |
|
||||
|
||||
### Phase 3B: Site I/O & Observability
|
||||
|
||||
| # | Question | Context | Impact | Status |
|
||||
|---|----------|---------|--------|--------|
|
||||
| Q-P3B-1 | What is the exact dedicated blocking I/O dispatcher configuration for Script Execution Actors? | KDD-runtime-3 says "dedicated blocking I/O dispatcher" — need Akka.NET HOCON config (thread pool size, throughput settings). | WP-15. Sensible defaults can be set; tuned in Phase 8. | Deferred — use Akka.NET default blocking-io-dispatcher config; tune during Phase 8 performance testing. |
|
||||
| Q-P3B-2 | Should LmxProxy adapter expose WriteBatchAndWaitAsync (write-and-poll handshake) through IDataConnection or as a protocol-specific extension? | CD-DCL-5 lists WriteBatchAndWaitAsync but IDataConnection only defines simple Write. | WP-8. Does not block core functionality. | Deferred — expose as protocol-specific extension method; not part of IDataConnection core contract. |
|
||||
| Q-P3B-3 | What is the Rate of Change alarm evaluation time window? | Section 3.4 says "changes faster than a defined threshold" but does not specify the time window (per-second? per-minute? configurable?). | WP-16. Needs a design decision for the evaluation algorithm. | Deferred — implement as configurable window (default: per-second rate). Document in alarm definition schema. |
|
||||
| Q-P3B-4 | How does the health report sequence number behave across failover? | Sequence number is monotonic within a singleton lifecycle. After failover, the new singleton starts at 1. Central must handle this. | WP-27, WP-28. | Resolved in design — central accepts report when site is offline; for online sites, requires seq > last. On failover, site goes offline first (missed reports), so the reset is naturally handled. |
|
||||
|
||||
### Phase 3C: Deployment Pipeline & Store-and-Forward
|
||||
|
||||
| # | Question | Context | Impact | Status |
|
||||
|---|----------|---------|--------|--------|
|
||||
| Q-P3C-1 | Should S&F retry timers be reset on failover or continue from the last known retry timestamp? | On failover, the new active node loads buffer from SQLite. Messages have `last_attempt_at` timestamps. Should retry timing continue relative to `last_attempt_at` or reset to "now"? | Affects retry behavior immediately after failover. Recommend: continue from `last_attempt_at` to avoid burst retries. | Open |
|
||||
| Q-P3C-2 | What is the maximum number of parked messages returned in a single remote query? | Communication Layer pattern 8 uses 30s timeout. Very large parked message sets may need pagination. | Recommend: paginated query (e.g., 100 per page) consistent with Site Event Logging pagination pattern. | Open |
|
||||
| Q-P3C-3 | Should the per-instance operation lock be in-memory (lost on central failover) or persisted? | In-memory is simpler and consistent with "in-progress deployments treated as failed on failover." Persisted lock could cause orphan locks. | Recommend: in-memory. On failover, all locks released. Site state query resolves any ambiguity. | Open |
|
||||
|
||||
### Phase 4: Operator/Admin UI
|
||||
|
||||
| # | Question | Context | Impact | Status |
|
||||
|---|----------|---------|--------|--------|
|
||||
| Q-P4-1 | Should the API key value be auto-generated (GUID/random) or allow user-provided values? | Component-InboundAPI.md says "key value" but does not specify generation. | Phase 4, WP-5. | Open — assume auto-generated with optional copy-to-clipboard; user can regenerate. |
|
||||
| Q-P4-2 | Should the health dashboard support configurable refresh intervals or always use the 30s report interval? | Component-HealthMonitoring.md specifies 30s default interval. | Phase 4, WP-9. | Open — assume display updates on every report arrival (no UI-side polling); interval is server-side config. |
|
||||
| Q-P4-3 | Should area deletion cascade to child areas or require bottom-up deletion? | HighLevelReqs 3.10 says "parent-child relationships" but does not specify cascade behavior. | Phase 4, WP-3. | Open — assume cascade delete of child areas (if no instances assigned to any area in the subtree). |
|
||||
|
||||
### Phase 7: Integrations
|
||||
|
||||
| # | Question | Context | Impact | Status |
|
||||
@@ -89,3 +32,25 @@
|
||||
| Q15 | Should the Machine Data Database schema be designed in this project, or is it out of scope? | Out of scope — Machine Data Database is a pre-existing database at customer sites. Test infra seeds sample tables/data in `infra/mssql/machinedata_seed.sql`. | 2026-03-16 |
|
||||
| Q13 | Who is the development team? | Solo developer with extensive Akka.NET experience and full availability. No parallelization constraints — phases are sequential. | 2026-03-16 |
|
||||
| Q14 | Is there an existing deployment target environment for early pilot testing? | Yes — developer can test directly. No separate pilot environment needed. | 2026-03-16 |
|
||||
| Q16 | Should `Result<T>` use a OneOf-style library or be hand-rolled? | Hand-rolled to maintain zero-dependency constraint (REQ-COM-7). | 2026-03-16 |
|
||||
| Q17 | Should entity POCO properties be required (init-only) or settable? | `{ get; set; }` for EF compatibility, with constructor invariants for required fields. | 2026-03-16 |
|
||||
| Q18 | What `QualityCode` values should the protocol abstraction define? | Good, Bad, Uncertain as the minimal set, with room to extend. | 2026-03-16 |
|
||||
| Q19 | Should `IDataConnection` be `IAsyncDisposable` for connection cleanup? | Yes — add `IAsyncDisposable` to support proper cleanup in DCL connection actors. | 2026-03-16 |
|
||||
| Q-P1-1 | Data Protection keys — DB or shared filesystem? | DB storage (EF Core Data Protection key store). More portable than shared filesystem mount. | 2026-03-16 |
|
||||
| Q-P2-1 | What hashing algorithm for revision hashes? | SHA-256. | 2026-03-16 |
|
||||
| Q-P2-2 | What serialization format for the deployment package contract? | JSON for debuggability. Can add binary format later if needed. | 2026-03-16 |
|
||||
| Q-P2-3 | How should script pre-compilation handle references to runtime APIs? | Compile against a stub ScriptApi assembly at central. Site uses real implementation. | 2026-03-16 |
|
||||
| Q-P2-4 | Semantic validation for CallShared — current library or deployed version? | Validate against current library; re-validate on deploy. | 2026-03-16 |
|
||||
| Q-P3A-1 | Staggered Instance Actor startup batch size/delay? | Default 20 actors per batch, 100ms delay. Make configurable. Tune during Phase 3B/8. | 2026-03-16 |
|
||||
| Q-P3A-2 | Single SQLite file or separate files per concern? | Single file with separate tables. Simpler transaction management. | 2026-03-16 |
|
||||
| Q-P3A-3 | Akka.Persistence or direct SQLite for Deployment Manager singleton? | Direct SQLite. Recovery is full read-all-configs-and-rebuild, not event replay. | 2026-03-16 |
|
||||
| Q-P3B-1 | Blocking I/O dispatcher config for Script Execution Actors? | Use Akka.NET default blocking-io-dispatcher config. Tune during Phase 8 performance testing. | 2026-03-16 |
|
||||
| Q-P3B-2 | Should WriteBatchAndWaitAsync be on IDataConnection or protocol-specific? | Add to `IDataConnection` — both OPC UA and LmxProxy can implement it. | 2026-03-16 |
|
||||
| Q-P3B-3 | Rate of Change alarm evaluation time window? | Configurable window, default per-second rate. Document in alarm definition schema. | 2026-03-16 |
|
||||
| Q-P3B-4 | Health report sequence number across failover? | Resolved in design — offline detection handles the reset naturally. Central accepts lower seq after site goes offline/online. | 2026-03-16 |
|
||||
| Q-P3C-1 | S&F retry timers on failover — reset or continue? | Continue from `last_attempt_at` to avoid burst retries. | 2026-03-16 |
|
||||
| Q-P3C-2 | Max parked messages per remote query? | Paginated, 100 per page, consistent with Site Event Logging pattern. | 2026-03-16 |
|
||||
| Q-P3C-3 | Per-instance operation lock — in-memory or persisted? | In-memory. Released on failover. Site state query resolves any ambiguity. | 2026-03-16 |
|
||||
| Q-P4-1 | API key values — auto-generated or user-provided? | Auto-generated with copy-to-clipboard. User can regenerate. | 2026-03-16 |
|
||||
| Q-P4-2 | Health dashboard refresh interval? | Updates on every report arrival (server push). No UI-side polling. | 2026-03-16 |
|
||||
| Q-P4-3 | Area deletion — cascade or bottom-up? | Cascade delete child areas if no instances are assigned to any area in the subtree. | 2026-03-16 |
|
||||
|
||||
Reference in New Issue
Block a user