Diagram
Public publication boundary
How a dedicated public bundle becomes a bounded complete publication and curated human presentation.
Question answered
How does an authoritative Superbee bundle become a bounded public publication, and which layer is responsible for keeping private material, operational records, presentation choices, and runtime authority in their proper places?
Publication starts with a bundle whose contents are already approved for its declared audience. The snapshot captures that complete bundle coherently. Portal then validates the complete exposure and builds an immutable artifact. A documentation projection selects the material intended for the main reader experience, while the Portal artifact retains the complete public bundle for inspection.
The first boundary is the source bundle
Superbee publication has no document-level privacy filter. Capture inventories every concept
document, reserved OKF file, and blob in the selected bundle, excluding dot-prefixed implementation
entries such as .git. The exact-byte inventory and default limits are defined by the
snapshot capture
and its
complete inventory walk.
This makes source selection consequential. A public site must capture a dedicated public bundle.
Private strategy, credentials, personal data, embargoed material, and security findings must stay in
another bundle. Portal's sensitive-content checks are a useful refusal layer for recognizable keys,
credential-shaped filenames, and workstation paths. They are not a general confidentiality
classifier. The current checks are visible in
checkPublication.
One coherent immutable snapshot
Capture authorizes one real, non-aliased filesystem root, rejects unsafe tree entries, reads the inventory twice, and retries only when the source changed during capture. Every accepted object is content-addressed. Documents carry exact Markdown and canonical inert rendered HTML; relationships are derived from the captured documents; registered Views bind their exact entry object. The snapshot construction and two-pass currentness check make the snapshot the stable handoff between mutable bundle authority and downstream consumers.
The snapshot backend is read-only. Every write and delete method refuses with
CAPABILITY_UNAVAILABLE, as shown by the
publication storage adapter.
Published Views may receive none or bundle-read; bundle-propose is refused. The
publication bridge admission
binds a View to its exact snapshot registration and entry digest, then disables actions and polling
in the
read-only bridge service.
Projection, runtime, and consumer ownership
| Layer | Owns | Refuses or omits |
|---|---|---|
| Public bundle | Which knowledge is eligible for the declared audience | Private or embargoed material must never enter this source |
superbee/publication | Exact complete inventory, immutable objects, semantic read model, inert rendering, registered View identity | Mutable source races, unsafe filesystem identities, malformed documents, missing View entries, write capability |
| Portal core | Explicit public or restricted audience, acknowledged complete-bundle exposure, sensitive-content checks, exact View admission, deterministic artifact and hosting requirements | Unregistered HTML, bundle-propose, unknown routes, unowned output replacement |
| Documentation projection | Curated navigation, supporting documents, operational type exclusions, relationships, brand, diagrams, and freshness facts for human presentation | Operational types in navigation or supporting content; documents outside the declared selection |
| Target adapters | Portal HTML or MkDocs materialization from one admitted projection | Reinterpreting bundle semantics or expanding the selected document set |
| Hosting runtime | Exact artifact verification, declared routes, response headers, static files, and the read-only View bridge | Fallback routes, changed bytes, unauthorized restricted access, undeclared View bridges |
The projection contract explicitly keeps operational document types in the complete publication bundle while forbidding them from the human presentation. It also bounds navigation, supporting documents, relationships, and assets. See the projection configuration and its selection validation.
Portal core still emits exact Markdown, reserved files, blobs, relationships, snapshot data, and the
read model for the complete bundle. The docs presentation supplies the curated routes and UI. That
composition is explicit in
createPortalArtifact.
The MkDocs adapter consumes the same projection through its own target contract and emits only the
selected documentation material, as shown by its
materialization loop.
Failure and trust boundaries
A wrong source bundle is a publication-authority failure. Later scanners cannot prove that prose is safe to disclose.
A source mutation during capture produces
SOURCE_CHANGED; no mixed snapshot is returned.Malformed documents, invalid View registrations, missing entries, limit violations, and digest mismatches stop capture.
Portal requires the caller to acknowledge
complete-publication-bundle, checks every admitted View against the snapshot, and refuses recognizable sensitive content before artifact creation.Operational types control reader presentation only. They remain public and inspectable because the Portal artifact carries the complete public bundle.
The documentation projection is host-neutral. Portal and MkDocs are consumers, so presentation changes do not alter bundle semantics or snapshot identity.
The hosting runtime serves only verified artifact paths. Public publication does not create a mutation channel back to the source bundle.
The visual summarizes these boundaries. Its prose equivalent is the layer table and failure list above.