Skip to content

pccxai/pccx-lab

BranchesTags

Repository files navigation

pccx-lab

CLI-first verification lab for pccx NPU trace profiling, workflow descriptors, proposal previews, disabled runner pilots, and bounded GUI inspection.

License Status Rust Tauri

Project status

Public alpha — v0.1.0-alpha is published as a prerelease. Core crates and the Tauri shell are in active development; APIs and .pccx schema may shift before v0.2.0. Feedback and issues are welcome.

Entry point Link
Documentation https://pccx.pages.dev/en/lab/
Releases https://github.com/pccxai/pccx-lab/releases
v0.1.0-alpha notes docs/releases/v0.1.0-alpha.md
Roadmap (project board) https://github.com/orgs/pccxai/projects/1
Contributing https://github.com/pccxai/.github/blob/main/CONTRIBUTING.md
How to cite CITATION.cff
Tooling status rust-check + frontend-check required on main; cargo fmt --check enforced
Discussions https://github.com/pccxai/pccx-lab/discussions
Good first issues good first issue Suitable for first-time contributors

Full documentation

Documentation is available in both English and Korean:

Why one repo, not five?

Read our design rationale on why we use a single monorepo to maintain strong module boundaries.

Module layout

Phase 1 split the original monolithic core into nine focused crates under crates/ plus a top-level ui/. pccx-core is the single sink of the dependency graph; no crate depends on pccx-ide or pccx-remote (both are terminal binaries).

  • crates/core/ (pccx-core) — pure Rust core: .pccx format, trace parsing, hardware model, roofline, bottleneck, VCD / chrome-trace, Vivado timing.
  • crates/reports/ — Markdown / HTML / PDF rendering.
  • crates/verification/ — golden-diff + robust-reader gates for CI.
  • crates/authoring/ — ISA / API TOML compilers.
  • crates/evolve/ — EAGLE-family speculative-decoding primitives; future home of the Phase 5 DSE loop.
  • crates/lsp/ — Phase 2 IntelliSense façade (sync + async provider traits, multiplexers, subprocess spawner).
  • crates/remote/ — Phase 3 backend-daemon scaffold.
  • crates/uvm_bridge/ — SystemVerilog/UVM DPI-C boundary.
  • crates/workflow_facade/ — workflow-boundary helper scaffolds; provider runtime integration is outside the CLI/core boundary.
  • ui/src-tauri/ (pccx-ide) — Tauri shell consuming the core / reports crates through IPC.
  • ui/ — React + Vite frontend; talks to pccx-ide via Tauri IPC.

See docs/design/phase1_crate_split.md for the full dependency graph and per-crate rationale.

.pccx file format

Read the open specification for our .pccx binary session format.

How others consume pccx-lab

