app.storage.values

Value types crossing the storage port.

Plain frozen dataclasses and enums, independent of any ORM. Import them through app.storage.port, which re-exports everything here.

Public API:

• enums RecordState, PollStatus, IntakeKind, IntakeStatus, SearchSort; constant MAX_PAGE_SIZE; alias JsonObject

• values RegistrationConfig, Registration, Revision, RecordWrite, StoredRecord, ErratumRow, UpsertResult, ChangeTokenEntry, SearchFilters, SearchItem, SearchPage, FacetEntry, NewDecision, DecisionEvent, IntakeRun

app.storage.values.MAX_PAGE_SIZE = 50

Upper bound for page_size in app.storage.port.CatalogStore.search().

type app.storage.values.JsonObject = Mapping[str, JsonValue]

class app.storage.values.RecordState(*values)

Bases: StrEnum

Lifecycle state of a stored record row.

PUBLISHED = 'published'

CANDIDATE = 'candidate'

class app.storage.values.PollStatus(*values)

Bases: StrEnum

Outcome of the latest poll of a registration.

NEVER = 'never'

OK = 'ok'

PARTIAL = 'partial'

FAILED = 'failed'

DISABLED = 'disabled'

class app.storage.values.IntakeKind(*values)

Bases: StrEnum

How content entered the catalog.

POLL = 'poll'

PUSH = 'push'

class app.storage.values.IntakeStatus(*values)

Bases: StrEnum

Status of one intake run.

RUNNING = 'running'

OK = 'ok'

PARTIAL = 'partial'

FAILED = 'failed'

class app.storage.values.SearchSort(*values)

Bases: StrEnum

Result order of app.storage.port.CatalogStore.search().

Every order ends with the lower-cased title and the record id, so pages are stable even when the leading key ties.

• relevance: text rank, best first; without a text query it is the same as title.

• title: lower-cased title A-Z.

• recent: record.updated_at (when the content digest last changed), newest first.

RELEVANCE = 'relevance'

TITLE = 'title'

RECENT = 'recent'

class app.storage.values.RegistrationConfig(*, id, type, config, enabled=True, config_error=None)

Bases: object

One source registration as read from catalog.yaml.

Parameters:

• id (str) – Stable registration id.

• type (str) – Source type (filesystem or gitlab).

• config (JsonObject) – Type-specific settings, secrets excluded.

• enabled (bool) – False when the entry is invalid.

• config_error (str | None) – Readable reason why the entry is invalid.

id: str

type: str

config: JsonObject

enabled: bool

config_error: str | None

class app.storage.values.Registration(*, id, type, config, enabled, config_error, last_attempt_at, last_success_at, last_status, last_error)

Bases: object

A stored source registration with its poll status.

Parameters:

• id (str) – Stable registration id.

• type (str) – Source type.

• config (JsonObject) – Type-specific settings, secrets excluded.

• enabled (bool) – Whether the registration may be polled / pushed to.

• config_error (str | None) – Why the registration is disabled, if invalid.

• last_attempt_at (datetime | None) – Start of the latest poll attempt.

• last_success_at (datetime | None) – Start of the latest fully successful poll.

• last_status (PollStatus) – Outcome of the latest poll.

• last_error (JsonValue) – Error details of the latest poll, if any.

id: str

type: str

config: JsonObject

enabled: bool

config_error: str | None

last_attempt_at: datetime | None

last_success_at: datetime | None

last_status: PollStatus

last_error: JsonValue

class app.storage.values.Revision(*, digest, content, created_at)

Bases: object

An immutable, content-addressed snapshot.

Parameters:

• digest (str) – Digest string (sha256-v1:...).

• content (str) – Canonical text content.

• created_at (datetime) – When the snapshot was first stored.

digest: str

content: str

created_at: datetime

class app.storage.values.RecordWrite(*, source_id, project, path, ref, adr_uuid, record_key, digest, change_token, metadata, title, title_source, decision_date, decision_date_inferred, record_kind, links, rendered_html, issues, source_url=None, author=None, erratum=None)

Bases: object

Everything ingest writes for one record row.

The revision for digest must have been stored first (app.storage.port.CatalogStore.put_revision()).

Parameters:

• source_id (str) – Owning registration id.

• project (str) – Owning project path.

• path (str) – File path inside the project.

• ref (str) – Branch/ref the content came from.

• adr_uuid (UUID | None) – Authored UUID, None if missing or invalid.

• record_key (str) – Identity key (app.domain.values.record_key()).

• digest (str) – Digest string of the current content.

• change_token (str | None) – Source change token (None for pushes).

• metadata (JsonObject) – Parsed frontmatter.

