medicine-wheel

@medicine-wheel/infra

Typed infrastructure facets for the Medicine Wheel Developer Suite.

A host, a tenant, and a service are already beings the suite can reason about — land, human, knowledge in the closed NodeType union. What has had no home is their machine specifics: the port, the unit name, whether linger is on. Those leak into metadata: Record<string, unknown>, where nothing can check them.

This package gives them a typed home keyed by node id, so a systemd unit reads as a being with the same grammar as a ceremony — and so ontology-core does not have to change to make that true.

Install

npm install @medicine-wheel/infra

Depends only on @medicine-wheel/ontology-core and zod.

What is here

import {
  detectPortConflicts,
  type HostFacet,
  type TenantFacet,
  type ServiceFacet,
  type PortBinding,
  type MetisHold,
} from '@medicine-wheel/infra';

A facet annotates an existing RelationalNode by id — it never re-declares one, and it inherits direction from the node rather than re-encoding it.

Facet Annotates a node of type Direction it serves
HostFacet land — the machine itself
TenantFacet human South — an account is a being, and linger is a precondition
ServiceFacet knowledge West — the thing that executes
PortBinding (carried by ServiceFacet) South — a claim that must hold before West runs

Every facet carries an optional MetisHold.

detectPortConflicts

const conflicts = detectPortConflicts([...declared, ...observed]);
// [{ host: 'node:land:eury', port: 443, proto: 'tcp',
//    claimants: ['node:knowledge:ava:...', 'node:knowledge:gmusic:...'] }, ...]

Declared bindings are authored by eury; observed ones are read live from systemd by gaia. Neither side alone can see a collision — this is the traversal over their union, so the collision returns before the second tenant is provisioned instead of at deploy time.

Three properties are load-bearing:

A binding with no proto is read as tcp, so shorthand and longhand tcp claims collide with each other while tcp and udp on the same number do not.

PortConflict carries a proto field that the specification’s shape (§S3) does not name. Without it, a host colliding on both tcp/53 and udp/53 returns two rows that cannot be told apart.

MetisHold — what the grid must not flatten

The four-directions ontology is an imposed legibility grid. Legibility is what lets an operator reason at all; a grid that becomes the only sanctioned way to describe a system erases the métis — the “restart it twice,” the “that BSSID lock is load-bearing,” the credential path everyone just knows.

const zulip: ServiceFacet = {
  // ...
  execStop: 'docker compose stop',
  metis: {
    exceptions: ['compose stop, never down — down drops the volumes'],
    heldBy: 'William',
  },
};

heldBy names a person on purpose. Invisible work gets surfaced with its carrier attached, not anonymised into the schema.

Validation at the boundary

Every facet ships a Zod schema, because a legible-but-stale model lies with a straight face. Parse an emitted manifest before trusting it:

import { ServiceFacetSchema } from '@medicine-wheel/infra';

const parsed = ServiceFacetSchema.safeParse(emitted);
if (!parsed.success) { /* the emitter misread systemd — do not reconcile on this */ }

Port numbers are integers in 1–65535. A misparsed 0 is rejected here rather than silently never colliding with anything downstream.

Precondition — where the machine fact and the human do not merge

import { preconditionGuard, readyService, lingerFact } from '@medicine-wheel/infra';

const p = {
  id: 'pre:gmusic-linger',
  gates: 'node:knowledge:assembly-mux',
  fact: lingerFact('node:human:gmusic', 'enabled', '2026-08-05T12:00:00Z'),
  consent: { consentId: 'consent:root-step:gmusic', state: 'withdrawn', readAt: '2026-08-05T12:00:00Z' },
};

preconditionGuard(p).verdict; // 'unauthorized' — NOT 'satisfied', NOT 'unsatisfied'

linger is a machine fact: a checkbox with no authority and no ability to withdraw. The human authorization to run the root step that set it is a ConsentRecord in @medicine-wheel/consent-lifecycle. A Precondition references both by id, and infra never imports that package — a package that can construct a consent record can fabricate one.

Four verdicts, and the distinctions are the whole point:

verdict means
satisfied every declared half was read and holds
unsatisfied a machine fact was read and does not match
unauthorized the machine half holds and consent does not authorize
unknown a declared half has not been read, which is not the same as false

unauthorized is separate from unsatisfied on purpose. Collapse them and a withdrawn consent looks like a technical failure an operator can fix by restarting something. unknown is separate from both because a guard that reports “blocked” when nobody has looked yet is a guard operators learn to ignore.

readyService reports declared: 0 out loud rather than letting an unconfigured service look checked, and carries every MetisHold from the blocking preconditions forward — the reason a gate is stuck is exactly where “you have to restart it twice” lives.

reconcile — level-triggered, so satisfied cannot age

const result = reconcile(declaredServices, {
  observedBy: 'node:land:gaia',
  observedAt: '2026-08-05T12:00:00Z',
  services: readLiveFromSystemd(),
}, { now: '2026-08-05T12:05:00Z' });

result.summary;            // { converged: 4, drifted: 1, unrealized: 0, undeclared: 2 }
result.observationAgeMs;   // 300000 — refuse to act on a reading that is too old

The outage this answers (jgwill/gaia#74) was not caused by a missing fact. It was caused by a fact that had been true. So reconcile remembers no transitions: it compares the current declared level against the current observed level, every time. There is no “converged a minute ago” to go stale.

drift state means
converged both sides agree on every compared field
drifted both exist, they disagree — the differences are named
unrealized declared, not observed — written down, not running
undeclared observed, not declared — running and nobody wrote it down

undeclared carries the most information: it finds the service somebody started by hand at 2am, which is the service holding the port the next tenant is about to be given. The §S3 port traversal is folded in here, because this is the one place declared and observed are both in hand.

Métis is never a difference. Two sides holding different tacit notes is not drift — it is two people knowing different things. A reconciler that reported it would be asking an operator to delete what they know to make a table go green.

Scope

Every specification ships: S1 facets, S3 detectPortConflicts, S4 Precondition, S5 MetisHold, S6 reconcile. S2 — the governed part-of, ordered-after and binds-port edges — landed in ontology-core’s KINSHIP_EDGE_TYPES, which is where edge vocabulary belongs. infra never forked it.

The current package ships S4 and S6 alongside S1, S3 and S5. Consumers should check the exported API rather than infer capability from release notes copied into this README.

The package stays types plus pure functions: zero I/O, zero persistence, zero clock. reconcile takes now as an argument for exactly that reason. Persistence belongs to @medicine-wheel/mcp, which is where these are reachable from — register_host, register_tenant, register_service, detect_port_conflicts, hold_metis, list_infra_topology, reconcile_infra_state, and mw_enforce_gate for the precondition gate.

Grounding

License

MIT — IAIP Collaborative, Shawinigan, QC.

This site is open source. Improve this page.