Models / Persistence

AttributePersistenceDecision

class teksi_hooks.models.persistence.AttributePersistenceDecision(class_id, attribute_id, permitted, metadata=<factory>)

Persistence decision for one changed canonical attribute.

This model records the authorization result only. It does not prescribe how an unpermitted attribute is represented or handled by a persistence adapter.

A model-specific persistence implementation may, for example:

• remove the corresponding source value;

• replace it with NULL;

• restore a mandatory value from live data;

• construct a canonical update directly;

• apply another model-specific strategy.

Parameters:

• class_id (str)

• attribute_id (str)

• permitted (bool)

• metadata (dict[str, Any])

key()

Return the decision key within its parent change decision.

Return type:

tuple[str, str]

Fields

class_id

Type: str

Canonical identifier of the changed attribute’s class to which this persistence decision applies.

attribute_id

Type: str

Canonical identifier of the changed attribute to which this persistence decision applies.

permitted

Type: bool

Whether the provider is permitted to persist the changed canonical attribute.

metadata

Type: dict[str, Any]

Optional model-specific metadata required to implement the persistence decision. This may include source-model provenance, source relation and attribute identifiers, mandatory-value information, mapping references or diagnostic context. Generic persistence logic must not assign semantics to these values.

ChangePersistenceDecision

class teksi_hooks.models.persistence.ChangePersistenceDecision(change, permitted, attribute_decisions=<factory>, metadata=<factory>)

Persistence decision for one object-level canonical change.

A Change describes one inserted, updated or deleted canonical object. Attribute-level changes are derived from its old and new values through Change.changed_attributes.

The object-level permitted decision is primarily applicable to insertion and deletion. Update decisions may additionally contain one AttributePersistenceDecision for each changed canonical attribute.

This model deliberately does not define how insertions, updates or deletions are physically persisted. Those semantics belong to the model-specific persistence implementation.

Parameters:

• change (Change)

• permitted (bool)

• attribute_decisions (tuple[AttributePersistenceDecision, ...])

• metadata (dict[str, Any])

property permitted_attributes: frozenset

Return changed attributes permitted for persistence.

property unpermitted_attributes: frozenset

Return changed attributes not permitted for persistence.

property decided_attributes: frozenset

Return all changed attributes having a persistence decision.

Fields

change

Type: Change

Object-level canonical change being considered for persistence. The change contains the canonical identity, operation, old values and new values.

permitted

Type: bool

Object-level persistence decision. For inserted and deleted objects, this indicates whether the object operation is permitted. For updated objects, attribute-level decisions provide the detailed authorization result for changed attributes.

attribute_decisions

Type: tuple[AttributePersistenceDecision, ...]

Persistence decisions for changed canonical attributes. These decisions are primarily used for updates and should refer only to attributes in Change.changed_attributes.

metadata

Type: dict[str, Any]

Optional model-specific metadata associated with the object-level persistence decision. This may contain source object identities, inheritance information, mapping provenance, cascade information or other data required by a concrete persistence adapter.

ChangePersistenceDocument

class teksi_hooks.models.persistence.ChangePersistenceDocument(job_id, snapshot_id, version=1, decisions=<factory>, metadata=<factory>)

Ordered persistence decisions for one reviewed change snapshot.

The document records authorization decisions independently of any concrete database, INTERLIS implementation or source-model mapping.

Parameters:

• job_id (str)

• snapshot_id (UUID)

• version (int)

• decisions (tuple[ChangePersistenceDecision, ...])

• metadata (dict[str, Any])

Fields

job_id

Type: str

Stable identifier of the review job to which this persistence document belongs.

snapshot_id

Type: UUID

Stable identifier of the immutable reviewed change snapshot to which these persistence decisions apply.

version

Type: int

Version of the persistence-decision document contract. Consumers must reject unsupported versions rather than silently interpreting them using different semantics.

decisions

Type: tuple[ChangePersistenceDecision, ...]

Ordered persistence decisions corresponding to the classified canonical changes.

metadata

Type: dict[str, Any]

Optional document-level metadata. Generic persistence consumers must not rely on model-specific entries.

ChangePersistenceResult

class teksi_hooks.models.persistence.ChangePersistenceResult(change_index, identity, affected_rows, metadata=<factory>)

Result of persisting one accepted canonical change.

The affected-row count describes physical persistence work and therefore may be greater than one for a single canonical object. For example, one canonical change may affect a base table, an extension table and related mapping tables.

