asterstore 0.1.0__py3-none-any.whl

asterstore/__init__.py

@@ -0,0 +1,84 @@
+"""Local data declarations, explicit publication, and lightweight bindings."""
+
+from .errors import (
+    AsterStoreError,
+    CandidateAbandonedError,
+    CandidateStateError,
+    HistoryUnavailableError,
+    InvalidDeclarationError,
+    PublicationConflictError,
+    PublicationNotFoundError,
+    PublicationRetiredError,
+    ReferenceConflictError,
+    ReferenceNotFoundError,
+    RepositoryNotInitializedError,
+    ResourceNotBoundError,
+    StoreCorruptionError,
+    UnknownMemberError,
+    UnsupportedCapabilityError,
+    UnsupportedPlatformError,
+)
+from .governance import (
+    CleanupPreview,
+    CleanupResult,
+    Governance,
+    GovernancePreview,
+    GovernanceResult,
+)
+from .metadata.capabilities import (
+    ByteStability,
+    Capabilities,
+    HistoryAccess,
+    Management,
+    RetentionScope,
+)
+from .metadata.declarations import Declaration
+from .metadata.membership import FileSet, Locator, Member, Object
+from .metadata.protocol import DeclarationRecord, FixedRetention, ObjectRecord, StoreRecord
+from .publishing import Candidate, CandidateStatus
+from .reading import Binding
+from .registration import RegistrationStatus
+from .repository import Repository
+
+__all__ = [
+    "CleanupPreview",
+    "CleanupResult",
+    "FixedRetention",
+    "Governance",
+    "GovernancePreview",
+    "GovernanceResult",
+    "Candidate",
+    "CandidateStatus",
+    "DeclarationRecord",
+    "ObjectRecord",
+    "StoreRecord",
+    "RegistrationStatus",
+    "ResourceNotBoundError",
+    "UnknownMemberError",
+    "UnsupportedCapabilityError",
+    "ByteStability",
+    "Capabilities",
+    "HistoryAccess",
+    "Management",
+    "RetentionScope",
+    "Declaration",
+    "FileSet",
+    "Locator",
+    "Member",
+    "Object",
+    "CandidateAbandonedError",
+    "PublicationRetiredError",
+    "ReferenceConflictError",
+    "ReferenceNotFoundError",
+    "AsterStoreError",
+    "Binding",
+    "CandidateStateError",
+    "InvalidDeclarationError",
+    "HistoryUnavailableError",
+    "PublicationConflictError",
+    "PublicationNotFoundError",
+    "Repository",
+    "RepositoryNotInitializedError",
+    "StoreCorruptionError",
+    "UnsupportedPlatformError",
+]

asterstore/errors.py

@@ -0,0 +1,75 @@
+"""Exceptions exposed by the implemented declaration and binding API."""
+
+
+class AsterStoreError(Exception):
+    """Base class for asterstore errors."""
+
+
+class InvalidDeclarationError(AsterStoreError, ValueError):
+    """A supplied declaration is structurally invalid."""
+
+
+class StoreCorruptionError(AsterStoreError):
+    """Persistent metadata is invalid or inconsistent."""
+
+
+class RepositoryNotInitializedError(AsterStoreError, FileNotFoundError):
+    """The root does not contain an initialized asterstore repository."""
+
+
+class PublicationNotFoundError(AsterStoreError, FileNotFoundError):
+    """The requested committed publication does not exist."""
+
+
+class PublicationConflictError(AsterStoreError):
+    """The publication's base generation or identity conflicts with stored state."""
+
+
+class CandidateStateError(AsterStoreError):
+    """An operation is not valid for the candidate's current state."""
+
+
+class HistoryUnavailableError(AsterStoreError):
+    """A dataset does not promise historical content access."""
+
+
+class UnsupportedPlatformError(AsterStoreError):
+    """The required local filesystem coordination is unavailable."""
+
+
+class ReferenceConflictError(AsterStoreError):
+    """The named reference revision or create request does not match."""
+
+
+class ReferenceNotFoundError(AsterStoreError, KeyError):
+    """The reference name has never been recorded."""
+
+
+class PublicationRetiredError(AsterStoreError):
+    """An identity was committed and irreversibly retired; it cannot be reopened."""
+
+    def __init__(self, dataset_id: str, publication_id: str, operation_id: str) -> None:
+        self.dataset_id = dataset_id
+        self.publication_id = publication_id
+        self.operation_id = operation_id
+        super().__init__(f"publication is retired: {dataset_id}/{publication_id} ({operation_id})")
+
+
+class CandidateAbandonedError(CandidateStateError):
+    """The candidate was permanently abandoned and cannot resume or commit."""
+
+    def __init__(self, operation_id: str) -> None:
+        self.operation_id = operation_id
+        super().__init__(f"candidate is abandoned: {operation_id}")
+
+
+class UnsupportedCapabilityError(AsterStoreError, ValueError):
+    """The declared profile cannot support the requested governance guarantee."""
+
+
+class ResourceNotBoundError(AsterStoreError, KeyError):
+    """A declaration refers to a resource without an explicit root binding."""
+
+
+class UnknownMemberError(AsterStoreError, KeyError):
+    """A requested logical member is absent from the bound declaration."""

asterstore/governance/__init__.py

@@ -0,0 +1,13 @@
+"""Explicit retention, retirement and recoverable collection."""
+
+from ._collection import GovernancePreview, GovernanceResult
+from ._service import Governance
+from .cleanup import CleanupPreview, CleanupResult
+
+__all__ = [
+    "CleanupPreview",
+    "CleanupResult",
+    "Governance",
+    "GovernancePreview",
+    "GovernanceResult",
+]

asterstore/governance/_abandonment.py

@@ -0,0 +1,60 @@
+"""Persist the control evidence needed to interpret irreversible abandonment."""
+
+from pathlib import Path
+
+from asterstore.errors import StoreCorruptionError
+from asterstore.metadata.membership import Object
+from asterstore.metadata.protocol import (
+    DeclarationRecord,
+    ManagedRequest,
+    StoreRecord,
+    decode_declaration_record,
+)
+from asterstore.storage import sync_control_files
+from asterstore.storage.registry import (
+    managed_directory,
+    object_record_path,
+    operation_path,
+    read_object_record,
+    read_operation,
+)
+
+from ._inventory import checked, control_bytes, entries
+
+
+def sync_candidate_evidence(root: Path, store: StoreRecord, request: ManagedRequest) -> None:
+    """Caller holds writer and root locks; missing partial-commit records are allowed.
+
+    This deliberately does not require full inventory: abandonment must remain
+    available after interruption before the initial protection write succeeds.
+    Existing candidate/creator evidence is checked and synced; data bytes are not.
+    """
+    directory = managed_directory(root, request.operation_id)
+    children = set(entries(directory))
+    paths = {root / ".asterstore/format.json", directory / "request.json"}
+    records: dict[str, DeclarationRecord] = {}
+    objects: dict[str, Object] = {}
+    for name in ("sealed.json", "protection.json"):
+        path = directory / name
+        if path not in children:
+            continue
+        record = checked(decode_declaration_record(control_bytes(path, paths)), store)
+        if record != request.declaration_record(record.declaration.files):
+            raise StoreCorruptionError("candidate evidence differs from abandonment request")
+        records[name] = record
+        for obj in record.declaration.files.objects:
+            if obj.object_id in objects and objects[obj.object_id] != obj:
+                raise StoreCorruptionError("candidate evidence has conflicting objects")
+            objects[obj.object_id] = obj
+    operation = read_operation(root, store, request.operation_id)
+    if operation is not None:
+        if operation != records.get("sealed.json"):
+            raise StoreCorruptionError("managed operation lacks matching sealed evidence")
+        paths.add(operation_path(root, request.operation_id))
+    for obj in objects.values():
+        proof = read_object_record(root, store, obj.object_id)
+        if proof is not None:
+            if proof.locator != obj.locator or proof.creator_operation_id is None:
+                raise StoreCorruptionError("candidate object proof conflicts with its declaration")
+            paths.add(object_record_path(root, obj.object_id))
+    sync_control_files(root, tuple(paths))

asterstore/governance/_collection.py

@@ -0,0 +1,178 @@
+"""Coordinated, fixed-plan collection. Only proven owned object files may be deleted."""
+
+from dataclasses import dataclass, replace
+from pathlib import Path
+from typing import Literal
+
+from asterstore.errors import PublicationNotFoundError, StoreCorruptionError
+from asterstore.metadata.capabilities import Management
+from asterstore.metadata.protocol import (
+    DeclarationRecord,
+    GovernancePlan,
+    GovernanceProgress,
+    ObjectRecord,
+    RetiredDeclaration,
+    encode_governance_plan,
+    encode_governance_progress,
+    encode_retired,
+)
+from asterstore.storage import (
+    atomic_write,
+    delete_owned_file,
+    file_lock,
+    immutable_write,
+    sync_control_files,
+)
+from asterstore.storage.registry import (
+    collection_directory,
+    lifecycle_store,
+    managed_data_root,
+    read_governance_plan,
+    read_governance_progress,
+    retired_path,
+    token,
+)
+
+from ._inventory import Inventory, PublicationKey, inventory, key
+
+
+@dataclass(frozen=True, slots=True)
+class GovernancePreview:
+    retiring: tuple[DeclarationRecord, ...]
+    reclaimable: tuple[ObjectRecord, ...]
+    protected_objects: tuple[str, ...]
+    retained_metadata: tuple[PublicationKey, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class GovernanceResult:
+    operation_id: str
+    retired_publications: tuple[PublicationKey, ...]
+    deleted_objects: tuple[str, ...]
+    missing_objects: tuple[str, ...]
+    protected_objects: tuple[str, ...]
+    complete: bool
+
+
+def preview_inventory(view: Inventory) -> GovernancePreview:
+    retiring = tuple(
+        value
+        for identity, value in sorted(view.publications.items())
+        if identity not in view.protected_publications
+        and identity not in view.retired
+        and value.declaration.capabilities.management is Management.MANAGED
+    )
+    reclaimable = tuple(
+        value
+        for oid, value in sorted(view.objects.items())
+        if value.creator_operation_id is not None
+        and oid not in view.protected_objects
+        and oid not in view.collected_objects
+        and oid not in view.cleaned_objects
+    )
+    return GovernancePreview(
+        retiring,
+        reclaimable,
+        tuple(sorted(view.protected_objects)),
+        tuple(sorted(view.retained_metadata)),
+    )
+
+
+def preview(root: Path) -> GovernancePreview:
+    lifecycle_store(root)
+    with file_lock(root / ".asterstore/gc.lock", exclusive=False):
+        return preview_inventory(inventory(root, lifecycle_store(root)))
+
+
+def result(value: GovernanceProgress) -> GovernanceResult:
+    return GovernanceResult(
+        value.operation_id,
+        value.retired,
+        tuple(oid for oid, state in value.outcomes if state == "deleted"),
+        tuple(oid for oid, state in value.outcomes if state == "missing"),
+        tuple(oid for oid, state in value.outcomes if state == "protected"),
+        value.complete,
+    )
+
+
+def execute(root: Path, plan: GovernancePlan, view: Inventory) -> GovernanceResult:
+    progress = read_governance_progress(root, plan)
+    # Persist deletion evidence, including weak publications and candidate roots.
+    sync_control_files(
+        root,
+        tuple(view.control_paths | {collection_directory(root, plan.operation_id) / "plan.json"}),
+    )
+    if progress.complete:
+        return result(progress)
+    retired = set(progress.retired)
+    for publication in plan.retirements:
+        identity = key(publication)
+        if view.publications.get(identity) != publication:
+            raise StoreCorruptionError("planned retirement no longer matches authority")
+        if identity in view.protected_publications:
+            continue
+        if identity not in view.retired:
+            value = RetiredDeclaration(plan.operation_id, publication)
+            immutable_write(retired_path(root, *identity), encode_retired(value), durable=True)
+            view.retired[identity] = value
+        retired.add(identity)
+    progress = replace(progress, retired=tuple(sorted(retired)))
+    outcomes = dict(progress.outcomes)
+    for obj in plan.objects:
+        if obj.object_id in outcomes:
+            continue
+        if view.objects.get(obj.object_id) != obj:
+            raise StoreCorruptionError("planned object no longer matches creator evidence")
+        state: Literal["deleted", "missing", "protected"]
+        if obj.object_id in view.protected_objects:
+            state = "protected"
+        else:
+            # No live published declaration may lose its bytes before retirement is durable.
+            owners = view.object_users.get(obj.object_id, set())
+            if not owners or any(identity not in view.retired for identity in owners):
+                raise StoreCorruptionError("object lacks complete durable retirement evidence")
+            state = (
+                "deleted"
+                if delete_owned_file(managed_data_root(root), obj.locator.relative_path)
+                else "missing"
+            )
+        outcomes[obj.object_id] = state
+        # Geometric checkpoints keep cumulative progress serialization linear in
+        # plan size. A crash between checkpoints is recovered as missing files.
+        count = len(outcomes)
+        if count & (count - 1) == 0:
+            progress = replace(progress, outcomes=tuple(outcomes.items()))
+            atomic_write(
+                collection_directory(root, plan.operation_id) / "progress.json",
+                encode_governance_progress(progress),
+                durable=True,
+            )
+    progress = replace(progress, outcomes=tuple(outcomes.items()), complete=True)
+    atomic_write(
+        collection_directory(root, plan.operation_id) / "progress.json",
+        encode_governance_progress(progress),
+        durable=True,
+    )
+    return result(progress)
+
+
+def collect(root: Path, operation_id: str, *, resume: bool = False) -> GovernanceResult:
+    token(operation_id)
+    lifecycle_store(root)
+    with file_lock(root / ".asterstore/gc.lock", exclusive=True):
+        store = lifecycle_store(root)
+        plan = read_governance_plan(root, store, operation_id)
+        if plan is None and resume:
+            raise PublicationNotFoundError("collection operation does not exist")
+        view = inventory(root, store)
+        if plan is None:
+            selection = preview_inventory(view)
+            plan = GovernancePlan(
+                store.store_id, operation_id, selection.retiring, selection.reclaimable
+            )
+            immutable_write(
+                collection_directory(root, operation_id) / "plan.json",
+                encode_governance_plan(plan),
+                durable=True,
+            )
+        return execute(root, plan, view)