cadrumo.domain.user_profile.values module

Strict Pydantic value records for centralized user profiles.

The portable-export bundle (UserProfilePortableExport) lives in the sibling portable_export module so its heavy domain-type imports do not enter sys.modules at user-profile package init.

declared_provenance_sources(schema)[source]

Return the provenance tokens declared by schema.

The schema is an explicit input now. This helper deliberately performs no authority or filesystem lookup; callers that need a profile schema must obtain it from their pinned authority generation first.

Return type:

frozenset[str]

Parameters:

schema (ProfileSchemaDefinition)

section_field_key(path)[source]

Reduce a fact path to the section.field form the schema declares.

A repeatable section addresses its rows by index (activities.0.iae_epigraph), and the schema declares the field once rather than per row, so the index is dropped before the declared set is consulted.

Return type:

str

Parameters:

path (str)

class ProfileSetupState(*values)[source]

Bases: StrEnum

The only current fact-record readiness state.

INCOMPLETE
COMPLETE
new_profile_id()[source]

Mint a fresh immutable profile identity.

A profile’s identity is a generated UUIDv4 in the canonical hyphenated 36-character form. It is created once at profile creation and never changes — the bucket directory, keystore directory, secure-object key, and active-profile pointer all key on it. The operator-chosen display name is a fully decoupled mutable label with no role in any key or path.

Return type:

str

new_profile_snapshot_id(profile_id, *, created_at=None)[source]

Create a deterministic-shape but unique snapshot id.

Return type:

str

Parameters:
class UserProfileFact(**data)[source]

Bases: BaseModel

One effective-dated user-profile fact.

Parameters:

  • path (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=3, max_length=192, pattern=^[a-z][a-z0-9_]*(?:\.(?:[0-9]+|[a-z][a-z0-9_]*))+$, ascii_only=None)])

  • value (UserProfileFactValue)

  • source (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=80, pattern=None, ascii_only=None)])

  • valid_from (date | None)

  • valid_to (date | None)

path: _FieldPath
value: UserProfileFactValue
source: _Source
valid_from: date | None
valid_to: date | None
validate_profile_schema_identity(schema_id, schema_version, *, schema, surface)[source]

Refuse payload schema metadata that is not exactly the current schema.

schema_id and schema_version name the authority a persisted payload claims to have been written under, and both were free: any non-empty id and any integer at or above one validated, were hashed into the canonical snapshot digest, and were read back later as if current. An unknown authority is not a value with a typo in it – it is a record asserting a contract nothing in this codebase defines.

Both halves are pinned to exactly what the supplied schema declares, so the two failure directions refuse alike. A FUTURE version was written by something newer than this code, so reading it as current understates what the payload means. A PRE-CURRENT version was written under a contract this code no longer implements, and accepting it silently is read-tolerance for a shape nothing here is entitled to interpret – the more dangerous of the two, because it produces a plausible profile rather than an error. Neither is repaired on the read path: the refusal names the claimed version and the canonical one so the payload can be rewritten under the current schema.

Return type:

None

Parameters:
validate_profile_fact(fact, *, schema)[source]

Validate schema-dependent provenance for one already-typed fact.

Return type:

None

Parameters:
class UserProfileRecord(**data)[source]

Bases: BaseModel

The current typed fact record, without label or removal projections.

Parameters:

data (Any)

schema_id: str
schema_version: PayloadSchemaVersion
profile_id: _ProfileId
facts: tuple[UserProfileFact, ...]
setup_state: ProfileSetupState
record_revision: int
previous_record_digest: ContentDigest | None
content_digest: ContentDigestOrAbsent
created_at: UtcInstant
updated_at: UtcInstant
class UserProfileSnapshot(**data)[source]

Bases: BaseModel

Immutable filing/export profile snapshot.

Parameters:

data (Any)

snapshot_id: _SnapshotId
profile_id: _ProfileId
schema_id: str
schema_version: PayloadSchemaVersion
created_at: UtcInstant
facts: tuple[UserProfileFact, ...]
canonical_hash: ContentDigest
classmethod from_profile(profile, *, context, snapshot_id=None, created_at=None)[source]

Create an immutable snapshot from a live profile record.

Parameters:

  • profile (UserProfileRecord) – The UserProfileRecord to snapshot.

  • context (ProfileCreateContext) – The pinned schema context for this creation operation.

  • snapshot_id (str | None) – Optional explicit snapshot identifier; when None a deterministic id is derived from the profile state.

  • created_at (datetime | None) – Optional UTC timestamp stamped on the snapshot; defaults to the core UTC clock when None.

Return type:

UserProfileSnapshot

Returns:

An immutable UserProfileSnapshot for the given profile.

create_user_profile_record(*, context, profile_id, facts=(), setup_state, record_revision=1, previous_record_digest=None, content_digest='', created_at=None, updated_at=None)[source]

Create a profile record under one pinned compiled schema.

This is the only production creation door. It stamps the schema identity supplied by the authority and validates every fact against that same immutable declaration. It never consults the bundled TOML loader.

Return type:

UserProfileRecord

Parameters:
decode_user_profile_record(payload, *, context)[source]

Decode a secure profile record against the operation-pinned schema.

Return type:

UserProfileRecord

Parameters:
create_user_profile_snapshot(profile, *, context, snapshot_id=None, created_at=None)[source]

Create an immutable encrypted-persistence snapshot under one schema.

Core types: UserProfileRecord.

Return type:

UserProfileSnapshot

Parameters: