openexit 0.1.0__py3-none-any.whl

openexit/__init__.py

@@ -0,0 +1,20 @@
+"""OpenExit Python SDK for PASP 1.0 directory bundles."""
+
+from .bundle import Bundle
+from .constants import PASP_VERSION
+from .errors import OpenExitError, PaspError
+from .inspection import inspect_bundle, verify_bundle
+from .manifest import parse_manifest
+from .models import (AssetSummary, Consistency, InspectionResult, IntegrityInfo,
+                     Manifest, ProducerInfo, Relationship, RelationshipEndpoint,
+                     Resource, ResourceChunk, Scope)
+from .validation import load_schema, validate_manifest
+from .version import __version__
+
+__all__ = [
+    "PASP_VERSION", "__version__", "OpenExitError", "PaspError",
+    "parse_manifest", "validate_manifest", "inspect_bundle", "verify_bundle",
+    "load_schema", "Bundle", "Scope", "ProducerInfo", "IntegrityInfo", "Consistency",
+    "ResourceChunk", "Resource", "AssetSummary", "RelationshipEndpoint",
+    "Relationship", "Manifest", "InspectionResult",
+]

openexit/bundle.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .inspection import inspect_bundle, verify_bundle
+from .models import InspectionResult
+
+
+@dataclass(frozen=True)
+class Bundle:
+    """A small optional handle for a PASP directory bundle."""
+
+    path: Path
+
+    @classmethod
+    def open(cls, path: str | Path) -> Bundle:
+        return cls(Path(path))
+
+    def inspect(self) -> InspectionResult:
+        return inspect_bundle(self.path)
+
+    def verify(self) -> InspectionResult:
+        return verify_bundle(self.path)

openexit/constants.py

@@ -0,0 +1,2 @@
+PASP_VERSION = "1.0"
+BUNDLE_FORMAT = "openexit.bundle"

openexit/errors.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class OpenExitError(Exception):
+    """Base exception for the OpenExit Python SDK."""
+
+
+class PaspError(OpenExitError):
+    """A PASP validation failure with a stable protocol error code."""
+
+    def __init__(self, code: str, message: str, *, context: Any = None) -> None:
+        self.code = code
+        self.context = context
+        super().__init__(message)

openexit/inspection.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Iterator
+
+from jsonschema import Draft202012Validator, FormatChecker
+from jsonschema.exceptions import SchemaError, ValidationError
+from referencing import Registry
+from referencing.exceptions import NoSuchResource, Unresolvable
+
+from .errors import PaspError
+from .integrity import verify_file, hash_file
+from .manifest import parse_manifest, _reject_non_json_constant
+from .models import (AssetSummary, Consistency, InspectionResult, IntegrityInfo,
+                     ProducerInfo, Resource, ResourceChunk, Scope)
+from .paths import safe_package_path
+from .validation import validate_document, validate_manifest
+
+
+def _json_file(path: Path, code: str) -> Any:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"), parse_constant=_reject_non_json_constant)
+    except (OSError, UnicodeError, ValueError) as exc:
+        raise PaspError(code, f"invalid or missing JSON file: {path}") from exc
+
+
+def _lines(path: Path, code: str) -> Iterator[tuple[int, Any]]:
+    try:
+        with path.open("r", encoding="utf-8") as stream:
+            for number, line in enumerate(stream, 1):
+                if not line.strip():
+                    continue
+                try:
+                    yield number, json.loads(line, parse_constant=_reject_non_json_constant)
+                except ValueError as exc:
+                    raise PaspError(code, f"invalid NDJSON at {path}:{number}") from exc
+    except (OSError, UnicodeError) as exc:
+        raise PaspError(code, f"cannot read NDJSON: {path}") from exc
+
+
+def _no_external_schema(uri: str):
+    raise NoSuchResource(ref=uri)
+
+
+def _schema_for_resource(root: Path, descriptor: dict[str, Any]) -> dict[str, Any]:
+    schema = descriptor["schema"]
+    if isinstance(schema, str):
+        schema_path = safe_package_path(root, schema)
+        if not schema_path.is_file():
+            raise PaspError("PASP_MISSING_SCHEMA", f"missing schema: {schema}")
+        schema = _json_file(schema_path, "PASP_MISSING_SCHEMA")
+    try:
+        Draft202012Validator.check_schema(schema)
+    except SchemaError as exc:
+        raise PaspError("PASP_INVALID_RESOURCE", "invalid record schema") from exc
+    return schema
+
+
+def _resource(root: Path, entry: dict[str, Any], deep: bool) -> Resource:
+    name = entry["name"]
+    descriptor_path = safe_package_path(root, entry["descriptor"])
+    descriptor = _json_file(descriptor_path, "PASP_INVALID_RESOURCE")
+    validate_document("resource", descriptor, "PASP_INVALID_RESOURCE")
+    if descriptor["name"] != name:
+        raise PaspError("PASP_INVALID_RESOURCE", f"descriptor name mismatch: {name}")
+    schema = _schema_for_resource(root, descriptor)
+    chunks = []
+    total_records = 0
+    for index, raw in enumerate(descriptor["chunks"], 1):
+        sequence = raw["sequence"]
+        if sequence != index or raw["path"] != f"resources/{name}/{index:08d}.ndjson":
+            raise PaspError("PASP_INVALID_RESOURCE", f"invalid chunk order/path: {name}")
+        chunk_path = safe_package_path(root, raw["path"])
+        if not chunk_path.is_file():
+            raise PaspError("PASP_INVALID_RESOURCE", f"missing chunk: {raw['path']}")
+        if deep:
+            verify_file(chunk_path, raw["sha256"], raw["uncompressedBytes"])
+            validator = Draft202012Validator(schema, format_checker=FormatChecker(), registry=Registry(retrieve=_no_external_schema))
+            count = 0
+            for line_number, record in _lines(chunk_path, "PASP_INVALID_RECORD"):
+                if not isinstance(record, dict):
+                    raise PaspError("PASP_INVALID_RECORD", f"record is not an object at {raw['path']}:{line_number}")
+                if any(identity not in record for identity in descriptor["identity"]):
+                    raise PaspError("PASP_INVALID_RECORD", f"missing identity at {raw['path']}:{line_number}")
+                try:
+                    validator.validate(record)
+                except (ValidationError, Unresolvable) as exc:
+                    raise PaspError("PASP_INVALID_RECORD", f"record schema failure at {raw['path']}:{line_number}: {exc}") from exc
+                count += 1
+            if count != raw["recordCount"]:
+                raise PaspError("PASP_INVALID_RESOURCE", f"chunk record count mismatch: {raw['path']}")
+        total_records += raw["recordCount"]
+        chunks.append(ResourceChunk(raw["sequence"], raw["path"], raw["recordCount"], raw["uncompressedBytes"], raw["sha256"]))
+    if total_records != descriptor["recordCount"]:
+        raise PaspError("PASP_INVALID_RESOURCE", f"resource record count mismatch: {name}")
+    return Resource(name, descriptor["schema"], tuple(descriptor["identity"]), descriptor["recordCount"], tuple(chunks), entry["descriptor"])
+
+
+def _assets(root: Path, raw: dict[str, Any], deep: bool) -> AssetSummary:
+    summary = AssetSummary(raw["count"], raw["totalBytes"], raw.get("index"))
+    if summary.count == 0 and summary.index is None:
+        return summary
+    index_path = safe_package_path(root, summary.index or "assets/index.ndjson")
+    if not index_path.is_file():
+        raise PaspError("PASP_MISSING_ASSET", "missing asset index")
+    count = total_bytes = 0
+    for _, asset in _lines(index_path, "PASP_MISSING_ASSET"):
+        validate_document("asset", asset, "PASP_MISSING_ASSET")
+        asset_path = safe_package_path(root, asset["path"])
+        if not asset_path.is_file():
+            raise PaspError("PASP_MISSING_ASSET", f"missing asset: {asset['path']}")
+        if deep:
+            verify_file(asset_path, asset["sha256"], asset["byteLength"])
+        count += 1
+        total_bytes += asset["byteLength"]
+    if count != summary.count or total_bytes != summary.total_bytes:
+        raise PaspError("PASP_MISSING_ASSET", "asset summary mismatch")
+    return summary
+
+
+def _relationships(root: Path, reference: str | None, names: set[str]) -> int:
+    if reference is None:
+        return 0
+    rel_path = safe_package_path(root, reference)
+    items = _json_file(rel_path, "PASP_INVALID_RELATIONSHIP")
+    if not isinstance(items, list):
+        raise PaspError("PASP_INVALID_RELATIONSHIP", "relationships must be an array")
+    for item in items:
+        validate_document("relationship", item, "PASP_INVALID_RELATIONSHIP")
+        if item["from"]["resource"] not in names or item["to"]["resource"] not in names:
+            raise PaspError("PASP_INVALID_RELATIONSHIP", "relationship endpoint resource is missing")
+    return len(items)
+
+
+def _checksum_index(root: Path, reference: str | None) -> None:
+    if reference is None:
+        return
+    index = safe_package_path(root, reference)
+    try:
+        with index.open("r", encoding="utf-8") as stream:
+            for number, line in enumerate(stream, 1):
+                if not line.strip():
+                    continue
+                parts = line.rstrip("\r\n").split(maxsplit=1)
+                if len(parts) != 2 or len(parts[0]) != 64 or any(c not in "0123456789abcdef" for c in parts[0]):
+                    raise PaspError("PASP_MALFORMED_PACKAGE", f"invalid checksums index line {number}")
+                entry = safe_package_path(root, parts[1].lstrip())
+                if not entry.is_file():
+                    raise PaspError("PASP_MALFORMED_PACKAGE", f"missing checksummed file: {parts[1]}")
+                actual, _ = hash_file(entry)
+                if actual != parts[0]:
+                    raise PaspError("PASP_CHECKSUM_MISMATCH", f"checksum index mismatch: {parts[1]}")
+    except (OSError, UnicodeError) as exc:
+        raise PaspError("PASP_MALFORMED_PACKAGE", "cannot read checksums index") from exc
+
+
+def _inspect(directory: str | Path, deep: bool) -> InspectionResult:
+    root = Path(directory)
+    if not root.is_dir():
+        raise PaspError("PASP_MALFORMED_PACKAGE", f"not a PASP directory: {root}")
+    manifest_path = safe_package_path(root, "manifest.json")
+    if not manifest_path.is_file():
+        raise PaspError("PASP_MALFORMED_PACKAGE", "missing manifest.json")
+    manifest = parse_manifest(manifest_path)
+    validate_manifest(manifest)
+    value = dict(manifest.raw)
+    names = {entry["name"] for entry in value["resources"]}
+    resources = tuple(_resource(root, entry, deep) for entry in value["resources"])
+    assets = _assets(root, value["assets"], deep)
+    relationships = _relationships(root, value.get("relationships"), names)
+    if deep:
+        _checksum_index(root, value["integrity"].get("checksums"))
+    return InspectionResult(
+        True, value["paspVersion"], value["packageId"], value["exportId"],
+        Scope(**value["scope"]), ProducerInfo(**value["producer"]),
+        Consistency(**value["consistency"]), resources, assets, relationships,
+        IntegrityInfo(**value["integrity"]), deep,
+    )
+
+
+def inspect_bundle(directory: str | Path) -> InspectionResult:
+    """Inspect a directory bundle using metadata and streamed asset index."""
+    return _inspect(directory, False)
+
+
+def verify_bundle(directory: str | Path) -> InspectionResult:
+    """Verify a directory bundle, hashing bytes and streaming records."""
+    return _inspect(directory, True)
+
+

