Shared code, shared checks

client-org-mock impersonates the IT infrastructure of a customer organisation: an OpenID provider, a SAML identity provider, a directory-provisioning client, a security-event sink and a webhook receiver. All five mount under path prefixes on one port, so one instance is one origin, and a fleet runs one instance per tenant with its own recording database. It is the passive half of the pair: the systems an application calls out to.

The problem it solves

Every enterprise integration is a claim about what happens on the other side of a boundary you do not control. Signature validation, per-tenant routing, provisioning, security-event delivery and webhook signing all fail in ways that look identical from inside the application: a request was sent, no error was raised, and nobody knows whether the right thing arrived at the right place.

Isolation defects are worse still, because the symptom is invisible from a single tenant. One customer’s audit records arriving at another customer’s security sink produces no error anywhere; the sending tenant sees a success and the receiving tenant sees data it should never have had. That class can only be caught by watching two independent receivers at once and asserting that one of them stayed silent, which is precisely what this double makes possible.

What it does

Each face wraps a standard library rather than reimplementing a protocol, mirroring the framework’s own choice so the handshake is symmetric. The package owns the wiring and the recording and nothing else: no fake business objects, only a small seed so sign-on and provisioning can round-trip.

Every observation is written to a durable per-instance database, carrying the face, a sub-kind, a one-line summary and an optional idempotency key mirroring the application’s own de-duplication. A scenario reads them back over an inspection surface, which is what turns “did the assertion land” into a row count rather than a guess. Because the database is per instance, the isolation question is answered without any shared query surface: the tenant that should have received the traffic has rows and every other tenant has none.

The package sits deliberately outside the framework’s workspace, with its own lockfile, so its dependencies never touch the framework’s resolution. The one exception is the security-event receiver, whose parser is written from the published grammars rather than from the framework’s emitter — and that independence is the entire point: a receiver derived from the producer would agree with the producer by construction, and a format defect would read as agreement.

The directory face inverts the direction. Wildo is the provisioning SERVER there, so the double is the client that pushes users in.

@wildo-ai/testing-core holds the parts every test lane needs and none of the parts any one lane is about: the scenario engine, the surface and adapter contracts, the isolation assertion, backend-flap resilience, the log observer and the managed child process. It declares no runtime dependency at all, and it is exported as TypeScript source rather than as a build, which is what lets a package with its own lockfile consume it without inheriting anything.

The problem it solves

Test doubles have to be independent to be worth anything. A double that impersonates a customer’s identity provider is only evidence if it speaks the protocol on its own terms rather than borrowing the types of the thing it is testing, and a double that shares a lockfile with the engine cannot demonstrate that it resolved a signature the way an outsider would.

Independence usually costs duplication. Each isolated package ends up with its own copy of the scenario loop, its own retry, its own idea of what an assertion is, and the copies drift until the same failure reads differently in two lanes. This package is the way out: the parts that are genuinely common carry no dependencies, so importing them costs an isolated package none of its isolation.

What it does

Cross-scope isolation is not a separate mechanism. It is a flag on an assertion, asserting that the active scope recorded the expected traffic AND every other scope stayed silent. That detects misrouting from record counts alone, with no payload parsing — which is why it works identically over an identity provider, a webhook receiver and a security-event sink.

The whole engine is generic, so a surface brings its own kinds rather than the engine knowing about any of them. That is what makes one loop drive an HTTP API, a browser, a message queue, a backend log and an external double.

One seam injects the application. An application supplies provisioning, capability configuration, a trigger, a store read and its addresses; the subprocess form turns that into a cross-process contract — so the adapter runs in the application’s own workspace with the application’s own module resolution, while the scenario stays application-agnostic.

The resilience module exists because a development stack restarts under recompile churn. Rather than widening timeouts, every application-facing call gates on the health endpoint and retries within a readiness ceiling — and a transport failure is described AS one, so a caller can tell an absent backend from a wrong answer.

@wildo-ai/engine-behavior-e2e is the suite that answers “does the engine actually work”. Fifty named scenarios are registered in one file; each is a script that provisions its own organisations against a running application, drives one engine capability over real HTTP or a real browser, reads the result back from the other side of a process boundary, and tears down. A run is green only when every assertion passed and the backend logged nothing fatal while they ran.

The problem it solves

Most of what this framework claims is about behaviour under conditions a unit test cannot create: two tenants at once, a signed assertion arriving from outside, a job that has to survive a broker, a token minted for one surface being refused on another. A test that mocks the boundary proves that the mock behaves; it says nothing about the running system.

The second problem is subtler and cost more. A suite can pass every assertion it makes while the application under it is failing at something the suite never looked at, so the report is green and the product is broken. The harness treats that as the default hazard rather than an edge case: the run window is watched independently of the assertions, and a run in which the backend screamed is not a passing run no matter what the scenarios concluded.

What it does

A scenario is a row carrying a stable identifier, the script that replays it, the lane it asserts against, and the runtime surfaces it needs ready. Forty-seven sit on the application-runtime lane and three on the control-plane lane. A third lane is declared and deliberately unused, so the tag is honest about being one of several on one substrate rather than pretending the substrate is single-purpose.

Everything application-specific sits behind ONE seam — an adapter shipped inside the application, injected as a subprocess whose working directory and command resolve from environment bindings rather than from a hardcoded path. A scenario therefore names capabilities, never the application, and a second application slots in by shipping its own adapter.

The gated command attaches to the stack a developer is already running, gates on health, pins the current end of the development log, runs the selected scenarios, then scans only what was appended during the window. The gate matches the fatal token on the RAW line, in both log shapes, because a parser that reads only structured records would certify a human-readable run as clean. It also matches criticals a caller caught by contract and logged at warning level — which is where a fire-and-forget dispatcher hides its own breakage.

Because every scenario opens with a destructive pre-clean keyed on a deterministic reference, two runs against one stack would delete each other’s fixtures mid-drive. A second run is refused by name, and the claim is held by the process TREE so a runner’s own subprocesses inherit it. The marker is honoured only while the owning process is alive and under two hours old, so a hard-killed run cannot wedge the lane.

provider-simulators stands in for the external target systems an application reads from. Four faces are implemented: a business-suite remote-procedure endpoint, an OData version-four endpoint, a version-two endpoint in the flavour a large enterprise suite actually publishes, and a route-driven generic HTTP double for provider operations. Each is a standalone server started from one orchestrator, with no framework imports.

The problem it solves

Reading data out of somebody else’s system is mostly a question of dialect. The envelope differs, the paging property differs, the query language differs, and a wrong answer looks like an empty result rather than an error. Testing that against the real system means holding an account, a network path and a data set, none of which belongs in a test lane; testing it against a stub written from the same assumptions as the reader proves only that the assumptions are self-consistent.

The version-two case is the clearest illustration. The engine’s OData reader expects a value array and a next link, which is version four. A widely used enterprise business-partner service publishes version two, whose envelope wraps everything in a different property, names its results differently and carries a different next link and count. A version-four reader pointed at it finds no array and fails on the first page. Only a double that is faithful to the published version-two format shows that, which is why the two are separate doubles rather than one with a flag.

What it does

Each face is faithful to a PUBLISHED protocol rather than to the framework, and none of them imports anything from it. That is the load-bearing property: a double derived from the reader would agree with the reader by construction, so a framework defect could never surface.

The business-suite face implements the envelope, the authenticate call including its rejection answer, and the read family with the domain query language, its prefix-notation combinators and its operator set. The newer query face parses the filter grammar subset a query compiler realistically emits, by recursive descent, and answers the metadata document as well as the count. The older face implements the other envelope, the other paging and the other count.

The generic double is deliberately a different shape. A provider operation has no dialect — only a method, a path template, parameters and a body encoding — so this face is route-driven: a test declares routes the way a vendor’s API reads on paper, and the double records what actually ARRIVED, including query parameters, headers and the raw body with its content type. That record is the assertion surface, and it is what turns “the parameter went to the query rather than the body” into a checkable fact rather than an inference from a successful status.

Two faces carry a knob that forces one throttled answer after a chosen number of calls, so transport-retry machinery has a live counterpart rather than a mocked one.

@wildo-ai/platform-e2e-runner provides the control-plane half of the end-to-end substrate: the back-office API surface, the three principals a request can arrive as, the shared verdict for a service-token read, and the assertions built on them. Three scenarios in the shared registry use it, and the package also carries its own browser and API lanes plus a deliberately opt-in destructive recovery journey.

The problem it solves

The platform services are what manage applications: they hold each application’s configuration, issue its credentials and register its scheduled work. An application’s own tests cannot cover them, because from an application’s point of view the control plane is simply somewhere its configuration comes from. Nothing else would look at them at all.

They also fail in a shape that ordinary assertions miss. A control plane that manages secrets can answer a configuration read successfully while logging a fatal error resolving a managed-secret branch, so a successful status is not evidence that the read was correct. And a key generation can drift, where the stored verification key and the materialised signing key stop matching, which presents as an authentication refusal that reads like a configuration mistake and is really a broken initialisation.

What it does

Its surface drives the back-office API and returns the status and body for ANY status — so a refusal is data the caller classifies rather than a thrown error.

