diff --git a/docs/Lab/fpga-synthesis-automation-guardrails.md b/docs/Lab/fpga-synthesis-automation-guardrails.md new file mode 100644 index 00000000..427e408a --- /dev/null +++ b/docs/Lab/fpga-synthesis-automation-guardrails.md @@ -0,0 +1,138 @@ +# FPGA synthesis automation guardrails + +This page defines the planning boundary for FPGA synthesis automation across +the pccx Lab, Trace, and workflow surfaces. It is a guardrail note for evidence +handling and flow orchestration before hosted execution paths are enabled. + +## Product boundary + +pccx can prepare synthesis plans, validate evidence, and summarize tool +reports. Commercial FPGA implementation suites and cloud FPGA image flows stay +behind explicit execution boundaries: user-owned environments, approved +isolated workers, or prebuilt accelerator artifacts. + +The default product shape is artifact-first: + +- generate project scripts, constraints, and review packets +- run open preflight checks where the target is supported +- import simulation, timing, design-rule, waveform, and board-smoke artifacts +- classify blockers before expensive implementation work begins +- keep customer source, commercial tool access material, and raw board captures + out of shared reference material + +## Flow presets + +The workflow surface should expose execution modes as separate presets instead +of one generic synthesis action. + +| Preset | Purpose | Execution boundary | +| --- | --- | --- | +| Artifact-first | Generate scripts and ingest reports | Planning and artifact review | +| Open preflight | Run parser, lint, and structural checks | Open adapters only | +| Local BYOL | Prepare commands for a user-owned tool install | Explicit preview and opt-in | +| Dedicated worker | Execute in an approved isolated environment | Tenant-isolated path | +| Cloud image handoff | Prepare image-flow artifacts for a user-owned cloud account | User owns account and billing | +| Prebuilt accelerator | Analyze PCCX-owned accelerator artifacts | PCCX-owned build artifacts only | + +## Preflight rules + +The synthesis request should be blocked before dispatch when a required +precondition is missing. + +| Rule | Blocks | Expected output | +| --- | --- | --- | +| `fpga.interface.modport_compat` | Interface names or exposed types that cannot be packaged by the selected flow | failing interface, top, and suggested wrapper action | +| `fpga.top.wrapper_required` | A typed top that cannot be consumed by the selected integration path | plain wrapper requirement | +| `fpga.ooc.final_artifact_gate` | Requesting final hardware output from an out-of-context module run | integration-stage handoff | +| `fpga.axis.single_ready_driver` | Multiple consumers driving one stream-ready signal | mux, demux, or arbitration requirement | +| `fpga.status.polling_semantics` | Host polling status exposed as a lossy event queue | latest or sticky status-register requirement | +| `fpga.timing.evidence_ladder` | Treating synthesis completion as timing closure | stage-specific timing state | +| `fpga.runtime.dma_provider_required` | Runtime test requesting physical DMA without a verified provider | provider fields or sysfs evidence | +| `fpga.artifact.source_of_truth` | Stale status files conflicting with canonical reports | canonical evidence list | +| `fpga.license.execution_boundary` | Unapproved commercial tool execution | blocked license state | +| `fpga.security.customer_artifact_policy` | Customer source or raw captures entering shared material | retention and redaction action | + +## Evidence states + +Do not collapse FPGA progress into a single pass/fail label. The review packet +should carry separate states for: + +- parser and lint status +- simulation status +- out-of-context synthesis status +- integration status +- implementation status +- timing status +- design-rule status +- final artifact status +- runtime smoke status +- throughput evidence status + +Use blocked states when evidence is absent. A successful early stage must not +be promoted beyond its own stage until final artifacts and runtime smoke +evidence are present. + +## Queue model + +Each synthesis request should become a job graph. The first implementation can +be planning-only, but the job shape should already match the future worker pool. + +Required job fields: + +- `job_id` +- `target_ref` +- `flow_preset` +- `target_part_class` +- `tool_policy` +- `artifact_policy` +- `state` +- `blocking_rules` +- `evidence_refs` + +Long-running implementation stages should run only in isolated work directories +with command allowlists, timeouts, cancellation, and log redaction. + +## Trace and Evolve integration + +Trace should show synthesis automation as an evidence timeline with each +hardware stage labeled separately. Recommended event groups: + +- `preflight` +- `simulation` +- `ooc_synthesis` +- `integration` +- `implementation` +- `timing` +- `design_rules` +- `runtime_smoke` +- `blocked` + +Evolve may propose RTL or constraint candidates only when the guardrails remain +satisfied. Candidate scoring should reward timing improvement, regression +preservation, single-driver interfaces, stable host-visible status semantics, +and complete evidence. It should heavily penalize missing runtime providers, +multi-driver introductions, incomplete stage evidence, and license-boundary +violations. + +## Initial review packet shape + +```json +{ + "flow": "fpga_synthesis_preflight.v0", + "state": "blocked", + "flowPreset": "artifact-first", + "blockingRules": [ + "fpga.ooc.final_artifact_gate", + "fpga.runtime.dma_provider_required" + ], + "evidenceRequired": [ + "post_implementation_timing_report", + "design_rule_report", + "dma_provider" + ] +} +``` + +The packet is deliberately data-only. It records requested actions and evidence +requirements while commercial execution, hardware access, source publication, +and repository mutation remain behind explicit approval boundaries. diff --git a/docs/Lab/index.rst b/docs/Lab/index.rst index 3ef1e56c..0d2cdba3 100644 --- a/docs/Lab/index.rst +++ b/docs/Lab/index.rst @@ -53,6 +53,13 @@ For the user-facing desktop app itself, see the separate ``generate_uvm_sequence``, ``list_uvm_strategies``) and the Phase 2 ``pccx-lsp`` provider traits + ``LspMultiplexer``. + .. grid-item-card:: :octicon:`shield-check;1em;sd-mr-1` FPGA synthesis guardrails + :link: fpga-synthesis-automation-guardrails + :link-type: doc + + Artifact-first synthesis automation boundaries, preflight rules, + evidence states, queue fields, and Trace/Evolve review packet shape. + .. grid-item-card:: :octicon:`milestone;1em;sd-mr-1` Research lineage :link: research :link-type: doc @@ -70,6 +77,7 @@ For the user-facing desktop app itself, see the separate cli analyzer_api workflow_facade + fpga-synthesis-automation-guardrails research panels ipc