openexit/integrity.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+from .errors import PaspError
+
+
+def hash_file(path: Path) -> tuple[str, int]:
+    """Hash a file in bounded blocks and return (lowercase SHA-256, byte count)."""
+    digest = hashlib.sha256()
+    count = 0
+    with path.open("rb") as stream:
+        while block := stream.read(1024 * 1024):
+            digest.update(block)
+            count += len(block)
+    return digest.hexdigest(), count
+
+
+def verify_file(path: Path, sha256: str, byte_length: int) -> None:
+    actual_hash, actual_length = hash_file(path)
+    if actual_hash != sha256 or actual_length != byte_length:
+        raise PaspError("PASP_CHECKSUM_MISMATCH", f"checksum or length mismatch: {path}", context=str(path))

openexit/manifest.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Mapping
+
+from .errors import PaspError
+from .models import Manifest
+
+
+def _reject_non_json_constant(value: str) -> None:
+    raise ValueError(f"invalid JSON constant: {value}")
+
+
+def parse_manifest(source: Mapping[str, Any] | os.PathLike[str] | str | bytes) -> Manifest:
+    """Parse a mapping, JSON text, UTF-8 bytes, or explicit PathLike file.
+
+    A string is always JSON text. Use pathlib.Path for filesystem input.
+    Parsing does not establish protocol validity; call validate_manifest for that.
+    """
+    try:
+        if isinstance(source, Mapping):
+            value = dict(source)
+        elif isinstance(source, os.PathLike):
+            value = json.loads(Path(source).read_text(encoding="utf-8"), parse_constant=_reject_non_json_constant)
+        elif isinstance(source, bytes):
+            value = json.loads(source.decode("utf-8"), parse_constant=_reject_non_json_constant)
+        elif isinstance(source, str):
+            value = json.loads(source, parse_constant=_reject_non_json_constant)
+        else:
+            raise TypeError("manifest source must be a mapping, PathLike, JSON str, or bytes")
+    except (OSError, UnicodeError, ValueError) as exc:
+        raise PaspError("PASP_INVALID_MANIFEST", "cannot parse manifest JSON") from exc
+    if not isinstance(value, dict):
+        raise PaspError("PASP_INVALID_MANIFEST", "manifest must be a JSON object")
+    return Manifest(value)