Three principals are supported, matching the three doors the control plane actually opens: an application’s own platform credential, which is exactly what a real backend sends; an administrative credential; and a service token. A call can override the default, so one scenario can prove that a door which should be shut is shut.

The service-token verdict lives in ONE place. Every control plane classifies the same way — served, key generations incoherent, or an unexpected fault — and only the human-readable message differs per door, so each door supplies its wording and the classification is written once.

The gated entry point reuses the registry, the replay command and the fatal-gate wrapper from the application lane, and changes only the gate’s SCOPE. The development command tees the platform tree and the application tree into one log with per-line labels, so the platform gate reads only the platform lines: an application’s fatal error never reds a platform run and a platform fatal never reds an application run.

One of its contract lanes checks the customer-infrastructure double against wire drift — which is how an independent double stays independent without silently diverging.

Every browser scenario signs in through one implementation, and that implementation gates each wait that cannot succeed while the backend is away. A repository check enforces the same rule on waits a scenario writes for itself: a browser wait is either inside the gate or carries a comment saying why it does not need to be, and anything else fails the check.

The problem it solves

A browser wait absorbs a slow backend; it does not absorb an absent one. A development stack restarts under compile churn, and when it does, a wait for a password field expires with a message naming a locator. That message is indistinguishable from a genuinely broken form, and it was reported as a product failure. The investigation cost more than the outage.

Widening the timeout does not fix it, and that was measured rather than assumed. Outages were timed at sixty-eight seconds, about a hundred, and two hundred and seventeen. The distribution is long-tailed because recompiles stack, so any fixed number is eventually walked through. Gating costs nothing when the stack is up and absorbs the whole outage when it is not.

The deeper problem is that this rule was already written down, already understood, and applied to one of four scenario files. The other three each carried their own copy of the login, one of them waiting on the identical locator on the identical form, because the incident named one scenario and nobody asked which other files contained the same wait.

What it does

It owns the wait for the form to paint, the two-phase login where an address is submitted and the form then swaps to a password method, the reload that returns a fresh unauthenticated form, and the second-factor variant. Where the application lands afterwards is left to the scenario, because that is the scenario’s subject.

The gate waits for health within the readiness ceiling, runs the step, and then does the one thing that makes the whole mechanism worth having: if the step failed AND the backend is not answering, it raises an error naming the infrastructure while preserving the original as its cause. If the backend IS answering, the original error is rethrown completely untouched — because then it is a real product failure and must read as one.

It deliberately does not retry. An adapter subcommand is replayable and a browser step is not: re-running a click that already created a row would corrupt the scenario’s own state and could manufacture a pass. The gate is side-effect-free in both directions.

What the shared drive cannot cover is covered by a check. It scans every file that imports the browser surface, finds each wait, and requires it to be either inside the gate or carrying an explicit declaration with a reason. Files are discovered by IMPORT rather than by filename, so a browser scenario named anything at all is covered the day it is written. The check does not decide which waits need the gate; it refuses to let the answer stay implicit — the guarantee that was actually available.

The declaration is a decision rather than a suppression, and the distinction earns its keep: a pure client render after an already-gated navigation genuinely should not be gated, and reflexively gating everything would blur which waits depend on the backend at all.

client-integration-app is the active half of the pair: where the customer-infrastructure double receives what an application sends, this one authenticates and drives. It holds an authentication face, a role-checked API client, an agent-protocol client, a model-context-protocol agent driven by a real language model, and a webhook receiver of its own. It reaches the application over HTTP only, holds no literal secrets, and takes its credentials from the scenario at bind time.

The problem it solves

An application’s outward-facing surface is the one part of it that no in-process test can honestly exercise. Authentication, audience binding, role checks, tenant scoping and tool exposure all behave differently to a caller that shares the process and its types than to one that does not, and the differences are exactly where the interesting failures are: a token minted for one surface accepted on another, a tool that advertises one contract and enforces a second, a webhook signed with a key nobody validated.

There is a second reason to build the caller rather than script the calls. When the surface is an agent protocol, the realistic consumer is a language model choosing tools from a catalogue it just discovered, and what it chooses is not what a hand-written script would send. A double that discovers and drives the way a real integrator does is the only way to find out whether the catalogue is usable.

What it does

One frozen contract crosses the boundary. The double runs as a spawned subprocess exposing a command endpoint; the scenario posts a command and reads back an observation. The shapes were frozen after the first real path was built rather than sketched in advance, and later faces extended them additively.

Authentication covers all three methods: machine credentials with discovery, a delegated authorisation-code exchange with a proof key where the audience is required, and an API key echoed as a raw secret. Tokens are cached per principal and the header is resolved per method, so a scenario asks for a PRINCIPAL rather than for a mechanism.

