HTTP API¶
Everything the UI does is an HTTP call to the Design API; scripts and agents use the same calls. A running server describes them itself:
| URL | |
|---|---|
http://127.0.0.1:8700/docs |
interactive API documentation (Swagger UI) |
http://127.0.0.1:8700/redoc |
the same, as ReDoc |
http://127.0.0.1:8700/openapi.json |
the OpenAPI schema |
Conventions:
- Projects, libraries and cells are in the path:
/api/p/{project}/l/{lib}/.... A changeset's working copy is the project{project}~{changeset}(see Changesets). X-Undine-Actor: user | agent:<name>attributes an edit;reasonin the body records why (see the operation log).- Errors are
{"detail": "...", "code": "...", "params": {}}with 400 (bad request), 403 (not allowed, e.g. a read-only library, or a dependency's code no person trusted), 404 (no such object), 409 (someone else is editing that changeset, a whole text sent back was loaded from a file that changed since: see below, or a changeset's merge conflicts: see Changesets) or 502 (an LLM connection failed).codenames the kind (invalid_request,busy,stale,merge_conflict,not_set_up,unsupported_library,untrusted,resolution_refused, ...);detailis English, and the UI words the kinds it knows in its own language. A kind with values of its own has them at the top level of the body and inparamstoo. - The views a client sends back whole, the RTL (
POST .../c/{cell}/rtlwithop: save) and the intent's YAML (POST .../c/{cell}/intent/editwithop: replace), take"base": the"sha"theirGETreturned with the text edited from. When the file changed since (a git merge, checkout or pull), the save is a 409 instead of undoing that change; withoutbaseit is saved as before. GET /api/projectslists a project whoseproject.jsoncannot be read (a git merge left conflict markers in it) as{"name", "error"}; opening it is a 400 that says so.- Agents can also use the MCP endpoint.
Projects, PDKs and library dependencies¶
| Call | |
|---|---|
GET /api/pdks |
the PDKs the server found: id (name@ the first 12 characters of the version), name, family, the full version, and what Undine supports of it (profile) |
POST /api/pdks/rescan |
find the PDKs again under the server's PDK roots (one installed or fetched since the server started), with no restart; returns {pdks} as GET /api/pdks lists them. The open layouts and editors of a project whose PDK now resolves to another install (or to one at last) are reloaded on their next use |
GET /api/projects, POST /api/projects {name, pdk?} |
list the projects; create one pinned to a PDK (an id, or a bare name: a version whose PCells Undine runs, the tested one first) |
GET /api/p/{project} |
the project, its PDK and its libraries (own, dependencies, the PDK's). Each library has package (a dependency's package name, else null), direct (false for a package only other packages place) and via (the packages that place it); a dependency's cell outside its package's [exports] has internal: true in the cell list and is left out of the symbols offered for placement |
POST /api/p/{project}/libs {name} |
create a library of the project's own (libs/<name>, named in project.json) |
POST /api/p/{project}/pdk {pdk} |
pin the project to another PDK version (recorded in pdk_history and in undine.lock, which it creates when the project has none; a format 2 lock gets the new PDK's pin, its tree hashed first); returns {from, to}. Not in a changeset preview |
GET /api/p/{project}/deps |
the project as locked vs. as installed here (lib status), below. A dependency project.json no longer names but still installed or locked is listed with state: "leftover" and an issue (so ok is false) |
POST /api/p/{project}/deps {name, git, rev?, subdir?, package?} or {name, package, version?, index?} |
add a library dependency (lib add), or with no git a package from an index (pkg add: version a requirement, default ^ the newest that fits; index a nickname or URL, default the default index; needs lock format 2): fetched, installed read-only and locked, with the packages it depends on. Returns the lock entry with name, cells, public_cells, internal_cells, created (whether it made undine.lock), package and version (null for a plain dependency), resolved (each entry resolved: {name, ...entry}, for a package also package, version, names, via, flagged, trusted), flagged ({spice, rtl, tcl}: what the trust rule finds in it) and trusted. package: the [package] name its manifest must give. A local git (file://, /path, ~/path) is refused unless the server was started with --dep-root and the repository is under one of those directories; the same holds for sync and update, and for every URL a manifest names. Refusals: below |
POST /api/p/{project}/deps/sync {offline?} |
install every dependency exactly as locked (lib sync), and remove each leftover (its files and its undine.lock entry); returns {libraries: [{name, action, commit}]}, action one of ok (installed as locked already), installed, removed (commit may be null for removed). A package's row also has package, and a row whose package the locked PDK does not fit has warning (CHAIN: does not fit the PDK ID: REASON): the package is installed all the same, and GET /deps reports it as an issue. The body is optional: {"offline": true} never fetches, false may, and no body (or null) follows the server's UNDINE_OFFLINE. Frozen: a lock that does not pin a dependency as project.json names it is refused before anything is read (lib lock resolves it). All or nothing: when one dependency fails (a remote unreachable, files that do not match the lock, offline and not in the store), none is installed and none removed. A dependency in the store is installed from there and reads no repository; a local repository, also one project.json names, is checked against --dep-root before git reads it (a fetch, or a commit kept in the store's copy of the repository) |
POST /api/p/{project}/deps/lock |
lib lock: fetch, install and lock what undine.lock does not pin as project.json names it (under the --dep-root rule, as add), and record the tool versions in use now (in a format 1 lock the PDK id too); returns the status with resolved: [{name, git, rev?, subdir?, commit, sha or tree}]. It writes the lock in its own format: making it format 2 is the command line's (lib lock --format 2, pdk verify --pin) |
POST /api/p/{project}/deps/{name}/update {rev?, version?} |
move a dependency to rev (default: its rev again), or a package from an index to the newest version its requirement accepts (version: a new requirement, written to project.json); returns {name, from, to, rev, changed, used_by, packages_changed}: the changed files and the cells using them, and packages_changed: [{package, names, from, to, changed}] for each entry that moved, was brought in (from null) or is no longer needed (to null). The trust of what moved is taken out of project.json |
POST /api/p/{project}/deps/{name}/remove |
remove a dependency, with the packages nothing needs any more; returns {ok, name, removed_packages: [{package, version, commit, names}], kept: [{name, placed_by}]} (package null for a plain dependency; kept: packages another dependency still places) |
POST /api/p/{project}/deps/changeset {action, name?, git?, rev?, subdir?, package?, version?, index?, pdk?, title?, reason?} |
the browser's own Add, Update, Remove and Set PDK: a small changeset opened (title title, default Add NAME, Update NAME, Remove NAME, Set the PDK to PDK; a project in no git repository is made one first, as any changeset open does), the operation run in its working copy (action add, update, remove with the fields of the routes above, or pdk with pdk), then adopted, which installs it in the project from the store. Returns {changeset, status: "applied", result, git_setup, first_commit, first_commit_note, deps?, deps_warning?, deps_dropped?, deps_pending?}: result what the direct route returns (POST /deps, /deps/{name}/update, /deps/{name}/remove, or {from, to, created} as POST /pdk), git_setup, first_commit and first_commit_note as the changeset's open answers them, the rest as the adopt's Merge. What the request alone shows wrong (an add with neither git nor package, a name that is taken or is no dependency, no or an unknown pdk) is refused before anything is opened, so such a refusal never makes the project a repository. An operation refused answers as the direct route would, the changeset discarded; an adopt refused (409 merge_conflict, ...) carries changeset in its body and params, the changeset left open for review. On a preview ({project}~{id}) the operation goes into that changeset, not adopted: status: "open". The direct routes above work as before |
GET /api/p/{project}/trust |
what the project trusts and what each installed dependency holds: {trusted: [keys], dependencies: [{name, package, version, key, trusted, findings}]}, one row per local name. In a changeset preview trusted includes the project's keys. A finding is {content, cell, file, where, kind, line, text} (below) |
GET /api/packages?q=&index=&project= |
the Packages section: the newest version that is not yanked of each package of an index whose name or description holds q (every package for an empty one): {index, index_name, commit, packages: [{name, version, description, license, yanked, fits}]}. index: a nickname or URL (default: the default index); project: for the nicknames its project.json names, and fits ({ok, reason}: whether the version accepts the project's PDK; null without project). The first read of an index fetches it; after that the local copy is read until a refresh |
GET /api/packages/{name}?index=&project= |
every version of a package, newest first: {index, index_name, commit, name, newest, locked, versions: [{name, version, description, license, yanked, fits, git, subdir, commit, tree, size, pdk, exports, deps: [{name, package, req, index, index_name}]}]}. newest: the newest that is not yanked; locked: the version the project locks of it from this index, or null. 404 when the index lists no such package |
GET /api/indexes?project= |
the indexes known here and to the project: {indexes: [{name, url, commit}]} (commit null before the first fetch) |
POST /api/indexes/{name}/refresh?project= |
fetch the index name (a nickname) again: {index, index_name, commit} |
POST /api/p/{project}/trust {name, token} or {name, untrust: true} |
trust the dependency installed as name, with a confirmation token of kind trust, or take that trust back (no token): {key, trusted}. Below |
The lock status¶
GET /api/p/{project}/deps (and /deps/lock) answers:
| Field | |
|---|---|
format |
the lock's format, 1 or 2; null without undine.lock |
libraries |
[{name, kind, state, ...}]: own libraries (kind: "own", or "linked" from outside the project), and dependencies (kind: "dependency") with git, rev, subdir, locked and installed (commits), state (ok, unlocked, missing, other version, modified, leftover), hash ("sha" for a format 1 entry, "tree" for a format 2 one, null when not locked) and in_store (whether its files are all in the store, so that a sync needs no network). One row per local name: the dependencies project.json names in its order, then the names packages place, then leftovers. Each dependency row also has package and version (null for a plain dependency), names (every local name of that entry), direct, via (the packages that place it), chain (demo -> analog_ip 1.2.0 (v1.2.0 @ 229914698b1f) -> ..., or null), trusted and flagged ({spice, rtl, tcl}; both null when not installed), internal_cells, and pdk ({compatible, reason, note, built_with}: compatible null with reason no manifest or no [pdk] when not checked; null for a row not locked). A package from an index has index (its URL) and requirement (project.json's), and newer ({accepted, newest}) when the local copy of its index lists a newer version: the newest its requirement accepts and the newest listed, each null when not newer. The local copy is read as it is, never fetched |
pdk |
{requested, locked, commit, installed, state, changed, verified_by, ok}: project.json's PDK, the lock's id and full commit (format 2), the id found here, and state, one of none, missing, not locked, other version, not pinned, mismatch (project.json and the lock disagree), error (a pin without tree hashes), unchecked (files changed since the last hash: run pdk verify), modified, unverified (matches the pin; trust on first use), verified (not given before PDK profiles publish hashes). changed: per part, the files added, removed, modified. The status never reads the PDK itself, only the hashes kept in the store |
tools |
[{name, locked, now, now_path, ok}], locked and now each {version, from, text?} or null (not installed, or not recorded): the version number, where the executable came from (pixi, UNDINE_TOOLS, undine-tools, env, PATH; null in a format 1 lock), and the banner when no number could be read from it |
issues |
what makes ok false: a dependency not as locked, the PDK missing, modified or not as project.json asks, no undine.lock, a library linked from outside; a package the PDK does not fit, a project cell named like a package's cell, a lock that does not install what a package needs, a trusted entry that is not a key |
warnings |
worth a look, never an issue: another tool version or origin, another Undine version, tools not pinned (pixi.lock not recorded) |
notes |
the PDK unverified, unchecked or not pinned (format 1), another Undine commit or pixi.lock, and for format 1 that origins are not recorded; a dependency not trusted that holds what the trust rule refuses, PDK compatibility not checked, a package used at a commit other than its built_with, a project cell named like a plain dependency's, a name in project.json that shadows another library |
ok |
no issue |
The dependency calls are refused in a changeset preview. They run one at a time per project, each from project.json
as the one before it left it. They fetch (git) without holding up other requests and take the server's lock only to
swap the installed files and write project.json and undine.lock. What they fetch goes into the user's
store, shared by every project, and is installed by hard link; in a format 2 lock, add,
update and lock pin an entry by tree, in a format 1 lock by sha. Undine's writers of those two files (the server's
requests, the lib commands of the CLI, adopting or reverting a changeset) take a lock file, .undine/project.lock,
so they never overwrite each other. A git command run on the project (checkout, pull, merge) does not take it: run it
when no lib command or dependency call is running.
Dependency refusals¶
Refusals, with HTTP 400 and a detail that says what to do:
- undine.lock it cannot read. Every
/depscall andPOST /pdkread the lock before they change anything, and refuse one of a newer format (undine.lock has format 3, made by a newer Undine (this one reads formats 1 and 2): update Undine ...), one with aformatno Undine writes, and one that is not valid JSON or not a JSON object. Nothing of the project is changed.GET /api/p/{project}still opens the project. - A lock that does not pin what project.json names.
/deps/syncrefuses it, naming each dependency (analog_ip: project.json asks for rev v2, undine.lock locks v1, ornot in undine.lock) and thelib lockandlib updatecommands;/deps/lockresolves it. - Offline and not in the store.
/deps/syncwithoffline(orUNDINE_OFFLINE=1) refuses when a locked dependency is neither in the store nor in a kept repository:offline, and not in the store: analog_ip @ 229914698b1f (sha e6d28176...): run the sync with the network .... The adopt of a changeset refuses the same way (409merge_conflict, a conflict of undine.lock) a lock entry it brings whose files are neither in the store nor installed in the project:analog_ip @ 229914698b1f (...) is not in the store: fetch it first. - An index the browser may not read.
GET /api/packages,/api/packages/{name}and/api/indexes/{name}/refreshread an index under the rule of a git dependency: a local index only below--dep-root, a remote one only on a host of the configured indexes or one given with--dep-host; refused (400) before any fetch. - A local repository outside
--dep-root.POST /deps,/deps/sync,/deps/lockand/deps/{name}/updaterefuse agitthat isfile://, an absolute path or~/...unless its real path (symlinks and..resolved) and its git directory are under a directory given withserve --dep-root; the message names--dep-rootand thepython -m undine lib ...command that does it from the command line. Afile://URL with a host other thanlocalhost, a query or a fragment is refused asnot a plain file:// URL (file:///path/to/repo). Remote URLs (https://,ssh://,git://,git@host:path) are checked by their host instead (next item). - A remote host not allowed. The same routes fetch a remote repository or index only from the host of an index
this machine configures (the default index's,
github.com, and those in$UNDINE_HOME/config.toml, not a project's ownindexes) or one given withserve --dep-host. This covers a URL from the request and one that project.json, a manifest or an index line names. Anything else is refused before git runs:https://gitlab.com/me/ip.git: from the browser this server fetches only from github.com (...); not from gitlab.com. Start the server with --dep-host gitlab.com, or run python -m undine lib add ... from the command line. From these routes, a commit the server does not serve by itself (an abbreviated id, a commit no branch or tag reaches) is not looked for by fetching every branch and tag; the message says to run the operation once from the command line, which keeps the commit for the browser to read.
The refusals of packages have codes of their own; detail is the whole message,
and each nothing changed:
| Code | HTTP | When | Extra |
|---|---|---|---|
resolution_refused |
409 | POST /deps, /deps/lock, /deps/{name}/update: the requirements do not resolve (two versions of one package, a version that does not match, one local name for two packages, a reserved name, a cell clash, a package the PDK does not fit, a bad manifest, an index requirement, a local URL from a remote package) |
problems: [{code, message, chains}], code one of conflict, version, local_name, reserved_name, cell_clash, pdk, manifest, index_dependency, local_url, package_mismatch, no_manifest |
needs_lock_format_2 |
409 | a package with dependencies, or under another local name, on a format 1 lock; no route converts the lock: lib lock PROJECT --format 2 |
|
not_direct |
400 | /deps/{name}/update or /remove of a name only packages place |
placed_by: [...] |
pdk_incompatible |
409 | POST /pdk to a PDK a locked package does not accept |
packages: [{name, package, version, chain, reason, family, variants, commits, compat, built_with}] |
not_synced |
409 | a locked package is in neither the store nor the project's install (a fresh clone): lib sync first |
|
untrusted |
403 | a job that would run a dependency's content no person trusted (below) | name, package, key, cell, findings |
Trusting a dependency¶
A simulation (POST /api/p/{project}/sim; the agents' sweeps and spec checks too), an LVS run (/lvs,
/netgen-lvs, when it starts), an RTL lint or simulation (.../c/{cell}/rtl/lint, /rtl-sim), and the netlist
view with Xschem's netlister (GET .../c/{cell}/netlist?backend=xschem) are refused with 403 and code untrusted when they
would use what the trust rule refuses in a dependency the project
does not trust. The body has name (the dependency's local name), package (null without a manifest), key
(analog_ip@1.2.0, or ip@229914698b1f), cell (<local>/<cell>, or <local>/<file> for RTL and Tcl) and
findings: [{file, kind, line, text}]; with several dependencies refused at once these name the first, and
findings holds them all. kind is one of control, control_line, path, unparsed, rtl_c, systemc,
rtl_system, dpi, rtl_path, rtl_define, tcl. The netlist view with backend=undine is not refused: its
warnings add not trusted: would be refused in a simulation: ....
A person trusts a dependency in the browser's trust dialog:
| Call | |
|---|---|
POST /api/confirmations {kind: "trust", project, name} |
after the person's click: {token, expires, key, tree, findings}, the token bound to the project, the local name, the key and the installed files' hash (tree). 404 when nothing is installed under name, 400 in a changeset preview or for an install without a record |
POST /api/p/{project}/trust {name, token} |
use the token up and add the key to project.json's trusted: {key, trusted: true}. 403 for no token, an unknown, used or expired one, one of another kind, project or name, and when what is installed changed since it was confirmed (... changed since it was confirmed ...: confirm the trust again); 400 in a changeset preview |
POST /api/p/{project}/trust {name, untrust: true} |
take the trust back, with no token: {key, trusted: false} |
A finding of the listing and the confirmation is {content, cell, file, where, kind, line, text}: content spice,
rtl or tcl; cell <local>/<cell> (null for RTL); file <local>/<path>; where the file and the instance
and attribute the text is in. As for PDK fetches, no MCP tool, undine call command, Python client method or agent
tool asks for a trust confirmation or trusts anything.
PDK fetch¶
A PDK missing on the server is installed with ciel, only after a person confirms it in the browser's Fetch PDK dialog (Fetching a project's PDK):
| Call | |
|---|---|
GET /api/p/{project}/pdk/fetch-plan?allow_network=false |
what a fetch would run: {family, variant, commit, libraries, source, root}, libraries null for ciel's default set, source ciel's data source, root the PDK root ciel installs into (the first the server scans that has ciel/, does not exist yet or is empty). The commit comes from undine.lock's pin, else from the 12-character id, expanded from the installed PDKs, or with allow_network=true by ciel ls-remote. Reads only |
POST /api/confirmations {kind: "pdk", project, commit, variant, libraries, allow_network?} |
a token for exactly that fetch: {token, expires, plan}. The request must match the plan the server makes now (commit may be its first 7 or more characters; libraries null for ciel's default set), else 400 (... show the fetch dialog again). The token is single use, expires after five minutes (expires, a Unix time) and is bound to the project and the whole plan. The other kind is trust (Trusting a dependency); any other is a 400. A changeset preview and a source other than ciel's default are refused |
POST /api/p/{project}/pdk/fetch {token} |
start ciel fetch as a job, once the token is used up: {job} (below). 403 for no token, an unknown, used or expired one, or one for another project; 400 for a changeset preview, or when the plan changed since it was confirmed (undine.lock or project.json changed: confirm again). One fetch of a PDK at a time: a second one waits, queued |
GET /api/p/{project}/pdk/fetch/{job} |
the job: {id, project, state, log, result, error, created, ended}, state one of queued, running, done, failed; log the last 200 lines of ciel's output; result {path, verify} once done, verify the PDK against undine.lock ({state, changed, missing_libraries, extra_libraries, warnings}, state as in pdk verify); error the reason it failed. 404 for a job the server does not know |
The job holds no lock of the server or the project while ciel runs, writes nothing into the project (undine.lock included), and rescans the PDKs when ciel is done, so the project finds its PDK without a restart. Jobs live in the server's memory: a restart forgets them (ciel's run ends with the server or runs to its end; fetch again, or rescan, to find what it installed). The server keeps the last 50 finished jobs.
No MCP tool, undine call command, Python client method or agent tool asks for a confirmation token or starts a
fetch: only the dialog does, after the person's click. Undine has no authentication yet, so this keeps agents that work
through Undine's tools, and mistakes, from fetching; it is no defence against a process that runs as the person.
Changesets¶
A changeset is a git branch of the project, undine/<project>/<id>, and its working copy, the project
{project}~{id} (its baseline, the base commit checked out read-only: {project}~{id}~base); see
Changesets and the design, changesets on git branches.
{project} in these calls may also be a preview's name (except to open one): they act on the real project.
| Call | |
|---|---|
POST /api/p/{project}/changesets |
opens one ({"title", "reason"}, X-Undine-Actor): the record, with "git_setup": true when the project was in no git repository and git-setup made it one, "first_commit": the project's first commit made then (its files as they were, a log's unsaved layout edits as a journal, as the base has them; Undine's own output and the changeset records left out; null when none was made: a commit of the person's came first), so that what is applied is committed, and "first_commit_note": what to do after it (git's index not reset to it: run git reset), or why none was made; null. 400 not_set_up (below) when the project is in a repository not set up for Undine. 400 unsupported_library (below) when one of the project's own libraries is one a worktree cannot hold: at its folder, above it, inside it or where a link on the way leads, a symbolic link that leads out of the project or nowhere, whose text is an absolute path or climbs out of the project, or that the repository does not keep (nor what it leads to), or a git repository of its own (a clone, a submodule). That is checked before anything is set up: a refused open makes no repository (the design) |
GET /api/p/{project}/changesets |
the changesets: id, title, reason, actor, created, status, preview, and git; closing (below) while one is being adopted, discarded or reverted. Newest first (by created, then by id) |
GET /api/p/{project}/changesets/{id} |
the record (below), with the changes by library (changes: the operations, net of undo and redo), the checks with their freshness (verify), and while open the writer (writer) and the last change of each view (activity); once closed, the changes and checks as archived, retained, and the evidence with its size now (evidence.size); closing while it is being closed |
GET /api/p/{project}/changesets/evidence |
the evidence of the closed changesets as it is now: {"bytes", "raw" (of them, the waveforms a prune removes), "changesets": {id: {"bytes", "raw", "files", "shared", "raw_shared", "pruned"}}} (size below) |
GET /api/p/{project}/changesets/{id}/evidence[?check=true] |
a closed changeset's evidence: {"path", "captured", "commits"?, "size", "bytes" (as captured), "linked", "pruned" (the manifest's notes), "jobs" (each with"pruned": its files a prune removed, and the job's"about": the packages, PDK and profile it used, when it recorded them), "packages" and "pdk" (: what each side's undine.lock pins; see [Job provenance](data.md#job-provenance))}; check=true reads every archived file against its hash: "check": {"ok": count, "pruned", "missing", "changed": [path in the evidence]} (a pruned file is pruned, not missing). 400 for an open one |
POST /api/p/{project}/changesets/{id}/evidence/prune |
removes the waveforms (*.raw, *.vcd, *.fst) of a closed changeset's archived runs, keeping their status, logs, results and the manifest's hashes, and notes it in the manifest and the record (X-Undine-Actor): {"pruned": {"t", "by", "files", "bytes", "freed"}, "size"} ("freed": of the bytes, those no other name held; a working copy the closure kept frees the rest when it is removed). A person's call: 403 for an agent's actor (agent:...); 400 for an open changeset; 409 busy while it is being closed or reverted |
GET /api/p/{project}/changesets/{id}/diff[?lib=L&cell=C] |
the semantic diff of the branch, in /git/diff's shape: from the base to the working copy while it is open (what no operation recorded too: what an apply merges), to the tip it was closed with afterwards. 400 for an older changeset (no git) |
POST /api/p/{project}/changesets/{id}/verify[?fresh=true] |
the needed checks on the working copy and the baseline (the working copy is committed onto the branch first): DRC with the KLayout deck and, where the PDK profile says so (sky130), Magic (checker), LVS, and its ERC (kind: "erc", warnings with findings); a job that ran on the same inputs is reused (reused), unless fresh |
POST /api/p/{project}/changesets/{id}/apply |
merges the branch into the project, all or nothing: the record with "applied" (below). A conflict is a 409 merge_conflict (below), nothing written, the changeset still open. 400 for an older changeset (open it again as a new one), while someone is writing it, or while an interrupted merge of it is still to be finished (below). One changeset is closed at a time: the call waits while another is being adopted, discarded or reverted (its closing says waiting); 409 busy while this one is being closed already (also for discard and revert) |
POST /api/p/{project}/changesets/{id}/revert |
takes an applied changeset back by the merge the other way round (the files it added kept): the record with "reverted". A later edit of what it changed is a 409 merge_conflict. 400 for one applied before changesets were git branches, or while an interrupted merge of it is still to be finished |
POST /api/p/{project}/changesets/{id}/discard |
archives the evidence, removes the worktrees, keeps the branch: the record with "discarded" (X-Undine-Actor). 400 while an interrupted merge of it is still to be finished |
POST /api/p/{project}/changesets/{id}/deps {action, name, git?, rev?, subdir?, package?, version?, index?, reason?} |
a dependency operation in the working copy (action add, update or remove, with the fields of POST /deps and /deps/{name}/update): fetched under the working copy's own dependency lock, then written and installed there (never in the project, nor the baseline: 403), and recorded in its project log (history/@project.jsonl, a name no library can have) with project.json and undine.lock before and after; the timeline shows it, restore takes it back (installing from the store), the adopt merges and installs it. Returns {changeset, op: {gseq, opid} | null (nothing changed), result: what the direct route returns, status: the working copy's deps status}; refusals as the direct routes', and 409 busy while someone else holds the write lease |
POST /api/p/{project}/changesets/{id}/pdk {pdk, reason?} |
pins the working copy to another PDK, recorded the same way (pdk_set): {changeset, op, old, new, created}; 409 pdk_incompatible as POST /pdk |
GET .../changesets/{id}/timeline, POST .../restore, GET .../activity, POST .../writer/stop |
the timeline, restoring a checkpoint, following the writer, stopping it (Live changesets) |
record {"id", "project", "title", "reason", "actor", "created", "status": open | applied | discarded | reverted,
"preview": "{project}~{id}", "baseline": "{project}~{id}~base", "libs": [lib],
"git": Git (absent for a changeset made before changesets were git branches: review and discard only),
"verify": [check], "evidence"?: Evidence, "cleanup_warning"?: text, "closing"?: Closing,
"interrupted"?: text (a merge a stopped server left was taken back: the note, in cleanup_warning too;
gone once an apply, revert, discard or recovery succeeds),
"retained": closed, and the working copy its closure kept (a late edit) is still there to open,
"applied": Merge | null, "reverted"?: Merge, "discarded"?: {"t", "by"}}
("base": {lib: {}}, the libraries, is kept for older readers)
Evidence {"path", "captured", "jobs": how many runs, "bytes": its size as captured,
"pruned"?: {"t", "by", "files", "bytes"} (its waveforms removed: the last prune, the files and bytes of all),
"size"?: {"bytes", "raw", "files", "shared", "raw_shared"} (GET of a closed changeset: as it is now;
"raw": the waveforms; "shared", "raw_shared": of the bytes and of the waveforms, those of files another
name still holds, a working copy the closure kept: removing them from the evidence frees them only
once that copy goes too)}
Closing {"action": apply | discard | revert, "by", "since",
"phase": waiting | committing | evidence | merging | cleanup,
"behind"?: {"id", "title", "action"} | null (waiting: the closure under way; null: another operation),
"files"?, "files_total"?, "bytes"?, "bytes_total"? (evidence: done of how many)}
(in memory: only while this server closes it; also in GET /api/p/{project}/live)
Git {"branch": "undine/<project>/<id>", "base": sha (the project's files when it was opened),
"head": sha | null (the project's HEAD then), "prefix": the project's directory in its repository,
"base_seq": {lib: the last seq of the log in the base}, "tip": sha | null (the branch's last commit;
null: none yet), "ref": "refs/undine/changesets/<project>/<id>" | null (the branch kept once closed),
"commits": the commits from the base to the tip}
Merge {"t", "by", "commit": sha | null (the merge commit, or the revert's commit, on the user's branch; null: not
committed), "uncommitted": the merge was left in the working tree, "why": why it was ("no_commit": the
repository has no commit yet, POST .../git/first-commit makes one; "changes": the project had other
uncommitted changes; "failed": the commit failed, or Undine stopped before it; null when committed,
absent in an older record), "paths": [the files it wrote], "tip": the commit applied (apply),
"kept": [the files the changeset added, kept] (revert),
"deps"?: [the install's rows, as POST /deps/sync's] (a merge that changed undine.lock or project.json's
dependencies installs them from the store, offline; nothing is fetched at adopt),
"deps_warning"?: what the install could not do (said, the merge done: lib sync installs later), or a
dependency that went while cells still place it, "deps_dropped"?: [{"name", "used_by": ["lib/cell"]}],
"deps_pending"?: true (another operation held the project's dependencies, a `pkg add` fetching: the
adopt never waits for it, `lib sync` installs them)}
409 {"detail", "code": "merge_conflict", "params": {},
"files": [{"path" (from the project's directory), "kind": schematic | symbol | layout | netlist |
intent | log | text, "conflicts": [Conflict]}]}
400 {"detail", "code": "not_set_up", "top": the repository's top (a path), "project": the project's name,
"command": the command line that sets it up, "params": {"top", "project", "command"}}
(opening a changeset in a repository not set up for Undine; "command" is `undine git-setup <project>`,
with `--root <root>` first in a store that is not the command's default one)
400 {"detail", "code": "unsupported_library", "library", "path": the link or the repository (from the
project's directory), "kind": link_out | link_nowhere | own_repository, "target": the link's text |
null (a repository), "params": {"library", "path", "kind", "target"}}
(opening a changeset of a project with a library a worktree cannot hold. link_out: the link leads out
of the project, its text is an absolute path, or it climbs out of the project; link_nowhere: it leads
to nothing, or the repository does not keep it or what it leads to; own_repository: a clone or a
submodule. The detail says what to do)
A Conflict is the one of /git/verify (below): {"id", "what", "base", "ours", "theirs", "taken", "resolved"}; for
an apply, ours is the design now, theirs the proposal and base the value when it was opened; for a revert,
theirs is the value before it was adopted and base as adopted. A conflict about a whole file has the id file
(changed on one side, deleted on the other: what "deleted on ours, changed on the other side"; a side that cannot
be read as its view: what "the what "not a file in the project"), lines (a file of no view, merged
by lines), error (a merge that failed: what "cannot merge: ...", a side that cannot be read, a binary file) or
changed (the file changed in the project while the merge was being made, by something that did not wait for it,
such as another process: nothing was written, what that process wrote is kept, and applying or reverting again
merges it with that edit), with the sides' states (changed, deleted, added) as values. The checks across files
are conflicts too: of a symbol transaction's member changed since (symbol:<id>), of a schematic placed since that
uses the symbol (symbol-consumer:<lib>/<cell>), and of unsaved layout edits in the proposal's log
(layout-journal). what is English; the review words these ids and states in the UI's language itself (a file
conflict by the form of its what, a file that cannot be read with its error; any other what as it is).
An apply or a revert writes <project>/changesets/<id>/merging.json before it writes the project's files, and removes
it once the record says applied (reverted). A server stopped in between leaves it: undine serve deals with it at
its start, before the netlist watcher and the API, and so does the next request that reads the changeset (or lists
the project's changesets, the first time after a start). The merge is finished when it was all written (the commit
found only if Undine made it for this merge, else the merge is recorded as uncommitted); otherwise the files are put
back, keeping what was done since (records appended to a log, a file the merge had not reached; a file changed since
the merge wrote it is left as it is), and the changeset is left as it was, with the note in interrupted. Until
then apply, revert and discard are a 400.
Git history¶
A project kept in git (see Version control with git) shows its history by cell.
Paths are from the project directory, also when the project is a subdirectory of its repository (prefix), except
those of /git/verify: it answers what undine merge-check --json prints, with paths from the repository's top, as
git and undine resolve take them (prepend prefix to compare them with the others). A file directly in a library's
directory is a view of a cell: <cell>.sch schematic, .sym symbol, .oas layout, .netlist.yaml netlist,
.intent.yaml intent, .sv / .v rtl; every other file (project.json, undine.lock, history/<lib>.jsonl, ...)
is "other", of which the status and a diff list the first 500 by path. Undine's own output (runs/, tapeout/,
llm/, .undine/, *.pre-split) is never listed, whether or not the repository ignores it. Statuses are added,
deleted, modified, untracked (not ignored) and conflicted; a renamed file is deleted and added. A changeset's
working copy ({project}~{changeset}) is a worktree of its branch, with no history of its own here: its status names
the changeset, and its diff is the changeset's; the log, the diff, verify and setup are a 400 for it.
| Call | |
|---|---|
GET /api/p/{project}/git |
the status: the working tree and the index against HEAD by cell, the branch, HEAD's commit, a merge in progress, what git-setup set up in this clone, the open layouts with edits not saved to the cell files (unsaved; a commit of their log is refused by the pre-commit hook; a library with no cell: the edits cancel out, and the hook refuses them all the same), and the open layouts whose cell files changed on disk under such edits (stale: a git checkout, merge or pull; saving them is refused until the edits are dropped, see reload below). Outside a repository {"repo": false, ...} (setup and prefix null, the lists empty but stale), never an error; for a changeset's working copy "preview": true with "changeset", "branch" and "base", and its own unsaved, stale and reads |
POST /api/p/{project}/git/setup |
undine git-setup: git init when the project is in no repository, the attributes, the diff and merge drivers, the pre-commit hook; after its git init, the project's first commit too (its files as they are, Undine's own output and the changeset records left out, author user: an applied changeset is committed only onto a branch with a commit). Returns the status with "hook_note": why the pre-commit hook was not installed, with the line to add to the hook that is there (the repository has a pre-commit hook of its own, or core.hooksPath is set: git-setup never writes into those), null when it is installed; "init": it ran git init; "gitignore_added": the lines of Undine's own output it added to the project's .gitignore (the status' setup.gitignore lists those it lacks; nothing else adds them); "commit": the first commit (null: no git init, or refused); "commit_refused": why it was refused, as first-commit would answer ({"code": "unsaved", "detail", "logs"} or {"code": "unsupported_library", "detail", "library", "path", "kind", "target"}), null; "index_note": git's index not reset to the commit, null. 400 for a changeset's working copy |
POST /api/p/{project}/git/first-commit |
the project's first commit, in a repository that has none (made by hand, or set up by an older Undine): its files as they are, from what the index tracks of the project, Undine's own output and the changeset records left out (and untracked again when staged), author user; in a repository whose project is a subdirectory, only the project's directory. Returns the status with "commit" and "index_note" (another git held the index: the commit is made, run git reset; null). 409 has_commits when the branch has a commit already (one made meanwhile too); 409 unsaved with "logs" ([{"path", "lib", "cells"}]) while a log holds layout edits not saved to the cell files, which the pre-commit hook refuses in a commit too; 400 when the project is in no repository; 400 not_set_up (below) in one not set up for Undine; 400 unsupported_library (below) for a library a changeset's worktree cannot hold. The History panel's Make the first commit: no agent tool makes it |
GET /api/p/{project}/git/log?limit=50&skip=0[&lib=L&cell=C] |
the commits of HEAD that changed the project (with lib and cell: that cell's files), newest first, each with the cells it changed against its first parent. limit 1 to 500; more: there is a next page |
GET /api/p/{project}/git/diff?rev=REV[&lib=L&cell=C] |
the semantic diff of commit REV against its first parent (a root commit: against nothing), or with rev=worktree of the working tree against HEAD; by cell and view |
GET /api/p/{project}/git/verify[?rev=REV] |
undine merge-check --commit REV --json of a merge commit: the cells to verify with DRC / LVS and why, warnings, notes, files merged without a report here. 400 for a commit that is no merge. Without rev, undine merge-check --json of the merge, cherry-pick or rebase in progress: also the conflicts still open, each with its base, ours and theirs value (400 when none is in progress). Paths from the repository's top |
POST /api/p/{project}/l/{lib}/reload |
drops the library's unsaved layout edits and reads its cell files again, what the panel's Discard the edits and reload does for a stale library: {"version", "dirty", "result": {"dropped": there were unsaved edits}, "undo"}. The operation log keeps the dropped edits as history, ended by a layout save record with "args": {"reload": true}, so they are never replayed and undo stops there. Until then POST /api/p/{project}/l/{lib}/save of a stale library is a 400 |
Not a repository, an unknown revision, a merge check of a commit with one parent or of no merge in progress is a 400;
an unknown project 404. While project.json holds a merge's conflict markers, the status, the log and the diff still
answer, with the libraries of HEAD's project.json.
Commit {"sha", "short", "parents": [sha], "subject", "body", "author", "email", "date" (ISO 8601),
"refs": [branch and tag names]}
CellChange {"lib", "cell", "views": [{"view": schematic | symbol | layout | netlist | intent | rtl,
"path", "status"}]}
status {"repo", "preview", "setup": {"merge", "diff", "hook", "gitignore"} | null, "prefix": "" | "designs/prj/" | null,
"branch": name | null (detached HEAD), "head": Commit | null (no commit yet),
"operation": null | "merge" | "cherry-pick" | "rebase", "conflicted": [path],
"cells": [CellChange], "other": [{"path", "status"}], "unsaved": [{"lib", "cells": [cell]}],
"stale": [{"lib", "cells": [cell]}], "reads": {lib: n}}
(reads: how often each open layout read its cell files again because they changed on disk, without
unsaved edits; an editor showing that library draws anew when it goes up)
(setup and prefix are null outside a repository and for a changeset's working copy; setup.gitignore:
the lines of Undine's own output the project's .gitignore lacks, which only git-setup adds)
setup status + {"hook_note": text | null, "gitignore_added": [line]}
log {"commits": [Commit + {"cells": [CellChange], "other": number of other files}], "more"}
diff {"base": sha | null, "rev": sha | null (the working tree),
"cells": [CellChange, each view also with "diff"], "other": [{"path", "status"}]}
verify {"ours": sha, "theirs": sha | null (no commit is known for it: git merge --squash, cherry-pick -n),
"commit": sha | null (in progress), "parents": [sha] | null (more than two: an octopus merge),
"operation": null (a commit) | "merge" | "cherry-pick" | "rebase",
"unmerged": [{"path", "kind", "conflicts": [Conflict] | null (git's own conflict markers), "error"?}],
"warnings": [{"path", "warning"}], "merged": [path], "no_report": [path],
"verify": [{"lib", "cell", "why", "reason"}], "notes": [text],
"note_codes": [{"code": no_theirs | octopus | earlier, "operation"?: rebase | cherry-pick}]}
Conflict {"id", "what", "base", "ours", "theirs", "taken": ours | theirs (the file holds it), "resolved"}
reason {"kind": "merged"} (its own files were merged)
| {"kind": "side", "side", "below": [{"lib", "cell", "side": side | null (merged)}]} (its files are
that side's, the cells below it are not)
| {"kind": "resolves", "side"} (what it instantiates resolves to other cells)
side: "ours" | "theirs" | "parent N" (of an octopus merge)
A view's diff is what undine diff --json prints for the file: {"kind", "changes": [{"do": add | del | mod, "id",
"what", "before", "after"}]}, for a layout also "geometry": [{"cell", "layer", "xor_um2", "geometry_unchanged"}]
(the XOR area of each changed layer) and "note" (what that XOR covers: each cell's own shapes, instantiated cells
not flattened into it), for RTL {"kind": "text", "do"}, and {"kind", "error"} when a version cannot be read. id
names the object as the merge does (inst:M2:prop:W, wire:<end points>, shape:<cell>:<layer>, item:<id>, ...);
what is the English undine diff prints; the panel words the ids it knows in the UI's language itself. Likewise
why and notes of verify are merge-check's English, and reason and note_codes carry the same as data.