models

Bases: BaseModel

Base model with strict validation.

This model: - Allows mutation (frozen=False) - Validates assignments - Forbids extra fields - Strips whitespace from strings

Use for internal mutable state.

Bases: BaseModel

Immutable model (like a frozen dataclass).

This model: - Prevents mutation (frozen=True) - Validates assignments - Forbids extra fields

Use for result objects and immutable data transfer.

Bases: FrozenModel

Record of a file generated during a run.

Bases: FrozenModel

A narrative bundle about a specific area of the domain.

Bases: FrozenModel

Timing data for a single run phase.

Bases: FrozenModel

Confidence metadata attached to any team judgment.

Renamed from AnalysisConfidence to keep the framework layer domain-agnostic.

Bases: FrozenModel

A judgment with attached confidence and auditable reasoning.

Bases: FrozenModel

What a dispatched team is permitted to do (ASTR §4.7).

A capability grant attached to a team's task contract. Every capability defaults to False (deny by default): a caller must explicitly widen a team's authority. The framework enforces may_create_blocking_finding in dispatch_team code — a team whose grant forbids blocking findings cannot persist one, regardless of what its agents' prompts say.

Attributes:

Bases: FrozenModel

How much a dispatched team may spend (ASTR §6.2).

The resource envelope attached to a team's task contract. All three limits are non-negative; a negative value is rejected at construction (FrozenModel validates assignments). A value of 0 means "no explicit limit supplied" — dispatch_team only overrides the run-default swarm execution_timeout when max_wall_clock_minutes is strictly positive.

Attributes:

Bases: FrozenModel

A single evidence reference backing a finding.

Attributes:

Bases: FrozenModel

A typed, evidence-bearing finding produced by a team (ASTR §6.6, §8.3).

Immutable and extra="forbid" (inherited from :class:FrozenModel), so a finding is safe to pass by reference through invocation_state and any on-disk findings.json that carries unknown keys is rejected at the parse boundary rather than silently accepted.

Attributes:

Bases: FrozenModel

An immutable, content-addressed revision of one logical artifact (ASTR §4.8, §6.4).

A lightweight metadata record — not the artifact blob itself, which lives at the layout-resolved path. Immutable and extra="forbid" (inherited from :class:FrozenModel): any attempt to assign a field after construction raises a pydantic.ValidationError (AC-1-1). Build one with :meth:from_content so content_hash and per-facet hashes are computed deterministically from the content (AC-1-2); constructing directly is supported for round-tripping a persisted revision.

Attributes:

from_content(
    *,
    logical_name,
    facets=None,
    body=None,
    artifact_type="artifact",
    produced_by="",
    artifact_id=None,
    revision_id=None,
    parents=None,
    supersedes=None,
    classification="internal",
    created_at=None,
)

446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505

@classmethod
def from_content(
    cls,
    *,
    logical_name: str,
    facets: Mapping[str, str] | None = None,
    body: str | None = None,
    artifact_type: str = "artifact",
    produced_by: str = "",
    artifact_id: str | None = None,
    revision_id: str | None = None,
    parents: list[str] | None = None,
    supersedes: list[str] | None = None,
    classification: str = "internal",
    created_at: datetime | None = None,
) -> ArtifactRevision:
    """Build a revision from content, computing ``content_hash`` deterministically (AC-1-2).

    Supply the content either as ``facets`` (a ``{facet_name: content}``
    mapping, enabling facet-level ``semantic_diff``) or as a single ``body``
    string (wrapped as one ``"body"`` facet). ``content_hash`` and
    ``revision_id`` (which defaults to ``content_hash`` — content addressing)
    are derived from the content alone; ``artifact_id`` defaults to
    ``logical_name``.

    Args:
        logical_name: The logical artifact's name.
        facets: Facet-name to facet-content mapping. Mutually exclusive with
            ``body``; when both are omitted the revision has empty content.
        body: A single-blob content string (wrapped as facet ``"body"``).
        artifact_type: Kind of artifact.
        produced_by: Producer identifier.
        artifact_id: Stable logical identity; defaults to ``logical_name``.
        revision_id: Explicit revision id; defaults to ``content_hash``.
        parents: Input revision ids.
        supersedes: Superseded revision ids.
        classification: Handling classification.
        created_at: Explicit timestamp; defaults to now.

    Returns:
        A frozen :class:`ArtifactRevision`.
    """
    resolved_facets: dict[str, str] = dict(facets) if facets is not None else {}
    if body is not None:
        resolved_facets.setdefault("body", body)
    content_hash = compute_content_hash(resolved_facets)
    facet_hashes = _facet_hashes(resolved_facets)
    return cls(
        artifact_id=artifact_id or logical_name,
        revision_id=revision_id or content_hash,
        content_hash=content_hash,
        artifact_type=artifact_type,
        logical_name=logical_name,
        produced_by=produced_by,
        parents=list(parents or []),
        supersedes=list(supersedes or []),
        classification=classification,
        facets=facet_hashes,
        created_at=created_at or _utcnow(),
    )