The tool-protocol face is a real agent. It discovers the catalogue and drives real work through it, and reports its tool trace so a scenario can assert what the model actually called. Because a real model can also run out of credit, that outcome is reported as INCONCLUSIVE rather than as a failure: a lane whose skips are indistinguishable from failures teaches everyone to ignore it.

The webhook receiver is a second server inside the same process. It verifies the signature against the application’s own published key, fetched at run time from the administrative read rather than pinned in the double, and records what it received on the same inspection shape the other double uses — so the harness orchestrates both the same way.

Some of the rules a framework depends on cannot be written as types. An end-to-end assertion must reach the database through the adapter-neutral seam or say out loud that one dialect is its subject. A package subpath must be the only door onto its surface. A closed vocabulary must have one named home. Each of those has a dedicated script under code-conduct, thirty-six of them, and almost all of them ship a self-test that plants each failure shape and asserts it is caught.

The problem it solves

The rules that matter most in a framework are usually the ones a compiler cannot see. They are properties of how code is arranged rather than of what it evaluates to: which package a symbol is reachable through, whether a string is a vocabulary or a wire value, whether a security-relevant action emits a record. A type system has no opinion on any of them, so the fallback is review, and review is what authoring speed outruns. One of these checkers was written after a measurement that makes the point exactly: around a hundred call sites had been converted to a store-neutral seam, and by the time the conversion was reviewed, ten new sites of the old kind had arrived in code written during it. A sweep fixes the population that exists today; the population refills.

There is a second, sharper reason these are scripts rather than conventions. A convention is enforced by whoever remembers it, and nobody remembers thirty-six of them.

What it does

What most of them deliberately do NOT do is decide what is correct. A check cannot tell a deliberate exception from an unconverted one, so the guarantee on offer is weaker and honest: it refuses to let the answer stay unstated. A site that genuinely needs the exception carries a marker naming its reason, in a comment beside the code — visible in review, surviving a file move, and unable to drift from what it explains.

They are not text matching where text matching would be wrong in both directions. One check runs a real tokeniser, because its own source discusses the forbidden call in prose that must not be counted, and because the target appears inside string templates that must not be either. That was learned the expensive way: the first live run reported twenty-six sites where a plain search found sixty-one, because a pattern containing a quotation mark opened a string that swallowed the rest of one file — and every short fixture had passed.

Why a check proves it is not broken

This answers a failure with no symptom. A check reports findings; when it reports none, that reads as a clean repository — and there is nothing in the output to distinguish that from a check whose discovery has silently stopped matching anything. A widened directory layout, a renamed extension, a tokeniser that lost half the file: both print the same thing. So a broken check is not merely useless, it is worse than absent, because its silence is taken as evidence.

The answer is that a check carries fixtures of both kinds and asserts both directions: each planted bad input must be reported, and each good input must not. The second half is what makes it a test rather than a demonstration — detection without a clean control proves only that something fires, not that it discriminates. Several go further and check themselves against the live tree, so a tokeniser regression that stops seeing a file becomes a red run naming that file.

Shrink-only baselines, and what a check should refuse

A baseline is a different design decision from a gate, and the two answer different questions about a rule that is right and a codebase that does not yet satisfy it.

A gate refuses the state outright. That is correct for a rule with no pre-existing population.

A baseline is for the other case: the rule is correct, the population predates it, and converting everything before the rule can be enforced means the rule is not enforced for as long as the conversion takes — which is when the population grows. So a baseline records what exists as a per-file ceiling and enforces one thing only: that the ceiling never rises. Converting a site lowers the count, the row is deleted at zero, and the self-test refuses a row naming a file with nothing left to convert, so the ledger cannot rot into a list of resolved entries.

The rule the baselines carry in their own text is what keeps this from becoming an allowlist: never raise a count to silence a new finding. A new occurrence is the defect the check exists to catch, and the answer is to fix it or to declare it at the site with a marker naming the reason. A marker is visible in review; a raised number is not. The steady state of every one of these files is empty.

Two commands answer the question that costs the most time when a development stack misbehaves: is what I am running actually current. wildo fwk wt-status prints one screen covering build freshness, linked-snapshot coherence, registry alignment, process and port state, and index freshness. wildo fwk wt-tail streams every process log of the same application together with coloured prefixes. Both are read-only.

The problem it solves

In a repository where an application consumes the framework through linked copies of compiled output, a large share of apparent bugs are not bugs. A symptom that reproduces in one process and not another is usually a stale compiled artifact, a linked snapshot that has fallen behind, or a process that has been running since before the fix. Every one of those presents as a logic defect: a missing export reads as a bad import, a stored document rejected by a schema reads as a validation bug, a service that will not start reads as a configuration problem. The investigation goes into the code, and the code is fine.

What makes this expensive is that the cheap check is never the one anyone runs first, because at the moment of the symptom there is no reason to suspect the artifact. These commands exist to make that check cost one line instead of an afternoon, and to make it a single screen rather than six separate questions.

What it does

The snapshot compares each package’s compiled output against its source, then validates the linked snapshot the application resolves its framework dependencies through — reporting whether files are missing, drifted, or present in the snapshot after being DELETED from the framework. It compares the three module registries an application declares, which have to agree and are edited separately. It reports which processes are up, what their last build signal says, which ports are occupied, and whether the code-intelligence index is fresh.

Each finding names the exact command that repairs it, and the repairs differ: a drifted file is reconciled, a file left behind by a deletion has to be pruned instead, and an unfinalized compiled tree is a build problem wearing a snapshot symptom.

The currency sweep behind the same question is broader and application-agnostic. It asks one thing across every derived surface: whether the file watchers can still see edits at all, compiled output against source, unfinalized emit, accepted generations against the paths they name, linked snapshots compared by file set, the package store against the links that reach it, the configuration cache against its inputs, the provider set each runtime will bind against the configuration that declares it, each supervised process’s START time against the build it loads, and published documentation. It discovers application roots rather than being told them, and it prints both timestamps and the delta so a reader can see which side of the threshold a finding sits on.

The log tail is the companion to that: the development stack does not centralise its logs, so it finds whatever log files exist, prefixes each line with a coloured label, and can list which logs are present and which are missing rather than silently tailing nothing.

A code-intelligence index of the whole repository is built into a binary artifact and converted into a queryable database, so a question like “what actually uses this type” is a sub-second query rather than a text search. The distinction that matters is package boundaries: a text search finds occurrences of a name, and an index finds references to a symbol, which is what a change across a package boundary needs.

The problem it solves

At a million lines and thirty-odd interlinked packages, the cost of a change is dominated by enumeration. Before renaming a type, reshaping a schema or moving a symbol between public entrypoints, you have to know every consumer, and getting that list wrong produces a regression that compiles.

Text search is the tool everyone reaches for and it fails in both directions here. It matches names that happen to coincide and misses references that resolve through a re-export, an alias or a published declaration. It is also quietly blind: the repository’s default search tool skips hidden directories, and one of the largest consumer trees in the repository lives under a dotted directory. An enumeration run that way returned fifteen files where the real number was thirty-five, and the list looked complete, which is the dangerous property.

What it does

An index is produced and converted into a queryable database, so a lookup is a query rather than a scan. It is safe to run alongside the compile watchers.

Concurrent runs are serialised by an atomic directory-creation lock — chosen because it needs no external tool and works on every platform the repository is developed on. That choice was made after the previous approach, guarded by a check for a tool that does not exist on one of those platforms, silently skipped the guard entirely: over two days the watcher logged ninety-four index starts, thirty-two completions and no skips at all, and the overlapping runs corrupted each other’s output while the reported state kept moving.

The lock distinguishes a live owner from a dead one and from a recycled process, and only breaks a lock once it is old enough that it cannot belong to a run still starting. Its self-test exercises each of those independently, neutralising the other check in each case, so a passing run can only be explained by the check it names.

A daemon watches sources and regenerates on save with a delay, so the index settles after activity rather than rebuilding on every keystroke. It can run in the foreground, in the background with a log, or start at login, and it reports its own state.

A routing document sits beside the tooling and decides which tool answers which question, because the index is not the right answer to all of them: a literal string in a comment is a text search, a structural pattern is a structural matcher, and an architectural dependency rule belongs in a dedicated check. One command wraps a symbol query with a classification of what the change crosses, so the answer arrives with the rules a developer should read before editing.

A Wildo application declares its data as decorated schemas, and on a relational database those declarations have to become physical tables and columns. The wildo db commands make that a reviewable sequence: compare the current model against a committed baseline, generate a migration draft from the difference, apply pending migrations in order, and correct the ledger when a human has intervened.

The problem it solves

When the shape of a database is derived from application code, the temptation is to let the application reconcile the database at start-up. That works until the first change that cannot be inferred safely. Dropping a column and renaming one look identical from the outside; a column that gains a constraint needs the existing rows to satisfy it first; and a fleet of instances starting together will each try to reconcile the same database at the same time.

The other half of the problem is review. A schema change is one of the few changes whose worst case is unrecoverable, and it is exactly the kind of change that is hard to see in a code diff, because what changed was a decorator on a field. Turning it into a generated file that is committed, read and approved makes the destructive part visible before it runs rather than after.

