Class AuditChainService

src/orgkernel/services/audit_chain_service.py:94–438

Service for AuditChain persistence and querying. All public methods are async and require an ``AsyncSession`` as the first positional argument so the caller controls transaction boundaries. Usage:: svc = AuditChainService() chain_id = await svc.initialize(db, miss

class AuditChainService:
    """
    Service for AuditChain persistence and querying.

    All public methods are async and require an ``AsyncSession`` as the
    first positional argument so the caller controls transaction boundaries.

    Usage::

        svc = AuditChainService()
        chain_id = await svc.initialize(db, mission_id="msn_...", agent_id="aid_...")
        await svc.append(db, chain_id=chain_id, layer=AuditLayer.EXECUTION, event="EXECUTION_tool_call", ...)
        chain = await svc.get_by_mission(db, "msn_...")
        valid = await svc.verify_integrity(db, chain_id)
    """

    async def initialize(
        self,
        db: AsyncSession,
        mission_id: str,
        agent_id: str,
    ) -> str:
        """
        Create a new AuditChain and write the genesis IDENTITY entry.

        Args:
            db: AsyncSession.
            mission_id: Mission this chain belongs to.
            agent_id: Agent that owns this chain.

        Returns:
            The chain_id of the newly created chain.
        """
        # Create chain header
        chain_id = "ac_" + _new_id()
        initialized_at = _now_utc()

        chain_model = AuditChainModel(
            chain_id=chain_id,
            mission_id=mission_id,
            agent_id=agent_id,
            initialized_at=initialized_at,
        )
        db.add(chain_model)

        # Compute genesis entry
        genesis_entry = AuditEntry(
            chain_id=chain_id,
            sequence=0,
            layer=AuditLayer.IDENTITY,
            event="IDENTITY_chain_initialized",
            agent_id=agent_id,
            mission_id=mission_id,
            prev_hash=_GENESIS_HASH,
            data={"initialized_at": initialized_at.isoformat()},
            entry_hash="",  # placeholder
        )
        genesis_hash = _compute_entry_hash(genesis_entry)