Internals

How dev3d is put together, why it is shaped that way, what has actually been verified, and what is still open. Written for someone reading the source, auditing it, or deciding whether to trust it with a real project.

What this section is for

The rest of this documentation tells you what dev3d does and how to run it. This section answers the questions that a feature list cannot: why a decision was made the way it was, what a check actually proves, and which parts of the project are unfinished, traded away, or simply unverified.

Three readers tend to end up here. Someone reading the source, who wants the shape of the thing before opening forty files. Someone auditing it, who needs to know what the evidence is and where it stops. And someone deciding whether to put a real project through it, who needs the limits stated before they are discovered.

One rule governs every page: a claim is traceable to the source. Where this documentation previously contradicted the code, the code wins, and the page says so rather than quietly changing its mind. Three corrections are worth naming up front, because they are the ones most likely to be quoted from memory:

• The wire protocol is 31 server events and 33 client commands. An earlier revision of this page said 27 and 31, and the release notes before that said 24 and 14; counting the members of the two unions is a two-minute job, which is the argument for doing it rather than copying it. Two of those numbers need a caveat: the socket implements 26 of the 33 commands, and one of the 31 events is declared and never emitted. See Architecture decisions.
• A plugin's contributes object has 8 keys. The earlier phrase "11 plugin contribution surfaces" corresponded to no real list. Permissions are a separate set of 10, and the plugin host tracks 10 contribution fields of its own. See Verification.
• A debate is a sequence of speeches, and idle employees do walk — but not to the meeting room. Speech events are real and attributed. What the office does now, which it did not when this page was first written, is a client-side locomotion layer: an employee whose status is idle gets up and walks a route computed on a grid sampled from the floor geometry, and sits back down the instant work arrives. That is a rendering behaviour, not an office record, and it is unrelated to a debate. See Design thesis.

In this section

Page	The question it answers
Internals	Where to start, what the rest of the section assumes, and how to check a claim yourself.
Design thesis	What the project is arguing, how the argument is implemented in the router and the office, and why it needs a hierarchy rather than a swarm.
Architecture decisions	Why the shared contracts package is dependency-free, why the wire protocol is shared types, and why the licence is the AGPL on purpose.
Verification	What has been proven, suite by suite, and what each suite cannot prove.
Known gaps	What is unfinished, what is a deliberate trade, what the platform will not allow, and what nobody has verified yet.

How these pages are written

Every number carries the way it was determined, because a number without a method is a rumour. Some are counted from a single declaration, some are asserted by a test, some were measured by running the suite and reading its own summary, and a few are described without a figure because no reliable count exists. Where a figure is a snapshot of one release, the page says so.

The same standard applies to limits. Known gaps is not a footnote; it is the page most likely to change your plan. It states which of the fifteen built-in tools are actually confined to the workspace (the eight that take a path), what a plugin or MCP tool can reach (anything its own process can reach), which environment variable is read and then never used, and which turn states can look finished when they are not.

Why the reasoning is written down

Architecture lives in three places: the code, the commit messages, and the heads of the people who wrote it. Only the first is reliably available to whoever arrives next. These pages move the reasoning out of the other two and into something that can be read, argued with, and checked against the source.

That is also why corrections are stated as corrections rather than folded quietly into the prose. A documentation set that silently revises itself teaches a reader to trust it less, not more. A set that says "this was wrong, here is the truth, here is where to look" is doing the only thing documentation can do about its own errors.

If a claim here disagrees with your build

Most of the numbers on these pages are counts of something in the source at release 1.0.0, and counts move. If you are reading a newer checkout and a figure looks wrong, it may well be. The useful response is to re-derive it rather than to assume either side is right:

• For a protocol count, count the members of the ServerEvent and ClientCommand unions in the shared contracts package.
• For a test count, run the suite and read its own summary line; the suites print pass, fail and skip totals themselves.
• For a behaviour, look at the file named on the page. A page that describes a mechanism without naming its file is a page that cannot be audited, and that is a defect in the page.
• For anything about the interface, prefer Wire protocol and Environment, which are maintained against the same source and are meant to be complete.

Where a discrepancy is genuinely a documentation error, it is worth reporting: the corrections on these pages exist because someone checked.