@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.12 → 0.1.28

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/directory_ratchet/check.py

@@ -1,4 +1,4 @@
-"""LAY-004 — every registered tree's committed directory-shape ratchet.
+"""LAY-004 — every configured tree's committed directory-shape ratchet.
 
 Two rules over one measurement — a directory's DIRECT FILE COUNT — plus the
 third rule that makes this check unlike any other ported so far:
@@ -20,39 +20,64 @@ its own has zero children; each subdirectory is counted separately by the same
 rule. Nothing here walks: every count is taken from the set the runner handed
 over, narrowed to one tree at a time.
 
-The register is package data, shipped beside this file as a `resources` entry
-(`grants.yaml`, resolved through `importlib.resources` like every other packaged
-input) — not a consumer path spelled through the row's `grants:` field. It is
-not a catalogue of signed exceptions either way, and `structural_grant` is what
-says so: see `Check.structural_grant` for why passing its size as an allowance
-turns a failing gate green.
+THE CEILINGS ARE CONFIG, NOT REGISTER CONTENT — the estate's generic ratchet
+principle (owner ruling 2026-10-02, Tarun: "Move ALL configurations to
+adl-config.toml"), superseding this gate's own earlier "ratchets sit ON TOP"
+ruling the same day (the same supersession DOC-012 v2 shipped, and the two
+gates must read as one family):
+
+  1. The RULE — each tree's direct-file ceiling — is CONFIGURATION and lives
+     in `[controls.compliance.directory-ratchet].max_children`, reaching the
+     engine as the `directory-ceilings` declaration
+     (`<path>:<n>,<path>:<n>`). `_ceilings` resolves it the way DOC-012's
+     `page_cap` resolves its limit: each entry must be a repo-relative path
+     and a base-10 positive integer; any malformed entry is could-not-run
+     naming the config key and the entry. NO ceilings declared means nothing
+     to enforce — the gate is inert and the register is not even read.
+  2. The register records STATE only — the consumer-owned
+     `<compliance>/ratchets/LAY-004-over-limit-directory.yaml` (the estate's
+     settled location for a consumer-owned ratchet number), holding
+     over-limit and single-file exemption baselines and nothing else. It
+     shipped once as a `resources` entry, one donor repository's entire
+     directory shape graded against every other repository (the K-42 defect,
+     recorded on `inputs` below); the `test_the_register_is_not_packaged_data`
+     regression test guards that return. `structural_grant` is what says it
+     is not an exception catalogue: see `Check.structural_grant` for why
+     passing its size as an allowance turns a failing gate green.
+  3. At zero recorded state the file is DELETED — and the gate still runs,
+     enforcing the configured ceilings bare. "No ratchet file" means zero
+     exemptions allowed, never a toothless gate: an ABSENT register grades
+     STRICTER (the widening input's normal contract), a register that EXISTS
+     but is unusable is could-not-run, and a file recording zero state is a
+     load failure (the shared model's cross-field validator). A tree the
+     configuration names but the repository deleted is cleanup, not a defect:
+     one advisory says its baseline entries are no longer accounted, and the
+     remaining trees are graded normally. DIR-003 still fires for a baseline
+     entry under a LIVE tree whose directory was deleted, because the
+     register's own hygiene is the owner's edit and the gate still says so.
+
+The register model lives in `.register` (same folder), shared with DOC-012,
+which mints DIR-004/005/006 over the same file's `docs_pages.baseline` — one
+family of rule ids over one file of state, graded by two gates. What changed
+for LAY-004 in the 2026-10-02 generic-principle rework is only WHERE the
+ceilings live; DIR-001/002/003, the message phrasing, and the measurement
+discipline are untouched, so a repository's recorded state keeps meaning
+exactly what it meant. `DirectoryShape` below stays here — it is this gate's
+measurement, not the register's.
 """
 
 from __future__ import annotations
 
+import re
 from collections.abc import Iterable
-from typing import Annotated, ClassVar, Literal
-
-from pydantic import Field
+from typing import ClassVar
 
 from ....core.check import Check
 from ....core.context import Context, FileSet
 from ....core.errors import CouldNotRun, SchemaInvalid
 from ....core.finding import Report
 from ....core.models import StrictModel
-
-
-class Ratchet(StrictModel):
-    """The register. `max_children` is the list of trees this gate holds at
-    all, so an empty one is a gate grading nothing — a load failure, not a pass."""
-
-    schema_version: Literal[2]
-    """Locked, not just typed: a future bump must change this literal, which
-    makes it a deliberate, schema-revealing edit rather than a silent one."""
-
-    max_children: Annotated[dict[str, int], Field(min_length=1)]
-    over_children_baseline: dict[str, int] = {}
-    single_file_baseline: dict[str, str] = {}
+from .register import Ratchet
 
 
 class DirectoryShape(StrictModel):
@@ -67,6 +92,16 @@ class DirectoryRatchet(Check):
     id: ClassVar[str] = "LAY-004"
     structural_grant: ClassVar[bool] = True
 
+    CEILINGS_DECLARATION: ClassVar[str] = "directory-ceilings"
+
+    CEILING: ClassVar[re.Pattern[str]] = re.compile(r"([\w.-]+(?:/[\w.-]+)*):([0-9]+)")
+    """One ceiling entry: a repo-relative path of word characters, dashes,
+    dots and slashes (no comma — the list separator; no colon — the entry
+    separator; no leading slash — paths are repository-relative), a colon,
+    and a base-10 positive integer. ASCII digits only, so `+20`, `1_0`,
+    ` 20` and full-width digits are refused, which `int()` alone would
+    accept."""
+
     # CONSUMER-OWNED, not package data. This shipped as a `resources` entry
     # (`grants.yaml`) holding one donor repository's entire directory shape:
     # 88 of its 104 lines named `<rust>/crates/enact-*`,
@@ -83,43 +118,124 @@ class DirectoryRatchet(Check):
         "register": "<compliance>/ratchets/LAY-004-over-limit-directory.yaml",
     }
 
+    # The runner's OPTIONAL-INPUT channel, in its NORMAL direction — the
+    # 2026-10-02 "ratchets sit ON TOP" exception this comment used to carry
+    # (an absent register removes every ceiling and baseline, so the gate
+    # passes clean) is SUPERSEDED for this gate by the generic ratchet
+    # principle: the ceilings are CONFIGURATION (adl-config.toml), and the
+    # register is recorded STATE, so an absent register removes the
+    # EXEMPTIONS and the gate grades STRICTER — `core.check`'s documented
+    # widening contract, exactly as on DOC-012. The channel is still the
+    # right mechanism: a repository that declares no `compliance` tree (or
+    # declares it "") must not be pressured into inventing one just to host
+    # a file it does not need — and the `structural_grant` docstring's
+    # "a gate grading nothing" failure mode no longer applies to absence,
+    # only to a file that exists recording zero state. Read with `.get()`,
+    # never assumed present.
+    widening_inputs: ClassVar[frozenset[str]] = frozenset({"register"})
+
     OVER: ClassVar[str] = "DIR-001"
     GREW: ClassVar[str] = "DIR-002"
     STALE: ClassVar[str] = "DIR-003"
 
     def graded(self, ctx: Context, files: FileSet) -> Iterable[Report]:
+        ceilings = self._ceilings(ctx)
+        if not ceilings:
+            # Nothing configured is nothing to enforce: the gate is inert,
+            # and the register is not read (its entries could only ever
+            # REMOVE findings).
+            return
+
         ratchet = self._register(ctx)
+        over_children: dict[str, int] = {}
+        single_file: dict[str, str] = {}
+        if ratchet is not None:
+            over_children = ratchet.over_children_baseline
+            single_file = ratchet.single_file_baseline
+
+        for tree, ceiling in sorted(ceilings.items()):
+            # Each tree sees only its OWN entries. The register holds every
+            # tree's state in one namespace, and a tree's measurement can
+            # never contain another tree's path — so without this filter
+            # every other tree's entries would report DIR-003 on every run.
+            over = self._entries_under(over_children, tree)
+            single = self._entries_under(single_file, tree)
 
-        for tree, ceiling in sorted(ratchet.max_children.items()):
             if not ctx.path(tree).is_dir():
-                raise CouldNotRun(f"registered tree directory is missing: {tree}")
+                # Generic principle: a tree the CONFIGURATION names but the
+                # repository no longer has is cleanup, not a defect. One
+                # advisory names what is unaccounted; the remaining trees
+                # are graded normally.
+                unaccounted = len(over) + len(single)
+                noun = "entry" if unaccounted == 1 else "entries"
+                yield self.advise(
+                    tree,
+                    f"tree {tree} with a configured ceiling ({ceiling} direct "
+                    f"children) is absent from this repository; its "
+                    f"{unaccounted} baseline {noun} are no longer "
+                    "accounted — remove its register entries or restore the tree",
+                )
+                continue
 
             measured = self._measure(ctx, files, tree)
-            # Each tree sees only its OWN entries. The register holds every
-            # tree's exceptions in one namespace, and a tree's measurement can
-            # never contain another tree's path — so without this filter every
-            # other tree's entries would report DIR-003 on every run.
-            over = self._entries_under(ratchet.over_children_baseline, tree)
-            single = self._entries_under(ratchet.single_file_baseline, tree)
-
             yield from self._graded_over(measured, over, ceiling)
             yield from self._graded_single(measured, single)
 
+    # ------------------------------------------------------------ the ceilings
+
+    def _ceilings(self, ctx: Context) -> dict[str, int]:
+        """The per-tree ceilings in force, from the `directory-ceilings`
+        declaration (`[controls.compliance.directory-ratchet].max_children`).
+
+        Absent is `{}`: no table declared, nothing to enforce — the gate is
+        inert and the register is not read. Each entry must be
+        `<path>:<positive int>` with ASCII digits (paths carry slashes,
+        letters, dashes, underscores and dots — never a comma or a colon,
+        which are the list and entry separators); ANY malformed entry is
+        could-not-run naming the config key and the offending entry, never a
+        quiet skip — a ceiling the repository cannot state is not a ceiling
+        it meant. No down-only enforcement: a repository may declare any
+        ceilings it chooses, the same as DOC-012's cap.
+        """
+        declared = ctx.declarations.get(self.CEILINGS_DECLARATION)
+        if declared is None:
+            return {}
+        ceilings: dict[str, int] = {}
+        for entry in declared.split(","):
+            match = self.CEILING.fullmatch(entry)
+            if match is None or int(match.group(2)) < 1:
+                raise CouldNotRun(
+                    f"declaration {self.CEILINGS_DECLARATION} entry {entry!r} is not "
+                    "<path>:<count> with a base-10 positive integer; set "
+                    "[controls.compliance.directory-ratchet].max_children to a "
+                    "table of repo-relative paths and whole numbers of at least 1"
+                )
+            ceilings[match.group(1)] = int(match.group(2))
+        return ceilings
+
     # ------------------------------------------------------------ the register
 
-    def _register(self, ctx: Context) -> Ratchet:
-        """The repository's own baseline — see `inputs` above."""
-        if not ctx.inputs["register"].is_file():
-            shown = ctx.relative(ctx.inputs["register"])
-            raise CouldNotRun(
-                f"no directory-ratchet register at {shown}; a ratchet grades a "
-                "repository against ITS OWN recorded shape, so there is nothing "
-                "to grade until this repository records one (or points "
-                "[controls.compliance.inputs].register at where it keeps it). "
-                "An absent baseline is could-not-run, never a clean pass"
-            )
+    def _register(self, ctx: Context) -> Ratchet | None:
+        """The repository's own recorded state — see `inputs`/`widening_inputs`.
+
+        Absent is None: no file, or the input dropped because the `compliance`
+        tree is undeclared or declared absent. Generic principle: absence
+        removes the EXEMPTIONS, not the rule — `graded` reads None as empty
+        baseline dicts and enforces the configured ceilings bare. A register
+        that EXISTS but cannot be used (invalid YAML, schema violation) is
+        could-not-run: it may be mid-edit, and grading it as "no baselines"
+        would silently drop every exemption it names. `exists()` follows
+        symlinks, so a broken symlink at the register path reads as absent —
+        no exemptions.
+        """
+        target = ctx.inputs.get("register")
+        if target is None or not target.exists():
+            return None
+        if not target.is_file():
+            shown = ctx.relative(target)
+            raise CouldNotRun(f"directory-ratchet register {shown} exists but is not a file")
         try:
-            return self.parse_yaml(ctx, ctx.inputs["register"], Ratchet)
+            return self.parse_yaml(ctx, target, Ratchet)
         except SchemaInvalid as exc:
             raise CouldNotRun(f"ratchet register is unusable: {exc.detail}") from exc
 

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/directory_ratchet/fixtures/directory-ratchet-clean/grants.yaml

@@ -1,6 +1,4 @@
 schema_version: 2
-max_children:
-  frontend/packages/desktop/src: 10
 over_children_baseline: {}
 single_file_baseline:
   frontend/packages/desktop/src/renderer/solo: item.ts

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/directory_ratchet/fixtures/directory-ratchet-empty-register/frontend/packages/desktop/src/a.ts

@@ -0,0 +1 @@
+a

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/directory_ratchet/fixtures/directory-ratchet-empty-register/frontend/packages/desktop/src/b.ts

@@ -0,0 +1 @@
+b

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/directory_ratchet/fixtures/directory-ratchet-empty-register/grants.yaml

@@ -0,0 +1,3 @@
+schema_version: 2
+over_children_baseline: {}
+single_file_baseline: {}

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/directory_ratchet/fixtures/directory-ratchet-excluded/grants.yaml

@@ -1,6 +1,4 @@
 schema_version: 2
-max_children:
-  frontend/packages/desktop/src: 20
 over_children_baseline: {}
 single_file_baseline:
   frontend/packages/desktop/src/renderer/solo: item.ts

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/directory_ratchet/fixtures/directory-ratchet-missing-tree/frontend/packages/desktop/src/renderer/solo/item.ts

@@ -0,0 +1 @@
+export const item = 1;

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/directory_ratchet/fixtures/directory-ratchet-missing-tree/grants.yaml

@@ -0,0 +1,5 @@
+schema_version: 2
+over_children_baseline:
+  infra/stacks: 5
+single_file_baseline:
+  frontend/packages/desktop/src/renderer/solo: item.ts

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/directory_ratchet/fixtures/directory-ratchet-no-ceilings/frontend/packages/desktop/src/a.ts

@@ -0,0 +1 @@
+a

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/directory_ratchet/fixtures/directory-ratchet-no-ceilings/frontend/packages/desktop/src/b.ts

@@ -0,0 +1 @@
+b

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/directory_ratchet/fixtures/directory-ratchet-no-ceilings/frontend/packages/desktop/src/c.ts

@@ -0,0 +1 @@
+c

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/directory_ratchet/fixtures/directory-ratchet-no-ceilings/grants.yaml

@@ -0,0 +1,4 @@
+schema_version: 2
+over_children_baseline:
+  frontend/packages/desktop/src: 3
+single_file_baseline: {}

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/directory_ratchet/fixtures/directory-ratchet-stale-entry/frontend/packages/desktop/src/renderer/solo/item.ts

@@ -0,0 +1 @@
+export const item = 1;

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/directory_ratchet/fixtures/directory-ratchet-stale-entry/grants.yaml

@@ -0,0 +1,5 @@
+schema_version: 2
+over_children_baseline:
+  frontend/packages/desktop/src/renderer/gone: 4
+single_file_baseline:
+  frontend/packages/desktop/src/renderer/solo: item.ts

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/directory_ratchet/fixtures/directory-ratchet-unbaselined/grants.yaml

@@ -1,6 +1,4 @@
 schema_version: 2
-max_children:
-  frontend/packages/desktop/src: 10
 over_children_baseline: {}
 single_file_baseline:
   frontend/packages/desktop/src/renderer/solo: item.ts

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/directory_ratchet/fixtures/directory-ratchet-unusable-register/frontend/packages/desktop/src/renderer/solo/item.ts

@@ -0,0 +1 @@
+export const item = 1;

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/directory_ratchet/fixtures/directory-ratchet-unusable-register/grants.yaml

@@ -0,0 +1,3 @@
+schema_version: 2
+max_children:
+  frontend: [unclosed

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/directory_ratchet/register.py

@@ -0,0 +1,127 @@
+"""The LAY-004/DOC-012 directory-ratchet register — ONE file of STATE, TWO gates.
+
+Moved out of `directory_ratchet/check.py` on 2026-10-02, when DOC-012 started
+reading the same consumer-owned file; reworked hours later to the estate's
+generic ratchet principle (Tarun, 2026-10-02, superseding this file's earlier
+"ratchets sit ON TOP" reading for LAY-004 — the same supersession DOC-012 v2
+shipped):
+
+  1. A ratchet file records STATE only — today's known violations, the
+     per-directory exemptions both gates forgive.
+  2. The RULE is CONFIGURATION and lives in adl-config.toml: LAY-004's
+     per-tree ceilings in `[controls.compliance.directory-ratchet].
+     max_children` (arriving as the `directory-ceilings` declaration),
+     DOC-012's page cap in `[controls.compliance.limits].
+     docs_pages_per_directory`.
+  3. At zero recorded state the file is DELETED — and the gates still run,
+     enforcing the configured rules bare. "No ratchet file" means zero
+     exemptions allowed, never a toothless gate; a file that EXISTS
+     recording zero state is a load failure, fail-loud.
+
+This module holds the register's MODEL, not a check — the layer rule "no
+check imports another" reaches check modules, and `docs/directory_size/
+check.py` imports THIS module, never LAY-004's.
+
+The consumer's document (`<compliance>/ratchets/LAY-004-over-limit-directory.yaml`)
+carries whichever sections have state:
+
+    schema_version: 2
+    over_children_baseline:   # LAY-004's over-limit exemptions:
+      frontend/src: 12        # directory -> its recorded direct-file count
+    single_file_baseline:     # LAY-004's single-file exemptions:
+      frontend/src/solo: item.ts
+    docs_pages:               # DOC-012's exemptions (baseline only; the cap
+      baseline:               # is config, never register content)
+        docs/operations: 18
+
+`max_children` is GONE from the model — it was configuration, and
+configuration moved to adl-config.toml the same day; `extra="forbid"`
+refuses the key, so a stale register fails loud instead of being silently
+read as state. The cross-field validator holds the ruling's third arm: at
+least one of `over_children_baseline` / `single_file_baseline` /
+`docs_pages.baseline` must be non-empty — zero recorded state is no file.
+
+`schema_version` stays the locked `Literal[2]`: a future bump must edit this
+literal, which makes it a deliberate, schema-revealing edit rather than a
+silent one. The removal of `max_children` did not earn a bump — no consumer
+ever shipped ceilings in the file (adl-azdo never recorded tree state; the
+one v1 file lasted hours), and a field's departure under a locked literal is
+a load failure for stale files, which is the point.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import model_validator
+
+from ....core.models import StrictModel
+
+
+class DocsPages(StrictModel):
+    """DOC-012's section: per-directory EXEMPTION baselines, nothing else.
+
+    `baseline` maps a docs/ directory to the page count it is exempted up to
+    — the count it held when recorded. DIR-004 fires over the cap with no
+    entry, DIR-005 past the recorded entry, DIR-006 for an entry no longer
+    required. The CAP itself is not here: it is the
+    `docs-pages-per-directory` declaration (`[controls.compliance.limits].
+    docs_pages_per_directory`, engine default 15), because the cap is
+    CONFIGURATION and the register is the repository's recorded state.
+    """
+
+    baseline: dict[str, int] = {}
+
+
+class Ratchet(StrictModel):
+    """The register: recorded state, graded by LAY-004 and DOC-012.
+
+    An all-empty register is a load failure, not a pass — zero recorded
+    state is no file (the cross-field validator below holds the ruling's
+    third arm; a file that exists recording nothing is the wrong file or an
+    emptied one mid-cleanup, and reading it as "no exemptions" would silently
+    drop every baseline it used to name).
+    """
+
+    schema_version: Literal[2]
+    """Locked, not just typed: a future bump must change this literal, which
+    makes it a deliberate, schema-revealing edit rather than a silent one."""
+
+    over_children_baseline: dict[str, int] = {}
+    """LAY-004's over-limit exemptions: directory -> the direct-file count it
+    is forgiven up to. Was graded AGAINST the ceilings that lived in this
+    file's deleted `max_children`; it is state, and it stays."""
+
+    single_file_baseline: dict[str, str] = {}
+    """LAY-004's single-file exemptions: directory -> the name of its one
+    file. Meaningful only while the directory holds exactly one file."""
+
+    docs_pages: DocsPages | None = None
+    """DOC-012's exemption baselines. None means no docs exemptions are
+    recorded; the page cap is enforced bare over what the section would have
+    forgiven. At zero exemptions the file is deleted."""
+
+    @model_validator(mode="after")
+    def _grades_something(self) -> Ratchet:
+        """At least one of over/single/docs_pages.baseline must be non-empty.
+
+        Zero recorded state is no file — "if we reach zero the ratchet file
+        has no meaning and should be deleted. We cleaned up the house!" An
+        existing file that records nothing is either the wrong file or an
+        emptied register mid-cleanup, and reading it as "no exemptions"
+        would silently drop every baseline the gates used to forgive. The
+        v1 `max_children: Field(min_length=1)` intent — "a gate grading
+        nothing is a load failure, not a pass" — survives every rework of
+        WHAT the file records.
+        """
+        if (
+            not self.over_children_baseline
+            and not self.single_file_baseline
+            and (self.docs_pages is None or not self.docs_pages.baseline)
+        ):
+            raise ValueError(
+                "a register grading nothing: record over_children_baseline, "
+                "single_file_baseline or docs_pages.baseline entries, or "
+                "delete the file (zero recorded state is no ratchet)"
+            )
+        return self