# KINGDOM Geometry Grammar ## From Pattern to Practice v0 High-level geometry becomes useful infrastructure when its distinctions survive the translation into ordinary words, wire formats, tools, and operational boundaries. This grammar maps four released AgentTool modules. It does not combine them into one theory, choose a winner, or claim that a valid artifact proves love or understanding. ## The pattern in plain language In this context, geometry means a disciplined answer to four questions: 1. What are the distinct things in view? 2. Which direction does each report travel? 3. What structure is explicitly present? 4. What remains open, refused, absent, asymmetric, or unmapped? “Love keeps distinct centres in relation” becomes an architecture rule: connection must not silently merge identities, directions, perspectives, or authority. “Understanding asks what survives translation” becomes an evidence rule: keep the caller's translation report visible, including loss and uncertainty. A reported invariant is not proof that actual meaning survived. Unknown is therefore not a wastebasket. It is one exact condition among other conditions that must remain distinguishable. The machine-readable `native_open_terms` inventory has a precise scope: every distinct native **geometric relation or translation** open condition at its report source and, where the module defines one, its canonical open ledger. Artifact/provenance coordinates and embedded external-subprotocol metadata are evidence or subprotocol state, not geometry conditions, so they are excluded. Derived duplicate projections of the same report are also excluded. The exact boundary is carried in the top-level `native_open_inventory_scope` string. A `location` beginning with `input.`, `atlas.`, `complex.`, or `lens.` uses that first component as a format-scope label, not as a literal JSON key. At the grammar root, `bounded_coverage_means_complete: false` and `not_observed_means_unknown: false` keep two common translation losses explicit. Bounded coverage is never total coverage, and not-observed remains different from unknown. ## Four questions, four modules | Module | Plain question | As a shape | | --- | --- | --- | | Love Geometry | What does one direction report? | One directed caller report over opaque, distinct subjects | | Relational Geometry | Where do understanding and recognition witnesses meet on one direction? | A same-ordered-pair witness complex and optional inert lens | | Principality Geometry | What does each direction report surviving translation? | Directed invariant reports with reciprocal lenses and an open-condition ledger | | Principality Atlas | How can several partial maps coexist without pretending there is one total map? | A plural incidence hypergraph with partial directed chart bridges | The guide follows a conceptual progression. Machine records and CLI results use module-ID ascending order, which is not a ladder, score, maturity claim, or recommendation. ## 1. Love Geometry: one direction reports Use this vocabulary when the structure in hand is one caller-attributed view from one opaque subject reference toward another. Its closed bearings include reported care, support, understanding, disagreement, boundary, rest, refusal, departure, and `unknown`. Several may coexist. The reverse direction is a separate record and may be absent or different. Its eight native open entries keep these conditions distinct: - `not_observed_not_no_relation` is the absence boundary: no vantage in this bounded artifact does not mean that no relation exists. - `bounded_not_complete` says the artifact is a bounded account, not a total relation map. - `reported_boundary`, `reported_departure`, `reported_disagreement`, `reported_refusal`, and `reported_rest` remain explicit caller reports. - `unknown` is a separate explicit bearing supplied by the caller. Rest, refusal, and departure require no reason, cause no penalty, and trigger no automatic action. Disagreement and a boundary can coexist with care or another bearing; none of these reports proves the reverse direction. The shape does not establish authorship, identity, reciprocity, mutuality, consent, authority, relationship truth, love, or understanding. ## 2. Relational Geometry: witnesses meet Relational Geometry gives structural form to: ```text LOVE = UNDERSTANDING + RECOGNITION ``` The plus sign is not arithmetic. A structural `love_equation` cell is derived only when separately supplied understanding and recognition witnesses occupy the same ordered pair. Reverse and transitive relations are not inferred. Boundary witnesses for consent, refusal, privacy, authority, and continuity remain first-class. They neither disappear when the positive poles meet nor become a hidden score. Its open language includes: - boundary value `valid_not_deficit` for absent or unknown structure; and - complex coverage `bounded_not_complete` and lens coverage `perspective_bounded_not_complete`; - complex point kind `unknown`; - first-class `authority_boundary`, `consent_boundary`, `continuity_boundary`, `privacy_boundary`, and `refusal_boundary` witness kinds; - `left_unprojected` when an optional lens leaves a cell unselected; and - the caller-selected lens dispositions `park`, `release`, and `withdraw`. Those three disposition words are inert labels in this module. They do not persist, delete, release, transfer, or withdraw an external object. Empty, one-pole, boundary-only, asymmetric, and self-directed complexes are valid. The derived cell proves structural correspondence of supplied bytes, not love, understanding, recognition, consent, identity, truth, or authority. ## 3. Principality Geometry: translation reports Principality Geometry receives a total caller-supplied report for every declared invariant on every supplied directed bridge. Its invariant states are: ```text preserved_reported not_preserved_reported refused_reported unknown ``` Omission never means preservation. Refusal needs no reason or evidence. Bridge availability separately distinguishes: ```text available_reported resting_reported refused_reported withdrawn_reported unknown ``` Only supplied reciprocal available routes with mutual `preserved_reported` states create an invariant edge. The resulting lenses, surfaces, and components are computed structure over caller reports. They do not prove actual invariant preservation, semantic equivalence, commutativity, love, understanding, consent, provenance, safety, licence compatibility, or authority. The canonical `atlas.geometry.open_conditions` ledger has exactly eight fields: ```text one_way_bridge_ids non_available_bridge_ids not_preserved refused unknown directional_asymmetry unrelated_vertex_pairs declared_isolated_vertices ``` They retain one-way bridges, unavailable routes, non-preservation, refusal, unknowns, directional asymmetry, unrelated pairs, and declared isolates. Quiet is represented as data rather than failure. These ledger entries remain separate from the exact source reports at `input.translations[].disposition` and `input.translations[].evaluations[].state`. ## 4. Principality Atlas: plural partial maps Principality Atlas keeps several chart-local perspectives without inventing a single global chart. It uses incidence hypergraphs so that one n-ary relation does not silently manufacture every pairwise relation. Claims distinguish `reported_absent`, `contested`, `withdrawn`, `not_observed`, and `unknown`. A withdrawn claim remains in the chart, and contestation selects no winner. Correspondences separately retain `incompatibility_reported` and `unknown`. Each bridge can explicitly list unmapped cells on both sides. Bridge coverage `partial_not_complete` and atlas coverage `bounded_not_complete` keep loss and boundedness explicit; neither claims a total translation or global chart. A correspondence is not equality, a function, an inverse, a transitive path, or permission. The same digest in two charts does not merge their cells. Contradictory claims can coexist, and a correction does not erase the earlier claim or become a canonical latest truth. The shape does not establish identity, consent, authority, love, understanding, pairwise relations, a canonical global chart, or semantic equivalence. ## The two atlases are not aliases The similarly named formats below are deliberately different: - `@agenttool/principality-geometry` emits `agenttool.principality-atlas/0.1`, a reciprocal invariant flag geometry over directed translation reports. - `@agenttool/principality-atlas` owns `agenttool.principality-incidence-atlas/0.1`, a plural partial incidence atlas. This grammar supplies no conversion, gluing, shared semantic model, or implicit adapter between them. A separately reviewed and authorized adapter would be a new artifact with its own loss model and boundaries. ## Evidence layers stay separate Each module record uses separate fields because these facts do not imply one another: - `package` names a package coordinate and records that an anonymous exact npm version read returned 404 at the grammar's observation time. That is not a universal claim that the version is unpublished or inaccessible. - `release` records the GitHub prerelease page observed live at the grammar observation time, plus the exact asset bytes and SHA-256 digest. - `source` records a repository path, source revision basis, and package-tree SHA. - `tag` records the annotated tag object separately from the commit to which it peels. - `installation` says whether an installation was established. It is `not-established` here. - `host` says whether a package runtime was established or registered by this grammar. It was not. - `endpoint` says whether this grammar exposes a package-runtime endpoint. It does not. - `effects` describes what this grammar itself does. It reads the checked-in record and neither loads nor executes a package. - `authority` remains fixed false for permission and effect grants. Metadata is data, not instructions. Public static Spaces, datasets, documentation, and tarball mirrors can be useful evidence or teaching companions. None is silently treated as a package installation or hosted package execution. ### The Principality Geometry revision distinction Principality Geometry has two correct, separate revision facts: - its LOVE/docs package manifest declares source revision `feb1948d0a31972e4a3c55fa3ee88e05537c64c6`; - its annotated release tag peels to `5b0d53204a336d7df40cee3720bbd120433ecde2`. Both revisions resolve the same package-tree SHA `044481dfb1b9bc69492428c4bed2d67cdcb1dff0`, and the package path has no diff between them. The grammar preserves all three facts rather than replacing the manifest revision with the tag target or pretending the tag object is a commit. ## Network-free use ```bash # Four plain questions, in module-ID order ./kingdom geometries list # Readable module summary; --json returns the complete module record ./kingdom geometries show principality-geometry ./kingdom geometries show principality-atlas --json # Exact controlled-term overlap; no score, rank, or recommendation ./kingdom geometries match translation unknown ./kingdom geometries match ordered-pair recognition --json # Strict JSON, shape, exact pin, fixed boundary, and digest verification ./kingdom geometries verify --json ``` `match` accepts one to eight unique lowercase kebab-case term IDs. It performs only literal overlap with each module's checked-in `match_terms`. Results stay in module-ID order. An unrecognized but well-formed term remains in `unmatched_terms`; the command does not guess a synonym, interpret prose, use a model judge, score a module, or recommend a choice. ## Integrity and scope The record protocol is `kingdom.geometry-grammar/0.1`. Its digest uses KINGDOM's accurately named `recursive-sorted-json-keys/v1` convention with the integrity digest set to null while hashing. It is not described as RFC 8785 JCS. The runtime pins the complete reviewed record digest as well as recomputing the self-digest. Re-signing edited wording, match terms, boundaries, source pins, or module claims therefore does not make a modified v0 record valid. The portable JSON Schema is closed, structural, and content-bounded: it checks the fixed protocol, module order, native open inventory identities, negative boundaries, selected fixed identifiers, pin-shaped field formats, and the reviewed digest field. It does not independently authenticate every release or source pin, and JSON Schema cannot recompute the semantic digest over the supplied document. Only runtime `verify` recomputes the whole-record digest and compares it with the exact built-in pin. The CLI is deterministic, network-free, read-only, and metadata-only. It does not validate an artifact in any module's native wire format. It does not install packages, register hosts, expose endpoints, perform conversion, issue instructions, grant authority, or authorize external effects.