Skip to content
Cognithamus
Create account
← Documentation

docs/public-surface.md

What is the supported public surface of Cognithamus?

An architectural investigation, not an implementation plan. The deliverable is the contract. Nothing is published until the questions below have answers.

Prompted by measuring Enterprise XI, which forked Cognithamus' HQ modules rather than depending on them. Two questions had to be separated before that could be diagnosed.

Q1 — Could Enterprise XI depend on Cognithamus today?

No. Measured:
private true
exports none
main none
files none
npm not published
git remote exists (Xcortex.git)

A git dependency is technically reachable, but private: true with no exports or main means nothing can be imported from it. Publishing is therefore a real platform deficiency — but only once the right surface is known, which is Q2.

Q2 — If it were published, should an application depend on core/?

No — and the evidence is unusually direct. The only real consumer that has ever existed voted with its imports.

What Enterprise XI actually took

@/lib/hq/estate      @/lib/hq/roster     @/lib/hq/state
@/lib/hq/telemetry   @/lib/hq/view       @/lib/hq/layout
@/components/hq/CityConsole

What it did not take

src/core — 0 of 8 files. Also lib/world (0 of 15) and components/world (0 of 5).

core/ is the platform's most verified asset and is domain-free by construction. The one consumer that existed never touched it. Reusable and verified did not make it the application contract, exactly as suspected.

Why it took what it took — lag and specialization are both present

Distinguishing these is what settles the boundary.

Specialization — genuinely application-owned. Enterprise XI's telemetry.ts imports:

import { db } from "@/lib/db";                        // its own database
import { PLANS } from "@/lib/plans";                  // its own subscriptions
import { COURSE, MODULES } from "@/lib/course";       // its own academy

Cognithamus has no concept of plans or courses. This is an application wiring its own domain into a shape it obtained by copying. That is correct behaviour for an application, and this content must never be shared.

Lag — the shared mechanics, frozen. Every Enterprise XI file was last touched 2026-07-30; the platform kept moving.

Module EXI Cognithamus
telemetry.ts 430 lines, 07-30 675 lines, 07-31
estate.ts 118, 07-30 154, 07-30
view.ts 70, 07-30 92, 07-31
roster.ts 188, 07-30 178, 08-01

roster.ts is larger in Enterprise XI only because it still carries the hand-authored accent: "#8ea2ff" hex constants that the platform replaced with derived hueFor values. That is lag wearing the appearance of specialization, and it is why file size alone would have misled.

The correction this forces

The earlier assessment said Enterprise XI "copied the wrong layer." That was a premature diagnosis and the evidence does not support it. It copied the layer that solved its problem — the only layer that carried domain wiring — and then wired its own domain in. What it lacked was not judgement; it was an application-facing interface that did not exist.

The candidate public surface

Derived from the split above: what Enterprise XI lagged on is shared mechanics; what it specialized is its own.

Public — the honesty contract

The single most valuable thing Enterprise XI copied, and the thing it could not have invented:

Every reading declares its provenance: live (read just now from disk or database), unreachable (the source exists, this machine cannot see it), or not-wired (the integration does not exist yet).

That distinction — absence of data separated from absence of integration — is a platform invariant, is domain-free, and is what stops a dashboard from rendering zero as a fact. It is a contract, not code.

Public — candidates, each with its evidence

Surface Evidence it is public Status
The source provenance contract copied verbatim, unmodified, by the only consumer strong
The view shape an app renders (CityView) copied and lagged, not specialized strong
Structural types for estate/roster copied; only their content was specialized moderate
core/ ontology never consumed weak — no evidence of demand

Application-owned — must not be shared

Everything the consumer specialized: which products exist, which agents exist, which database is read, plans, courses. Cognithamus supplying these would be supplying another application's domain.

Explicitly private

  • src/core — until an application demonstrates demand. It remains the platform's own foundation; being unshared is not being unused.
  • src/lib/world, src/components/world — the 3D world, its metric layer, geometry and residual. Zero consumer demand measured.
  • The constitution, ledgers and mutation harness — platform-internal governance. Explicitly not a product.

Open questions — these gate publication

  1. Is the surface a package, an API, or both? Enterprise XI runs as a separate deployment; a package shares types at build time, an API shares data at runtime. The source contract is a type-and-invariant, which argues for a package; /api/world already exists, which argues an API is partly built. Not yet answered.
  2. What invariants would be guaranteed? Provenance labelling is the clear candidate. Whether Article-level guarantees (I.1 traceability, III.4 stability) extend to consumers is undecided — they are currently enforced only inside this repository.
  3. What is the versioning policy? World carries version: 1, which is the right instinct and the only versioning that exists. Nothing states what a bump means or what compatibility is promised.
  4. Does a second consumer exist? The entire surface above is inferred from n = 1. A surface designed to one consumer's needs is a surface fitted to its discovery set — the §4 soundness failure, applied to architecture. This is the strongest argument for keeping the first published surface narrow.

Recommendation

Publish the source provenance contract first, and little else. It is the one surface with unambiguous evidence of demand, it is domain-free, it is verifiable, and it is small enough that being wrong is cheap.

Defer core/ publication until an application asks for it. Its value is not in doubt; its demand is unmeasured, and publishing an interface nobody has requested creates a compatibility obligation with no corresponding benefit.

Do not begin B.1 as an implementation task until questions 1–3 are answered. The application track is independent and should not wait.