adopt-detect 0.3.0__py3-none-any.whl

adopt_detect/__init__.py

@@ -0,0 +1,67 @@
+"""Archetype detection, tier negotiation, the observability boundary.
+
+Implementation spec §4.11, PRD F10, sprint S6.
+
+Four invariants hold across this package and each is a refusal rather than a
+preference:
+
+1. **No model call on the deterministic path.** `04` §4 runs the walk to
+   completion; below `DETECT_CONFIDENCE_MIN` the answer is *ambiguous with
+   ranked scores*, never a guess. There is no call site for a model here.
+2. **No code execution in the target tree.** Files are read, at most
+   `DETECT_MAX_SNIFF_BYTES` each, and matched against literal substrings.
+3. **No network.** Detection is pure filesystem, and
+   `tests/property/test_offline.py` measures that rather than asserting it.
+4. **Archetype values are exactly `web|platform|lowcode|data|ai`**, read from
+   the generated enum rather than retyped.
+
+The tier ladder is **CR-38**, ratified 2026-08-05: three qualification questions
+to `T0`-`T4`, with `T0` a decline recommendation and `T3` the floor the `ai`
+archetype requires.
+"""
+
+from adopt_detect.boundary import (
+    DEFAULT_OUTBOUND_CATEGORIES,
+    METADATA_ONLY,
+    BoundaryView,
+    declare_boundary,
+)
+from adopt_detect.detect import DetectionResult, RuleHit, detect
+from adopt_detect.negotiate import (
+    AI_MINIMUM_TIER,
+    QUESTIONS,
+    Answers,
+    TierDecision,
+    negotiate,
+    parse_answers,
+    unavailable_capabilities,
+    violates_archetype_floor,
+)
+from adopt_detect.records import BoundaryRecords
+from adopt_detect.render import render_json, render_markdown
+from adopt_detect.rules import ARCHETYPES, ArchetypeRules, Rule, load_rule_sets
+
+__all__ = [
+    "AI_MINIMUM_TIER",
+    "ARCHETYPES",
+    "DEFAULT_OUTBOUND_CATEGORIES",
+    "METADATA_ONLY",
+    "QUESTIONS",
+    "Answers",
+    "ArchetypeRules",
+    "BoundaryRecords",
+    "BoundaryView",
+    "DetectionResult",
+    "Rule",
+    "RuleHit",
+    "TierDecision",
+    "declare_boundary",
+    "detect",
+    "load_rule_sets",
+    "negotiate",
+    "parse_answers",
+    "render_json",
+    "render_markdown",
+    "unavailable_capabilities",
+    "violates_archetype_floor",
+]

adopt_detect/boundary.py

@@ -0,0 +1,196 @@
+"""The observability boundary: one row, two renderings, one authority.
+
+PRD F10.5-F10.8 and contracts §3. The boundary is the object that **hard-limits
+every downstream claim**: what may be observed, where knowledge lives, and what
+may leave. Three things about it are load-bearing.
+
+**`BoundaryView` is the accessor every downstream item calls** (`05` S6). It is a
+read-only projection of one stored row, and it is the type contracts §8 names in
+`validate_envelope(env, boundary: BoundaryView)`. Its one home is here, so that
+"what may leave" has one answer rather than one per caller.
+
+**The boundary is the authority, never the caller's declaration** (contracts §8
+rule 3, PRD F12.5). `permitted_outbound_categories` lives on the row precisely so
+that widening it is a write to a client-signed artefact rather than a
+configuration change -- and `contractual_approval_ref` is what records the
+amendment that permitted it.
+
+**Both rendered artifacts come from one row** (F10.8). `render.py` takes a
+`BoundaryView` and nothing else; there is no path by which the human-readable
+statement could say something the machine-readable one does not. Two renderers
+reading two sources is how a client is shown a document that the system does not
+enforce.
+"""
+
+import datetime as _dt
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Final
+
+from adopt_detect.negotiate import TierDecision, violates_archetype_floor
+from adopt_detect.records import BoundaryRecords
+from adopt_model import ObservabilityBoundary
+from adopt_model._enums import Archetype, ControlPlane, KnowledgePlane, Tier
+from adopt_scope import Scope
+
+__all__ = [
+    "DEFAULT_OUTBOUND_CATEGORIES",
+    "METADATA_ONLY",
+    "BoundaryView",
+    "declare_boundary",
+]
+
+#: Contracts §8 rule 1 and the `observability_boundary` column default. The one
+#: policy that needs no contract amendment, and the value everything falls back
+#: to when nothing else was agreed.
+METADATA_ONLY: Final[str] = "metadata_only"
+
+#: PRD F10.5. The default is a *list* because the column is a JSON list, and it
+#: is a one-element list rather than an empty one because an empty permitted set
+#: would make every outbound envelope invalid -- including the metadata-only ones
+#: the product is built to send.
+DEFAULT_OUTBOUND_CATEGORIES: Final[tuple[str, ...]] = (METADATA_ONLY,)
+
+#: Local-first is the default posture: client knowledge stays with the customer
+#: and only routing lives with the vendor. Both are overridable per engagement,
+#: and both are recorded on the row rather than inferred at read time.
+DEFAULT_KNOWLEDGE_PLANE: Final[KnowledgePlane] = "customer"
+DEFAULT_CONTROL_PLANE: Final[ControlPlane] = "vendor"
+
+
+@dataclass(frozen=True, slots=True)
+class BoundaryView:
+    """A read-only projection of one `observability_boundary` row.
+
+    Contracts §8's `validate_envelope` second parameter. Frozen, because a
+    validator that could widen the boundary it is validating against is not a
+    validator.
+    """
+
+    boundary_id: str
+    system_id: str
+    environment_id: str | None
+    tier: Tier
+    archetype: Archetype | None
+    knowledge_plane_location: KnowledgePlane
+    control_plane_location: ControlPlane
+    permitted_outbound_categories: tuple[str, ...]
+    unavailable_capabilities: tuple[str, ...]
+    contractual_approval_ref: str | None
+    declared_at: _dt.datetime
+    decline_recommended: bool
+    archetype_floor_violated: bool
+    last_successful_observation_at: _dt.datetime | None = None
+    safe_probe_status: str | None = None
+
+    def permits(self, content_policy: str) -> bool:
+        """Whether this boundary permits a policy. **The authority.**"""
+        return content_policy in self.permitted_outbound_categories
+
+    @classmethod
+    def of(
+        cls,
+        row: ObservabilityBoundary,
+        *,
+        archetype: Archetype | None,
+        unavailable_capabilities: Sequence[str] = (),
+        decline_recommended: bool = False,
+        archetype_floor_violated: bool = False,
+    ) -> "BoundaryView":
+        """Project a stored row.
+
+        `archetype` is carried alongside rather than read from the row because
+        `observability_boundary` has no archetype column -- it is `system`'s, and
+        contracts §3 puts it there. Passing it explicitly keeps the view honest
+        about where each field came from instead of implying a column that does
+        not exist.
+        """
+        categories = row.permitted_outbound_categories
+        return cls(
+            boundary_id=row.id,
+            system_id=row.system_id,
+            environment_id=row.environment_id,
+            tier=row.tier,
+            archetype=archetype,
+            knowledge_plane_location=row.knowledge_plane_location,
+            control_plane_location=row.control_plane_location,
+            permitted_outbound_categories=tuple(categories) if isinstance(categories, list) else (),
+            unavailable_capabilities=tuple(unavailable_capabilities),
+            contractual_approval_ref=row.contractual_approval_ref,
+            declared_at=row.declared_at,
+            decline_recommended=decline_recommended,
+            archetype_floor_violated=archetype_floor_violated,
+            last_successful_observation_at=row.last_successful_observation_at,
+            safe_probe_status=row.safe_probe_status,
+        )
+
+
+def declare_boundary(
+    records: BoundaryRecords,
+    *,
+    scope: Scope,
+    decision: TierDecision,
+    archetype: Archetype | None,
+    knowledge_plane_location: KnowledgePlane = DEFAULT_KNOWLEDGE_PLANE,
+    control_plane_location: ControlPlane = DEFAULT_CONTROL_PLANE,
+    permitted_outbound_categories: Sequence[str] = DEFAULT_OUTBOUND_CATEGORIES,
+    contractual_approval_ref: str | None = None,
+    owner_actor_id: str | None = None,
+    safe_probe_status: str | None = None,
+) -> BoundaryView:
+    """Write the boundary a negotiation implies and return its view.
+
+    Args:
+        records: The storage port. Writes the row; decides nothing.
+        scope: Must resolve at least to a system.
+        decision: The negotiated tier, from `negotiate`.
+        archetype: What detection concluded, or `None` when it was ambiguous.
+        knowledge_plane_location: Where client knowledge lives.
+        control_plane_location: Where routing and entitlement live.
+        permitted_outbound_categories: What may leave. Defaults to
+            `["metadata_only"]`; anything wider needs `contractual_approval_ref`.
+        contractual_approval_ref: The contract amendment reference.
+        owner_actor_id: Who is accountable.
+        safe_probe_status: Whether a safe execution path exists.
+
+    Returns:
+        The `BoundaryView` for the row just written.
+
+    Raises:
+        AdoptError: ``SCOPE_VIOLATION`` from the facade when the scope resolves
+            no system.
+
+    Note:
+        **A `T0` decision still writes a boundary.** The decline recommendation
+        is a *finding about* the engagement, not a refusal to record what was
+        negotiated -- and an engagement that was declined is exactly the one
+        whose boundary someone will want to read six months later.
+    """
+    categories = tuple(permitted_outbound_categories)
+    row = records.declare(
+        scope=scope,
+        tier=decision.tier,
+        knowledge_plane_location=knowledge_plane_location,
+        control_plane_location=control_plane_location,
+        permitted_outbound_categories=categories,
+        covered=decision.rationale,
+        not_covered=_not_covered(decision.unavailable),
+        safe_probe_status=safe_probe_status,
+        owner_actor_id=owner_actor_id,
+        contractual_approval_ref=contractual_approval_ref,
+        contractual=contractual_approval_ref is not None,
+    )
+    return BoundaryView.of(
+        row,
+        archetype=archetype,
+        unavailable_capabilities=decision.unavailable,
+        decline_recommended=decision.decline_recommended,
+        archetype_floor_violated=violates_archetype_floor(archetype, decision.tier),
+    )
+
+
+def _not_covered(unavailable: Sequence[str]) -> str:
+    """The human-readable summary of what this tier does not grant."""
+    if not unavailable:
+        return "Nothing: every capability the platform offers is available at this tier."
+    return "Not available at this tier: " + ", ".join(unavailable) + "."

