cadrumo.application.search.workbench module

Frontend-neutral, intrinsically safe search projections for the workbench.

The service searches a private, ephemeral snapshot containing only closed semantic codes and canonical natural addresses. Providers cannot attach free text, raw search terms, token indexes, or an asserted result identity. The service derives each result identity from the safe projection itself and owns no repository, persistence, network, localization, or frontend dependency.

class WorkbenchSearchKind(*values)

Bases: StrEnum

Complete human-facing family for one cross-domain result.

LEDGER_ENTRY

LEDGER_EVIDENCE

DECLARATION

MODELO

REVISION

FILING

HISTORY

RECONCILIATION

NOTIFICATION

class WorkbenchSearchSource(*values)

Bases: StrEnum

Closed application projection that supplied a search record.

LEDGER_ENTRY

LEDGER_EVIDENCE

DECLARATION

MODELO

REVISION

FILING

HISTORY

RECONCILIATION

NOTIFICATION

class WorkbenchSearchStatus(*values)

Bases: StrEnum

Closed source-native statuses admitted by the search boundary.

LEDGER_ENTRY_READY

LEDGER_ENTRY_NEEDS_REVIEW

LEDGER_ENTRY_CLASSIFIED

LEDGER_EVIDENCE_CAPTURED

LEDGER_EVIDENCE_MISSING

LEDGER_EVIDENCE_STALE

DECLARATION_DRAFT

DECLARATION_IN_PROGRESS

DECLARATION_NEEDS_ATTENTION

DECLARATION_READY

DECLARATION_FILED

MODELO_AVAILABLE

MODELO_UNAVAILABLE

REVISION_CURRENT

REVISION_SUPERSEDED

FILING_SUBMITTED

FILING_ACCEPTED

FILING_REJECTED

HISTORY_OBSERVED

HISTORY_NOT_OBSERVED

RECONCILIATION_OPEN

RECONCILIATION_RESOLVED

NOTIFICATION_UNREAD

NOTIFICATION_READ

class WorkbenchSearchLabelKey(*values)

Bases: StrEnum

Closed localization key; never provider-authored display text.

LEDGER_ENTRY

LEDGER_EVIDENCE

DECLARATION

MODELO

REVISION

FILING

HISTORY

RECONCILIATION

NOTIFICATION

class WorkbenchDestinationAdmissionState(*values)

Bases: StrEnum

Whether a result’s owning destination can currently be opened.

AVAILABLE

LOCKED

STALE

NEVER_CAPTURED

UNAVAILABLE

class WorkbenchModeloAddress(**data)

Bases: BaseModel

Exact Modelo/year/period case address without a record identity.

Parameters:

data (Any)

address_kind: Literal['modelo_case']

modelo: ModeloCode

filing_year: FilingYear

period: Period

class WorkbenchRevisionAddress(**data)

Bases: BaseModel

Exact calculation-history revision address.

Parameters:

data (Any)

address_kind: Literal['calculation_revision']

modelo: ModeloCode

filing_year: FilingYear

period: Period

calculation_revision_id: CalculationRevisionId

class WorkbenchFilingAddress(**data)

Bases: BaseModel

Exact filing-record address.

Parameters:

data (Any)

address_kind: Literal['filing_record']

modelo: ModeloCode

filing_year: FilingYear

period: Period

filing_record_id: FilingRecordId

class WorkbenchDestinationAdmission(**data)

Bases: BaseModel

Destination identity and truthful availability for a search result.

Parameters:

data (Any)

destination: NamespacedId

state: WorkbenchDestinationAdmissionState

reason_code: NamespacedId | None

class WorkbenchSearchDocument(**data)

Bases: BaseModel

Intrinsically safe source projection accepted by the query service.

Structural fields are closed enums, canonical natural addresses, or technical namespaced action/admission tokens. Multi-record families carry a private source identity basis that is retained only in memory, excluded from serialization and representation, and converted to a process-keyed opaque result identity. There is no provider-authored label, caller-visible source identifier, or asserted stable identity. action_candidate_id remains unresolved until S369’s catalogue admits it.

content_terms carries the operator’s own words – a counterparty, a description, an amount – so that searching for them finds the record they belong to. A search index over enum names alone can only answer questions the operator already knows the vocabulary for: they can find “ledger entry” but not “Suministros Delta”, which is the only thing they actually remember. The session is authenticated against their own data, so the terms are theirs; the identity basis stays secret because it is machine addressing, and that distinction is the point.

Parameters:

data (Any)

kind: WorkbenchSearchKind

source: WorkbenchSearchSource

status: WorkbenchSearchStatus

label_key: WorkbenchSearchLabelKey

address: WorkbenchNaturalAddress | None

admission: WorkbenchDestinationAdmission

action_candidate_id: NamespacedId | None

identity_basis: SecretStr | None

content_terms: tuple[str, ...]

The operator’s own words for this record, matched alongside the enums.

class WorkbenchSearchRequest(**data)

Bases: BaseModel

Strict request whose plaintext query is transient and never serialized.

Parameters:

data (Any)

query: _TransientQuery

limit: Annotated[int, Field(gt=0, le=_MAX_SEARCH_RESULTS)]

class WorkbenchSearchResult(**data)

Bases: BaseModel

One ranked result containing only intrinsically safe metadata.

Parameters:

data (Any)

stable_id: Hex64Str

kind: WorkbenchSearchKind

source: WorkbenchSearchSource

status: WorkbenchSearchStatus

label_key: WorkbenchSearchLabelKey

address: WorkbenchNaturalAddress | None

admission: WorkbenchDestinationAdmission

action_candidate_id: NamespacedId | None

rank: NonNegativeInt

score: float

class WorkbenchSearchResponse(**data)

Bases: BaseModel

Bounded response carrying neither plaintext nor hashed query terms.

Parameters:

data (Any)

results: tuple[WorkbenchSearchResult, ...]

total_matches: NonNegativeInt

class WorkbenchSearchService(documents)

Bases: object

Pure search over one private, ephemeral, intrinsically safe snapshot.

Parameters:

documents (Sequence[WorkbenchSearchDocument])

search(request)

Return deterministic matches capped by the request’s result limit.

Return type:

WorkbenchSearchResponse

Parameters:

request (WorkbenchSearchRequest)