• title (str) – Display title.

• title_source (TitleSource) – Where the title came from.

• decision_date (date | None) – Displayed decision date.

• decision_date_inferred (bool) – Whether the date is only inferred from the filename.

• record_kind (RecordKind) – Decision or erratum.

• links (Links) – Validated outbound links.

• rendered_html (str) – Sanitized HTML rendering of the body.

• issues (tuple[Issue, ...]) – Validation issues.

• source_url (str | None) – Link to the content at the source, if any.

• author (str | None) – Push or commit author, if known.

• erratum (StoredErratum | None) – Rendered erratum content; None for decisions.

source_id: str

project: str

path: str

ref: str

adr_uuid: UUID | None

record_key: str

digest: str

change_token: str | None

metadata: JsonObject

title: str

title_source: TitleSource

decision_date: date | None

decision_date_inferred: bool

record_kind: RecordKind

links: Links

rendered_html: str

issues: tuple[Issue, ...]

source_url: str | None

author: str | None

erratum: StoredErratum | None

property identity: Identity

Logical identity of the record.

Returns:

(source_id, project, record_key).

class app.storage.values.StoredRecord(*, source_id, project, path, ref, adr_uuid, record_key, digest, change_token, metadata, title, title_source, decision_date, decision_date_inferred, record_kind, links, rendered_html, issues, source_url=None, author=None, erratum=None, id, kind, previous_digest, first_seen_at, updated_at, last_seen_at)

Bases: RecordWrite

A stored record row.

Parameters:

• id (UUID) – Surrogate id used in URLs.

• kind (RecordState) – Published or candidate.

• previous_digest (str | None) – Digest before the latest content change.

• first_seen_at (datetime) – When the row was created.

• updated_at (datetime) – When the content digest last changed.

• last_seen_at (datetime) – When ingest last wrote the row.

id: UUID

kind: RecordState

previous_digest: str | None

first_seen_at: datetime

updated_at: datetime

last_seen_at: datetime

class app.storage.values.ErratumRow(*, id, kind, source_id, project, path, ref, adr_uuid, record_key, digest, title, erratum, updated_at, issues)

Bases: object

One erratum row (published or candidate) correcting a decision.

Parameters:

• id (UUID) – Record id.

• kind (RecordState) – Published or candidate.

• source_id (str) – Registration id.

• project (str) – Project path.

• path (str) – File path inside the project.

• ref (str) – Branch/ref of the content.

• adr_uuid (UUID | None) – The erratum’s own UUID, if valid.

• record_key (str) – Identity key of the erratum.

• digest (str) – Current digest.

• title (str) – Display title.

• erratum (StoredErratum | None) – Stored content; None only for a row ingested before content was stored (the next ingest fills it).

• updated_at (datetime) – When the content digest last changed.

• issues (tuple[Issue, ...]) – Validation issues.

id: UUID

kind: RecordState

source_id: str

project: str

path: str

ref: str

adr_uuid: UUID | None

record_key: str

digest: str

title: str

erratum: StoredErratum | None

updated_at: datetime

issues: tuple[Issue, ...]

property identity: Identity

Logical identity of the erratum (approval is keyed by it).

Returns:

(source_id, project, record_key).

class app.storage.values.UpsertResult(*, id, created, digest_changed, previous_digest)

Bases: object

Outcome of a record upsert.

Parameters:

• id (UUID) – Record id.

• created (bool) – True if a new row was inserted.

• digest_changed (bool) – True if an existing row got new content.

• previous_digest (str | None) – The row’s previous digest, if any.

id: UUID

created: bool

digest_changed: bool

previous_digest: str | None

class app.storage.values.ChangeTokenEntry(*, id, project, path, change_token, digest)

Bases: object

Stored change state of one published file.

Parameters:

• id (UUID) – Record id.

• project (str) – Owning project path.

• path (str) – File path inside the project.

• change_token (str | None) – Source change token, if known.

• digest (str) – Current digest.

id: UUID

project: str

path: str

change_token: str | None

digest: str

class app.storage.values.SearchFilters(*, source_id=None, project=None, kind=None, needs_approval=False, record_kind=None)

Bases: object

Search filters; None / False means “no filter”.

Parameters:

• source_id (str | None) – Registration id.

• project (str | None) – Project path.

• kind (RecordState | None) – Published or candidate.

• needs_approval (bool) – Only records whose approval state needs approval (app.domain.approval.evaluate()).

• record_kind (RecordKind | None) – Only decisions or only errata.

source_id: str | None

project: str | None

kind: RecordState | None

needs_approval: bool

record_kind: RecordKind | None