What it does

The baseline is a committed file describing the plan the application’s model implies. Asking for the difference recomputes that plan from the live model and reports what separates the two, each change classified as safe, destructive, or requiring a data migration. A check mode exits non-zero on any drift — the ratchet: it does not decide what is correct, it refuses to let the answer stay implicit, because an unenforced snapshot rots.

The model is computed in a process spawned inside the application’s own workspace rather than imported into the command line. That is deliberate: the model is the application’s own modules merged with the framework core, resolved through the application’s own dependencies — and importing it here would bind the application to the command line’s framework version and to its schema library’s decorator state. The comparison then happens in the command line, because comparing two plans is a pure step.

The migration runner carries the guarantees. Its state lives in a table inside the database being migrated, deliberately not modelled as a resource, because it has to be readable before the resource system boots and must be unreachable from the API. Exclusion is a session-scoped lock in that same database, so the lock lives in the same failure domain as the writes it guards and releases itself when its holder dies, rather than relying on an external expiry that can lapse mid-migration. Instances that do not win the lock wait and then proceed, and every instance runs the schema verification afterwards regardless — so a runner defect cannot silently become a served schema.

Each migration runs in its own transaction. Because schema statements are transactional here, a failed migration rolls back whole: the database lands exactly at the previous migration, the ledger records the failure with its error, and recovery is to fix the draft and run again rather than to reconstruct a half-applied state.

wildo align-deps reads the framework packages an application actually has installed, derives from them the third-party versions the application should pin and the peer dependencies each of its packages must declare, and reports or writes the difference. It is what an application runs after moving to a new framework release, and it needs no framework checkout to do it.

The problem it solves

When an application is scaffolded, the versions it pins and the peers it declares are computed from the framework at that moment. Afterwards nothing recomputes them. The application moves to a newer framework release, keeps the old third-party versions, and quietly runs a set of libraries the new engine was never tested against.

The peer half is worse, because it cannot be repaired by reinstalling. A package manager override rewrites a version some manifest wrote down; it never creates one. So a peer dependency that no manifest declares is resolved automatically, that resolution is recorded, and it is then never re-derived: the same install command, repeatedly, changes nothing. The visible symptom arrives later, when a version range narrows and a resolution frozen months earlier starts reading as a live conflict, at which point the code looks like the culprit and is not.

What it does

Everything is derived from the framework packages resolved in the application’s own tree. Nothing new has to be published for that to work: the publish lane already substitutes the framework’s single root pin into every published manifest — exact for ordinary dependencies, widened for peers — so the pin set and the peer closure are recoverable from the installed packages themselves. That is why it reads the installed tree rather than a published list: the data cannot drift from the packages it describes, because it IS them.

Findings split on two axes rather than being degrees of one thing: whether a name belongs in the application’s own pins or in a package’s dependency list, and whether it is absent or present and wrong. The one worth naming is a peer declared at a concrete version rather than as a wildcard — because the framework’s pin then cannot reach it, and a later version bump silently will not land.

Exclusions are the application’s own, in a file seeded when the application is scaffolded. That is the right owner: the application knows which names its own toolchain controls, and it is the party that breaks when the judgement is wrong.

A scenario that creates a new workspace package inside an application reads a delivered copy of the peer closure, so a site, a portal or a background worker is born with the peers it needs declared rather than with none.

An application declares its design system as a configuration file, and wildo design-tokens generate turns it into the custom-property block every frontend surface reads. A separate command pushes the application’s accepted brand assets to each site that shows them. Both write into files a developer also edits, so both write into a marked region rather than owning the whole file.

The problem it solves

Colours, spacing, radii and typography end up duplicated across a product’s surfaces: the application, the marketing site, the documentation portal, and the emails. Each copy is edited separately, so within a few months they disagree, and the disagreement is the kind nobody files a bug about because each surface looks fine on its own.

Generating them from one declaration would be the obvious answer if not for one thing: the stylesheet is not only generated content. A developer has real hand-written CSS in the same file, and a generator that owns the file destroys it. The same is true of brand assets, which land in several served directories and in the head of several sites, and which may have been supplied by a person rather than produced by a generator.

What it does

The design system is authored at a fixed path. Generating loads it, produces the custom-property declarations, and replaces the content between a start and an end marker in the existing stylesheet, leaving everything outside the markers untouched. A separate step inserts that marked region into a stylesheet that does not yet have one, and another checks the authored configuration. The generated region carries its own notice saying it is generated and naming the command that regenerates it.