adopt_detect/detect.py

@@ -0,0 +1,323 @@
+"""Archetype detection: a bounded, deterministic walk over a file tree.
+
+PRD F10.1-F10.3 and implementation spec §4.11. Four properties are load-bearing
+and each is a refusal rather than a preference:
+
+**No code executes in the target tree.** Nothing here imports, evaluates or runs
+anything it finds. Files are opened for reading, at most
+`DETECT_MAX_SNIFF_BYTES` of each, and matched against literal substrings. This
+is what lets an FDE point the tool at a client repository they do not own.
+
+**No network.** Detection is pure filesystem. `01` N10 makes that measurable
+rather than asserted; `tests/property/test_offline.py` is the instrument.
+
+**No model call in this module.** `04` §4 is explicit: the deterministic path
+runs to completion, and below `DETECT_CONFIDENCE_MIN` the answer is *ambiguous
+with ranked scores*, never a guess. The model-backed disambiguation pass lives in
+`adopt_detect.disambiguate`, is reached only with `ADOPT_FEATURE_AGENT_DISAMBIGUATION`
+on **and** a runner handed in, and **there is still no call site for it here** --
+`detect()` cannot reach a model even transitively, which is what makes steps 1-3
+of `04` §4 model-free by construction rather than by intent.
+
+`bounded_listing` is the one thing this module lends that pass: the evidence a
+proposal is allowed to see includes a directory listing, and it must be *this*
+walk's listing -- same bounds, same `.gitignore` scope, same symlink refusal, same
+deterministic order. A second walk written next to the prompt would be a second
+answer to "what is in this tree", and the one that drifted would be the one that
+decided what left the environment.
+
+**Byte-identical across runs and machines** (`01` N2, N15). Every ordering in
+this module is explicit: entries are sorted before the walk, rules are scored in
+declaration order, and the archetype ranking breaks ties by the fixed
+`ARCHETYPES` order. Nothing depends on filesystem iteration order, on a `set`'s
+layout, or on a dict built from either.
+
+**The walk is bounded three ways**, and hitting a bound is reported rather than
+silently truncating the evidence: `DETECT_MAX_DEPTH` on nesting,
+`DETECT_MAX_FILES` on files considered, `DETECT_MAX_SNIFF_BYTES` on bytes read
+per file. A client monorepo is allowed to be enormous; it is not allowed to make
+detection unbounded.
+"""
+
+import os
+from collections.abc import Iterator, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path, PurePosixPath
+from typing import Final
+
+from adopt_const import DETECT_CONFIDENCE_MIN, DETECT_MAX_DEPTH, DETECT_MAX_FILES
+from adopt_const import DETECT_MAX_SNIFF_BYTES as _SNIFF_BYTES
+from adopt_detect.gitignore import GitignoreFilter
+from adopt_detect.rules import ARCHETYPES, ArchetypeRules, load_rule_sets, needs_content
+from adopt_model._enums import Archetype
+from adopt_obs import AdoptError, ErrorCode
+
+__all__ = ["DetectionResult", "RuleHit", "bounded_listing", "detect"]
+
+#: The flag whose name the ambiguity report prints. It is named here, not
+#: implemented here: `04` §4 step 4 is a later sprint's, and the re-run hint has
+#: to name the flag a caller would actually set.
+DISAMBIGUATION_FLAG: Final[str] = "ADOPT_FEATURE_AGENT_DISAMBIGUATION"
+
+#: Directories never descended into. `.git` is the one that matters for
+#: correctness rather than speed: its object store contains compressed copies of
+#: everything, and a `contains` rule would fire on packfile bytes that no longer
+#: reflect the working tree.
+_ALWAYS_SKIPPED: Final[frozenset[str]] = frozenset(
+    {".git", ".hg", ".svn", "node_modules", "__pycache__", ".venv", "venv", ".mypy_cache"}
+)
+
+
+@dataclass(frozen=True, slots=True)
+class RuleHit:
+    """One rule that fired, and the first path that fired it."""
+
+    archetype: Archetype
+    rule_id: str
+    path: str
+    weight: float
+    why: str
+
+
+@dataclass(frozen=True, slots=True)
+class DetectionResult:
+    """What detection concluded, and everything it concluded it from.
+
+    `archetype` is `None` exactly when `ambiguous` is true. The two are kept as
+    separate fields rather than one optional because callers branch on ambiguity
+    and reading `archetype is None` as "ambiguous" invites the other reading,
+    "not yet computed".
+    """
+
+    root: str
+    archetype: Archetype | None
+    confidence: float
+    scores: dict[Archetype, float]
+    rules_fired: tuple[RuleHit, ...]
+    files_considered: int
+    truncated: bool
+    ambiguous: bool = field(default=False)
+
+    def ranked(self) -> tuple[tuple[Archetype, float], ...]:
+        """Archetypes by score descending, ties broken by declaration order."""
+        return tuple(
+            sorted(self.scores.items(), key=lambda pair: (-pair[1], ARCHETYPES.index(pair[0])))
+        )
+
+
+def _sorted_entries(directory: Path) -> list[os.DirEntry[str]]:
+    """Directory entries in one fixed order, whatever the filesystem returns.
+
+    `scandir` order is filesystem- and machine-dependent. Sorting here is what
+    makes `rules_fired` -- which records the *first* path that fired each rule --
+    the same on a developer laptop and on the reference runner.
+    """
+    with os.scandir(directory) as entries:
+        return sorted(entries, key=lambda entry: entry.name)
+
+
+def _is_within(candidate: Path, root: Path) -> bool:
+    """Whether a resolved path is inside a resolved root.
+
+    The symlink check. A client tree may legitimately contain a symlink to
+    somewhere outside itself, and following one would let detection read files
+    the operator never pointed us at -- and, under a `contains` rule, let content
+    outside the tree change the archetype. Such a link is skipped, not an error:
+    refusing the whole tree over one stray link would make the tool unusable on
+    real repositories.
+    """
+    return candidate == root or root in candidate.parents
+
+
+def _walk(root: Path, ignore: GitignoreFilter) -> Iterator[tuple[str, Path, bool]]:
+    """Yield `(relative_posix_path, absolute_path, is_file)` breadth-first.
+
+    Breadth-first so that a bound is hit at the *bottom* of the tree rather than
+    inside whichever subdirectory happened to sort first -- a depth-first walk
+    that stops at `DETECT_MAX_FILES` on a monorepo would see all of one package
+    and none of the others, which is how a bound turns into a wrong answer
+    instead of a partial one.
+    """
+    queue: list[tuple[Path, str, int]] = [(root, "", 0)]
+    while queue:
+        directory, prefix, depth = queue.pop(0)
+        try:
+            entries = _sorted_entries(directory)
+        except OSError:
+            # Unreadable directory: skipped, never fatal. A client checkout with
+            # one permission-denied path is still a tree we can classify.
+            continue
+        for entry in entries:
+            relative = f"{prefix}{entry.name}"
+            absolute = Path(entry.path)
+            if entry.is_symlink() and not _is_within(absolute.resolve(), root):
+                continue
+            if entry.is_dir(follow_symlinks=False):
+                if entry.name in _ALWAYS_SKIPPED or ignore.is_ignored(relative, is_dir=True):
+                    continue
+                if depth < DETECT_MAX_DEPTH:
+                    queue.append((absolute, f"{relative}/", depth + 1))
+                continue
+            if ignore.is_ignored(relative, is_dir=False):
+                continue
+            yield relative, absolute, True
+
+
+def bounded_listing(root: Path | str, *, limit: int) -> tuple[tuple[str, ...], bool]:
+    """The first `limit` paths this walk would consider. Returns `(paths, truncated)`.
+
+    **Paths only.** No file is opened, so nothing here can carry file contents --
+    which is the `04` §4 step 4 privacy invariant, held by the function not having
+    the capability rather than by its caller remembering not to use it.
+
+    Truncation is reported rather than silent, for the reason `DetectionResult`
+    reports it: a proposal reasoning over a listing that stopped somewhere is
+    reasoning over less evidence than it appears to have, and a model told the
+    listing was truncated can say so in its confidence.
+    """
+    # Resolved and filtered exactly as `detect()` does it, three lines below.
+    # Copying the two lines rather than sharing them is the smaller risk: sharing
+    # would mean a helper both call, and the thing that must not drift is the
+    # *bounds and the filter*, which are named constants and one classmethod.
+    resolved = Path(root).resolve()
+    ignore = GitignoreFilter.for_tree(resolved)
+    paths: list[str] = []
+    for relative, _absolute, _is_file in _walk(resolved, ignore):
+        if len(paths) >= limit:
+            return tuple(paths), True
+        paths.append(relative)
+    return tuple(paths), False
+
+
+def _head(path: Path) -> bytes | None:
+    """The first `DETECT_MAX_SNIFF_BYTES`, or `None` if unreadable."""
+    try:
+        with path.open("rb") as handle:
+            return handle.read(_SNIFF_BYTES)
+    except OSError:
+        return None
+
+
+def detect(
+    root: Path | str, *, rule_sets: Sequence[ArchetypeRules] | None = None
+) -> DetectionResult:
+    """Classify a file tree into exactly one archetype, or report ambiguity.
+
+    Args:
+        root: The tree to classify. Never read as code, never executed.
+        rule_sets: Injected rule sets, for tests that need a small closed corpus.
+            Defaults to the packaged `rules/*.yaml`.
+
+    Returns:
+        A `DetectionResult`. When the winning score is below
+        `DETECT_CONFIDENCE_MIN` the result is `ambiguous` with `archetype` of
+        `None` and the full ranked scores -- **never a best guess**. PRD F10.3
+        makes that a product statement: a wrong archetype is not a wrong answer
+        but a different set of extractors, which nothing downstream can detect.
+
+    Raises:
+        AdoptError: ``DETECT_AMBIGUOUS`` is *not* raised here -- ambiguity is a
+            result, and the CLI maps it to exit `2`. This function raises only
+            ``MANIFEST_INVALID``, from rule loading, and
+            ``ADOPT_CONFIG_UNRESOLVED`` when `root` is not a directory.
+    """
+    tree = Path(root)
+    if not tree.is_dir():
+        raise AdoptError(
+            ErrorCode.ADOPT_CONFIG_UNRESOLVED,
+            message=f"{tree} is not a directory",
+            hint="Detection classifies a file tree. Point it at a checkout root.",
+        )
+    resolved = tree.resolve()
+    sets = tuple(rule_sets) if rule_sets is not None else load_rule_sets()
+    read_content = needs_content(sets)
+    ignore = GitignoreFilter.for_tree(resolved)
+
+    hits: dict[tuple[Archetype, str], RuleHit] = {}
+    files_considered = 0
+    truncated = False
+
+    for relative, absolute, _ in _walk(resolved, ignore):
+        if files_considered >= DETECT_MAX_FILES:
+            truncated = True
+            break
+        files_considered += 1
+        head: bytes | None = None
+        head_read = False
+        for rule_set in sets:
+            for rule in rule_set.rules:
+                key = (rule_set.archetype, rule.id)
+                if key in hits:
+                    continue
+                if rule.contains is not None:
+                    if not read_content:  # pragma: no cover -- defensive
+                        continue
+                    if not head_read:
+                        head = _head(absolute)
+                        head_read = True
+                if rule.matches(relative, head):
+                    hits[key] = RuleHit(
+                        archetype=rule_set.archetype,
+                        rule_id=rule.id,
+                        path=relative,
+                        weight=rule.weight,
+                        why=rule.why,
+                    )
+
+    scores = _score(sets, hits)
+    ranked = sorted(scores.items(), key=lambda pair: (-pair[1], ARCHETYPES.index(pair[0])))
+    winner, confidence = ranked[0]
+    ambiguous = confidence < DETECT_CONFIDENCE_MIN
+
+    return DetectionResult(
+        root=PurePosixPath(resolved.as_posix()).as_posix(),
+        archetype=None if ambiguous else winner,
+        confidence=confidence,
+        scores=scores,
+        rules_fired=tuple(
+            sorted(hits.values(), key=lambda hit: (ARCHETYPES.index(hit.archetype), hit.rule_id))
+        ),
+        files_considered=files_considered,
+        truncated=truncated,
+        ambiguous=ambiguous,
+    )
+
+
+def _score(
+    rule_sets: Sequence[ArchetypeRules], hits: dict[tuple[Archetype, str], RuleHit]
+) -> dict[Archetype, float]:
+    """Each archetype's **share of the total matched weight**, rounded.
+
+    **The denominator is the evidence found, not the evidence available**, and
+    that is the whole design. Dividing by an archetype's own total weight would
+    ask "how many of the web rules did this tree fire?" -- and a Django service
+    fires none of the Rails, Go or Express rules, so a perfectly clear web system
+    would score around 0.3 and be reported ambiguous. The question worth asking
+    is "how much of what we found points one way?", which is what
+    `DETECT_CONFIDENCE_MIN = 0.70` reads as in prose: seventy per cent of the
+    evidence agrees.
+
+    Two consequences follow, both wanted. Scores sum to 1, so the ranked list in
+    an ambiguity report is a genuine distribution rather than five unrelated
+    ratios. And a tree that fires **nothing** scores 0.0 everywhere and is
+    ambiguous -- the correct answer for a directory with no signals in it, and
+    one that costs no special case downstream.
+
+    **Rounded deliberately.** The score crosses a threshold, is printed as JSON
+    and is compared byte-for-byte by `01` N2's determinism property, so a value
+    whose last bits depend on summation order would make that property fail for a
+    reason that has nothing to do with detection. Six places is far finer than
+    `DETECT_CONFIDENCE_MIN`'s two and removes the question.
+    """
+    matched: dict[Archetype, float] = {
+        rule_set.archetype: sum(
+            hit.weight for key, hit in hits.items() if key[0] == rule_set.archetype
+        )
+        for rule_set in rule_sets
+    }
+    total = sum(matched.values())
+    if total == 0:
+        return dict.fromkeys(matched, 0.0)
+    # const-sync: ok -- 6 is JSON rendering precision for a ratio in [0,1], not a
+    # behavioural threshold; `DETECT_CONFIDENCE_MIN` is the threshold.
+    return {archetype: round(weight / total, 6) for archetype, weight in matched.items()}