class app.storage.values.SearchItem(*, id, kind, source_id, project, path, ref, adr_uuid, record_key, digest, title, record_kind, decision_date, decision_date_inferred, issues, approval_state, corrects=None)

Bases: object

One search hit.

Parameters:

• id (UUID) – Record id.

• kind (RecordState) – Published or candidate.

• source_id (str) – Registration id.

• project (str) – Project path.

• path (str) – File path inside the project.

• ref (str) – Branch/ref of the content.

• adr_uuid (UUID | None) – Authored UUID, if valid.

• record_key (str) – Identity key.

• digest (str) – Current digest.

• title (str) – Display title.

• record_kind (RecordKind) – Decision or erratum.

• decision_date (date | None) – Displayed decision date.

• decision_date_inferred (bool) – Whether the date is inferred.

• issues (tuple[Issue, ...]) – Validation issues.

• approval_state (ApprovalStateCode) – Approval state of the current digest, computed by the store with the same rules as app.domain.approval.evaluate().

• corrects (UUID | None) – UUID an erratum corrects (None for decisions).

id: UUID

kind: RecordState

source_id: str

project: str

path: str

ref: str

adr_uuid: UUID | None

record_key: str

digest: str

title: str

record_kind: RecordKind

decision_date: date | None

decision_date_inferred: bool

issues: tuple[Issue, ...]

approval_state: ApprovalStateCode

corrects: UUID | None

class app.storage.values.SearchPage(*, items, total, page, page_size)

Bases: object

One page of search results.

Parameters:

• items (tuple[SearchItem, ...]) – Hits on this page.

• total (int) – Number of hits over all pages.

• page (int) – 1-based page number.

• page_size (int) – Requested page size.

items: tuple[SearchItem, ...]

total: int

page: int

page_size: int

class app.storage.values.FacetEntry(*, source_id, project, count)

Bases: object

Row count for one (source_id, project) pair.

Used to populate the source/project filter select in the UI (app.storage.port.CatalogStore.list_facets()); counts include both published and candidate decision rows, never errata.

Parameters:

• source_id (str) – Registration id.

• project (str) – Project path.

• count (int) – Number of rows for this source and project.

source_id: str

project: str

count: int

class app.storage.values.NewDecision(*, identity, adr_uuid, digest, action, actor_issuer, actor_subject, actor_display, actor_email, comment, policy_id, policy_version, provenance=dict())

Bases: object

A decision to append.

Parameters:

• identity (Identity) – Logical identity decided on.

• adr_uuid (UUID) – The record UUID.

• digest (str) – Digest of the decided content.

• action (DecisionAction) – Accepted or rejected.

• actor_issuer (str) – Reviewer token issuer.

• actor_subject (str) – Reviewer token subject.

• actor_display (str | None) – Reviewer display name, if known.

• actor_email (str | None) – Reviewer verified email, if known.

• comment (str | None) – Optional reviewer comment.

• policy_id (str) – Applied policy id.

• policy_version (int) – Applied policy version.

• provenance (JsonObject) – Record id, kind, ref, path and source URL at decision time.

identity: Identity

adr_uuid: UUID

digest: str

action: DecisionAction

actor_issuer: str

actor_subject: str

actor_display: str | None

actor_email: str | None

comment: str | None

policy_id: str

policy_version: int

provenance: JsonObject

class app.storage.values.DecisionEvent(*, identity, adr_uuid, digest, action, actor_issuer, actor_subject, actor_display, actor_email, comment, policy_id, policy_version, provenance=dict(), id, created_at)

Bases: NewDecision

A stored, append-only decision event.

Parameters:

• id (UUID) – Stable event id.

• created_at (datetime) – Server timestamp.

id: UUID

created_at: datetime

as_view()

Convert to the domain view used by approval evaluation.

Return type:

DecisionEventView

Returns:

The event view.

class app.storage.values.IntakeRun(*, id, source_id, kind, identity, delivery_id, started_at, finished_at, status, counts, errors)

Bases: object

One poll or push intake run.

Parameters:

• id (UUID) – Run id.

• source_id (str) – Registration id as requested.

• kind (IntakeKind) – Poll or push.

• identity (JsonValue) – Who triggered the run (no secrets).

• delivery_id (str | None) – Client-supplied push delivery id, if any.

• started_at (datetime) – Start time.

• finished_at (datetime | None) – End time, None while running.

• status (IntakeStatus) – Run status.

• counts (JsonValue) – Outcome counters.

• errors (JsonValue) – Error details.

id: UUID

source_id: str

kind: IntakeKind

identity: JsonValue

delivery_id: str | None

started_at: datetime

finished_at: datetime | None

status: IntakeStatus

counts: JsonValue

errors: JsonValue