Design proposal — 0.14.0: Git-registry hardening + richer IP-XACT¶

Status: accepted (decisions recorded in §4); in progress on develop (workstream A — the four Git fixes — landed first). The hdl-ip-packager -> hdlpkg rename took 0.13.0 (see docs/design/rename-to-hdlpkg.md); this work now lands in 0.14.0 on the renamed package. Two workstreams, both in this release: A. Git-registry hardening (the follow-ups filed from the 0.11.0/0.12.0 reviews, validated via hdlpkg-livetest) and B. richer IP-XACT mapping + an IP-XACT 2022 output mode.

A. Git-registry hardening¶

GitRegistry (git+... locations, shipped in 0.11.0) works, but the release reviews filed four+ correctness/UX follow-ups. None are integrity bugs (gen --locked verifies the fetched digest regardless), but they weaken provenance and the offline story. All need a real git server, which the in-repo integration tests can't exercise on the CFA-restricted Windows box — so hdlpkg-livetest is the validation vehicle: it runs against a live remote (e.g. a throwaway GitHub/Bitbucket repo or a local git daemon).

#	Problem (in `registry.py`)	Proposed fix
A1	`_resolve` prefers a remote branch over a tag of the same name — `git+…@v1.0.0` resolves `origin/v1.0.0` (a moving branch tip) before the `v1.0.0` tag, so a pinned tag can drift.	Prefer the tag for an `@ref` pin (try `refs/tags/<ref>` first, then `origin/<ref>`, then a raw SHA), or resolve unambiguously and record the SHA. Provenance (`git+<url>@<sha>`) must bind to what the user meant.
A2	`_parse_git_location` mis-splits an scp-style URL with an `@ref` — `git+git@host:repo.git@v1.0` (no `/` before the repo) `partition('@')`s at the first `@`.	Either (a) document `git+ssh://host/repo.git@ref` as the only supported form and reject scp-style with a clear error, or (b) special-case scp syntax (`user@host:path`). Recommend (a) — simpler, unambiguous.
A3	A bare scp URL (`git@host:repo.git`, no `git+`) silently becomes a `LocalRegistry` and fails with a confusing "not in the local registry" error.	In `registry_from_location`, detect an scp-looking string and raise a hint to use `git+ssh://…`.
A4	`gen --locked` against a `git+` location still re-fetches — `_sync` always `git fetch`es when a clone exists, so "works offline after install" is only true for the cache path.	Thread the pinned `@sha` from the lockfile `source`; if that commit is already present in the clone, skip the fetch (offline). Only fetch when the requested commit is missing.

A1 and A4 touch provenance/offline guarantees and are the priority; A2/A3 are UX. The livetest additions (clone → resolve → lockfile provenance → offline re-run, plus tag-vs- branch and scp cases) are the real proof and land alongside the fixes.

B. Richer IP-XACT mapping + IP-XACT 2022¶

Current state¶

to_ipxact (ipxact.py) emits a 1685-2014 component: the VLNV identity + fileSets/file entries (with the fileType user escape), validated against the vendored official XSD. It does not emit model views, ports, parameters, bus interfaces, or memory maps — the richer half of the standard that lets vendor tools wire a core into a block design.

The core constraint¶

IP-XACT ports, parameters, and bus interfaces describe a core's interface, which ip.toml does not capture today and the tool cannot infer without parsing HDL port/parameter lists (we have a token lexer, not a port parser). So "richer IP-XACT" forces a choice about where the data comes from:

B-opt1 — declare it in the manifest (recommended). Add an optional, additive [component]-style section to ip.toml (e.g. [ipxact.parameters], [ipxact.ports], [ipxact.busInterfaces]) where the producer states parameters/ports/bus interfaces explicitly. to_ipxact maps them through. Pros: deterministic, no parser, no gu#essing; the producer already knows these. Cons: an ip.toml schema addition (additive, behind a bumped optional schema), and authoring effort. No guessing.
B-opt2 — parse the HDL. Extract ports/params from the top module/entity. Pros: no authoring. Cons: needs a real port parser (well beyond the coexistence token rules) for SV and VHDL, with all the generate/param edge cases — large, and the "no full parser" stance still holds. Defer.
B-opt3 — minimal now. Skip ports/bus interfaces; add only parameters (cheap to declare) + the 2022 output mode, leaving bus interfaces for a later release once the manifest-schema shape is proven.

