Define schema authority and durable store refinements

docs/schema.md

@@ -0,0 +1,416 @@
+# Lazaret schemas
+
+This document is the normative design schema for Lazaret records. The
+[specification](specification.md) defines their physical use, while the TLA+
+models define lifecycle and ordering above the implementation abstraction. The
+diagrams define logical fields, variants, and relationships; they do not select a
+programming-language representation.
+
+## Domain Store
+
+```mermaid
+classDiagram
+    class DomainStore
+
+    class StoreMetadata {
+        schema_id
+        schema_version
+    }
+
+    class Domain {
+        domain_id
+        profile_name
+        canonical_workspace
+    }
+
+    class Generation {
+        domain_id
+        generation_id
+        configuration_fingerprint
+        coordinator_id
+        network_sidecar_id
+        sandbox_id
+        durable_decision
+    }
+
+    class Participant {
+        generation_id
+        role
+        state
+        ownership
+    }
+
+    class ParticipantState {
+        <<enumeration>>
+        Intent
+        LeaseHeld
+        Prepared
+        Committed
+        ReleaseIntent
+        Clean
+    }
+
+    class ParticipantOwnership {
+        <<union>>
+        PreparedLower
+        StateAnchor
+        GitRouting
+        Network
+        Helper
+        Sandbox
+        Publication
+    }
+
+    class Session {
+        generation_id
+        session_id
+        cli_id
+        session_anchor_id
+        session_phase
+    }
+
+    class Mailbox {
+        generation_id
+        identity_path
+        inbox_path
+        outbox_path
+        state
+    }
+
+    DomainStore "1" *-- "1" StoreMetadata
+    DomainStore "1" *-- "1" Domain
+    Domain "1" --> "0..*" Generation
+    Generation "1" --> "0..*" Participant
+    Participant --> ParticipantState
+    Participant --> ParticipantOwnership
+    Generation "1" --> "0..*" Session
+    Generation "1" --> "0..1" Mailbox
+    Mailbox --> ParticipantState
+```
+
+`durable_decision` and `session_phase` contain values defined by the application
+protocol model. This schema records them without redefining either state machine.
+Each store carries its own schema identity and version.
+
+### Participant ownership
+
+```mermaid
+classDiagram
+    class ParticipantOwnership {
+        <<union>>
+    }
+
+    class ProcessIdentity {
+        pid
+        start_time
+    }
+
+    class NamespaceIdentity {
+        device
+        inode
+    }
+
+    class MountIdentity {
+        mount_id
+        device
+        inode
+    }
+
+    class PreparedLowerOwnership {
+        prepared_artifact_id
+        source_identity
+        lease_state
+        path
+        device
+        inode
+    }
+
+    class StateAnchorOwnership {
+        lower_artifact_id
+        upper_path
+        work_path
+        merged_path
+        daemon
+        mount
+    }
+
+    class GitRoutingOwnership {
+        mountpoint
+        host_root
+        isolated_root
+        daemon
+        mount
+    }
+
+    class NetworkOwnership {
+        derived_policy_digest
+        readiness_fingerprint
+        readiness_evidence
+        namespace
+        runtime_supervisor
+    }
+
+    class HelperOwnership {
+        network_sidecar_id
+        connectivity_helper
+        runtime_supervisor
+    }
+
+    class SandboxOwnership {
+        container_id
+        runtime_root
+        bundle_digest
+        host_coordinator
+        runtime_supervisor
+        attached_runsc
+    }
+
+    class PublicationOwnership {
+        socket_path
+        identity_path
+    }
+
+    ParticipantOwnership --> PreparedLowerOwnership
+    ParticipantOwnership --> StateAnchorOwnership
+    ParticipantOwnership --> GitRoutingOwnership
+    ParticipantOwnership --> NetworkOwnership
+    ParticipantOwnership --> HelperOwnership
+    ParticipantOwnership --> SandboxOwnership
+    ParticipantOwnership --> PublicationOwnership
+    StateAnchorOwnership --> ProcessIdentity : daemon
+    StateAnchorOwnership --> MountIdentity : mount
+    GitRoutingOwnership --> ProcessIdentity : daemon
+    GitRoutingOwnership --> MountIdentity : mount
+    NetworkOwnership --> NamespaceIdentity : namespace
+    NetworkOwnership --> ProcessIdentity : runtime_supervisor
+    NetworkOwnership --> NetworkReadinessEvidence : readiness_evidence
+    HelperOwnership --> ProcessIdentity : connectivity_helper
+    HelperOwnership --> ProcessIdentity : runtime_supervisor
+    SandboxOwnership --> ProcessIdentity : host_coordinator
+    SandboxOwnership --> ProcessIdentity : runtime_supervisor
+    SandboxOwnership --> ProcessIdentity : attached_runsc
+```
+
+## Storage Catalog
+
+```mermaid
+classDiagram
+    class StorageCatalog
+
+    class StoreMetadata {
+        schema_id
+        schema_version
+    }
+
+    class PreparedArtifact {
+        prepared_artifact_id
+        source_identity
+        selected_manifest_digest
+        policy_id
+        id_map_digest
+        path
+        device
+        inode
+        state
+    }
+
+    class ArtifactState {
+        <<enumeration>>
+        Available
+        Reclaiming
+    }
+
+    class ArtifactLease {
+        prepared_artifact_id
+        domain_id
+        generation_id
+    }
+
+    class PrepareOperation {
+        operation_id
+        expected_artifact_id
+        source_identity
+        stage_path
+        device
+        inode
+    }
+
+    StorageCatalog "1" *-- "1" StoreMetadata
+    StorageCatalog "1" *-- "0..*" PreparedArtifact
+    StorageCatalog "1" *-- "0..*" ArtifactLease
+    StorageCatalog "1" *-- "0..*" PrepareOperation
+    PreparedArtifact --> ArtifactState
+    PreparedArtifact "1" --> "0..*" ArtifactLease
+    PrepareOperation "0..*" --> "0..1" PreparedArtifact : publishes
+```
+
+An artifact lease identifies one prepared artifact, Domain, and generation. Its
+Domain and generation fields correspond to a Domain Store generation; the stores
+do not form one transactional database.
+
+`ReleaseIntent` is a physical recovery state. It does not redefine the modeled
+lease lifecycle: the specification defines how Domain Store release intent,
+physical unmount, and Storage Catalog lease removal refine model unmount and
+release actions.
+
+## Derived network policy
+
+```mermaid
+classDiagram
+    class DerivedNetworkPolicy {
+        schema_id
+        address_families
+        default_actions
+        prefix_rules
+        resolvers
+    }
+
+    class AddressFamilyDisposition {
+        family
+        disposition
+    }
+
+    class DefaultAction {
+        family
+        action
+    }
+
+    class PrefixRule {
+        family
+        network
+        action
+    }
+
+    class Resolver {
+        family
+        address
+    }
+
+    class AddressFamily {
+        <<enumeration>>
+        IPv4
+        IPv6
+    }
+
+    class PolicyAction {
+        <<enumeration>>
+        Allow
+        Deny
+    }
+
+    DerivedNetworkPolicy "1" *-- "2" AddressFamilyDisposition
+    DerivedNetworkPolicy "1" *-- "1..2" DefaultAction
+    DerivedNetworkPolicy "1" *-- "0..*" PrefixRule
+    DerivedNetworkPolicy "1" *-- "1..*" Resolver
+    AddressFamilyDisposition --> AddressFamily
+    DefaultAction --> AddressFamily
+    DefaultAction --> PolicyAction
+    PrefixRule --> AddressFamily
+    PrefixRule --> PolicyAction
+    Resolver --> AddressFamily
+```
+
+The policy has exactly one disposition for each address family. Each enabled
+family has exactly one default action. Prefixes and addresses are canonical, and
+equal-prefix action conflicts are invalid. Policy identity is the SHA-256 digest
+of its canonical form with a schema-specific domain separator.
+
+## Network readiness
+
+```mermaid
+classDiagram
+    class NetworkReadinessEvidence {
+        domain_id
+        generation_id
+        network_sidecar_id
+        readiness_fingerprint
+    }
+
+    class NetworkReadinessAttestation {
+        schema_id
+        domain_id
+        generation_id
+        configuration_fingerprint
+        network_sidecar_id
+        derived_policy_digest
+        enforcement_namespace
+        runtime_supervisor
+        connectivity_helper
+        observation
+    }
+
+    class NetworkObservation {
+        policy_delivery
+        helper_ready
+        observed_routes
+        routes_attested
+    }
+
+    class PolicyDelivery {
+        <<enumeration>>
+        SealedMemfd
+    }
+
+    class NetworkReadinessIdentity {
+        schema_id
+        domain_id
+        generation_id
+        configuration_fingerprint
+        network_sidecar_id
+        derived_policy_digest
+        enforcement_namespace
+    }
+
+    class NamespaceIdentity {
+        device
+        inode
+    }
+
+    class ProcessIdentity {
+        pid
+        start_time
+    }
+
+    class NetworkReachabilityProbe {
+        domain_id
+        generation_id
+        enforcement_namespace
+    }
+
+    class DeniedDestinationObservation {
+        destination
+        unreachable
+    }
+
+    class PermittedDestinationObservation {
+        destination
+        reachable
+    }
+
+    class DnsObservation {
+        resolver
+        query_name
+        resolved_addresses
+    }
+
+    NetworkReadinessEvidence --> NetworkReadinessAttestation : accepts
+    NetworkReadinessEvidence --> NetworkReadinessIdentity : fingerprints
+    NetworkReadinessEvidence --> NetworkReachabilityProbe : includes
+    NetworkReadinessAttestation --> NamespaceIdentity : enforcement_namespace
+    NetworkReadinessAttestation --> ProcessIdentity : runtime_supervisor
+    NetworkReadinessAttestation --> ProcessIdentity : connectivity_helper
+    NetworkReadinessAttestation --> NetworkObservation
+    NetworkObservation --> PolicyDelivery
+    NetworkReadinessIdentity --> NamespaceIdentity : enforcement_namespace
+    NetworkReadinessAttestation ..> NetworkReadinessIdentity : projects
+    NetworkReachabilityProbe --> NamespaceIdentity : enforcement_namespace
+    NetworkReachabilityProbe "1" *-- "1..*" DeniedDestinationObservation
+    NetworkReachabilityProbe "1" *-- "1..*" PermittedDestinationObservation
+    NetworkReachabilityProbe "1" *-- "1..*" DnsObservation
+```
+
+The readiness fingerprint is the SHA-256 digest of the canonical readiness
+identity with a schema-specific domain separator. Process identities and network
+observations are attestation evidence but are not part of that fingerprint. The
+Host Coordinator binds the accepted attestation and generation-bound reachability
+probe into Network Readiness Evidence before publication.