pccx-lab is CLI-first. GUI, editor-adjacent, launcher-adjacent, and future plugin-facing workflows sit on top of the same controlled boundary. There is no private back channel into lab internals. See docs/CLI_CORE_BOUNDARY.md.

  • pccx-lab status --format json returns deterministic lab status for headless tools and the GUI status panel.
  • pccx-lab theme --format json returns the early theme-token contract for a theme-neutral presentation layer.
  • pccx-lab workflows --format json returns descriptor-only workflow metadata for GUI, CI/headless, and future tool consumers.
  • pccx-lab workflow-proposals --format json returns proposal-only previews for future approved workflow runs.
  • pccx-lab workflow-results --format json returns summary-only workflow result metadata without full logs.
  • docs/examples/sail-adoption-plan.example.json records a descriptor-only adoption plan for future Sail reference-model review; it is not a Sail source reader, parser, compiler, model execution path, refinement check, proof path, report writer, artifact writer, or hardware path.
  • docs/examples/sail-interface-boundary.example.json records a descriptor-only Sail interface handoff boundary over approved summaries; it is not a Sail source reader, parser, compiler, AST reader, model execution path, refinement check, proof path, report reader/writer, artifact reader/writer, or hardware path.
  • docs/examples/sail-review-packet.example.json records a summary-only Sail review packet over approved adoption, interface, workflow, verification, and report-gate summaries; it is not a Sail source reader, RTL source reader, AST reader, parser, compiler, model generator, model execution path, refinement check, proof path, report/artifact reader or writer, or hardware path.
  • docs/examples/sail-evidence-manifest.example.json records a summary-only Sail evidence manifest over approved adoption, interface, review, workflow, and verification-gate summaries; it is not a Sail source reader, RTL source reader, AST reader, parser, compiler, model generator, model execution path, refinement check, proof path, report/artifact reader or writer, command runner, repository reader, or hardware path.
  • docs/examples/sail-evidence-detail.example.json records a descriptor-only detail view for one selected approved Sail evidence summary reference; it is not a Sail source reader, RTL source reader, AST reader, generated-model reader, parser, compiler, model generator, model execution path, refinement check, proof path, verification run, report/artifact reader or writer, command runner, repository reader, marketplace flow, or hardware path.
  • docs/examples/sail-model-readiness.example.json records a descriptor-only readiness gate for future Sail model work over approved Sail boundary summaries; it is not a Sail source reader, RTL source reader, AST reader, generated-model reader, parser, compiler, model generator, model execution path, refinement check, proof path, verification run, report/artifact reader or writer, command runner, repository reader, marketplace flow, or hardware path.
  • docs/examples/sail-implementation-gap-matrix.example.json records a descriptor-only gap matrix for future Sail implementation work over approved Sail boundary summaries; it is not a Sail source reader, RTL source reader, AST reader, generated-model reader, parser, compiler, model generator, model execution path, refinement check, proof path, verification run, report/artifact reader or writer, command runner, repository reader, release flow, marketplace flow, or hardware path.
  • docs/examples/sail-source-intake-boundary.example.json records a descriptor-only source-intake boundary for future Sail and RTL source handoff planning over approved Sail boundary summaries; it is not a Sail source reader, RTL source reader, source path reader, source content reader, source hash reader, source metadata reader, manifest reader, AST reader, generated-model reader, parser, compiler, model generator, model execution path, refinement check, proof path, verification run, report/artifact reader or writer, command runner, repository reader, release flow, marketplace flow, or hardware path.
  • docs/examples/sail-source-intake-approval.example.json records a descriptor-only approval gate for future Sail source-intake planning over approved Sail boundary summaries; it does not request, record, or grant approval and is not a Sail source reader, RTL source reader, source path reader, source content reader, source hash reader, source metadata reader, manifest reader, AST reader, generated-model reader, parser, compiler, model generator, model execution path, refinement check, proof path, verification run, report/artifact reader or writer, command runner, repository reader, release flow, marketplace flow, or hardware path.
  • docs/examples/sail-source-intake-result.example.json records a descriptor-only blocked result boundary for future Sail source-intake outcomes over approved Sail boundary summaries; it does not request, record, or grant approval, attempt or complete source intake, materialize result payloads, read Sail sources, read RTL sources, read source paths, read source content, read source hashes, read source metadata, read manifests, read ASTs, read generated models, run parsers, run compilers, generate or execute models, run refinement checks, run proofs, run simulators, run verification, read or write reports or artifacts, execute commands, read repositories, run a release flow, run a marketplace flow, or control hardware.
  • docs/examples/sail-source-intake-handoff.example.json records a descriptor-only blocked handoff summary for future Sail source-intake result review over approved Sail boundary summaries; it does not request, record, or grant approval, attempt or complete source intake, materialize result payloads, generate public text, publish a handoff, read Sail sources, read RTL sources, read source paths, read source content, read source hashes, read source metadata, read manifests, read ASTs, read generated models, run parsers, run compilers, generate or execute models, run refinement checks, run proofs, run simulators, run verification, read or write reports or artifacts, execute commands, read repositories, run a release flow, run a marketplace flow, or control hardware.
  • docs/examples/sail-source-intake-status-summary.example.json records a descriptor-only status summary for future Sail source-intake display over approved Sail source-intake boundary, approval, result, handoff, gap-matrix, and evidence-detail summaries; it does not execute approval, dispatch source intake, read Sail sources, read RTL sources, read source paths, read source content, read source hashes, read source metadata, read manifests, read ASTs, read generated models, run parsers, run compilers, generate or execute models, run refinement checks, run proofs, run simulators, run verification, read or write reports or artifacts, execute commands, read repositories, publish handoffs, run a release flow, run a marketplace flow, or control hardware.
  • docs/examples/hybrid-strategy-plan.example.json records a descriptor-only hybrid strategy plan for future C++/SystemVerilog and custom-script control tracks; it is not a source reader, grammar reader, parser, compiler, runtime, simulator runner, verification run, report writer, artifact writer, or hardware-control path.
  • docs/examples/hybrid-interface-boundary.example.json records a descriptor-only hybrid interface handoff boundary over approved summaries; it is not a C++/SystemVerilog/custom-script source reader, grammar reader, parser, compiler, runtime, script execution path, simulator runner, verification run, report/artifact reader or writer, or hardware-control path.
  • docs/examples/hybrid-review-packet.example.json records a summary-only hybrid review packet over approved strategy, interface, workflow, verification, and report-gate summaries; it is not a source reader, grammar reader, parser, compiler, runtime, script execution path, simulator runner, verification run, report/artifact reader or writer, or hardware-control path.
  • docs/examples/hybrid-evidence-manifest.example.json records a summary-only hybrid evidence manifest over approved strategy, interface, review, workflow, and verification-gate summaries; it is not a source reader, grammar reader, parser, compiler, runtime, script execution path, simulator runner, verification run, report/artifact reader or writer, command runner, repository reader, or hardware-control path.
  • docs/examples/hybrid-evidence-detail.example.json records a descriptor-only detail view for one selected approved hybrid evidence summary reference; it is not a source reader, grammar reader, parser, compiler, runtime, script execution path, simulator runner, verification run, report/artifact reader or writer, command runner, repository reader, marketplace flow, or hardware-control path.
  • docs/examples/hybrid-implementation-readiness.example.json records a descriptor-only readiness gate for future hybrid C++/SystemVerilog and custom-script work over approved hybrid boundary summaries; it is not a source reader, grammar reader, parser, compiler, runtime, script execution path, simulator runner, verification run, report/artifact reader or writer, command runner, repository reader, marketplace flow, or hardware-control path.
  • docs/examples/hybrid-implementation-gap-matrix.example.json records a descriptor-only gap matrix for future hybrid C++/SystemVerilog and custom-script implementation work over approved hybrid boundary summaries; it is not a source reader, grammar reader, parser, compiler, runtime, script execution path, simulator runner, verification run, report/artifact reader or writer, command runner, repository reader, release flow, marketplace flow, or hardware-control path.
  • docs/examples/hybrid-source-intake-boundary.example.json records a descriptor-only source-intake boundary for future C++/SystemVerilog, custom-script, and grammar handoff planning over approved hybrid boundary summaries; it is not a source reader, grammar reader, source path reader, source content reader, source hash reader, source metadata reader, manifest reader, parser, compiler, runtime, script execution path, simulator runner, verification run, report/artifact reader or writer, command runner, repository reader, release flow, marketplace flow, or hardware-control path.
  • docs/examples/hybrid-source-intake-approval.example.json records a descriptor-only approval gate for future hybrid source-intake planning over approved hybrid boundary summaries; it does not request, record, or grant approval and is not a source reader, grammar reader, source path reader, source content reader, source hash reader, source metadata reader, manifest reader, parser, compiler, runtime, script execution path, simulator runner, verification run, report/artifact reader or writer, command runner, repository reader, release flow, marketplace flow, or hardware-control path.
  • docs/examples/hybrid-source-intake-result.example.json records a descriptor-only blocked result boundary for future hybrid source-intake outcomes over approved hybrid boundary summaries; it does not request, record, or grant approval, attempt or complete source intake, materialize result payloads, read sources, read grammar, read source paths, read source content, read source hashes, read source metadata, read manifests, run parsers, run compilers, execute runtimes or scripts, run simulators, run verification, read or write reports or artifacts, execute commands, read repositories, run a release flow, run a marketplace flow, or control hardware.
  • docs/examples/hybrid-source-intake-handoff.example.json records a descriptor-only blocked handoff summary for future hybrid source-intake result review over approved hybrid boundary summaries; it does not request, record, or grant approval, attempt or complete source intake, materialize result payloads, generate public text, publish a handoff, read sources, read grammar, read source paths, read source content, read source hashes, read source metadata, read manifests, run parsers, run compilers, execute runtimes or scripts, run simulators, run verification, read or write reports or artifacts, execute commands, read repositories, run a release flow, run a marketplace flow, or control hardware.
  • docs/examples/hybrid-source-intake-status-summary.example.json records a descriptor-only status summary for future hybrid source-intake display over approved hybrid source-intake boundary, approval, result, handoff, gap-matrix, and evidence-detail summaries; it does not execute approval, dispatch source intake, read C++ sources, read SystemVerilog sources, read custom-script sources, read grammar input, read source paths, read source content, read source hashes, read source metadata, read manifests, run parsers, run compilers, execute runtimes or scripts, run simulators, run verification, read or write reports or artifacts, execute commands, read repositories, publish handoffs, run a release flow, run a marketplace flow, or control hardware.
  • docs/examples/mcp-read-only-tool-plan.example.json maps a future MCP/tool adapter to read-only CLI/core commands; it is a checked plan, not a runtime implementation.
  • docs/examples/mcp-tool-list.example.json records a descriptor-only MCP tool listing over approved boundary summaries; it is not an MCP server, client, runtime, transport, command executor, tool invocation path, file reader, report writer, audit logger, or write path.
  • docs/examples/mcp-tool-detail.example.json records a descriptor-only MCP tool detail view for one selected listed tool; it is not an MCP server, client, runtime, transport, command executor, tool invocation path, input reader, output payload reader, report writer, audit logger, or write path.
  • docs/examples/mcp-sample-result.example.json records descriptor-only result metadata for a planned read-only MCP status sample; it is not an MCP server, client, runtime, transport, command executor, result payload reader, report reader/writer, artifact reader/writer, audit logger, or tool invocation path.
  • docs/examples/mcp-sample-catalog.example.json records a descriptor-only catalog for planned read-only MCP samples; it is not sample discovery, an MCP server/client/runtime/transport, command executor, result payload reader, report reader/writer, artifact reader/writer, audit logger, or tool invocation path.
  • docs/examples/mcp-sample-detail.example.json records descriptor-only detail metadata for one planned read-only MCP sample; it is not sample discovery, an MCP server/client/runtime/transport, command executor, payload reader, report/artifact reader or writer, audit logger, tool invocation path, marketplace flow, or compatibility claim.
  • docs/examples/mcp-sample-status-summary.example.json records a descriptor-only status summary over the checked MCP sample plan, result, catalog, detail, tool-detail, and permission summaries; it is not sample discovery, an MCP server/client/runtime/transport, command executor, payload reader, report/artifact reader or writer, audit logger, tool invocation path, marketplace flow, or compatibility claim.
  • docs/examples/mcp-read-only-analysis-flow.example.json records a checked dry-run flow contract for composing existing CLI/core summaries into a future read-only report path; it is not a command executor or report writer.
  • docs/examples/mcp-read-only-report-contract.example.json records the summary-only report output shape for a future read-only tool adapter; it is not an MCP runtime, command executor, artifact writer, or report writer.
  • docs/examples/mcp-verification-run-comparison.example.json records a summary-only comparison shape for approved workflow-result summaries; it is not an MCP runtime, command executor, file reader, trace reader, report writer, artifact writer, or repository mutation path.
  • docs/examples/mcp-pr-summary-handoff.example.json records the summary-only PR handoff shape for approved issue, change, and validation summaries; it is not an MCP runtime, command executor, file reader, repository reader, PR creator, comment writer, or repository mutation path.
  • docs/examples/mcp-evidence-manifest.example.json records the summary-only evidence manifest shape for approved evidence summary references; it is not an MCP runtime, command executor, file reader, artifact reader, report writer, hardware probe, audit logger, or repository mutation path.
  • docs/examples/mcp-evidence-detail.example.json records a descriptor-only detail view for one selected approved evidence reference; it is not an MCP runtime, command executor, file reader, artifact reader, report reader, report writer, hardware probe, audit logger, or repository mutation path.
  • docs/examples/mcp-permission-model.example.json records the descriptor-only permission profiles and approval gates for a future MCP/tool adapter; it is not a permission runtime or command executor.
  • docs/examples/mcp-approval-request.example.json records the approval-request and repository-mutation gate for a future MCP/tool adapter; it is not an MCP runtime, permission executor, command executor, audit logger, or write path.
  • docs/examples/mcp-approval-decision.example.json records a denied approval-decision gate for a future MCP/tool adapter; it is not an MCP runtime, approval executor, permission executor, command executor, audit logger, tool invocation path, or write path.
  • docs/examples/mcp-invocation-request.example.json records a blocked invocation-request gate for a future MCP/tool adapter; it is not an MCP server, client, runtime, approval executor, permission executor, command executor, tool invocation path, file reader, or write path.
  • docs/examples/mcp-client-session-state.example.json records a blocked client/session state for a future MCP/tool adapter; it is not an MCP server, client, runtime, transport, command executor, tool invocation path, audit logger, file reader, or write path.
  • docs/examples/mcp-blocked-invocation-result.example.json records a blocked, non-executed invocation result for a future MCP/tool adapter; it is not an MCP runtime, command executor, tool invocation path, file reader, artifact writer, or write path.
  • docs/examples/mcp-audit-event.example.json records the redacted audit-event shape for a future read-only MCP/tool adapter; it is not an audit logger or runtime implementation.
  • docs/examples/plugin-boundary-plan.example.json records the plugin manifest and host API planning boundary; it is not a plugin loader or package distribution flow.
  • docs/examples/plugin-sample-result.example.json records descriptor-only result metadata for a planned diagnostics summary plugin sample; it is not a plugin loader, runtime, sandbox, host API binding, capability dispatcher, invocation path, result payload reader, report reader/writer, or artifact reader/writer.
  • docs/examples/plugin-sample-catalog.example.json records a descriptor-only catalog for planned plugin samples; it is not sample discovery, a manifest/package/source reader, plugin loader, runtime, sandbox, capability dispatcher, invocation path, result payload reader, report reader/writer, or artifact reader/writer.
  • docs/examples/plugin-sample-detail.example.json records descriptor-only detail metadata for one planned plugin sample; it is not sample discovery, a manifest/package/source reader, payload reader, report/artifact reader or writer, plugin loader, runtime, sandbox, capability dispatcher, invocation path, package distribution, marketplace flow, or compatibility claim.
  • docs/examples/plugin-sample-status-summary.example.json records a descriptor-only status summary over the checked plugin sample plan, result, catalog, detail, capability-detail, and permission summaries; it is not sample discovery, a manifest/package/source reader, payload reader, report/artifact reader or writer, plugin loader, runtime, sandbox, capability dispatcher, invocation path, package distribution, marketplace flow, or compatibility claim.
  • docs/examples/plugin-manifest-validation-result.example.json records the summary-only result shape for a future approved plugin manifest validation request; it is not a manifest reader, validator command, plugin loader, runtime, sandbox, or package distribution flow.
  • docs/examples/plugin-capability-list.example.json records a descriptor-only capability listing for future CLI/core and GUI consumers; it is not a manifest reader, package reader, plugin loader, runtime, capability dispatcher, compatibility promise, or marketplace flow.
  • docs/examples/plugin-capability-detail.example.json records a descriptor-only capability detail view for one selected listed capability; it is not a manifest reader, package reader, plugin loader, runtime, sandbox, capability dispatcher, compatibility promise, or marketplace flow.
  • docs/examples/plugin-load-request.example.json records a blocked load-request gate for a future reviewed plugin loader path; it is not a plugin loader, runtime, sandbox, manifest reader, package installer, dynamic code loader, or compatibility promise.
  • docs/examples/plugin-host-session-state.example.json records a blocked host/session state for a future reviewed plugin loader path; it is not a plugin loader, runtime, sandbox, host API binding, capability dispatcher, command executor, or compatibility promise.
  • docs/examples/plugin-invocation-request.example.json records a blocked invocation-request gate for a future reviewed plugin capability dispatch path; it is not a plugin loader, runtime, sandbox, host API binding, command executor, or compatibility promise.
  • docs/examples/plugin-dry-run-flow.example.json records a checked dry-run flow contract for future approved plugin manifest, capability, diagnostics, and report-panel summaries; it is not a plugin loader, runtime, sandbox, command executor, or report writer.
  • docs/examples/plugin-input-contract.example.json records the summary-only input shape for future approved plugin diagnostics and report previews; it is not a plugin loader, runtime, input reader, command executor, artifact reader, or compatibility promise.
  • docs/examples/plugin-trace-summary-input.example.json records the summary-only trace metadata input gate for future plugin trace review; it is not a plugin loader, runtime, input reader, trace importer, raw trace reader, command executor, artifact reader, or ABI promise.
  • docs/examples/plugin-output-contract.example.json records the summary-only output shape for future plugin diagnostic, report-panel, and report item previews; it is not a plugin loader, runtime, command executor, artifact writer, or compatibility promise.
  • docs/examples/plugin-blocked-invocation-result.example.json records a blocked, non-executed invocation result for a future plugin path; it is not a plugin loader, runtime, sandbox, permission executor, input reader, report writer, artifact reader, or ABI promise.
  • docs/examples/plugin-permission-model.example.json records the descriptor-only permission profiles, sandbox requirements, and approval gates for future plugin capabilities; it is not a plugin runtime, sandbox, or permission executor.
  • docs/examples/plugin-audit-event.example.json records the redacted audit-event shape for future approved plugin metadata review; it is not an audit logger, plugin loader, runtime, sandbox, or command executor.
  • pccx-lab run-approved-workflow <proposal-id> --format json returns a blocked result by default; the pilot only runs fixed allowlisted pccx-lab commands when explicitly enabled for local validation.
  • pccx-lab analyze <file> --format json returns file-shape diagnostics through the reusable CLI/core boundary.
  • pccx-lab diagnostics-handoff validate --file <path> --format json validates a launcher diagnostics handoff JSON file as a read-only future-consumer boundary.