Bases: Exception

Raised by promote_artifact when the optimistic compare-and-set fails (AC-2-3).

Signals that expected_current_revision did not match the alias's stored current revision for logical_name — another promotion won the race, or the caller's view of "current" is stale. The alias pointer is left unchanged.

Attributes:

Record the artifact, the expected revision, and the actually-current one.

521
522
523
524
525
526
527
528

def __init__(self, logical_name: str, expected: str, actual: str) -> None:
    """Record the artifact, the expected revision, and the actually-current one."""
    self.logical_name = logical_name
    self.expected = expected
    self.actual = actual
    super().__init__(
        f"stale promotion of {logical_name!r}: expected current revision {expected!r} but alias holds {actual!r}",
    )

Bases: Exception

Raised when a revision_id is re-persisted with content differing from the stored one (AC-1-5).

The revision store is content-addressed and append-only: a given revision_id binds to exactly one content_hash. Re-persisting the same revision_id with identical content is idempotent; re-persisting it with differing content is a conflict that leaves the stored revision unchanged.

Attributes:

Record the conflicting revision id and the stored vs. incoming content hashes.

545
546
547
548
549
550
551
552
553

def __init__(self, revision_id: str, stored_hash: str, incoming_hash: str) -> None:
    """Record the conflicting revision id and the stored vs. incoming content hashes."""
    self.revision_id = revision_id
    self.stored_hash = stored_hash
    self.incoming_hash = incoming_hash
    super().__init__(
        f"revision {revision_id!r} already persisted with content_hash {stored_hash!r}; "
        f"refusing to overwrite with differing content {incoming_hash!r}",
    )

Bases: FrozenModel

The structured outcome of a successful promote_artifact compare-and-set (AC-2-6).

Returned (as model_dump_json()) by the promote_artifact tool so the calling agent parses JSON per the strands tool norm (research-coding-runtimes line 26).

Attributes:

Bases: FrozenModel

A typed, causal, replayable event on the team event plane (ASTR §6.5, §7).

Immutable and extra="forbid" (inherited from :class:FrozenModel): an unexpected field — notably a raw-transcript or chain-of-thought field — is rejected at construction rather than silently accepted (AC-1-4). Serializing one event to a single JSON line and re-parsing it yields an equal object, so the event log is a lossless round-trip substrate for replay (AC-1-5).

event_id, created_at, and correlation_id are auto-assigned when omitted: a fresh UUID event id, a UTC creation timestamp, and a correlation id defaulting to goal_id when present and otherwise to the assigned event_id (AC-1-3).

Attributes:

Bases: FrozenModel

A revision-bound, signed, expiring approval of a consequential transition (ASTR §14.7).

An approval names the exact :class:ArtifactRevision it approves — by both artifact_revision_id and the revision's immutable revision_content_hash captured at grant time (AC-1-2) — so it goes stale the moment the artifact changes (AC-5-1). Its signature is an HMAC over the canonical serialization of its identity fields (:func:approval_signing_payload), so a forged or tampered token fails :meth:signature_valid and the PolicyEngine treats it as absent (AC-1-4). Past valid_until the engine rejects it as expired (AC-1-5). invalidation_rules names the artifact facets whose change sunsets the approval (AC-5-2, AC-5-3).

Build one with :meth:mint so the signature is computed with the configured signing key; constructing directly is supported for round-tripping a persisted token.

Attributes:

mint(
    *,
    approved_transition_kind,
    artifact_revision_id,
    revision_content_hash,
    approver,
    signing_key,
    valid_until=None,
    valid_for=None,
    invalidation_rules=None,
    token_id=None,
    granted_at=None,
)

791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850

@classmethod
def mint(
    cls,
    *,
    approved_transition_kind: str,
    artifact_revision_id: str,
    revision_content_hash: str,
    approver: str,
    signing_key: str,
    valid_until: datetime | None = None,
    valid_for: timedelta | None = None,
    invalidation_rules: list[str] | None = None,
    token_id: str | None = None,
    granted_at: datetime | None = None,
) -> ApprovalToken:
    """Mint a signed :class:`ApprovalToken` over its canonical payload (AC-1-3).

    Computes the HMAC ``signature`` with ``signing_key`` so the token verifies
    against the same key later (AC-1-4). Supply the expiry either as an absolute
    ``valid_until`` or a relative ``valid_for`` (added to ``granted_at``); when
    neither is given the token is valid for 24 hours (AC-1-5).

    Args:
        approved_transition_kind: The transition kind approved.
        artifact_revision_id: The approved revision's id.
        revision_content_hash: The approved revision's content hash (AC-1-2).
        approver: The approving principal.
        signing_key: The configured signing key (from ``TeamsSettings``).
        valid_until: Absolute UTC expiry (wins over ``valid_for``).
        valid_for: Relative validity window from ``granted_at``.
        invalidation_rules: Facet names whose change sunsets the approval.
        token_id: Explicit id; defaults to a fresh UUID hex.
        granted_at: Explicit grant time; defaults to now.

    Returns:
        A signed, frozen :class:`ApprovalToken`.
    """
    resolved_id = token_id or uuid4().hex
    resolved_granted = granted_at or _utcnow()
    if valid_until is None:
        valid_until = resolved_granted + (valid_for if valid_for is not None else timedelta(hours=24))
    payload = approval_signing_payload(
        token_id=resolved_id,
        approved_transition_kind=approved_transition_kind,
        artifact_revision_id=artifact_revision_id,
        revision_content_hash=revision_content_hash,
        approver=approver,
        valid_until=valid_until,
    )
    return cls(
        token_id=resolved_id,
        approved_transition_kind=approved_transition_kind,
        artifact_revision_id=artifact_revision_id,
        revision_content_hash=revision_content_hash,
        approver=approver,
        granted_at=resolved_granted,
        valid_until=valid_until,
        signature=_sign(payload, signing_key),
        invalidation_rules=list(invalidation_rules or []),
    )

