Index: flexoentity/domain.py =================================================================== --- flexoentity/domain.py (revision 5c72356eddc16f354a461320a48eaf1e34225257) +++ flexoentity/domain.py (revision bf30018015014e2dd66ac551665ff6d2d17b5793) @@ -1,16 +1,22 @@ from dataclasses import dataclass -from flexoentity.flexo_entity import FlexOID, FlexoEntity, EntityType, EntityState +from flexoentity import FlexOID, FlexoEntity, EntityType, EntityState @dataclass class Domain(FlexoEntity): + """ + I am a helper class to provide more information than just a + domain abbreviation in FlexOID, doing mapping and management + """ + ENTITY_TYPE = EntityType.DOMAIN + fullname: str = "" description: str = "" classification: str = "UNCLASSIFIED" - owner: str = "unknown" @classmethod def default(cls): - return cls(domain="GEN") + """I return an default instance of myself""" + return cls("GENERIC") def __post_init__(self): @@ -28,12 +34,14 @@ ) - - @property def text_seed(self) -> str: - """Deterministic text seed for ID generation.""" - return f"{self.fullname}|{self.classification}|{self.owner}" + """ + I provide a deterministic text seed for ID generation. + FIXME: There might be a better text seed, json probably + """ + return f"{self.fullname}|{self.classification}|{self.owner_id}" def to_dict(self): + """I return a dictionary representing my state""" base = super().to_dict() base.update({ @@ -41,5 +49,4 @@ "description": self.description, "classification": self.classification, - "owner": self.owner }) return base @@ -47,8 +54,8 @@ @classmethod def from_dict(cls, data): + """I return a new instance of myself, created from state provided by a dictionary""" return cls( fullname=data.get("fullname", ""), description=data.get("description", ""), classification=data.get("classification", "UNCLASSIFIED"), - owner=data.get("owner", "unknown"), ) Index: flexoentity/flexo_entity.py =================================================================== --- flexoentity/flexo_entity.py (revision 5c72356eddc16f354a461320a48eaf1e34225257) +++ flexoentity/flexo_entity.py (revision bf30018015014e2dd66ac551665ff6d2d17b5793) @@ -17,14 +17,14 @@ - state (single capital letter) -- My derived properties (`state`, `entity_type`, `version`) read from that ID. +- My derived properties (state, entity_type, version) read from that ID. They are never stored separately, so I cannot become inconsistent. -- My attributes `origin`, `originator_id`, and `owner_id` express authorship +- My attributes origin, originator_id, and owner_id express authorship and workflow context: - - `origin` links to the FlexOID of the entity I was derived from - - `originator_id` identifies the original creator (UUID) - - `owner_id` identifies the current responsible user or process (UUID) - -- My optional `domain` field is a semantic hint, useful for filtering or + - origin links to the FlexOID of the entity I was derived from + - originator_id identifies the original creator (UUID) + - owner_id identifies the current responsible user or process (UUID) + +- My domain field is a semantic hint, useful for filtering or multi-tenant setups, but the canonical domain remains encoded in my ID. @@ -49,5 +49,5 @@ - My identity never changes; only my content or ownership does. - My lifecycle transitions (approve, sign, publish) are represented by new - FlexOIDs, not by mutating state attributes. + FlexOIDs, not by mutating my own attributes. - My audit trail and access control live in the provenance layer, not the ID. @@ -73,4 +73,8 @@ class EntityType(Enum): + """ + I map a fixed number of entity types to a single unique letter, + that structures different types + """ GENERIC = "G" DOMAIN = "D" @@ -89,14 +93,6 @@ @classmethod def from_letter(cls, a_letter): + """I am a convenience constructor method for EntityType(a_letter)""" return cls(a_letter) - - # FIXME: Add more mappings - def short(self) -> str: - mapping = { - EntityType.MEDIA: "M", - EntityType.DOMAIN: "DOM", - EntityType.CATALOG: "CAT", - } - return mapping[self] # ────────────────────────────────────────────────────────────────────────────── @@ -106,4 +102,5 @@ class EntityState(Enum): + """I describe the life cycle states for all entity types""" DRAFT = "D" APPROVED = "A" @@ -116,21 +113,22 @@ -@dataclass(kw_only=True) +@dataclass() class FlexoEntity(ABC): """ I represent a mutable entity identified by an immutable FlexOID. - My `flexo_id` is the single source of truth for what I am: + My flexo_id is the single source of truth for what I am: - it encodes my domain, entity type, version, and lifecycle state. I never store those values separately, but derive them on demand. I extend the raw identity with provenance and authorship data: - - `origin` → the FlexOID of the entity I was derived from - - `originator_id` → the UUID of the first creator - - `owner_id` → the UUID of the current responsible person or system - - `domain` → optional semantic domain hint (for filtering or indexing) + - origin -> the FlexOID of the entity I was derived from + - originator_id -> the UUID of the first creator + - owner_id -> the UUID of the current responsible person or system + - domain -> FIXME: Explain reasons, why keep domain mutable. semantic + domain hint (for filtering or indexing) I am designed to be traceable and reproducible: - - My identity (`flexo_id`) never mutates. + - My identity (flexo_id) never mutates. - My lifecycle transitions are represented by new FlexOIDs. - My provenance (origin, originator_id, owner_id) can change over time @@ -139,9 +137,10 @@ Behavior ───────── - - `state` and `entity_type` are read-only views derived from my FlexOID. - - `to_dict()` and `from_dict()` serialize me with human-readable fields + - state and entity_type are read-only views derived from my FlexOID. + - to_dict() and from_dict() serialize me with human-readable fields while preserving the canonical FlexOID. - Subclasses (such as questions, media items, or catalogs) extend me with domain-specific content and validation, but not with new identity rules. + - Subclasses have to define a class attribute ENTITY_TYPE to allow specific instance creation I am the living, editable layer that connects identity with accountability. @@ -157,5 +156,5 @@ def with_new_owner(self, new_owner: UUID): - """Return a clone of this entity with a different owner.""" + """I return a clone of this entity with a different owner.""" copy = replace(self) copy.owner_id = new_owner @@ -165,16 +164,22 @@ @abstractmethod def text_seed(self) -> str: - """Canonicalized text used for ID generation.""" + """I provide a canonicalized text used for ID generation.""" raise NotImplementedError("Subclasses must define text_seed property") @property def state(self) -> EntityState: + """I return the state derived from my FlexOID""" return EntityState(self.flexo_id.state_code) @property def entity_type(self) -> EntityType: - return EntityType(self.flexo_id.entity_type) + """I return the entity type derived from my FlexOID""" + return EntityType(self.flexo_id.entity_type) def canonical_seed(self) -> str: + """ + I use a helper method to flatten my text_seed. + NOTE:This might become superfluous when text_seed provides this by itself. Redesign possible + """ return canonical_seed(self.text_seed) @@ -182,9 +187,14 @@ @abstractmethod def default(cls): - """Return a minimal valid instance of this entity (DRAFT state).""" + """I return a minimal valid instance of this entity (in DRAFT state).""" raise NotImplementedError("Subclasses must implement default()") def domain_code(self) -> str: - """Return canonical domain code for serialization and ID generation.""" + """ + I return a canonical domain code for serialization and ID generation. + As domains have their own domain code, I need to distinguish between Domains and + other FlexoEntities to avoid cyclic structures. + FIXME: Write a better comment + """ return self.domain.domain if hasattr(self.domain, "domain") else self.domain @@ -193,6 +203,6 @@ Optionally generate a new FlexOID and fingerprint if none exist. - I check for subclass attributes `ENTITY_TYPE` and `INITIAL_STATE`. - If they exist, I use them to generate a draft FlexOID. + I check for subclass attribute ENTITY_TYPE. + If it exist, I use it to generate a draft FlexOID. Otherwise, I skip ID generation — leaving it to the subclass. """ @@ -202,5 +212,5 @@ return - # Skip if subclass doesn’t declare ENTITY_TYPE / INITIAL_STATE + # Skip if subclass doesn’t declare ENTITY_TYPE or initial state etype = getattr(self.__class__, "ENTITY_TYPE", None) if not etype: @@ -210,9 +220,9 @@ # Generate a new draft FlexOID self.flexo_id = FlexOID.safe_generate( - self.domain_code(), - etype.value, - EntityState.DRAFT.value, - self.text_seed, - 1, + domain=self.domain_code(), + entity_type=etype.value, + estate=EntityState.DRAFT.value, + text=self.text_seed, + version=1, ) @@ -234,4 +244,6 @@ "fingerprint": self.fingerprint, "origin": self.origin, + "originator_id": str(self.originator_id), + "owner_id": str(self.owner_id) } @@ -239,9 +251,5 @@ def from_dict(cls, data): from flexoentity.domain import Domain # avoid circular import - domain = data["domain"] - abbrev, fullname = (lambda p: (p[0], p[1] if len(p) > 1 else ""))(domain.split("_", 1)) - domain_obj = Domain( - domain=abbrev - ) + domain_obj = Domain(data.get("domain", "GENERIC")) obj = cls( domain=domain_obj, @@ -250,13 +258,15 @@ obj.fingerprint = data.get("fingerprint", "") obj.origin = data.get("origin") + obj.originator_id = UUID(int=int(data.get("originator_id", "0"))) + obj.owner_id = UUID(int=int(data.get("owner_id", "0"))) return obj - + def to_json(self, *, indent: int | None = None) -> str: - """Serialize entity (and its FlexOID) into JSON.""" + """I serialize myself (and my FlexOID) into JSON.""" return json.dumps(self.to_dict(), indent=indent, ensure_ascii=False) @classmethod def from_json(cls, data_str: str) -> "FlexoEntity": - """Deserialize from a JSON string.""" + """I create a new instance from a JSON string.""" data = json.loads(data_str) return cls.from_dict(data) @@ -265,5 +275,7 @@ def should_version(state) -> bool: """ - Determine if a given lifecycle state should trigger a version increment. + FIXME: This is now superfluous, because lifecycle changes should not increment + version at all. + I determine if a given lifecycle state should trigger a version increment. Entities typically version when they move into more stable or @@ -277,10 +289,13 @@ ) def _compute_fingerprint(self) -> str: - """Always recompute the entity's content fingerprint.""" + """I always recompute the entity's content fingerprint.""" seed = self.canonical_seed() return hashlib.blake2s(seed.encode("utf-8"), digest_size=8).hexdigest().upper() def _update_fingerprint(self) -> bool: - """Update FlexOID if the content fingerprint changed.""" + """ + FIXME: I am not sure if this is correct behaviour. + I Update FlexOID if the content fingerprint changed. + """ new_fp = self._compute_fingerprint() if new_fp != self.fingerprint: @@ -296,5 +311,5 @@ def _transition(self, target_state: EntityState): """ - Internal helper for state transitions with version/fingerprint checks + I am an internal helper for state transitions with version/fingerprint checks and forward-only enforcement. """ @@ -326,5 +341,5 @@ @property def version(self) -> int: - """Extract numeric version from the FlexO-ID string.""" + """I extract numeric version from the FlexO-ID string.""" try: return int(str(self.flexo_id).rsplit("@", 1)[-1]) @@ -333,9 +348,9 @@ def bump_version(self): - """Increment version number on the ID.""" + """I increment the version number on the ID.""" self.flexo_id = FlexOID.next_version(self.flexo_id) def lineage(self, repo): - """Return full ancestry chain [origin → ... → self].""" + """I return full ancestry chain [origin → ... → self].""" chain = [self] current = self @@ -347,8 +362,7 @@ def approve(self): """ - Move from DRAFT to APPROVED state. + I move from DRAFT to APPROVED state. Draft entities receive a new permanent FlexOID with incremented version. """ - if self.state == EntityState.DRAFT: new_fid = FlexOID.safe_generate(self.domain_code(), @@ -366,6 +380,7 @@ def sign(self): """ - Mark entity as approved and signed without bumping version. + I mark entity as approved and signed without bumping version. Only changes the state letter in the FlexOID. + FIXME: We need a signature here """ if self.state != EntityState.APPROVED: @@ -378,5 +393,5 @@ def publish(self): """ - Move from APPROVED or APPROVED_AND_SIGNED to PUBLISHED. + I move from APPROVED or APPROVED_AND_SIGNED to PUBLISHED. Uses allowed_transitions() to verify legality,