gitgrip 2.0.0a4__tar.gz → 2.0.0a6__tar.gz

{gitgrip-2.0.0a4 → gitgrip-2.0.0a6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitgrip
-Version: 2.0.0a4
+Version: 2.0.0a6
 Summary: Workspace layer for multi-repo work: workspaces, isolated lanes, and one grouped review per slice
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -12,6 +12,7 @@ Requires-Dist: jsonschema>=4.18
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: packaging>=22; extra == "dev"
 
 # gr2
 
@@ -76,7 +77,7 @@ gr2 commit -m "my change" --workspace-root ~/ws --owner-unit default
 ```bash
 gr2 exec run ~/ws default --actor human:you -- pytest -q   # one command, every lane repo
 gr2 review create-project ~/ws default feat-x              # prints gr:<sha>: one object to review
-gr2 lane current ~/ws default                              # where am I?
+gr2 lane show ~/ws default                                 # where am I?
 gr2 lane exit ~/ws default --actor human:you
 ```
 
@@ -86,7 +87,7 @@ gr2 lane exit ~/ws default --actor human:you
 
 Alpha 2 is a working local workspace layer. Verified by running the walk above:
 
-- `workspace` (init, materialize, status, migrate-gr1 from a gr1 gripspace), `lane` (create, enter, exit, current, lease), `store` (init, snapshot, log, diff, checkout), `exec run`, `repo status`, `sync status`, `review create-project`.
+- `workspace` (init, materialize, status, migrate-gr1 from a gr1 gripspace), `lane` (create, enter, exit, current, lease), `store` (init, commit, log, diff, checkout), `exec run`, `repo status`, `sync status`, `review create-project`.
 - Lanes are independent clones: two lanes, or two agents, never share refs, an index, or a working tree.
 - A lane commit that commits nothing anywhere refuses loudly instead of reporting success.
 
@@ -100,17 +101,18 @@ Not there yet:
 
 | Group | Verbs |
 |---|---|
-| `workspace` | init, init-from-topology, materialize, status, convert-clone, detect-gr1, migrate-gr1, migrate-lane-state, bootstrap-gr1 |
+| `workspace` | init, init-from-topology, materialize, status, convert-clone, detect-gr1, migrate-gr1, migrate-lane-state, bootstrap-gr1, gitinclude |
 | `spec` | show, validate |
-| `lane` | create, enter, exit, current, resolve, bind, lease |
-| (top level) | branch, add, commit, push, prune |
+| `lane` | create, enter, exit, show, resolve, bind, lease |
+| (top level) | branch, add, commit, push, prune, status, plan, apply |
 | `sync` | status, run |
-| `pr` | create, status, checks, merge |
+| `pr` | create, status, checks, merge, view |
 | `review` | open, close, checkout-pr, run, requirements, bind, verify, rebind, create-project |
 | `exec` | status, run |
-| `repo` | status, hooks, hook-run, projection-run |
-| `store` | init, snapshot, log, diff, checkout |
-| `target`, `config`, `plan`, `apply` | stored PR target; config overlays; show/apply the materialization plan |
+| `repo` | status, projection-run |
+| `hooks` | trust, revoke, status, show, run |
+| `store` | init, commit, check, push, status, log, diff, checkout, materialize, migrate |
+| `target`, `config` | stored PR target; config overlays |
 
 ## Overlay substrate
 
@@ -123,3 +125,5 @@ pip install -e "gr2[dev]"    # from the repository root
 cd gr2 && pytest             # the gr2 suite (tests + overlay tests)
 cd gr2 && ruff check .       # lint, same config as CI
 ```
+
+The Rust development binary is **`gr2-dev`** — built by `cargo build -p gr2-cli --release`, `publish = false`, and not shipped with `cargo install gitgrip`. It answered to the name `gr2` until 2026-09-30, so a branch written before that rename goes red on `cargo test -p gr2-cli` with `CARGO_BIN_EXE_gr2 is unset`; the repair is `cargo_bin("gr2-dev")`, from which Cargo derives `CARGO_BIN_EXE_gr2-dev`.

{gitgrip-2.0.0a4 → gitgrip-2.0.0a6}/README.md

@@ -61,7 +61,7 @@ gr2 commit -m "my change" --workspace-root ~/ws --owner-unit default
 ```bash
 gr2 exec run ~/ws default --actor human:you -- pytest -q   # one command, every lane repo
 gr2 review create-project ~/ws default feat-x              # prints gr:<sha>: one object to review
-gr2 lane current ~/ws default                              # where am I?
+gr2 lane show ~/ws default                                 # where am I?
 gr2 lane exit ~/ws default --actor human:you
 ```
 
@@ -71,7 +71,7 @@ gr2 lane exit ~/ws default --actor human:you
 
 Alpha 2 is a working local workspace layer. Verified by running the walk above:
 
-- `workspace` (init, materialize, status, migrate-gr1 from a gr1 gripspace), `lane` (create, enter, exit, current, lease), `store` (init, snapshot, log, diff, checkout), `exec run`, `repo status`, `sync status`, `review create-project`.
+- `workspace` (init, materialize, status, migrate-gr1 from a gr1 gripspace), `lane` (create, enter, exit, current, lease), `store` (init, commit, log, diff, checkout), `exec run`, `repo status`, `sync status`, `review create-project`.
 - Lanes are independent clones: two lanes, or two agents, never share refs, an index, or a working tree.
 - A lane commit that commits nothing anywhere refuses loudly instead of reporting success.
 
@@ -85,17 +85,18 @@ Not there yet:
 
 | Group | Verbs |
 |---|---|
-| `workspace` | init, init-from-topology, materialize, status, convert-clone, detect-gr1, migrate-gr1, migrate-lane-state, bootstrap-gr1 |
+| `workspace` | init, init-from-topology, materialize, status, convert-clone, detect-gr1, migrate-gr1, migrate-lane-state, bootstrap-gr1, gitinclude |
 | `spec` | show, validate |
-| `lane` | create, enter, exit, current, resolve, bind, lease |
-| (top level) | branch, add, commit, push, prune |
+| `lane` | create, enter, exit, show, resolve, bind, lease |
+| (top level) | branch, add, commit, push, prune, status, plan, apply |
 | `sync` | status, run |
-| `pr` | create, status, checks, merge |
+| `pr` | create, status, checks, merge, view |
 | `review` | open, close, checkout-pr, run, requirements, bind, verify, rebind, create-project |
 | `exec` | status, run |
-| `repo` | status, hooks, hook-run, projection-run |
-| `store` | init, snapshot, log, diff, checkout |
-| `target`, `config`, `plan`, `apply` | stored PR target; config overlays; show/apply the materialization plan |
+| `repo` | status, projection-run |
+| `hooks` | trust, revoke, status, show, run |
+| `store` | init, commit, check, push, status, log, diff, checkout, materialize, migrate |
+| `target`, `config` | stored PR target; config overlays |
 
 ## Overlay substrate
 
@@ -108,3 +109,5 @@ pip install -e "gr2[dev]"    # from the repository root
 cd gr2 && pytest             # the gr2 suite (tests + overlay tests)
 cd gr2 && ruff check .       # lint, same config as CI
 ```
+
+The Rust development binary is **`gr2-dev`** — built by `cargo build -p gr2-cli --release`, `publish = false`, and not shipped with `cargo install gitgrip`. It answered to the name `gr2` until 2026-09-30, so a branch written before that rename goes red on `cargo test -p gr2-cli` with `CARGO_BIN_EXE_gr2 is unset`; the repair is `cargo_bin("gr2-dev")`, from which Cargo derives `CARGO_BIN_EXE_gr2-dev`.

{gitgrip-2.0.0a4 → gitgrip-2.0.0a6}/gitgrip.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitgrip
-Version: 2.0.0a4
+Version: 2.0.0a6
 Summary: Workspace layer for multi-repo work: workspaces, isolated lanes, and one grouped review per slice
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -12,6 +12,7 @@ Requires-Dist: jsonschema>=4.18
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: packaging>=22; extra == "dev"
 
 # gr2
 
@@ -76,7 +77,7 @@ gr2 commit -m "my change" --workspace-root ~/ws --owner-unit default
 ```bash
 gr2 exec run ~/ws default --actor human:you -- pytest -q   # one command, every lane repo
 gr2 review create-project ~/ws default feat-x              # prints gr:<sha>: one object to review
-gr2 lane current ~/ws default                              # where am I?
+gr2 lane show ~/ws default                                 # where am I?
 gr2 lane exit ~/ws default --actor human:you
 ```
 
@@ -86,7 +87,7 @@ gr2 lane exit ~/ws default --actor human:you
 
 Alpha 2 is a working local workspace layer. Verified by running the walk above:
 
-- `workspace` (init, materialize, status, migrate-gr1 from a gr1 gripspace), `lane` (create, enter, exit, current, lease), `store` (init, snapshot, log, diff, checkout), `exec run`, `repo status`, `sync status`, `review create-project`.
+- `workspace` (init, materialize, status, migrate-gr1 from a gr1 gripspace), `lane` (create, enter, exit, current, lease), `store` (init, commit, log, diff, checkout), `exec run`, `repo status`, `sync status`, `review create-project`.
 - Lanes are independent clones: two lanes, or two agents, never share refs, an index, or a working tree.
 - A lane commit that commits nothing anywhere refuses loudly instead of reporting success.
 
@@ -100,17 +101,18 @@ Not there yet:
 
 | Group | Verbs |
 |---|---|
-| `workspace` | init, init-from-topology, materialize, status, convert-clone, detect-gr1, migrate-gr1, migrate-lane-state, bootstrap-gr1 |
+| `workspace` | init, init-from-topology, materialize, status, convert-clone, detect-gr1, migrate-gr1, migrate-lane-state, bootstrap-gr1, gitinclude |
 | `spec` | show, validate |
-| `lane` | create, enter, exit, current, resolve, bind, lease |
-| (top level) | branch, add, commit, push, prune |
+| `lane` | create, enter, exit, show, resolve, bind, lease |
+| (top level) | branch, add, commit, push, prune, status, plan, apply |
 | `sync` | status, run |
-| `pr` | create, status, checks, merge |
+| `pr` | create, status, checks, merge, view |
 | `review` | open, close, checkout-pr, run, requirements, bind, verify, rebind, create-project |
 | `exec` | status, run |
-| `repo` | status, hooks, hook-run, projection-run |
-| `store` | init, snapshot, log, diff, checkout |
-| `target`, `config`, `plan`, `apply` | stored PR target; config overlays; show/apply the materialization plan |
+| `repo` | status, projection-run |
+| `hooks` | trust, revoke, status, show, run |
+| `store` | init, commit, check, push, status, log, diff, checkout, materialize, migrate |
+| `target`, `config` | stored PR target; config overlays |
 
 ## Overlay substrate
 
@@ -123,3 +125,5 @@ pip install -e "gr2[dev]"    # from the repository root
 cd gr2 && pytest             # the gr2 suite (tests + overlay tests)
 cd gr2 && ruff check .       # lint, same config as CI
 ```
+
+The Rust development binary is **`gr2-dev`** — built by `cargo build -p gr2-cli --release`, `publish = false`, and not shipped with `cargo install gitgrip`. It answered to the name `gr2` until 2026-09-30, so a branch written before that rename goes red on `cargo test -p gr2-cli` with `CARGO_BIN_EXE_gr2 is unset`; the repair is `cargo_bin("gr2-dev")`, from which Cargo derives `CARGO_BIN_EXE_gr2-dev`.

{gitgrip-2.0.0a4 → gitgrip-2.0.0a6}/gitgrip.egg-info/SOURCES.txt

@@ -7,6 +7,7 @@ gitgrip.egg-info/entry_points.txt
 gitgrip.egg-info/requires.txt
 gitgrip.egg-info/top_level.txt
 gr2/__init__.py
+gr2/api_core.py
 gr2/overlay/__init__.py
 gr2/overlay/activate.py
 gr2/overlay/agent_manifest.py
@@ -23,6 +24,7 @@ gr2/overlay/types.py
 gr2/overlay/units.py
 gr2/overlay/workspace_spec.py
 gr2/schemas/gr2-materialization-plan-v1.schema.json
+gr2/schemas/gr2-workspace-spec-v1.schema.json
 gr2_overlay/__init__.py
 prototypes/__init__.py
 prototypes/cache_materialization_probe.py
@@ -59,6 +61,7 @@ python_cli/consent.py
 python_cli/env_exec.py
 python_cli/events.py
 python_cli/execops.py
+python_cli/exit_codes.py
 python_cli/failures.py
 python_cli/file_exec.py
 python_cli/git_review.py
@@ -68,6 +71,7 @@ python_cli/grip.py
 python_cli/grip_cli.py
 python_cli/hooks.py
 python_cli/launch_exec.py
+python_cli/layout.py
 python_cli/merge_verification.py
 python_cli/migration.py
 python_cli/open_gr_review.py
@@ -80,19 +84,26 @@ python_cli/review.py
 python_cli/review_dispatch.py
 python_cli/review_ephemeral.py
 python_cli/review_rebind.py
+python_cli/review_records.py
 python_cli/review_run.py
 python_cli/review_runners.py
 python_cli/spec_apply.py
 python_cli/staging_cleanup.py
 python_cli/syncops.py
 python_cli/target.py
+python_cli/version.py
 python_cli/workspace_guidance.py
 python_cli/workspace_snapshot.py
 tests/test_add.py
 tests/test_agent_manifest_overlay_source.py
+tests/test_api_core_seam.py
+tests/test_api_dump.py
 tests/test_app_event_outcomes.py
 tests/test_apply_convergence.py
+tests/test_apply_gr1_sibling_adoption.py
 tests/test_branch.py
+tests/test_break_17_unit_path_containment.py
+tests/test_break_18_gr1_sibling_units.py
 tests/test_channel_bridge.py
 tests/test_cli_adapter_error_boundary.py
 tests/test_cli_shape_witnesses.py
@@ -102,6 +113,7 @@ tests/test_config_base_path_guard.py
 tests/test_config_overlay.py
 tests/test_conftest_git_isolation.py
 tests/test_contribution_protocol.py
+tests/test_deprecation_registry.py
 tests/test_ensure_lane_checkout_reference_clone.py
 tests/test_env_materialization.py
 tests/test_event_log_integrity.py
@@ -121,32 +133,41 @@ tests/test_gr2_packaging.py
 tests/test_gr2_review_receipt.py
 tests/test_grip_cli.py
 tests/test_grip_hardening.py
-tests/test_grip_object_model.py
 tests/test_grip_snapshot.py
+tests/test_grip_toml_schema_v1.py
 tests/test_hook_events.py
 tests/test_hook_hardening.py
 tests/test_hooks_consent.py
+tests/test_hooks_group_names.py
 tests/test_jsonl_store.py
 tests/test_lane_create_fork_base_cli.py
+tests/test_lane_create_refusal_leaves_nothing.py
 tests/test_lane_create_refuses_own_branch.py
+tests/test_lane_enter_hook_warnings.py
 tests/test_lane_lease_show_json.py
 tests/test_lane_lifecycle_safety.py
 tests/test_lane_repo_paths_and_all_skipped.py
+tests/test_lane_show_name.py
 tests/test_lane_toml_serialization.py
 tests/test_launch_primitive.py
+tests/test_layout_census.py
 tests/test_m2_overlay_hindsight.py
 tests/test_m2_overlay_mem0.py
 tests/test_m2_overlay_zep.py
 tests/test_materialization_plan_contract.py
+tests/test_materialize_pin.py
+tests/test_member_working_root_checkout_materialize.py
 tests/test_merge_evidence.py
 tests/test_merge_parent_verification.py
 tests/test_migration.py
 tests/test_migration_overlay_compatibility.py
 tests/test_migration_unadopted_notice.py
+tests/test_native_store_review_record_probes.py
 tests/test_no_bare_python_cli_imports.py
 tests/test_null_current_lane_refusal.py
 tests/test_open_gr_enter.py
 tests/test_open_project_refusal_reason_cli.py
+tests/test_outbox_ack_after_effect.py
 tests/test_overlay_acceptance.py
 tests/test_overlay_activate.py
 tests/test_overlay_cli.py
@@ -168,8 +189,12 @@ tests/test_overlay_tier_b_staging_discipline.py
 tests/test_overlay_trust_model.py
 tests/test_overlay_workspace_spec.py
 tests/test_pr_events.py
+tests/test_pr_group_legibility.py
+tests/test_pr_merge_head_pin.py
 tests/test_pr_merge_method.py
+tests/test_pr_merge_missing_target.py
 tests/test_pr_merge_partial_failure.py
+tests/test_pr_view.py
 tests/test_project_file_materialization.py
 tests/test_project_review_range_reconstruction.py
 tests/test_project_review_three_repo.py
@@ -180,11 +205,13 @@ tests/test_propagation_state_machine.py
 tests/test_prune.py
 tests/test_push.py
 tests/test_readme_verbs_exist.py
+tests/test_repo_path_read_through.py
 tests/test_repo_status_linked_worktree.py
 tests/test_repo_status_schema_version.py
 tests/test_repo_status_symlinked_git_dir.py
 tests/test_review_bind_fork_base.py
 tests/test_review_bind_from_range.py
+tests/test_review_bind_native_store.py
 tests/test_review_bind_verify.py
 tests/test_review_cli.py
 tests/test_review_close_gr.py
@@ -193,8 +220,11 @@ tests/test_review_dispatch.py
 tests/test_review_ephemeral.py
 tests/test_review_open_lane.py
 tests/test_review_rebind.py
+tests/test_review_receipt_cleanup.py
 tests/test_review_run.py
 tests/test_review_run_import_isolation.py
+tests/test_review_run_integrity_recheck.py
+tests/test_review_run_multi_repo.py
 tests/test_review_run_rerun_and_refusal_receipt.py
 tests/test_review_runners.py
 tests/test_review_verify_inside.py
@@ -205,8 +235,21 @@ tests/test_spec_apply_event_outcomes.py
 tests/test_spec_declaration_ref_pin.py
 tests/test_sprint21_sync_platform.py
 tests/test_staging_cleanup.py
+tests/test_store_break_attempts.py
+tests/test_store_checkout_atomicity.py
+tests/test_store_commit_noop.py
+tests/test_store_declared_members.py
+tests/test_store_git_native_smoke.py
+tests/test_store_init_branch_inference.py
+tests/test_store_log_adoption_boundary.py
+tests/test_store_member_path_hygiene.py
+tests/test_store_member_state.py
+tests/test_store_migrate_branch_inference.py
+tests/test_store_status_values.py
 tests/test_store_verb_rename.py
+tests/test_store_verb_witnesses.py
 tests/test_submodule_member_predicate.py
+tests/test_superproject_import.py
 tests/test_sync_event_outcomes.py
 tests/test_sync_fast_forward.py
 tests/test_sync_fetch.py
@@ -221,6 +264,8 @@ tests/test_unit_apply_dry_run.py
 tests/test_unit_manifest_schema.py
 tests/test_unit_propose.py
 tests/test_unit_topological_apply.py
+tests/test_validate_repo_path_conflict.py
+tests/test_version_identity.py
 tests/test_version_static.py
 tests/test_workspace_convert_clone.py
 tests/test_workspace_edit_lease_cap.py

{gitgrip-2.0.0a4 → gitgrip-2.0.0a6}/gitgrip.egg-info/requires.txt

@@ -7,3 +7,4 @@ jsonschema>=4.18
 [dev]
 pytest>=8.0
 ruff>=0.4
+packaging>=22

gitgrip-2.0.0a6/gr2/api_core.py

@@ -0,0 +1,306 @@
+"""The generic core of the API dumper: walker, line format, marker lookup.
+
+THE SEAM. This module knows four things -- how to walk a command tree, how an
+``.api`` line is shaped, how a stability table is keyed, and how items are
+GROUPED into blocks -- and it knows nothing about gr2: not its app, not its
+tables, not its exit codes. Everything that names gr2 lives in the consumer
+(``gr2/scripts/dump_api.py``), which REGISTERS the kinds it emits, supplies the
+marker rules for them, and says which COMMAND each item belongs to (``Row.group``).
+Grouping is a core rule over a consumer-supplied fact, which is the same
+division as the marker table: the core owns the shape, the consumer owns the
+meaning.
+
+The boundary is a test, not a convention: ``tests/test_api_core_seam.py`` walks
+this module's imports at any depth and fails if any of them reaches gr2, with
+the plugin beside it as the control that proves the walker can fail.
+
+WHY IT IS WORTH THE SPLIT. The dumper does not move to its own repo yet -- but
+the regroup of the dump by command and subcommand is the moment to cut the
+seam, so that the later extraction is a MOVE rather than a rewrite. A core with
+no gr2 import can be lifted out with its tests; one that reaches into
+``grip_cli`` for an exit prefix cannot.
+
+WHAT IS NOT HERE YET, named rather than implied: the alias registry
+(``grip_cli.STORE_MOUNTS`` is gr2's own mount table) and the three gates are
+still on the plugin side, because both answer questions about gr2's surface
+rather than about the format. They move when a second consumer exists to make
+their generic shape decidable.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import NamedTuple
+
+
+class Row(NamedTuple):
+    """One item, before it is rendered.
+
+    ``group`` is the COMMAND PATH the item belongs to, and the CONSUMER supplies
+    it rather than the core deriving one. Only the consumer knows what a command
+    is in its own tree: the walk answers for a verb and the flags beneath it, but
+    an exit code belongs to a GROUP and a layout path belongs to no verb at all.
+    Deriving it here would mean the core guessing at the shape of a spelling.
+
+    An EMPTY group means "attached to no command" and renders under the
+    ``UNGROUPED`` heading. A heading is what separates one block from the next,
+    so the ungrouped block is given one rather than left as rows appended to
+    whichever command sorted before them.
+    """
+
+    kind: str
+    spelling: str
+    hidden: bool = False
+    hidden_by: str | None = None
+    group: str = ""
+
+# (kind, spelling) -> "may-change" | "reserved". An item absent here is stable.
+Markers = dict[tuple[str, str], str]
+
+# The spelling column is padded to this width so the stability markers line up
+# and a diff reads as a change to one item rather than to the whole block.
+COLUMN = 64
+
+# The heading an item renders under when its consumer gave it no command.
+#
+# NAMED RATHER THAN LEFT BLANK, because a heading is the only thing separating
+# one block from the next: an ungrouped row printed with NO heading lands
+# directly under the last command's items and reads as one of them. The blank
+# version looks tidier in the one case it helps -- a consumer that groups nothing
+# -- and misleads in the case that matters, which is a consumer that groups
+# almost everything and forgets one.
+UNGROUPED = "(ungrouped)"
+
+
+def walk(cmd, prefix: tuple[str, ...] = (), hidden_by: str | None = None):
+    """Every leaf command, as (path, command, hidden_by).
+
+    Hidden is INHERITED: a command is hidden when its own flag says so OR any
+    ancestor group is hidden. Typer marks a sub-app hidden at the GROUP level
+    (``add_typer(app, name="grip", hidden=True)``), and the group's children
+    keep ``hidden=False`` of their own -- so reading only the leaf reports a
+    hidden group's whole subtree as part of the visible surface. Measured: the
+    ``grip`` alias group is hidden and 28 of its items were dumped as visible.
+
+    ``hidden_by`` NAMES the ancestor group that did the hiding, because the dump
+    carries no group row of its own: without the name, one group flag reads as
+    dozens of identical lines and the cause is invisible to a reader.
+    """
+    subs = getattr(cmd, "commands", None)
+    if subs:
+        if getattr(cmd, "hidden", False) and prefix:
+            hidden_by = prefix[-1]
+        out: list[tuple[tuple[str, ...], object, str | None]] = []
+        for name, sub in subs.items():
+            out.extend(walk(sub, prefix + (name,), hidden_by))
+        return out
+    return [(prefix, cmd, hidden_by)]
+
+
+def label(spelling: str, hidden: bool, hidden_by: str | None) -> str:
+    """The label column for one item -- the text BEFORE any parsing strips it.
+
+    One home for the rule, because a gate that wants to ask a question about the
+    label TEXT (does it end in a space? how long is it?) cannot use the parsed
+    rows: a parser strips the padding, and the trailing space it would be asking
+    about is exactly what stripping removes. Measured -- a first version of
+    ``test_no_label_ends_in_a_space`` read labels through a parser and could not
+    have failed for any input, because every label it saw had already been
+    stripped.
+
+    An inherited hide names the group that did it; a command hidden in its own
+    right is just ``(hidden)``. The dump carries no group row, so the name is the
+    only place the cause can live.
+    """
+    if not hidden:
+        return spelling
+    return f"{spelling} (hidden:{hidden_by})" if hidden_by else f"{spelling} (hidden)"
+
+
+def line(kind: str, label: str, marker: str) -> str:
+    """One ``.api`` line: two fixed columns, with the separator GUARANTEED.
+
+    A label at or past ``COLUMN`` is emitted at its own length, so padding it to
+    ``COLUMN`` adds nothing and the marker runs straight into the label. Every
+    label in this dump contains spaces (a flag reads ``verb --flag <str>``), so a
+    reader splitting the two columns then takes a space INSIDE the label as the
+    separator and recovers neither column.
+
+    Measured before this rule existed: the 65-char ``exit`` label rendered as
+    ``...store verb: "may-change``, whose last space is the one inside the quoted
+    prefix. The columns came back as the label truncated at ``verb:`` and a
+    marker of ``"may-change``, the marker lookup then missed, and every exit line
+    silently read as ``stable``.
+
+    Pulled out of ``render`` so the width rule has ONE home and a synthetic long
+    label can be tested against it directly, rather than only through whichever
+    labels happen to reach ``COLUMN`` today.
+
+    ONE SHAPE THIS CANNOT FIX, because the ambiguity is on the reader's side of
+    the line: a label whose LAST character is a space is indistinguishable from
+    the padding, so a reader stripping the padding returns it one character
+    short. Guaranteeing the separator does not help -- the space is inside the
+    label, before it. No label ends in a space today, and
+    ``test_no_label_ends_in_a_space`` keeps it that way.
+    """
+    width = max(COLUMN, len(label) + 1)
+    return f"{kind:<6}{label:<{width}}{marker}"
+
+
+def load_markers(path: Path) -> Markers:
+    """(kind, spelling) -> 'may-change' | 'reserved', from a stability table.
+
+    An absent file is an empty table rather than an error: a checkout with no
+    stability table has made no promises, and every item reading ``stable``
+    there is the stated default. The entries are ``"<kind> <spelling>"``, split
+    on the FIRST space, because a spelling carries spaces of its own.
+    """
+    if not path.exists():
+        return {}
+    data = tomllib.loads(path.read_text())
+    out: Markers = {}
+    for marker in ("may-change", "reserved"):
+        for entry in data.get(marker, []):
+            kind, _, spelling = entry.partition(" ")
+            out[(kind, spelling)] = marker
+    return out
+
+
+def plain_marker(kind: str) -> Callable[[str, Markers], str]:
+    """The default marker rule for a kind: plain lookup, stable unless named.
+
+    Defaulting to stable is deliberate -- a new item is stable unless somebody
+    says otherwise in review -- and it is the rule most kinds want, so a
+    consumer registering one writes ``plain_marker("exit")`` rather than a
+    four-line closure that has to be read to be trusted.
+    """
+
+    def resolve(spelling: str, markers: Markers) -> str:
+        return markers.get((kind, spelling), "stable")
+
+    return resolve
+
+
+@dataclass(frozen=True)
+class Kind:
+    """One item kind, as the consumer registers it.
+
+    ``items`` yields ``Row``s; ``marker`` answers for this kind alone, which is
+    the point of registering per kind -- the lookup rule for a ``json`` key path
+    (inherit the canonical verb's promise) is not the rule for an ``exit`` code
+    (plain lookup) and a single dispatching function had to know both.
+    """
+
+    name: str
+    items: Callable[[], list[Row]]
+    marker: Callable[[str, Markers], str]
+
+
+class Registry:
+    """The kinds this dump carries, in the order the consumer registered them."""
+
+    def __init__(self) -> None:
+        self._kinds: list[Kind] = []
+
+    def register(
+        self,
+        name: str,
+        items: Callable[[], list[Row]],
+        marker: Callable[[str, Markers], str],
+    ) -> Kind:
+        if any(kind.name == name for kind in self._kinds):
+            raise ValueError(f"kind {name!r} is already registered")
+        kind = Kind(name=name, items=items, marker=marker)
+        self._kinds.append(kind)
+        return kind
+
+    @property
+    def names(self) -> tuple[str, ...]:
+        return tuple(kind.name for kind in self._kinds)
+
+    def rows(self) -> list[Row]:
+        out: list[Row] = []
+        for kind in self._kinds:
+            out.extend(kind.items())
+        return out
+
+    def marker(self, kind: str, spelling: str, markers: Markers) -> str:
+        """The marker for one item, from the kind that owns it.
+
+        An UNREGISTERED kind is refused rather than defaulted. Answering
+        ``stable`` for a kind nobody registered would publish a promise no one
+        made, and it would do it silently -- the failure would look exactly like
+        an item the reviewers simply never named.
+        """
+        for registered in self._kinds:
+            if registered.name == kind:
+                return registered.marker(spelling, markers)
+        raise KeyError(
+            f"no kind {kind!r} is registered; registered: {list(self.names)}"
+        )
+
+
+def blocks(rows: list[Row]) -> list[tuple[str, list[Row]]]:
+    """Rows grouped by command path, the groups in COMMAND-TREE order.
+
+    The ORDER is by path, which is what makes the file read as a tree: ``store``
+    before ``store init``, and both before ``store-x``, so a command's
+    subcommands sit with it rather than scattered by an unrelated key.
+
+    THE KEY IS WRITTEN ON THE PATH'S TOKENS, AND ON THIS DUMP THAT CHANGES
+    NOTHING -- measured, not assumed: the separator is a space (0x20), every
+    character a path component can begin with sorts above it, and token order and
+    joined-string order agree on all 88 real headings. It is written on tokens
+    because the RULE is what a reader auditing the order should find stated, and
+    citing a separator's incidental collation order as the reason is how a rule
+    becomes an accident nobody can check.
+
+    The UNGROUPED block sorts LAST, and THAT is the part the key actually earns:
+    it keys on the ABSENCE of tokens rather than on the empty string, which would
+    sort it first and open the file with the items that have no home.
+    """
+    by_group: dict[str, list[Row]] = {}
+    for row in rows:
+        by_group.setdefault(row.group, []).append(row)
+    return sorted(
+        by_group.items(), key=lambda item: (not item[0].split(), item[0].split())
+    )
+
+
+def render(registry: Registry, markers: Markers | None = None) -> str:
+    """The exact bytes of an ``.api`` file, terminated by one newline.
+
+    GROUPED BY COMMAND, not by kind. The first column is still the item kind and
+    each line still carries one item, but the ORDER is now the command tree: a
+    heading names a command and its items sit under it. The previous order was a
+    single flat lexicographic sort, so all 120 ``arg`` rows preceded all 215
+    ``flag`` rows and no command's surface could be read in one place -- "what
+    does ``store init`` take" was four searches, one per kind.
+
+    WITHIN a block the rows are sorted by their rendered line, which is the old
+    (kind, then label) order: a diff then reads one command at a time, and an
+    item that moves shows up moving between two blocks rather than teleporting
+    to a different corner of the file.
+
+    The heading is a COMMENT (``# <command>``) rather than a row, so a reader
+    that parses item lines has one unambiguous shape to parse and the heading
+    cannot be mistaken for a kind. EVERY block gets one, the ungrouped block
+    included (``# (ungrouped)``): a heading is what separates one block from the
+    next, so the block without one is the block that gets misread.
+    """
+    markers = {} if markers is None else markers
+    lines: list[str] = []
+    for group, rows in blocks(registry.rows()):
+        lines.append(f"# {group or UNGROUPED}")
+        lines += sorted(
+            line(
+                row.kind,
+                label(row.spelling, row.hidden, row.hidden_by),
+                registry.marker(row.kind, row.spelling, markers),
+            )
+            for row in rows
+        )
+    return "\n".join(lines) + "\n"