Brand propagation reads the COMMITTED source of truth for the application’s resolved assets, never a staging directory, and runs every destination it discovers. The destinations are found by file rather than enumerated in the command, so a new surface plugs in by adding one file — demonstrated rather than promised: the destination that stamps the assets into the backend’s runtime configuration was described as a future addition and was picked up without any edit to the command.

Each destination copies the asset files into one surface’s served directory and reconciles that surface’s references to them. Because it only ever reads the committed assets, it runs identically whether they were generated or supplied by hand, and it is a clean no-op when there are none.

An application’s HTTP API is not written by hand, so its reference is not either. Each operation the application exposes is projected into a validated description, and a generator turns those into OpenAPI documents: one for the public API, one for the administration API, each serialised both ways. The output is meant to read like a reference a developer wrote, not like a dump.

The problem it solves

Generated API documentation has a reputation, and it is deserved. The usual output is technically complete and unusable: operations named after internal handlers, every request body inlined so the same shape appears forty times under forty names, authentication described nowhere, error responses absent, and defaults captured from whatever the machine that generated it happened to hold. A developer reading it cannot tell which of six similar endpoints they want, and a generated client built from it has method names nobody would type.

The alternative, writing the reference by hand, fails differently. It is correct on the day it is written and then diverges from the API silently, because nothing compares the two.

What it does

The projection comes first: each exposed operation becomes a description carrying its resource, its variant, its address, its authentication mode and its schemas, and that projection is validated before the generator sees it, so every step downstream can assume a well-formed input. The generator itself is a pure step, with no reading or writing of its own, which is what makes it testable in isolation.

Operation names are BUILT rather than borrowed — a verb, the resource noun, then qualifiers, in consistent casing, with a semantic qualifier added for an operation reachable at more than one address so that two paths onto the same operation do not collide. That name becomes the method name of a generated client, which is why it is worth composing carefully.

Structured request and response bodies are hoisted into named components and referenced, and identical shapes are detected by a key-sorted comparison, so the same body authored on different operations collapses onto one component rather than repeating. Bare scalars stay inline, because a reference to a one-line schema is pure overhead.

Security schemes are emitted unconditionally, because every Wildo API authenticates the same three ways, and each operation references the ones that apply rather than describing them again. The error responses the framework owns are written once and referenced from every operation that can return them.

A section with no operations after filtering is omitted rather than emitted empty.

The framework publishes itself with commands rather than with a document someone follows. One version is set once and synchronised into the framework marker and every managed package manifest; the package publish derives its own ordering from the dependency graph; the image publish builds and pushes the declared images under an immutable tag. What gets published is declared in the framework configuration, so the release set is reviewable rather than remembered.

The problem it solves

A framework that ships as several dozen interdependent packages plus a container image has a release that is mostly bookkeeping, and bookkeeping done by hand goes wrong in ways that are expensive downstream. Versions drift apart between manifests. Packages get published in an order where a consumer briefly resolves a version of its dependency that does not exist yet. A prerelease lands on the default distribution tag and reaches every consumer running a plain install, which cannot be withdrawn, only superseded. An alias tag is repointed at an image whose push then fails.

The other half is subtler and specific to a framework built as one workspace. Inside the repository every package declares its third-party dependencies as a wildcard and the real version is pinned once at the root, which is correct for a workspace and meaningless to a consumer, who has no such root. The published manifest has to say something concrete, and what it says has to be derived from that one pin rather than typed a second time.

What it does

The version has one source. Setting or bumping it establishes it; a sync writes it into the framework marker file and into every managed package manifest.

Publishing packages stages a publishable manifest for each declared package, and materialisation is where the workspace wildcard becomes a real range: the root pin is substituted in, exactly for ordinary dependencies and widened for peers — so a consumer keeps the tested version as a floor without inheriting an override it has no way to express.

Publication order comes from the dependency graph, and a cycle is refused rather than published in an arbitrary order. A prerelease version with no explicit distribution tag is refused outright, because the default tag is what a bare install resolves.

Publishing images builds each declared image and pushes it under an IMMUTABLE tag, defaulting to the framework version — and a channel that publishes per commit supplies its own tag instead, because on that channel the commit rather than the version is what makes the artifact unique. Mutable aliases are repointed afterwards, and only after every immutable push has succeeded, by pointing the alias at the published manifest rather than by rebuilding.

Both publish commands support a dry run that prints the exact commands they would execute, and the registry host and namespace are pinned in code, so a framework configuration naming a different pair is refused.

The framework compiles itself with two TypeScript compilers at once. A ledger names which packages use the newer native compiler; everything else uses the established one. Both are installed side by side under distinct package names, so promoting a package is adding a name to a list, and one environment variable puts the entire fleet back on the compiler that has always worked.

The problem it solves

Changing the compiler of a large codebase is normally an all-or-nothing event. You bump one dependency, every package retargets at once, and whatever breaks breaks together, in packages maintained by different people, with no way to tell a real defect from an artefact of the move. The usual mitigations are worse than the problem: a long-lived branch that diverges, or a per-package build script edit, which means the rollback is as many edits as the migration was and a partial revert is the state nobody notices.

The second problem is quieter. Once two compilers can be installed, the name of the binary stops identifying which one runs. Whichever package wins the shared executable name is an accident of install order, and a build that used the wrong compiler produces output that looks correct.

What it does

A lane is a named pair of a package and an expected identity, resolved by ASKING the package what it is: its own manifest is read, the name is asserted and — for the new lane — the exact version; then the executable that package itself declares is spawned with an argument array. Nothing resolves a bare binary name, and nothing goes through a shell, so a checkout path containing a space is inert. The established lane deliberately asserts no version, because its version is owned by the workspace pin and duplicating it here would create a second authority that drifts.

The compiler is resolved from the invoking package’s own workspace, and a workspace that has not installed the lane’s compiler is REFUSED rather than allowed to borrow one from a parent. That refusal is the boundary that keeps a nested application workspace from silently inheriting the framework’s compiler: resolution walks upwards, the borrowed binary exists and works, and nothing would ever report it.

Incremental build state is scoped per lane, so state written by one compiler can never be read by the other — rewritten by the runner rather than left to each caller to remember, because a shared state file fails as a confusing stale-type error far from its cause.

The lane only decides which compiler emits into the private staging area. The finalizer, the publication journal, the writer lock and the publication ordering are all downstream and unchanged — so a lane flip cannot corrupt a published artifact; the worst case is a package that fails to compile, which fails closed and leaves the previous generation standing.

Because the split is held together by four surfaces that cannot import one another, a dedicated check keeps them in agreement: the declared version against the asserted one, the separate declaration a nested workspace must carry, a ledger entry naming a package that does not exist, a ledger entry for a package with no lane to select, and the executable staying a registered binary of a workspace package.

Working inside the framework repository, you start one process and every package compiles, finalizes and republishes itself as you edit. The chain has five stages with distinct owners, and its load-bearing property is not speed: a package’s published output directory only ever holds a complete generation, so a consumer importing it mid-edit cannot read a file that is half written.

The problem it solves

A monorepo with dozens of interdependent packages has a build problem that is easy to underestimate. The obvious half is ordering: package B cannot compile until package A has emitted. The expensive half is that the emitted directory is a shared, mutable surface, read by other compilers, by running processes, and by an application whose dependencies are linked into it. Every write to that surface is visible to a reader the instant it happens.

Two failures follow, and both were paid for here. Two processes watching the same output directory interleave their writes and produce truncated files, so a running service crashes on a syntax error in a file nobody edited. And a compiler that kills its own post-compile step when the next compilation starts can interrupt an in-place write between truncating a file and refilling it, leaving a zero-byte module and every link to it empty. Both present as a defect somewhere else entirely: a missing export, a module that cannot be found, a service that will not start. The chain’s design is a response to those, not to build times.

What it does

The watcher fleet is derived, not listed. The workspace graph is read and the packages that declare a watch step are selected — so a new package is watched the day it is created. One status document is written for supervisors to read, and it is enforced that there is only ever one writer, because two writers produce oscillating timestamps and drive every supervisor into a restart loop.

Each watcher runs behind an exclusive lock on its own output directory, and the lock records both the compiler process and the orchestrator that started it — so a holder can be JUDGED rather than trusted. A live holder under a live orchestrator is respected and the newcomer stands down with a distinct exit code; a live holder whose orchestrator is gone is an orphan, and is terminated and replaced. Reclaiming is atomic, so two processes racing the same reclaimable lock cannot both win.

The finalizer runs on the compiler’s success signal. It resolves each package’s internal path aliases and rewrites module extensions in a single in-memory pass, so each emitted file is written exactly once rather than twice with an observable intermediate state. It installs a cooperative interrupt guard before anything else it imports, because installing any signal listener moves the signal onto the event loop and a synchronous write can no longer be torn apart part-way.

Before anything is published, one shared rule refuses a generation containing a zero-byte module — applied at every write path rather than at one of them.

Publication is journaled: the generation is recorded, written into the public directory in place so that linked files survive, and the signal raised that tells supervisors the package is ready. Compiler state files and the writer lock are excluded from what is published, distinguished from what is merely present on disk so that a stray file can still be reclaimed rather than becoming permanent.