openexit/models.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Mapping
+
+
+@dataclass(frozen=True)
+class Scope:
+    type: str
+    id: str
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ProducerInfo:
+    name: str
+    version: str
+
+
+@dataclass(frozen=True)
+class IntegrityInfo:
+    algorithm: str
+    checksums: str | None = None
+
+
+@dataclass(frozen=True)
+class Consistency:
+    level: str
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ResourceChunk:
+    sequence: int
+    path: str
+    record_count: int
+    uncompressed_bytes: int
+    sha256: str
+
+
+@dataclass(frozen=True)
+class Resource:
+    name: str
+    schema: str | Mapping[str, Any]
+    identity: tuple[str, ...]
+    record_count: int
+    chunks: tuple[ResourceChunk, ...]
+    descriptor: str
+
+
+@dataclass(frozen=True)
+class AssetSummary:
+    count: int
+    total_bytes: int
+    index: str | None = None
+
+
+@dataclass(frozen=True)
+class RelationshipEndpoint:
+    resource: str
+    pointer: str
+
+
+@dataclass(frozen=True)
+class Relationship:
+    id: str
+    from_endpoint: RelationshipEndpoint
+    to_endpoint: RelationshipEndpoint
+    cardinality: str
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class Manifest:
+    """Parsed JSON with lossless access to all fields, including future fields."""
+
+    raw: Mapping[str, Any]
+
+    @property
+    def pasp_version(self) -> str | None:
+        return self.raw.get("paspVersion")
+
+    @property
+    def package_id(self) -> str | None:
+        return self.raw.get("packageId")
+
+    @property
+    def export_id(self) -> str | None:
+        return self.raw.get("exportId")
+
+    @property
+    def scope(self) -> Scope | None:
+        data = self.raw.get("scope")
+        if not isinstance(data, dict):
+            return None
+        return Scope(data.get("type"), data.get("id"), data.get("metadata", {}))
+
+
+@dataclass(frozen=True)
+class InspectionResult:
+    valid: bool
+    pasp_version: str
+    package_id: str
+    export_id: str
+    scope: Scope
+    producer: ProducerInfo
+    consistency: Consistency
+    resources: tuple[Resource, ...]
+    assets: AssetSummary
+    relationship_count: int
+    integrity: IntegrityInfo
+    verified: bool

openexit/paths.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path, PurePosixPath
+
+from .errors import PaspError
+
+
+def validate_package_path(value: str) -> None:
+    """Reject unsafe protocol paths before any native filesystem access."""
+    if (not isinstance(value, str) or not value or "\x00" in value or "\\" in value
+            or value.startswith(("/", "~")) or re.match(r"^[A-Za-z]:", value)
+            or any(part in ("", ".", "..") for part in value.split("/"))):
+        raise PaspError("PASP_PATH_TRAVERSAL", f"unsafe package path: {value}")
+    return None
+
+
+def safe_package_path(root: Path, value: str) -> Path:
+    """Resolve a PASP relative path without native-OS path ambiguity."""
+    validate_package_path(value)
+    root_real = root.resolve()
+    candidate = root_real.joinpath(*PurePosixPath(value).parts)
+    try:
+        candidate.resolve().relative_to(root_real)
+    except ValueError as exc:
+        raise PaspError("PASP_PATH_TRAVERSAL", f"path escapes package: {value}") from exc
+    return candidate