The GUI is a CLI-backed GUI surface, not a separate logic island. Theme work is experimental. Workflow descriptors, proposals, and result summaries do not execute anything, and the runner pilot is disabled by default. No plugin compatibility promise is made. No MCP runtime, provider runtime, launcher runtime, or editor runtime integration is implemented by this foundation.

The diagnostics handoff validator does not execute pccx-llm-launcher, load plugins, call providers, touch hardware, upload telemetry, write files, or start GUI workflows. It reads a local JSON document and emits a deterministic summary. See docs/DIAGNOSTICS_HANDOFF_CONSUMER.md.

Part of the pccx ecosystem

License

Apache 2.0 License.

Trademark

PCCX™ is a mark used by the PCCX project. Korean trademark applications are pending for PCCX in Classes 09 and 42. Registration has not been granted; do not use PCCX® until the central trademark policy is updated. See pccx/TRADEMARKS.md.

About

CLI-first verification lab for PCCX™ traces, reports, diagnostics, and workflow boundaries.

pccx.pages.dev/en/

Topics

testing rust cli workflow fpga simulation devtools lab verification trace analyzer reports diagnostics systemverilog tauri npu edge-ai hardware-accelerator pccx pccx-lab

Resources

Readme

License

Apache-2.0 license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity
Custom properties

Stars

1 star

Watchers

2 watching

Forks

1 fork
Report repository

Releases

1 tags

Packages

 
 
 

Contributors

Languages