signing_payload()

852
853
854
855
856
857
858
859
860
861

def signing_payload(self) -> str:
    """Return this token's canonical signing payload (AC-1-3)."""
    return approval_signing_payload(
        token_id=self.token_id,
        approved_transition_kind=self.approved_transition_kind,
        artifact_revision_id=self.artifact_revision_id,
        revision_content_hash=self.revision_content_hash,
        approver=self.approver,
        valid_until=self.valid_until,
    )

signature_valid(signing_key)

863
864
865
866
867
868
869
870
871

def signature_valid(self, signing_key: str) -> bool:
    """Return whether ``signature`` verifies against ``signing_key`` (AC-1-4).

    Uses :func:`hmac.compare_digest` for a constant-time comparison so a
    signature check cannot be timing-attacked. A token whose signature does not
    verify is treated as absent by the ``PolicyEngine``.
    """
    expected = _sign(self.signing_payload(), signing_key)
    return hmac.compare_digest(expected, self.signature)

is_expired(now=None)

873
874
875

def is_expired(self, now: datetime | None = None) -> bool:
    """Return whether the token is at or past its ``valid_until`` (AC-1-5)."""
    return (now or _utcnow()) >= self.valid_until

Bases: FrozenModel

An auditable record of a consequential choice (ASTR §11).

Captures the full deliberation: the question, the options considered, what was selected, the rationale, the evidence (reusing the P1 :class:Evidence vocabulary — file:line / test / command exit / artifact / url / log, AC-2-2), any dissent, and the prior decision_id this record supersedes when it reverses or replaces an earlier decision (AC-2-3). The PolicyEngine appends one on every allow/deny verdict (AC-2-4).

Attributes:

Bases: FrozenModel

A proposed consequential state transition the PolicyEngine judges (ASTR §14.7).

The model constructs one of these and hands it to PolicyEngine.authorize_transition; the engine — never the model — issues the final verdict (AC-6-1). A consequential transition (e.g. a release or a merge) is refused unless a valid revision-bound approval is present and no open blocking finding remains (AC-6-2, AC-6-3).

Attributes:

Bases: FrozenModel

A first-class human-gate protocol state (ASTR §14, §5.2).

Where a transition kind is human-gated, the PolicyEngine emits one of these as pending rather than letting the model self-approve (AC-4-1). The runner persists it to disk and suspends the outer loop for that transition until a human resolves it (AC-4-3, AC-4-5); an approving resolution resumes and re-authorizes the transition (AC-4-4), a rejecting one abandons it (AC-4-6).

Attributes:

resolve(*, approved, resolved_by, resolved_at=None)

 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010

def resolve(self, *, approved: bool, resolved_by: str, resolved_at: datetime | None = None) -> HumanDecision:
    """Return a resolved copy of this gate (frozen — never mutates in place).

    Args:
        approved: ``True`` -> ``resolved`` (approve); ``False`` -> ``rejected``.
        resolved_by: The principal resolving the gate.
        resolved_at: Resolution timestamp; defaults to now.

    Returns:
        A new :class:`HumanDecision` with the updated status and resolver.
    """
    return self.model_copy(
        update={
            "status": "resolved" if approved else "rejected",
            "resolved_by": resolved_by,
            "resolved_at": resolved_at or _utcnow(),
        },
    )

Bases: FrozenModel

The PolicyEngine's final allow/deny on a transition (ASTR §14.7, AC-3-1).

The model never decides — this verdict, produced by PolicyEngine.authorize_transition, is the authority (AC-3-1). On a deny, failed_gate names which gate in the ordered stack refused and reason is human-readable. On an allow, failed_gate is None (AC-3-6). When the denying gate is human_required, pending_human_decision carries the gate the runner must suspend on (AC-4-1).

Attributes: