adopt-ask 0.4.0__py3-none-any.whl

adopt_ask/__init__.py

@@ -0,0 +1,114 @@
+"""`adopt ask` -- the Private Project Assistant. Build 3.
+
+Honest three-way answers over the store: **KNOWN** (the answer, citing the exact
+revisions, the identity URIs they are bound to, and the rule that let them
+serve), **STALE** (the prior answer, served *with* the cause that made it stale),
+**UNKNOWN** (a refusal). Never an unqualified guess.
+
+**The invariant this package exists to hold** (v6.1 §4 R6, critical semantic
+invariant #5): *no code path serves an answer without a freshness resolution.*
+`branch.compose` takes `Resolved` values -- a candidate welded to its resolution
+-- so a caller cannot express "serve this passage, I did not check". The rule is
+a type, not a review comment. See `adopt_ask.branch` for why that shape was
+chosen over a required mapping argument.
+
+Three further postures, each inherited rather than invented:
+
+* **No model call anywhere in this sprint.** The extractive answer *is* the
+  complete no-model mode (R3): the store holds prose a human wrote, so answering
+  is quotation with attribution rather than generation. Optional grounded
+  synthesis arrives in S3.2, behind the existing agent seam, and is discarded
+  when it cites nothing (invariant #7).
+* **The index is derived, never canon.** FTS5 lives in the runtime annex,
+  rebuilt from the store whenever the two disagree, never exported. One canon
+  (R9) survives the existence of a second searchable copy because the second one
+  is disposable and is treated as such.
+* **Only verified knowledge serves as KNOWN** (F6). Enforced when the index is
+  built *and* again when the branch is decided, against the store rather than
+  the index -- the derived copy is the wrong authority on what may be said.
+"""
+
+from adopt_ask.answer import (
+    ASK_EVENT_TYPE,
+    envelope,
+    guard,
+    json_payload,
+    render,
+    sendable_payload,
+)
+from adopt_ask.branch import (
+    KNOWN,
+    STALE,
+    UNKNOWN,
+    Answer,
+    Branch,
+    Citation,
+    Resolved,
+    compose,
+)
+from adopt_ask.capture import (
+    CaptureResult,
+    CaptureStore,
+    capture_answer,
+    identities_to_bind,
+)
+from adopt_ask.escalate import (
+    ESCALATABLE,
+    EscalationWriter,
+    consent_prompt,
+    consented,
+    escalate,
+    escalation_branch,
+    may_escalate,
+)
+from adopt_ask.questionlog import QuestionLog, QuestionRecord, log_question, should_log
+from adopt_ask.records import Passage, RefreshOutcome, SearchRecords
+from adopt_ask.retrieve import Candidate, CandidateOrigin, retrieve, uris_in
+from adopt_ask.serve import build_server, exposure_warning, is_loopback
+from adopt_ask.synthesis import SYNTHESIS_PROMPT_REF, Synthesis, ground, synthesize
+
+__all__ = [
+    "ASK_EVENT_TYPE",
+    "ESCALATABLE",
+    "KNOWN",
+    "STALE",
+    "SYNTHESIS_PROMPT_REF",
+    "UNKNOWN",
+    "Answer",
+    "Branch",
+    "Candidate",
+    "CandidateOrigin",
+    "CaptureResult",
+    "CaptureStore",
+    "Citation",
+    "EscalationWriter",
+    "Passage",
+    "QuestionLog",
+    "QuestionRecord",
+    "RefreshOutcome",
+    "Resolved",
+    "SearchRecords",
+    "Synthesis",
+    "build_server",
+    "capture_answer",
+    "compose",
+    "consent_prompt",
+    "consented",
+    "envelope",
+    "escalate",
+    "escalation_branch",
+    "exposure_warning",
+    "ground",
+    "guard",
+    "identities_to_bind",
+    "is_loopback",
+    "json_payload",
+    "log_question",
+    "may_escalate",
+    "render",
+    "retrieve",
+    "sendable_payload",
+    "should_log",
+    "synthesize",
+    "uris_in",
+]

adopt_ask/answer.py

@@ -0,0 +1,238 @@
+"""Rendering an `Answer`, and the boundary that decides whether it may leave.
+
+**The extractive answer is the passages themselves.** No summarization, no
+paraphrase, no stitching -- the cited revision bodies verbatim, in retrieval
+order, each with its revision id, the identity URIs it is bound to, and the
+freshness rule that permitted it. That is the complete no-model mode R3
+requires, and it is complete because the store already holds prose a human
+wrote: an assistant that had to generate in order to answer would have nothing
+to say without a model, which is exactly the dependency v6.1 refuses.
+
+**The boundary check, and the sentence it implements.** v6.1 §6 Build 3: *the
+assistant never answers outside the declared observability boundary*. Two ways
+that can be false, and both are refusals here:
+
+* **No boundary is declared.** Fail closed, on Build 0's egress posture -- an
+  undeclared boundary is not an unlimited one. `adopt init` always declares one,
+  so a store without one is a store assembled by something else, and that is
+  precisely when guessing is worst.
+* **The boundary does not permit what this answer would carry.** The envelope is
+  validated by the Build 0 gate rather than by a second rule invented here, so
+  the deny-list widens by itself when a `md`/`text` column is added to the
+  manifest (`content_fields`).
+
+**Why a local answer validates a metadata-only envelope.** `adopt ask` prints
+inside the boundary: the content does not leave, so the envelope that represents
+what *would* leave carries ids, URIs, states and counts -- never the question
+text, the titles or the bodies. Those three are content fields by derivation,
+and building them into a metadata-only payload would make the gate reject every
+answer on every default store, which is how a control ends up switched off. A
+caller with a genuinely outbound destination passes the policy that destination
+uses, and then the boundary is asked the real question. B7's channels are the
+first such caller.
+"""
+
+import datetime as _dt
+from collections.abc import Mapping
+from typing import Any, Final
+
+from adopt_ask.branch import Answer
+from adopt_const import SCHEMA_VERSION
+from adopt_detect import METADATA_ONLY, BoundaryView
+from adopt_obs import AdoptError, ErrorCode
+from adopt_policy import validate_envelope
+from adopt_schema.manifest import Manifest
+from adopt_scope import Scope
+
+__all__ = ["ASK_EVENT_TYPE", "envelope", "guard", "render", "sendable_payload"]
+
+#: The envelope's `event_type` for an answer. One name, because a boundary
+#: audit that had to recognise three spellings of "we answered a question" is a
+#: boundary audit nobody completes.
+ASK_EVENT_TYPE: Final[str] = "ask_answered"
+
+
+def sendable_payload(answer: Answer, *, include_content: bool) -> dict[str, Any]:
+    """The envelope payload for `answer`.
+
+    Under `include_content=False` this is deliberately free of every content
+    field: no `question`, no `title`, no `body_md`. Those are the names
+    `find_content_fields` derives from the manifest and the logger deny-list,
+    and omitting them is what makes a metadata-only answer honestly
+    metadata-only rather than merely asserted to be.
+    """
+    citations: list[dict[str, Any]] = []
+    for citation in answer.citations:
+        entry: dict[str, Any] = {
+            "revision_id": citation.revision_id,
+            "item_id": citation.item_id,
+            "identity_uris": list(citation.identity_uris),
+            "origin": citation.origin,
+            "freshness_state": citation.freshness_state,
+            "deciding_rule": citation.deciding_rule,
+        }
+        if include_content:
+            entry["title"] = citation.title
+            entry["body_md"] = citation.body_md
+        citations.append(entry)
+
+    payload: dict[str, Any] = {
+        "branch": answer.branch,
+        "citation_count": len(answer.citations),
+        "withheld_count": len(answer.withheld),
+        "citations": citations,
+    }
+    if answer.cause is not None:
+        payload["cause"] = answer.cause
+    if include_content:
+        payload["question"] = answer.question
+    return payload
+
+
+def envelope(
+    answer: Answer,
+    *,
+    scope: Scope,
+    occurred_at: _dt.datetime,
+    content_policy: str = METADATA_ONLY,
+) -> dict[str, Any]:
+    """A contracts §8 envelope for `answer`, in `scope`.
+
+    Raises:
+        AdoptError: ``ASK_OUTSIDE_BOUNDARY`` when the scope is not resolved to an
+            environment. Every scope id is required to check an envelope against
+            any boundary at all, and a half-resolved scope is a question we
+            cannot say whose system it concerns.
+    """
+    if scope.engagement is None or scope.system is None or scope.environment is None:
+        raise _refuse(
+            f"the scope {scope.path()!r} does not resolve to an environment, so no "
+            "boundary governs it",
+            "Open the store at a full firm/engagement/system/environment scope. An "
+            "answer whose system is unknown cannot be checked against any boundary.",
+        )
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "firm_id": scope.firm.id,
+        "engagement_id": scope.engagement.id,
+        "system_id": scope.system.id,
+        "environment_id": scope.environment.id,
+        "event_type": ASK_EVENT_TYPE,
+        "occurred_at": occurred_at.isoformat(),
+        "content_policy": content_policy,
+        "payload": sendable_payload(answer, include_content=content_policy != METADATA_ONLY),
+    }
+
+
+def guard(
+    answer: Answer,
+    boundary: BoundaryView | None,
+    *,
+    scope: Scope,
+    occurred_at: _dt.datetime,
+    content_policy: str = METADATA_ONLY,
+    manifest: Manifest | None = None,
+) -> None:
+    """Refuse `answer` unless the declared boundary permits it. Raises, or returns None.
+
+    Args:
+        answer: The composed answer. Not modified, and never partially served --
+            a refusal here withholds the whole answer, because an answer with
+            its citations stripped to fit a boundary is an unattributed claim,
+            which is worse than a refusal.
+        boundary: The declared boundary, or `None` when the store holds none.
+        scope: The full scope the store was opened at.
+        occurred_at: Injected clock reading; never `datetime.now()` here.
+        content_policy: What the destination carries. The default is the local
+            terminal's: metadata only, because the content never leaves.
+        manifest: Injected manifest, for tests asserting the derived deny-list.
+
+    Raises:
+        AdoptError: ``ASK_OUTSIDE_BOUNDARY`` for every refusal, with the
+            underlying Build 0 envelope violation named in the message.
+    """
+    if boundary is None:
+        raise _refuse(
+            "no observability boundary is declared for this scope",
+            "Run `adopt init` (or `adopt boundary`) to declare one. An undeclared "
+            "boundary is not an unlimited boundary -- with nothing to check against, "
+            "the assistant refuses rather than guesses what the client agreed to.",
+        )
+
+    try:
+        validate_envelope(
+            envelope(answer, scope=scope, occurred_at=occurred_at, content_policy=content_policy),
+            boundary,
+            manifest=manifest,
+        )
+    except AdoptError as violation:
+        if violation.code is ErrorCode.ASK_OUTSIDE_BOUNDARY:
+            raise
+        raise _refuse(
+            f"the declared boundary does not permit this answer: {violation.message}",
+            "The boundary is the authority, not the question. Widening what may leave "
+            "is a contract amendment recorded on the boundary row with "
+            "`contractual_approval_ref`.",
+        ) from violation
+
+
+def render(answer: Answer) -> str:
+    """The human rendering: the branch, then each passage verbatim with its grounds."""
+    if answer.branch == "unknown":
+        lines = [f"UNKNOWN: the store holds no confirmed answer to {answer.question!r}."]
+        if answer.withheld:
+            lines.append(
+                f"{len(answer.withheld)} matching revision(s) were withheld as unverified. "
+                "Confirm them in `adopt review` and ask again."
+            )
+        return "\n".join(lines)
+
+    header = f"{answer.branch.upper()}: {answer.question}"
+    if answer.branch == "stale":
+        header += f"\nSTALE because {answer.cause} -- the answer below is what was true before."
+
+    blocks = [header]
+    for citation in answer.citations:
+        grounds = f"  revision {citation.revision_id} ({citation.freshness_state}, "
+        grounds += f"matched by {citation.origin}, rule {citation.deciding_rule})"
+        if citation.identity_uris:
+            grounds += "\n  bound to: " + ", ".join(citation.identity_uris)
+        blocks.append(f"\n## {citation.title}\n{citation.body_md}\n{grounds}")
+
+    if answer.withheld:
+        blocks.append(f"\n{len(answer.withheld)} further revision(s) withheld as unverified.")
+    return "\n".join(blocks)
+
+
+def _refuse(message: str, hint: str) -> AdoptError:
+    return AdoptError(ErrorCode.ASK_OUTSIDE_BOUNDARY, message=message, hint=hint)
+
+
+def json_payload(answer: Answer) -> Mapping[str, Any]:
+    """The `--json` payload: the full answer, content included.
+
+    Distinct from `sendable_payload` on purpose. This one is for the operator's
+    own terminal inside the boundary and carries everything; that one is for an
+    envelope that may leave and carries what the boundary permits. Collapsing
+    the two would mean either an unreadable local answer or an egress payload
+    shaped by what is convenient to print.
+    """
+    return {
+        "question": answer.question,
+        "branch": answer.branch,
+        "cause": answer.cause,
+        "withheld": list(answer.withheld),
+        "citations": [
+            {
+                "revision_id": citation.revision_id,
+                "item_id": citation.item_id,
+                "title": citation.title,
+                "body_md": citation.body_md,
+                "identity_uris": list(citation.identity_uris),
+                "origin": citation.origin,
+                "freshness_state": citation.freshness_state,
+                "deciding_rule": citation.deciding_rule,
+            }
+            for citation in answer.citations
+        ],
+    }