IP-XACT 2022 (1685-2022) output mode¶

Add a second serializer target so export-ipxact can emit 2022 as well as 2014: vendor the official 1685-2022 XSD set (as we did for 2014, license-permitting), add a --std {2014,2022} flag (default 2014 for back-compat), and a 2022 variant of the builder (namespace + a few renamed/moved elements). Validate both against their XSDs in tests. This is self-contained and independent of the ports/bus-interface question.

Recommendation¶

Ship B-opt1 scoped to parameters first + the 2022 output mode in 0.13.0, and gate ports/bus interfaces on a confirmed ip.toml schema (a follow-up within 0.13.0 or a 0.14.0 item). This delivers visible IP-XACT value (parameters + 2022) without a parser and without over-committing the manifest schema in one step.

Phasing — small staged commits (toward 0.14.0)¶

Each chunk is code + tests + doc + tracker update, gates green, on develop:

A1+A4 — tag-preferring ref resolution + offline @sha short-circuit (the provenance/offline fixes) + unit tests for the pure parsing/decision logic. [done]
A2+A3 — scp-URL handling + the registry_from_location hint. [done — landed with A1+A4 since all four are in registry.py.]
hdlpkg-livetest — exercise git+ end to end against a live remote (clone, resolve, lockfile provenance, offline re-run, tag-vs-branch); this is workstream A's real proof. [done] Added a --git mode (local bare repo, fully offline) and a --git-remote mode (a real private GitHub repo, created/reused via gh) to run_livetest.py. Both assert: commit provenance in the lockfile, tag-preferred-over- branch (@shared), a stable digest across resolves, and — for --git — that after install --locked the cache serves an offline @sha resolve and an offline gen --locked with the remote removed. Both passed against a live remote.

While validating A4 end to end, two follow-on fixes proved necessary for the offline promise to actually hold (not just the _sync @sha skip): (i) the clone cache is now keyed by the repo URL, not the full @ref location, so an exact-@sha pin reuses the clone a no-ref install already made; and (ii) gen --locked no longer builds the registry at all when every locked artifact is already in the content-addressed cache — so a git+ (or any) source is never re-contacted offline-after-install. 4. IP-XACT 2022 output mode — vendor the 1685-2022 XSD, --std flag, 2022 builder, XSD-validated tests. [done] to_ipxact(manifest, std=...) emits 2014 (default) or 2022; the only structural delta is description placement (2022 carries it in documentNameGroup right after the version, 2014 trails it after fileSets). The full 1685-2022 XSD set is vendored under tests/schema/ipxact-1685-2022/ (Apache-2.0) and both standards are validated against their official XSDs over the example cores + custom fileType cases. export-ipxact --std {2014,2022} wired through the CLI + man page. 5. Richer mapping (parameters) — the optional ip.toml [ipxact.*] section + parameter export, both 2014 and 2022, XSD-validated. [done] A new optional [ipxact.parameters] table (Manifest.ipxact_parameters, an IpxactParameter tuple) accepts a scalar (WIDTH = 8) or a { value, description } table; to_ipxact emits an ipxact:parameters block (name + optional description + value) at the end of the component, valid in both standards. Purely additive and ignorable — an older hdlpkg skips the [ipxact] table — so no schema bump is needed; unknown [ipxact.*] subsections are rejected so a typo is not silently dropped. Ports/bus interfaces remain deferred (decision 4). 6. Docs close-out — architecture/INDEX/user-guide; cut 0.13.0 via /release.

(Workstreams A and B are independent; if B's schema question needs more bake time, A can ship as 0.14.0 alone and B follows as 0.15.0.)

4. Decisions (recorded 2026-06-15)¶

Git fixes: all four (A1–A4) in 0.13.0.
scp-style URLs: document git+ssh://host/repo.git[@ref] as the only supported form; reject scp syntax (user@host:path) with a clear hint (A2/A3).
Richer IP-XACT data source: B-opt1 — declare ports/parameters (and later bus interfaces) in an optional, additive ip.toml [ipxact.*] section; no HDL parsing.
IP-XACT scope for 0.13.0: parameters + the 2022 output mode; bus interfaces / ports deferred to a follow-up once the manifest-schema shape is proven.
Bundling: A + B together in one 0.13.0.

Sequencing: the hdl-ip-packager -> hdlpkg rename ships first (its own release); 0.13.0 then builds on the renamed package.