aeat.application.storage_write_policy module¶

Runtime write-policy decisions for operator command dispatch.

The CLI root asks inspect_storage_write_policy() before opening profile-bound storage. The returned StorageWritePolicyDecision combines the matched StorageWritePolicyCode with the StorageRouteKind derived from Settings.

This module is the application-side policy query, not the session opener. It classifies the dispatched verb path, honours bootstrap-exempt CLI surfaces, delegates stub-only Modelo work-create refusals to the leaf handler, and refuses profile-bound mutations when storage is routed to the root fallback database or to an explicit AEAT_DATABASE_URL. A stale settings object with a valid active-profile pointer is reclassified through settings_for_active_profile_bucket() so the root callback sees the same active-bucket route the storage runtime would use.

See also

aeat.entrypoints.cli: Root command callback that reconstructs verb paths, consults this policy, and opens active bucket sessions only after the policy allows dispatch.
aeat.entrypoints.cli._bootstrap_exempt.is_bootstrap_exempt(): Supplies the sessionless bootstrap flag passed into inspect_storage_write_policy().
aeat.core.config.classify_storage_route(): Produces the StorageRouteClassification inspected for guarded mutation paths.
aeat.core.storage_route_guidance.EXPLICIT_DATABASE_URL_PROFILE_RECOVERY: Operator recovery text attached to explicit database URL refusals.

class StorageWritePolicyCode(*values)[source]¶

Bases: StrEnum

Machine-readable outcomes from the root write-policy query.

The values distinguish allowed active-bucket writes, read-only or bootstrap-exempt paths, leaf-owned refusals, and the two route-level denials the CLI root must stop before opening profile storage. Each value is carried in the code field of StorageWritePolicyDecision, returned from inspect_storage_write_policy().

ALLOWED_ACTIVE_BUCKET¶

BOOTSTRAP_EXEMPT¶

LEAF_REFUSAL_DELEGATED¶

NON_PROFILE_BOUND_VERB¶

NO_VERB_PATH¶

REFUSED_ROOT_FALLBACK¶

REFUSED_EXPLICIT_DATABASE_URL¶

class StorageWritePolicyDecision(**data)[source]¶

Bases: BaseModel

Decision returned by the backend storage write-policy query.

The CLI root converts refusing decisions into CliRefusedBoundaryError instances; allowed decisions let dispatch continue toward the active-bucket session opener.

Variables:

allowed – Whether root dispatch may continue.
code – The StorageWritePolicyCode that determined the result.
profile_bound_write – Whether the verb path matched the guarded profile-bound mutation catalogue.
bootstrap_exempt – Whether the CLI root classified the invocation as bootstrap-exempt before policy inspection.
route_kind – Effective StorageRouteKind for guarded writes, or None when no route was inspected.
message_key – Locale key for a refusal message rendered at the CLI boundary.
detail_message_key – Optional nested detail key for the refusal message.
recovery_hint – Structured operator recovery hint for the error envelope.

Parameters:

allowed (bool)
code (StorageWritePolicyCode)
profile_bound_write (bool)
bootstrap_exempt (bool)
route_kind (StorageRouteKind | None)
message_key (str)
detail_message_key (str)
recovery_hint (str)

allowed: bool¶

code: StorageWritePolicyCode¶

profile_bound_write: bool¶

bootstrap_exempt: bool¶

route_kind: StorageRouteKind | None¶

message_key: str¶

detail_message_key: str¶

recovery_hint: str¶

render_refusal_message(*, locale=None)[source]¶

Render the translated user-facing refusal message through tr().

Return type:: str
Parameters:: locale (str | None)

refusal_context()[source]¶

Return structured context for CliRefusedBoundaryError.

Return type:: dict[str, str] | None

PROFILE_BOUND_WRITE_VERB_PATHS: tuple[str, ...]¶

Profile-bound mutation verb prefixes guarded by the root write policy.

is_profile_bound_write_verb_path() matches this catalog by prefix after the CLI root reconstructs the Typer verb path. The catalog is separate from BOOTSTRAP_EXEMPT_VERB_PATHS: bootstrap-exempt verbs skip the active-session gate, while these prefixes identify commands that must be routed through an active profile bucket before they can mutate profile-bound storage.

inspect_storage_write_policy(verb_path, *, bootstrap_exempt, settings=None, argv_tokens=None)[source]¶

Return whether verb_path may perform profile-bound writes.

Bootstrap-exempt and non-profile-bound paths are allowed without route inspection. Guarded mutation paths are allowed only when the effective storage route is an active bucket; root fallback and explicit database routes return refusing StorageWritePolicyDecision values before the CLI opens a bucket session. The effective route comes from StorageRouteClassification so root dispatch does not duplicate storage-routing logic.

See also

PROFILE_BOUND_WRITE_VERB_PATHS: Guarded mutation catalog consulted by this policy query.
is_bootstrap_exempt(): Source of the bootstrap_exempt input from the CLI root.
is_profile_bound_write_verb_path(): Prefix matcher used before route classification.

Return type:

StorageWritePolicyDecision

Parameters:

verb_path (str | None)
bootstrap_exempt (bool)
settings (Settings | None)
argv_tokens (Sequence[str] | None)

is_profile_bound_write_verb_path(verb_path)[source]¶

Return whether verb_path names a profile-bound mutation surface.

Matching is prefix-based against PROFILE_BOUND_WRITE_VERB_PATHS so positional arguments appended by Click/Typer reconstruction do not hide a guarded operator command.

Return type:: bool
Parameters:: verb_path (str)