adopt_ask/branch.py

@@ -0,0 +1,211 @@
+"""The three-way branch: KNOWN, STALE, UNKNOWN -- and never anything else.
+
+**This module is where critical semantic invariant #5 stops being a rule and
+becomes a shape.** `compose` does not accept candidates. It accepts `Resolved` --
+a candidate welded to the `FreshnessResolution` for its item -- and `Resolved`
+cannot be constructed without one. So there is no argument a caller can supply
+that represents "a passage I have not resolved freshness for", which means there
+is no code path from retrieval to a served answer that skips the check. Not a
+guard that runs first: a value that cannot exist.
+
+That is deliberately stronger than a required `Mapping[item_id, resolution]`
+argument, which was the obvious design. A mapping can be missing a key, so it
+needs a runtime raise for the gap, and a runtime raise is exactly the thing a
+later refactor quietly turns into `.get(..., FRESH)`. Pairing removes the gap
+instead of checking for it.
+
+Why any of this is worth the ceremony: "check freshness before serving" is the
+kind of rule that survives its first author and dies in the third refactor, when
+someone adds a fast path for a case that "obviously cannot be stale". The
+failure is silent and lands in a client's face -- a confident, cited answer
+about a system that changed last month.
+
+**Two verification filters, deliberately duplicated.** Unverified knowledge never
+serves as KNOWN (F6). The FTS index already refuses to hold it, and this module
+checks again against the store's own answer. Not belt-and-braces: the index is
+derived and can be stale, so it is precisely the wrong authority on what may be
+served. The index makes the common case fast; the store makes the guarantee
+true.
+
+**STALE serves rather than refuses.** A stale answer carries the prior content
+*and* the rule that decided staleness (F3, pre-B6: identity death, moves,
+retirement). Refusing would discard knowledge the store genuinely holds; the
+honest form is "here is what we knew, and here is why it may be wrong".
+"""
+
+from collections.abc import Sequence, Set
+from dataclasses import dataclass
+from typing import Final, Literal
+
+from adopt_ask.retrieve import Candidate, CandidateOrigin
+from adopt_freshness import FreshnessResolution
+
+__all__ = ["KNOWN", "STALE", "UNKNOWN", "Answer", "Branch", "Citation", "Resolved", "compose"]
+
+Branch = Literal["known", "stale", "unknown"]
+
+KNOWN: Final[Branch] = "known"
+STALE: Final[Branch] = "stale"
+UNKNOWN: Final[Branch] = "unknown"
+
+#: The freshness states that may serve as KNOWN. Everything else -- `stale`,
+#: `observation_stale`, `retired` -- serves as STALE with its cause named.
+#:
+#: **`unverified` is here, and that is the subtle one.** It is
+#: `INITIAL_ITEM_FRESHNESS`: the state every knowledge item is created in,
+#: meaning *no freshness rule has fired either way*. It is not a staleness
+#: signal, and reading it as one would be false staleness manufactured from a
+#: default -- the precise failure v6.1's H5 calls "the exact failure that makes
+#: FDEs stop trusting the queue". It would also make Build 3 undeliverable:
+#: pre-B6 nothing sets an item to `fresh`, so treating `unverified` as STALE
+#: means `adopt ask` could never answer KNOWN until Build 6 shipped.
+#:
+#: v6.1 §6 F3 is the authority and was explicit about the pre-B6 scope: staleness
+#: arose from identity **death and moves** surfaced by map reruns, and from
+#: **retirement**. Those three arrive as `stale` and `retired`, each carrying the
+#: rule that produced it.
+#:
+#: **Build 6 has since shipped, and F3's boundary has moved -- with no change to
+#: this module.** `adopt refresh` adds the fourth source: a changed attribute
+#: digest on a bound referent stales the *binding*, which `resolve_freshness`
+#: already reads as `RULE_BINDING_STALE`. That the sensitivity of STALE could
+#: grow without this file being edited is F3's design working as intended: the
+#: three-way contract was complete at Build 3, and Build 6 fed it rather than
+#: extending it. The one thing that did change is `adopt_freshness`' treatment of
+#: a **superseded** binding, which a rebind now creates -- and that is a rule
+#: about which bindings are consulted, not about which states serve.
+#:
+#: Naming the servable states rather than the unservable ones is deliberate in
+#: the other direction: a `freshness_state` added to the manifest later falls
+#: into STALE, which is the safe way to be wrong about a state this code has
+#: never seen.
+_SERVES_AS_KNOWN: Final[frozenset[str]] = frozenset({"fresh", "unverified"})
+
+
+@dataclass(frozen=True, slots=True)
+class Resolved:
+    """A retrieval candidate and the freshness resolution for its item.
+
+    The pairing is the invariant, and `__post_init__` enforces that it is a
+    *true* pairing: a resolution computed for some other item is rejected at
+    construction. Without that check the type would still admit the failure it
+    exists to prevent -- freshness resolved, but not for this passage.
+    """
+
+    candidate: Candidate
+    freshness: FreshnessResolution
+
+    def __post_init__(self) -> None:
+        if self.freshness.item_id != self.candidate.passage.item_id:
+            raise ValueError(
+                "the freshness resolution is for a different item than the candidate: "
+                f"{self.freshness.item_id} != {self.candidate.passage.item_id}"
+            )
+
+
+@dataclass(frozen=True, slots=True)
+class Citation:
+    """One served passage and the exact grounds for serving it."""
+
+    revision_id: str
+    item_id: str
+    title: str
+    body_md: str
+    identity_uris: tuple[str, ...]
+    origin: CandidateOrigin
+    freshness_state: str
+    deciding_rule: str
+
+
+@dataclass(frozen=True, slots=True)
+class Answer:
+    """What `adopt ask` returns. One of exactly three branches, always cited.
+
+    An UNKNOWN carries no citations by construction; a KNOWN or STALE carries at
+    least one. `__post_init__` refuses to build the alternatives rather than
+    leaving a caller to notice -- an uncited KNOWN is the unqualified guess this
+    whole build exists to make impossible.
+    """
+
+    question: str
+    branch: Branch
+    citations: tuple[Citation, ...]
+    #: Present exactly when `branch` is STALE: the rule that decided staleness,
+    #: taken verbatim from the resolution rather than re-derived here.
+    cause: str | None = None
+    #: Revisions retrieved but withheld as unverified. Reported so an UNKNOWN
+    #: over a store that *does* hold matching text says which of the two reasons
+    #: applied -- nothing matched, or nothing matched that was verified. Those
+    #: send an operator to different places: write the answer, or go confirm the
+    #: draft that already says it.
+    withheld: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if self.branch == UNKNOWN and self.citations:
+            raise ValueError("an UNKNOWN answer cannot carry citations")
+        if self.branch != UNKNOWN and not self.citations:
+            raise ValueError(f"a {self.branch.upper()} answer must cite at least one revision")
+        if (self.cause is None) == (self.branch == STALE):
+            raise ValueError("cause is set exactly when the branch is STALE")
+
+
+def compose(resolved: Sequence[Resolved], verified_revision_ids: Set[str], question: str) -> Answer:
+    """Decide the branch over already-resolved candidates.
+
+    Args:
+        resolved: Retrieval output paired with freshness, best first. Order is
+            preserved into the citations: retrieval already decided what "best"
+            means and this function does not second-guess it.
+        verified_revision_ids: Revision ids the **store** reports as verified.
+            Read from canon rather than from the derived index, because the
+            index is exactly the wrong authority on what may be served.
+        question: Echoed into the answer so a payload is self-describing.
+
+    Returns:
+        KNOWN if any resolved candidate is verified and carries no staleness
+        signal; otherwise STALE if any is verified and has gone out of date;
+        otherwise UNKNOWN. `_SERVES_AS_KNOWN` records which states are which and
+        why `unverified` freshness is not staleness.
+    """
+    servable = [
+        item for item in resolved if item.candidate.passage.revision_id in verified_revision_ids
+    ]
+    withheld = tuple(
+        item.candidate.passage.revision_id
+        for item in resolved
+        if item.candidate.passage.revision_id not in verified_revision_ids
+    )
+
+    fresh = [item for item in servable if item.freshness.state in _SERVES_AS_KNOWN]
+    if fresh:
+        return Answer(
+            question=question,
+            branch=KNOWN,
+            citations=tuple(_cite(item) for item in fresh),
+            withheld=withheld,
+        )
+
+    if servable:
+        return Answer(
+            question=question,
+            branch=STALE,
+            citations=tuple(_cite(item) for item in servable),
+            cause=servable[0].freshness.deciding_rule,
+            withheld=withheld,
+        )
+
+    return Answer(question=question, branch=UNKNOWN, citations=(), withheld=withheld)
+
+
+def _cite(item: Resolved) -> Citation:
+    passage = item.candidate.passage
+    return Citation(
+        revision_id=passage.revision_id,
+        item_id=passage.item_id,
+        title=passage.title,
+        body_md=passage.body_md,
+        identity_uris=passage.identity_uris,
+        origin=item.candidate.origin,
+        freshness_state=item.freshness.state,
+        deciding_rule=item.freshness.deciding_rule,
+    )