Parameters:

• change_index (int)

• identity (CanonicalObjectIdentity)

• affected_rows (int)

• metadata (dict[str, Any])

Fields

change_index

Type: int

Zero-based index of the corresponding decision in ChangePersistenceDocument.decisions.

identity

Type: CanonicalObjectIdentity

Canonical identity of the object whose persistence decision was applied.

affected_rows

Type: int

Number of physical database rows affected while persisting the canonical change. The value may be zero when a model-specific decision intentionally results in no live mutation.

metadata

Type: dict[str, Any]

Optional model-specific result metadata. This may contain affected physical relations, generated identifiers, ignored operations, cascade results or diagnostic information.

DeletionConfirmation

class teksi_hooks.models.persistence.DeletionConfirmation(plan_id, confirmed_at, reviewer_id=None, comment=None)

Explicit reviewer confirmation of one immutable deletion plan.

Parameters:

• plan_id (str)

• confirmed_at (datetime)

• reviewer_id (str | None)

• comment (str | None)

Fields

plan_id

Type: str

Identifier of the confirmed deletion plan.

confirmed_at

Type: datetime

Timestamp when the reviewer confirmed the plan.

reviewer_id

Type: str | None

Optional identifier of the reviewer who confirmed the deletion plan.

comment

Type: str | None

Optional reviewer comment associated with the confirmation.

DeletionPlan

class teksi_hooks.models.persistence.DeletionPlan(plan_id, job_id, snapshot_id, created_at, targets=<factory>, metadata=<factory>)

Immutable plan of permitted canonical deletions awaiting confirmation.

The plan is linked to the diff snapshot and persistence-decision document from which it was produced. Confirming a plan does not bypass current-state validation. Every target must be revalidated before deletion.

Parameters:

• plan_id (str)

• job_id (str)

• snapshot_id (str)

• created_at (datetime)

• targets (tuple[DeletionTarget, ...])

• metadata (dict[str, Any])

Fields

plan_id

Type: str

Stable identifier of this deletion plan.

job_id

Type: str

Logical review-job identifier owning the deletion plan.

snapshot_id

Type: str

Identifier of the immutable diff snapshot from which the deletion decisions were derived.

created_at

Type: datetime

Timestamp when the deletion plan was created.

targets

Type: tuple[DeletionTarget, ...]

Ordered canonical objects proposed for deletion.

metadata

Type: dict[str, Any]

Optional plan-level metadata, such as the persistence strategy or results of a transactional dry run.

DeletionTarget

class teksi_hooks.models.persistence.DeletionTarget(change_index, identity, last_modification=None, metadata=<factory>)

One canonical object proposed for deletion.

The target records the object state observed while the deletion plan was created. A persistence adapter must revalidate this state immediately before executing the deletion.

Parameters:

• change_index (int)

• identity (CanonicalObjectIdentity)

• last_modification (datetime | None)

• metadata (dict[str, Any])

Fields

change_index

Type: int

Zero-based index of the ChangePersistenceDecision from which this deletion target was derived.

identity

Type: CanonicalObjectIdentity

Canonical identity of the object proposed for deletion.

last_modification

Type: datetime | None

Last-modification value observed when the deletion plan was created. This value is used for stale-state detection before the deletion is executed.

metadata

Type: dict[str, Any]

Optional model-specific deletion metadata. This may include physical relation identifiers, mapped source objects, dependent-object information or cascade diagnostics.

PersistenceResult

class teksi_hooks.models.persistence.PersistenceResult(snapshot_id, change_results=<factory>, metadata=<factory>)

Result of atomically persisting a reviewed change set.

A successful result indicates that the model-specific persistence adapter completed its transaction. The concrete adapter remains responsible for defining and enforcing the physical persistence semantics.

Parameters:

• snapshot_id (UUID)

• change_results (tuple[ChangePersistenceResult, ...])

• metadata (dict[str, Any])

property affected_rows: int

Return the total number of affected physical rows.

Fields

snapshot_id

Type: UUID

Stable identifier of the immutable reviewed change snapshot to which these persistence decisions apply.

change_results

Type: tuple[ChangePersistenceResult, ...]

Results for persistence decisions successfully processed by the model-specific persistence adapter.

metadata

Type: dict[str, Any]

Optional transaction-level result metadata. This may include the persistence strategy, application schema, transaction identifier, duration or cleanup information.