openexit/schemas/asset.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openexit.dev/pasp/1.0/schemas/asset.schema.json",
+  "title": "PASP Asset",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "path", "sha256", "byteLength"],
+  "properties": {
+    "id": { "type": "string", "minLength": 1 },
+    "path": { "type": "string", "pattern": "^assets/objects/[A-Za-z0-9][A-Za-z0-9._/-]*$" },
+    "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "byteLength": { "type": "integer", "minimum": 0 },
+    "name": { "type": "string" },
+    "mediaType": { "type": "string" },
+    "metadata": { "type": "object" }
+  }
+}

openexit/schemas/checkpoint.schema.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openexit.dev/pasp/1.0/schemas/checkpoint.schema.json",
+  "title": "PASP Checkpoint",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["resource", "value"],
+  "properties": {
+    "resource": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" },
+    "value": {}
+  }
+}

openexit/schemas/event.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openexit.dev/pasp/1.0/schemas/event.schema.json",
+  "title": "PASP Adapter Event",
+  "type": "object",
+  "required": ["type"],
+  "properties": {
+    "type": { "enum": ["export_begin", "resource_begin", "schema", "record", "checkpoint", "relationship", "asset", "resource_end", "export_end"] },
+    "scope": { "$ref": "scope.schema.json" },
+    "resource": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" },
+    "schema": { "type": "object" },
+    "schemaRef": { "type": "string" },
+    "value": {},
+    "relationship": { "$ref": "relationship.schema.json" },
+    "asset": { "$ref": "asset.schema.json" }
+  },
+  "allOf": [
+    { "if": { "properties": { "type": { "const": "export_begin" } } }, "then": { "required": ["scope"] } },
+    { "if": { "properties": { "type": { "enum": ["resource_begin", "resource_end", "schema", "record", "checkpoint"] } } }, "then": { "required": ["resource"] } },
+    { "if": { "properties": { "type": { "const": "record" } } }, "then": { "required": ["value"] } },
+    { "if": { "properties": { "type": { "const": "checkpoint" } } }, "then": { "required": ["value"] } },
+    { "if": { "properties": { "type": { "const": "relationship" } } }, "then": { "required": ["relationship"] } },
+    { "if": { "properties": { "type": { "const": "asset" } } }, "then": { "required": ["asset"] } }
+  ]
+}

openexit/schemas/inspection-result.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openexit.dev/pasp/1.0/schemas/inspection-result.schema.json",
+  "title": "PASP Inspection Result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["valid", "paspVersion", "resources", "assets", "errors"],
+  "properties": {
+    "valid": { "type": "boolean" },
+    "paspVersion": { "type": "string" },
+    "resources": { "type": "integer", "minimum": 0 },
+    "assets": { "type": "integer", "minimum": 0 },
+    "errors": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["code", "message"], "properties": { "code": { "type": "string", "pattern": "^PASP_[A-Z0-9_]+$" }, "message": { "type": "string" }, "path": { "type": "string" } } } }
+  }
+}

openexit/schemas/manifest.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openexit.dev/pasp/1.0/schemas/manifest.schema.json",
+  "title": "PASP Manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["format", "paspVersion", "packageId", "exportId", "createdAt", "producer", "scope", "consistency", "resources", "assets", "integrity"],
+  "properties": {
+    "format": { "const": "openexit.bundle" },
+    "paspVersion": { "const": "1.0" },
+    "packageId": { "type": "string", "minLength": 1 },
+    "exportId": { "type": "string", "minLength": 1 },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "producer": { "type": "object", "additionalProperties": false, "required": ["name", "version"], "properties": { "name": { "type": "string", "minLength": 1 }, "version": { "type": "string", "minLength": 1 } } },
+    "scope": { "$ref": "scope.schema.json" },
+    "consistency": { "type": "object", "additionalProperties": false, "required": ["level"], "properties": { "level": { "enum": ["snapshot", "bounded", "best_effort"] }, "metadata": { "type": "object" } } },
+    "resources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["name", "descriptor"], "properties": { "name": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" }, "descriptor": { "type": "string", "pattern": "^resources/[A-Za-z0-9][A-Za-z0-9._-]{0,127}/resource\\.json$" } } } },
+    "assets": { "type": "object", "additionalProperties": false, "required": ["count", "totalBytes"], "properties": { "count": { "type": "integer", "minimum": 0 }, "totalBytes": { "type": "integer", "minimum": 0 }, "index": { "type": "string", "const": "assets/index.ndjson" } } },
+    "integrity": { "type": "object", "additionalProperties": false, "required": ["algorithm"], "properties": { "algorithm": { "const": "sha256" }, "checksums": { "type": "string", "const": "checksums.sha256" } } },
+    "relationships": { "type": "string", "const": "relationships.json" }
+  }
+}

openexit/schemas/relationship.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openexit.dev/pasp/1.0/schemas/relationship.schema.json",
+  "title": "PASP Relationship",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "from", "to", "cardinality"],
+  "properties": {
+    "id": { "type": "string", "minLength": 1 },
+    "from": { "$ref": "#/$defs/endpoint" },
+    "to": { "$ref": "#/$defs/endpoint" },
+    "cardinality": { "enum": ["one-to-one", "one-to-many", "many-to-one", "many-to-many", "reference"] },
+    "metadata": { "type": "object" }
+  },
+  "$defs": {
+    "endpoint": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["resource", "pointer"],
+      "properties": {
+        "resource": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" },
+        "pointer": { "type": "string", "pattern": "^(/([^/~]|~[01])*)*$" }
+      }
+    }
+  }
+}

openexit/schemas/resource-chunk.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openexit.dev/pasp/1.0/schemas/resource-chunk.schema.json",
+  "title": "PASP Resource Chunk",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["sequence", "path", "recordCount", "uncompressedBytes", "sha256"],
+  "properties": {
+    "sequence": { "type": "integer", "minimum": 1 },
+    "path": { "type": "string", "pattern": "^resources/[A-Za-z0-9][A-Za-z0-9._-]{0,127}/[0-9]{8}\\.ndjson$" },
+    "recordCount": { "type": "integer", "minimum": 0 },
+    "uncompressedBytes": { "type": "integer", "minimum": 0 },
+    "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "firstIdentity": {},
+    "lastIdentity": {},
+    "completedAt": { "type": "string", "format": "date-time" }
+  }
+}
+
+

openexit/schemas/resource.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openexit.dev/pasp/1.0/schemas/resource.schema.json",
+  "title": "PASP Resource",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["name", "schema", "identity", "recordCount", "chunks"],
+  "properties": {
+    "name": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" },
+    "schema": { "oneOf": [{ "type": "string", "pattern": "^schemas/[A-Za-z0-9._/-]+\\.schema\\.json$" }, { "type": "object" }] },
+    "schemaId": { "type": "string", "minLength": 1 },
+    "schemaVersion": { "type": "string", "minLength": 1 },
+    "identity": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+    "recordCount": { "type": "integer", "minimum": 0 },
+    "chunks": { "type": "array", "items": { "$ref": "resource-chunk.schema.json" } },
+    "ordered": { "type": "boolean" },
+    "metadata": { "type": "object" },
+    "capturedAt": { "type": "string", "format": "date-time" },
+    "snapshotToken": { "type": "string" }
+  }
+}

openexit/schemas/scope.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openexit.dev/pasp/1.0/schemas/scope.schema.json",
+  "title": "PASP Scope",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["type", "id"],
+  "properties": {
+    "type": { "type": "string", "minLength": 1 },
+    "id": { "type": "string", "minLength": 1 },
+    "metadata": { "type": "object" }
+  }
+}

openexit/validation.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from importlib import resources
+from typing import Any, Mapping
+
+from jsonschema import Draft202012Validator, FormatChecker
+from jsonschema.exceptions import SchemaError, ValidationError
+from referencing import Registry, Resource
+
+from .constants import PASP_VERSION
+from .errors import PaspError
+from .manifest import parse_manifest
+from .models import Manifest
+from .paths import validate_package_path
+
+
+@lru_cache(maxsize=None)
+def load_schema(name: str) -> dict[str, Any]:
+    """Load a canonical PASP schema bundled with the installed wheel."""
+    if name not in {"manifest", "scope", "resource", "resource-chunk", "asset", "relationship", "checkpoint", "event", "inspection-result"}:
+        raise ValueError(f"unknown PASP schema: {name}")
+    resource = resources.files("openexit.schemas").joinpath(f"{name}.schema.json")
+    return json.loads(resource.read_text(encoding="utf-8"))
+
+
+@lru_cache(maxsize=1)
+def _registry() -> Registry:
+    registry = Registry()
+    for name in ("manifest", "scope", "resource", "resource-chunk", "asset", "relationship", "checkpoint", "event", "inspection-result"):
+        schema = load_schema(name)
+        registry = registry.with_resource(schema["$id"], Resource.from_contents(schema))
+    return registry
+
+
+def validate_document(name: str, value: Any, code: str) -> None:
+    try:
+        schema = load_schema(name)
+        Draft202012Validator(schema, registry=_registry(), format_checker=FormatChecker()).validate(value)
+    except (ValidationError, SchemaError) as exc:
+        raise PaspError(code, f"invalid {name}: {exc.message}") from exc
+
+
+def validate_manifest(manifest: Manifest | Mapping[str, Any]) -> None:
+    """Validate PASP 1.0 manifest against the packaged canonical JSON Schema."""
+    value = manifest.raw if isinstance(manifest, Manifest) else manifest
+    if not isinstance(value, Mapping):
+        raise PaspError("PASP_INVALID_MANIFEST", "manifest must be an object")
+    version = value.get("paspVersion")
+    if isinstance(version, str) and version != PASP_VERSION:
+        raise PaspError("PASP_UNSUPPORTED_VERSION", f"unsupported PASP version: {version}")
+    entries = value.get("resources")
+    if isinstance(entries, list):
+        seen: set[str] = set()
+        import re
+        for entry in entries:
+            if not isinstance(entry, dict) or not isinstance(entry.get("name"), str) or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]{0,127}", entry["name"]):
+                raise PaspError("PASP_INVALID_RESOURCE", "invalid resource name")
+            if entry["name"] in seen:
+                raise PaspError("PASP_DUPLICATE_RESOURCE", f"duplicate resource: {entry['name']}")
+            seen.add(entry["name"])
+            if isinstance(entry.get("descriptor"), str):
+                validate_package_path(entry["descriptor"])
+    validate_document("manifest", dict(value), "PASP_INVALID_MANIFEST")

openexit/version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

openexit-0.1.0.dist-info/METADATA

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: openexit
+Version: 0.1.0
+Summary: Python SDK for OpenExit and the PASP portable application state protocol.
+Author: OpenExit contributors
+License-Expression: MIT
+Keywords: data portability,PASP,application state,export,openexit
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jsonschema<5,>=4.18
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: build<2,>=1; extra == "dev"
+Requires-Dist: twine<7,>=6; extra == "dev"
+Dynamic: license-file
+
+# OpenExit
+
+> Portable state for any application.
+
+This package implements PASP — the Portable Application State Protocol — for Python. OpenExit is the implementation and ecosystem; PASP 1.0 is the language-neutral protocol. SDK version 0.1.0 is separate from protocol version 1.0.
+
+## Install
+
+```bash
+pip install openexit
+```
+
+## Inspect and verify
+
+```python
+from openexit import inspect_bundle, verify_bundle
+
+bundle = inspect_bundle("./acme.pasp")
+print(bundle.pasp_version)
+print(bundle.scope)
+print(bundle.resources)
+
+verified = verify_bundle("./acme.pasp")
+print(verified.verified)
+```
+
+`inspect_bundle` reads the manifest, descriptors, relationship metadata, and asset index. `verify_bundle` additionally streams all resource records and asset bytes, checks record schemas and identities, counts, and SHA-256 hashes. Both accept directory bundles.
+
+## Manifest validation
+
+```python
+from pathlib import Path
+from openexit import parse_manifest, validate_manifest
+
+manifest = parse_manifest(Path("./acme.pasp/manifest.json"))
+validate_manifest(manifest)  # returns None or raises PaspError
+```
+
+`parse_manifest` also accepts a mapping, JSON text, or UTF-8 JSON bytes. A string is treated as JSON text; pass a `Path` to read a file. Parsing does not imply validation. Models retain the raw manifest fields. Protocol errors expose a stable `code`:
+
+```python
+from openexit import PaspError
+
+try:
+    verify_bundle("./acme.pasp")
+except PaspError as exc:
+    print(exc.code)
+```
+
+## Protocol source
+
+The canonical PASP definition is in the repository at `protocol/pasp/v1/`; the shared suite is `protocol/pasp/v1/conformance/suite.json`. Installed wheels contain exact copies of the canonical JSON Schemas and do not require the repository at runtime.
+
+## Current limits
+
+This SDK reads PASP 1.0 directory bundles. It does not export or import application state, run adapters, execute external processes, unpack archives, or check full referential integrity. Inspection and verification use bounded file reads; one NDJSON record or metadata file is parsed at a time. Symlinks that leave the bundle root are rejected.

openexit-0.1.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+openexit/__init__.py,sha256=9PQaOvpnAI6EgaDLvxJl9ad5HjJ6OREycH4AUFDwwGc,930
+openexit/bundle.py,sha256=TXQkHcG8Pkn2KWOkx0t0oWjSlPNGa198qwZZzoDtlBo,570
+openexit/constants.py,sha256=l-75VsakOWnPtbpz7y2Tu8fYeR_xtoO6zs7qWfwjHAY,55
+openexit/errors.py,sha256=pfx1ucJoEgGWjUHoIBjH5xx65Q_e0pkbebg6Wygw2KI,424
+openexit/inspection.py,sha256=GPAN2gOkNNOiQGScumKfp8gxTL6l7gnuPziN_Htw7mg,9221
+openexit/integrity.py,sha256=biWhIv5dqiMvM34rhbUrFbnsQlZ-UXPYShsO97SOkhI,760
+openexit/manifest.py,sha256=1tuwoinDyLlvSAoATZ7UE30TJmtMWT5gpbo8fIsWqRA,1515
+openexit/models.py,sha256=tF2Oxxf1dUwbpJxz-q4wmvvfARpgjkp-jWIwDoD_W8A,2313
+openexit/paths.py,sha256=bz_M62ymvWVO5tTGfXg8dUHrTTN3F8ofaIRwxvXguVo,1034
+openexit/validation.py,sha256=Wsh7WVgqZhvMqc5oG1VtP_Ijy3mbRtR_MdfJF3gKDI4,2961
+openexit/version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+openexit/schemas/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+openexit/schemas/asset.schema.json,sha256=InNjsAWFW-JjfXYfqCKQ019tq9VKRzBn4mLOlaMjTbc,658
+openexit/schemas/checkpoint.schema.json,sha256=BL32CzybrrAZUvf6r4Nzzv7srvBmgfizgo202fh2xJ4,383
+openexit/schemas/event.schema.json,sha256=u8k6IISxh_jSsw0N6zLyurXTq21LQk4lN5D7hhpzXcE,1424
+openexit/schemas/inspection-result.schema.json,sha256=DC9QKA0s7lyDshTxI9OcTIG723X-wl-pJUtwrPPO7Zo,784
+openexit/schemas/manifest.schema.json,sha256=NJQJ57hPG8BF6gaWL5qnx7bOsNnC1todANPJ7rfbjlc,2029
+openexit/schemas/relationship.schema.json,sha256=sem7eLmvDLkmN-6ewbLPyVGnzG3S28aOB0vsZ4m5L_8,917
+openexit/schemas/resource-chunk.schema.json,sha256=nIMqw1OARH8Oe1H5PAnwx0s9NIwSIt-5iu4A4PCi0MA,796
+openexit/schemas/resource.schema.json,sha256=eO-Y-N2ZVifCucB0R0rPtZw-zw6eU8-GuyLAkVlsRfY,1058
+openexit/schemas/scope.schema.json,sha256=hNEPaG0DCLTJDMF8rMSVzHOk5DrUBej__8UXQJOrnjs,398
+openexit-0.1.0.dist-info/licenses/LICENSE,sha256=nftgLgoUyqC-kr1DBtrR4QuX_5aZhLN-gmXcMoTyCoI,1078
+openexit-0.1.0.dist-info/METADATA,sha256=sT0qKO0v5jjAR-piizvZkwVJiI7WU2gBBARyQKrUlE4,3151
+openexit-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+openexit-0.1.0.dist-info/top_level.txt,sha256=g__fyluRYNFCGPUZE9MuhLhhgpfgdzKIXTIJTvNvqH4,9
+openexit-0.1.0.dist-info/RECORD,,

openexit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

openexit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenExit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

openexit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+openexit