Changes between Version 1 and Version 2 of WikiStart

Timestamp:

11/25/25 14:09:42 (5 days ago)

Author:

enno

Comment:

--

WikiStart

@@ -1 @@
-= Welcome to Trac
-
-Trac is a '''minimalistic''' approach to '''web-based''' management of
-'''software projects'''. Its goal is to simplify effective tracking and
-handling of software issues, enhancements and overall progress.
-
-All aspects of Trac have been designed with the single goal to
-'''help developers write great software''' while '''staying out of the way'''
-and imposing as little as possible on a team's established process and
-culture.
-
-As all Wiki pages, this page is editable, this means that you can
-modify the contents of this page simply by using your
-web-browser. Simply click on the "Edit this page" link at the bottom
-of the page. WikiFormatting will give you a detailed description of
-available Wiki formatting commands.
-
-"[wiki:TracAdmin trac-admin] ''yourenvdir'' initenv" created
-a new Trac environment, containing a default set of wiki pages and some sample
-data. This newly created environment also contains
-[wiki:TracGuide documentation] to help you get started with your project.
-
-You can use [wiki:TracAdmin trac-admin] to configure
-[http://trac.edgewall.org/ Trac] to better fit your project, especially in
-regard to ''components'', ''versions'' and ''milestones''.
-
-
-TracGuide is a good place to start.
-
-Enjoy! [[BR]]
-''The Trac Team''
-
-== Starting Points
-
- * TracGuide --  Built-in Documentation
- * [http://trac.edgewall.org/ The Trac project] -- Trac Open Source Project
- * [http://trac.edgewall.org/wiki/TracFaq Trac FAQ] -- Frequently Asked Questions
- * TracSupport --  Trac Support
-
-For a complete list of local wiki pages, see TitleIndex.
+* Overview
+
+`flexoentity` provides the *identity and lifecycle backbone* for all Flex-O components  
+(Flex-O-Grader, Flex-O-Vault, Flex-O-Drill, …).
+
+It defines how entities such as questions, media, catalogs, and exams are *identified, versioned, signed, and verified* — all without any external database dependencies.
+
+At its heart lie two modules:
+
+- =id_factory.py= – robust, cryptographically-verifiable *Flex-O ID generator*
+- =flexo_entity.py= – abstract *base class for all versioned entities*
+
+Together, they form a compact yet powerful foundation for audit-ready, reproducible data structures across offline and air-gapped deployments.
+
+- Design Goals
+
+|----------------|--------------------------------------------------------------------------------------------------------|
+| Goal           | Description                                                                                            |
+|----------------|--------------------------------------------------------------------------------------------------------|
+| *Determinism*  | IDs are derived from canonicalized entity content — identical input always yields identical ID prefix. |
+| *Integrity*    | BLAKE2s hashing and digital signatures protect against manual tampering.                               |
+| *Traceability* | Version numbers (=@001A=, =@002S=, …) track entity lifecycle transitions.                              |
+| *Stability*    | Hash prefixes remain constant across state changes; only version and state suffixes evolve.            |
+| *Auditability* | Every entity can be serialized, verified, and reconstructed without hidden dependencies.               |
+| *Simplicity*   | Pure-Python, zero external libraries, self-contained and easy to embed.                                |
+|----------------|--------------------------------------------------------------------------------------------------------|
+
+* Flex-O ID Structure
+
+Each entity carries a unique *Flex-O ID*, generated by =FlexOID.generate()=.
+
+#+BEGIN_EXAMPLE
+AF-I250101-9A4C2D@003S
+#+END_EXAMPLE
+
+|-----------+-----------------+----------------------------------------------|
+| Segment   | Example         | Meaning                                      |
+|-----------+-----------------+----------------------------------------------|
+| *Domain*  | =AF or PY_LANG= | Uppercase - Logical scope (e.g. "Air Force") |
+| *Type*    | =I=             | Entity type (e.g. ITEM)                      |
+| *Date*    | =250101=        | UTC creation date (YYMMDD)                   |
+| *Hash*    | =9A4C2D4F6E53=  | 12-digit BLAKE2s digest of canonical content |
+| *Version* | =003=           | Sequential version counter                   |
+| *State*   | =S=             | Lifecycle state (D, A, S, P, O)              |
+|-----------+-----------------+----------------------------------------------|
+
+
+* Lifecycle States
+
+|-----------------------|---------|-----------------------------|
+| State                 | Abbrev. | Description                 |
+|-----------------------|---------|-----------------------------|
+| *DRAFT*               | =D=     | Editable, not yet validated |
+| *APPROVED*            | =A=     | Reviewed and accepted       |
+| *APPROVED_AND_SIGNED* | =S=     | Cryptographically signed    |
+| *PUBLISHED*           | =P=     | Released to consumers       |
+| *OBSOLETE*            | =O=     | Archived or replaced        |
+|-----------------------|---------|-----------------------------|
+
+Transitions follow a strict progression:
+#+BEGIN_EXAMPLE
+DRAFT -> APPROVED -> APPROVED_AND_SIGNED -> PUBLISHED -> OBSOLETE
+#+END_EXAMPLE
+
+Only DRAFT entities can be deleted - all others got OBSOLETE mark instead
+
+* Core Classes
+
+** FlexOID
+
+A lightweight immutable class representing the full identity of an entity.
+
+*Highlights*
+- safe_generate(domain, entity_type, estate, text, version=1, repo) -> create a new ID
+- next_version(oid) -> increment version safely
+- clone_new_base(domain, entity_type, estate, text) -> start a new lineage
+- Deterministic prefix, state-dependent signature
+
+** =FlexoEntity=
+Abstract base class for all versioned entities (e.g., Question, Exam, Catalog).
+
+Implements:
+- ID lifecycle management (approve(), sign(), publish(), obsolete())
+- Serialization (to_json(), from_json(), to_dict(), from_dict())
+- Integrity verification (verify_integrity(entity))
+- Controlled state transitions with automatic timestamps
+
+Subclasses define a single property:
+
+#+BEGIN_SRC python
+@property
+def text_seed(self) -> str:
+    """Canonical text or core content for hashing."""
+#+END_SRC
+
+* Integrity Verification
+
+Each entity can self-verify its integrity:
+
+#+BEGIN_SRC python
+entity = Question.with_domain_id(domain_id="AF", text="What is Ohm’s law?", topic="Electronics")
+json_str = entity.to_json()
+reloaded = Question.from_json(json_str)
+
+assert FlexoEntity.verify_integrity(reloaded)
+#+END_SRC
+
+If the file is tampered with (e.g. "Ohm’s" → "Omm’s"), verification fails:
+
+* Real World Example
+
+Below you can see the implementation of a dedicated FlexoEntity class, used for Domains.
+We set an ENTITY_TYPE and define the needed fields in the data class. We define how to create
+a default object, the text_seed (it is easy because the domain id is unique and therefore sufficient)
+and the methods for serialization.
+
+#+BEGIN_SRC python
+from uuid import UUID
+from dataclasses import dataclass
+from flexoentity import FlexOID, FlexoEntity, EntityType
+
+@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"
+
+    @classmethod
+    def default(cls):
+        """Return the default domain object."""
+        return cls.with_domain_id(domain_id="GEN_GENERIC",
+                                  fullname="Generic Domain", classification="UNCLASSIFIED")
+
+    @property
+    def text_seed(self) -> str:
+        return self.domain_id
+
+    def to_dict(self):
+        base = super().to_dict()
+        base.update({
+            "flexo_id": self.flexo_id,
+            "domain_id": self.domain_id,
+            "fullname": self.fullname,
+            "description": self.description,
+            "classification": self.classification,
+        })
+        return base
+
+    @classmethod
+    def from_dict(cls, data):
+        # Must have flexo_id
+        if "flexo_id" not in data:
+            raise ValueError("Domain serialization missing 'flexo_id'.")
+
+        flexo_id = FlexOID(data["flexo_id"])
+
+        obj = cls(
+            fullname=data.get("fullname", ""),
+            description=data.get("description", ""),
+            classification=data.get("classification", "UNCLASSIFIED"),
+            flexo_id=flexo_id,
+            _in_factory=True
+        )
+
+        # Restore metadata
+        obj.origin = data.get("origin")
+        obj.fingerprint = data.get("fingerprint", "")
+        obj.originator_id = (
+            UUID(data["originator_id"]) if data.get("originator_id") else None
+        )
+        obj.owner_id = (
+            UUID(data["owner_id"]) if data.get("owner_id") else None
+        )
+
+        return obj
+#+END_SRC
+        
+* Usage
+#+BEGIN_SRC python
+d = Domain.default()
+print(d.flexo_id)             # GEN_GENERIC-D251124-67C2CAE292CE@001D
+d.approve()
+print(d.flexo_id)             # GEN_GENERIC-D251124-67C2CAE292CE@001A
+d.sign()
+print(d.flexo_id)             # GEN_GENERIC-D251124-67C2CAE292CE@001S
+#+END_SRC
+
+* Serialization Example
+
+to_dict()
+
+#+BEGIN_SRC python 
+{
+    'flexo_id': FlexOID(GEN_GENERIC-D251124-29CE0F4BE59D@001S),
+    'fingerprint': '534BD2EC5C5511F1',
+    'origin': FlexOID(GEN_GENERIC-D251124-67C2CAE292CE@001D),
+    'originator_id': '00000000-0000-0000-0000-000000000000',
+    'owner_id': '00000000-0000-0000-0000-000000000000',
+    'domain_id': 'GEN_GENERIC',
+    'fullname': 'Generic Domain',
+    'description': '',
+    'classification': 'UNCLASSIFIED'}
+#+END_SRC
+
+to_json()
+
+#+BEGIN_SRC js
+{
+        "flexo_id": "GEN_GENERIC-D251124-29CE0F4BE59D@001S",
+        "fingerprint": "534BD2EC5C5511F1",
+        "origin": "GEN_GENERIC-D251124-67C2CAE292CE@001D",
+        "originator_id": "00000000-0000-0000-0000-000000000000",
+        "owner_id": "00000000-0000-0000-0000-000000000000",
+        "domain_id": "GEN_GENERIC",
+        "fullname": "Generic Domain",
+        "description": "",
+        "classification": "UNCLASSIFIED"
+}
+#+END_SRC
+
+
+* Entity Type and State Codes
+
+|-------------+------+----------------------------------------------------------------------------|
+| EntityType  | Code | Typical Use                                                                |
+|-------------+------+----------------------------------------------------------------------------|
+| GENERIC     | G    | Generic entities that does not fit other types yet or are temporarily only |
+| DOMAIN      | D    | Every Domain is of this type                                               |
+| MEDIA       | M    | Every media item belongs to this type, e.g. Pictures, Audio, Video         |
+| ITEM        | I    | An Entity what is usually used in a collection, e.g. Questions in a test   |
+| COLLECTION  | C    | A collection of items, as an Exam or a catalog                             |
+| TEXT        | T    | A text document                                                            |
+| HANDOUT     | H    | A published document                                                       |
+| OUTPUT      | O    | The output of a computation                                                |
+| RECORD      | R    | Record type data, as bibliography entries                                  |
+| SESSION     | S    | A unique session, e.g. managed by a session manager
+| USER        | U    | User objects                                                               |
+| CONFIG      | F    | CONFIG files that need to be tracked over time and state                   |
+| EVENT       | E    | Events that have to be tracked over time, as status messages or orders     |
+| ATTESTATION | X    | Entities that attest a formal technical (not human) check e.g. Signatures  |
+|-------------+------+----------------------------------------------------------------------------|
+
+|---------------------|------|-------------------|
+| EntityState         | Code | Meaning           |
+|---------------------|------|-------------------|
+| DRAFT               | D    | Work in progress  |
+| APPROVED            | A    | Reviewed          |
+| APPROVED_AND_SIGNED | S    | Signed version    |
+| PUBLISHED           | P    | Publicly released |
+| OBSOLETE            | O    | Deprecated        |
+|---------------------|------|-------------------|
+
+* Design Notes
+- *Hash Stability:* Only domain, entity type, and content text influence the hash.
+  This ensures consistent prefixes across state changes.
+- *State-Dependent Signatures:* Each lifecycle stage has its own signature seed.
+  Modifying a file without re-signing invalidates integrity.
+- *Obsolescence Threshold:* Version numbers above 900 trigger warnings;
+  beyond 999 are considered obsolete.
+- *Clone Lineages:* Cloning an entity resets versioning but preserves metadata lineage.
+
+* Dependencies
+- Python 3.11+
+- Standard library only (=hashlib=, =json=, =datetime=, =enum=, =dataclasses=)
+
+No external packages. Fully compatible with *Guix*, *air-gapped* deployments, and *reproducible builds*.
+
+* Integration
+`flexoentity` is imported by higher-level modules such as:
+
+- *Flex-O-Grader* → manages question catalogs and exam bundles
+- *Flex-O-Vault* → provides persistent media storage with metadata integrity
+- *Flex-O-Drill* → uses versioned entities for training simulations
+
+All share the same identity and versioning logic — ensuring that
+*what was approved, signed, and published remains provably authentic.*
+
+* License
+MIT License 2025
+Part of the *Flex-O family* by Flex-O-Dyne GmbH 
+Designed for reproducible, audit-ready, human-centered software.