refactor(engine): expose headless workspace contracts and drop in-process RPC by KoEkko · Pull Request #275 · openecos-projects/ecc

KoEkko · 2026-09-10T03:46:25Z

What Changed

Move workspace create/update, configuration, step configuration, spec validation, and execution readiness into headless engine APIs so CLI and Studio share one contract.
Keep Project Manifest ownership in chipcompiler.project and expose load/create/mutate APIs that CLI reuses through compatibility aliases.
Publish committed analysis, signoff, and QoR scoring from the engine, including a shared scoring policy for headless assessment and CLI reports.
Remove the in-process RPC runtime (chipcompiler.runtime, ecc rpc, FastAPI/jsonrpcserver/uvicorn). Transport stays outside ECC.
Align CLI parameter filters with flow steps, keep read-only inspection side-effect free, and preserve rollback evidence on failed configuration updates.

Scope

Select the areas touched by this PR:

CLI - command behavior, Typer command surface, output formats, or workspace commands.
Flow/runtime - workspace lifecycle, EngineFlow, step execution, logs, metrics, or artifacts.
EDA integration - Yosys, ECC-Tools, DreamPlace, KLayout, PDKs, or native/runtime wrappers.
Build/package - Nix, PyInstaller, wheels, uv.lock, or release artifacts.
CI/release - GitHub Actions, version checks, changelog, or release automation.
Tests/docs only

Runtime And Packaging Impact

No runtime or packaging impact
CLI output or machine-readable contract changed
Workspace layout, flow state, or artifact paths changed
Native toolchain or wrapper behavior changed
ecc-tools or ecc-dreamplace dependency changed
PyInstaller, Nix, or release artifact changed

Notes:

Breaking: ecc rpc and chipcompiler.runtime are gone. Studio must use Runtime Adapter plus these headless APIs.
Packaging drops FastAPI, jsonrpcserver, pydantic, and uvicorn from pyproject.toml, uv.lock, Nix, and PyInstaller collection.
Workspace configuration still uses home/ecc.toml; failed updates restore the previous files under the workspace lock.

Validation

List the commands you ran. Mark checks that are not applicable as N/A.

uv run pytest test/
uv run ruff check chipcompiler test (scoped to changed engine/project/data/test paths)
uv run ruff format --check chipcompiler test (same scoped paths)
PyInstaller smoke: ecc --help, ecc --version, ecc version --json
Nix smoke: nix run .#cli -- --help
Manual flow smoke:
Other: uv run pytest -q test/engine test/project test/cli/params/test_flow_filters.py test/cli/params/test_workspace_commands.py test/cli/commands/test_signoff.py test/data/test_workspace.py test/data/test_workspace_config.py test/packaging/test_cli_entrypoint.py — 199 passed

Skipped checks and reason:

Full uv run pytest test/ not run in this pass; CI Test job covers the remaining suite.
PyInstaller and Nix smokes not run locally; packaging change is dependency removal plus ecc.spec resource collection, not CLI entrypoint behavior.

Checklist

I kept the change scoped to ECC.
I updated docs or user-facing CLI text where behavior changed.
I included lockfile or version metadata updates when dependencies changed.
I documented any submodule updates and why they are needed.
I did not include local caches, virtual environments, or generated build outputs.
I explained skipped validation and remaining risk.

Move the public parameter schema and workspace override helpers into the data layer while keeping CLI compatibility facades.

Preserve creator input modes, flow filters, read-only configuration and signoff assessment semantics across CLI and headless APIs.

Reuse the report scoring policy for headless assessments and expose the committed step callback contract.

Keep ECC headless and leave Runtime Adapter transport dependencies to Studio.

Keep manifest audit timestamps, tolerate forward-version QoR facts and malformed checklists, and map collector failures to the signoff domain error.

Keep the CLI import paths as module aliases while making Project APIs independent of CLI internals, add read-only workspace loading, and materialize config-target parameters.

Keep configuration updates under an exclusive lock and recover from on-disk backups instead of restoring file bytes from process memory.

Move fail thresholds, weights, and metric selection into qor_scoring. CLI reports and Snapshot assessment call that module; stop documenting a GUI port and a second threshold table.

Bring in #243 so the branch sits on current ECC main.

Studio rejects the whole snapshot QoR section when any analysis metric uses category "power". Restore the canonical power_integrity mapping and remap existing on-disk qor_metrics.json when assembling snapshots.

Studio reads std_cell/macro/io-pad metrics plus database_facts and lvs_connectivity_summary from the snapshot. Emit those from existing feature JSON, and reject STA when pdk.sdc is unset instead of crashing.

Emin017 · 2026-09-10T07:20:38Z

Remove the in-process RPC runtime (chipcompiler.runtime, ecc rpc, FastAPI/jsonrpcserver/uvicorn). Transport stays outside ECC

So after this PR is merged, what will the new transport solution be?

KoEkko · 2026-09-10T07:48:51Z

Remove the in-process RPC runtime (chipcompiler.runtime, ecc rpc, FastAPI/jsonrpcserver/uvicorn). Transport stays outside ECC

So after this PR is merged, what will the new transport solution be?

Transport is still stdio JSON-RPC; ownership just moves from ECC to the Studio Runtime Adapter. ECC keeps only the headless engineering APIs shared by the CLI and the Adapter.
Just like this.

Emin017 · 2026-09-10T07:51:57Z

Transport is still stdio JSON-RPC; ownership just moves from ECC to the Studio Runtime Adapter. ECC keeps only the headless engineering APIs shared by the CLI and the Adapter. Just like this.

So will the Studio Runtime Adapter be implemented in TypeScript in the ecos-studio repository?

KoEkko · 2026-09-10T07:54:43Z

Python

Sizer stores Timing Opt as timing_optimization_sizer. Snapshot analysis fell back to Timing optimization_sizer, so Studio showed empty QoR, layout, reports, and subflow for a successful step.

KoEkko added 19 commits September 8, 2026 23:38

fix(cli): align parameter filters with flow steps

754b9f0

feat(workspace): share project and workspace contracts

aa270df

feat(workspace): add revision-aware configuration updates

02929ef

feat(workspace): add scoped step configuration

1c989c8

feat(engine): add headless execution contracts

c056ecc

feat(engine): expose analysis and signoff facts

85cb3a6

refactor(cli): use headless signoff interface

150deaf

refactor(runtime): move transport ownership to studio

84eb3c7

fix(workspace): complete cross-creator update contract

b20d51f

fix(workspace): preserve rollback evidence atomically

1c4f4af

refactor(data): centralize parameter catalog ownership

d1cbde1

Move the public parameter schema and workspace override helpers into the data layer while keeping CLI compatibility facades.

fix(workspace): complete headless lifecycle contracts

3b50fc1

Preserve creator input modes, flow filters, read-only configuration and signoff assessment semantics across CLI and headless APIs.

refactor(engine): share canonical QoR scoring

7e1a0a3

Reuse the report scoring policy for headless assessments and expose the committed step callback contract.

chore(deps): remove obsolete RPC server dependencies

2259a69

Keep ECC headless and leave Runtime Adapter transport dependencies to Studio.

fix(engine): harden query and signoff error boundaries

621489a

Keep manifest audit timestamps, tolerate forward-version QoR facts and malformed checklists, and map collector failures to the signoff domain error.

refactor(project): move manifest ownership to headless domain

6993937

Keep the CLI import paths as module aliases while making Project APIs independent of CLI internals, add read-only workspace loading, and materialize config-target parameters.

fix(workspace): preserve read-only and error boundaries

932bf87

refactor(workspace): isolate hydration helpers

591a40a

fix(signoff): keep read-only inspection side-effect free

cd718d0

KoEkko marked this pull request as draft September 10, 2026 03:51

KoEkko added 5 commits September 10, 2026 12:24

refactor(workspace): replace in-memory restore with flock backups

d16dedd

Keep configuration updates under an exclusive lock and recover from on-disk backups instead of restoring file bytes from process memory.

docs(qor): point scoring rules at the shared qor_scoring module

13fb33f

Move fail thresholds, weights, and metric selection into qor_scoring. CLI reports and Snapshot assessment call that module; stop documenting a GUI port and a second threshold table.

merge(main): include scoped stdio redirection tests

7f27a70

Bring in #243 so the branch sits on current ECC main.

fix(qor): map synthesis power metrics to power_integrity

f384034

Studio rejects the whole snapshot QoR section when any analysis metric uses category "power". Restore the canonical power_integrity mapping and remap existing on-disk qor_metrics.json when assembling snapshots.

fix(qor): restore instance metrics and dashboard detail facts

2f75cf0

Studio reads std_cell/macro/io-pad metrics plus database_facts and lvs_connectivity_summary from the snapshot. Emit those from existing feature JSON, and reject STA when pdk.sdc is unset instead of crashing.

KoEkko closed this Sep 10, 2026

Emin017 reopened this Sep 10, 2026

KoEkko added 2 commits September 10, 2026 17:18

fix(snapshot): resolve sizer Timing Opt directory names

cd7eac4

Sizer stores Timing Opt as timing_optimization_sizer. Snapshot analysis fell back to Timing optimization_sizer, so Studio showed empty QoR, layout, reports, and subflow for a successful step.

style(test): drop extra trailing newline in qor facts fixture

b10ba2d

KoEkko closed this Sep 11, 2026

KoEkko deleted the ekko/refactor-ecc-cli-integration branch September 14, 2026 02:44

Navigation Menu

Uh oh!

refactor(engine): expose headless workspace contracts and drop in-process RPC - #275

refactor(engine): expose headless workspace contracts and drop in-process RPC#275
KoEkko wants to merge 26 commits into
mainfrom
ekko/refactor-ecc-cli-integration

KoEkko commented Sep 10, 2026

Uh oh!

Emin017 commented Sep 10, 2026

Uh oh!

KoEkko commented Sep 10, 2026

Uh oh!

Emin017 commented Sep 10, 2026

Uh oh!

KoEkko commented Sep 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

KoEkko commented Sep 10, 2026

What Changed

Scope

Runtime And Packaging Impact

Validation

Checklist

Uh oh!

Emin017 commented Sep 10, 2026

Uh oh!

KoEkko commented Sep 10, 2026

Uh oh!

Emin017 commented Sep 10, 2026

Uh oh!

KoEkko commented Sep 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants