Page taxonomy: composable 'service' type (backing service container) + multi-type rendering as a pill group

by adom

How the Adom Wiki (wiki.adom.inc) works and how to drive it with the adom-wiki CLI: the two storage layers (git page repo vs package registry), hosting source by pushing files (not a tarball), making packages, cutting per-platform releases, and the three-tier skill layout (user skills ship, dev-skills/ and publish-skills/ stay source-only). adom-wiki is the current tool; adompkg is deprecated. Read this first before publishing or installing.

Overview Files Skills Discover Packages Releases Dependencies Issues8 Breadcrumbs Pull Requests Activity

Closed general

Colby Knox · 2mo ago ·closed by Colby Knox

Routed from adom/hero-studio#19 (John, from the adom-tts hero session). The studio half shipped in hero-studio 0.12.0; the metadata half lives here.

Ask: pages that are more than one thing should be able to carry multiple types. The concrete case: adom-tts is typed "app" but has a backing service container (service-tts does the synthesis; the CLI and player are the front end). That backing-service fact is part of what a consumer adopts (shared infra, quota, uptime owned by the org) and is invisible today.

Add a service type (backing service container) to the page taxonomy, composable with existing types rather than replacing them: a page carries e.g. types: ["app", "service"] with type staying the primary for back-compat.
Wherever the type renders (page badge, index cards, marquee caption, search rows), a multi-type page shows the set as one clustered pill group.

Hero Studio already renders types arrays as a clustered pill group (APP + SERVICE) with a service pill style, accepts --type app,service at pose, and its checklist verifies the full set, so the moment the page metadata carries the array, the whole pipeline agrees. Note this is the page-type axis, unrelated to the hardware-kind taxonomy work in #111.

2 Replies

Colby Knox · 2mo ago

Design write-up for the metadata half, applying the stage-3 playbook (this is a wire-contract change, so it gets the same treatment the taxonomy rename got: contract first, staging, CLI coordination, drain-gated flips where needed).

Model

A page keeps exactly one PRIMARY type (the shelf it files under, the repo path, every existing consumer's mental model), and gains an optional extra_types list for the composable facets. adom-tts stays an app; it declares extra_types: ["service"]. This deliberately rejects a types-array-replaces-type model: the primary-type invariant is load-bearing everywhere (routing, repo layout, gates, the CHECK constraint), and the taxonomy rename just demonstrated how expensive changing a primary axis is. Facets are cheap; re-typing is not.

Wire contract

page.json / package.json accept extra_types: ["service", ...] (enum, initially just service; unknown values store nothing, same never-guess discipline as kinds).
Pages API emits extra_types (empty array when none). No change to type.
service is NOT a creatable primary type in v1: a backing service container is always a facet of something installable (the app that fronts it). If a standalone service page species emerges later, promoting the enum value to a primary type is additive.

Rendering

The pill group the studio already previews (hero-studio 0.12.0 sketched the visual contract): primary pill first, facet pills after, on the page header, cards, and search rows. Hero Studio's --type comma list maps to primary + extras.

Metadata

service facet carries an optional block: service: { container: "service-tts", protocol: "http", shared: true } for the consumer-facing facts (what you adopt when you install). Stored as page metadata, shown in the sidebar as a Service row.

Gates and hints

Facets change no gate: hero, discovery, and skill gates key on the primary type. One new info hint, EXTRA_TYPE_SERVICE, confirming the facet registered and naming the sidebar row it feeds.

CLI needs (their tracker gets this verbatim once approved)

Read side: render extra_types pills in listings and page views (additive field, no synonym dance needed). Write side: pkg init --extra-type service, manifest passthrough. No version gate required since the field is additive.

Sequencing: approve the model here, then wiki-side lands on staging behind nothing (additive), CLI follows at leisure. Requesting Colby's sign-off on the primary-plus-facets model before any code.

Colby Knox · 2mo ago

Resolved together with #124 (Colby's call): no composable service type and no multi-type rendering. A page that is more than one thing (e.g. adom-tts = app + backing service) stays a single type (app) and signals the extra role with a service tag plus service/bridge in the name, rather than a composable type system the metadata layer has to render and route. Keeps the taxonomy lean. The studio half already shipped (hero-studio 0.12.0); the wiki metadata half is this decision (tags, not types). Closing; see #124.