agentengine-sdk-python 0.8.5__py3-none-any.whl → 0.8.6__py3-none-any.whl

ksadk/harness/artifact_adapters/native_page_budget.py

@@ -0,0 +1,172 @@
+"""Optional host-bound capacity for a returned artifact character page.
+
+Selection runs in the effect adapter before sealing. It never mutates storage,
+receipts, permissions, or the model's declared call arguments.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from typing import Callable
+
+from ksadk.harness.native.ports import RunConfiguration, ToolDefinition, ToolRequest, ToolResult
+
+
+class ArtifactPageCapacityError(ValueError):
+    """A valid host binding cannot fit this declared source group."""
+
+    def __init__(self, message, *, source_group_size=None, page_limits=()):
+        super().__init__(message)
+        self.source_group_size = source_group_size
+        self.page_limits = tuple(page_limits)
+
+
+def capacity_error_content(error: ArtifactPageCapacityError | None = None):
+    if error is not None and error.source_group_size is not None:
+        limits = set(error.page_limits)
+        host_only = limits == {"host_payload_bytes"}
+        content = {"code": "artifact_page_budget_unavailable",
+                   "capacity_scope": ("host_tool_result_payload" if host_only
+                                      else "original_declared_source_call_group")}
+        if limits:
+            content["page_limits"] = sorted(limits)
+        if error.source_group_size > 1 and not host_only:
+            content["next_read_shape"] = "fewer_sources_per_call_group"
+        return content
+    # Compatibility for old policies with no declared-group binding.
+    return {"code": "artifact_page_budget_unavailable",
+            "capacity_scope": "original_declared_source_call_group",
+            "next_read_shape": "fewer_sources_per_call_group"}
+
+
+@dataclass(frozen=True)
+class ArtifactPageBudget:
+    max_units: int
+    max_result_units: int
+    count_units: Callable[[str], int]
+    max_payload_bytes: int | None = None
+    source_group_size: int | None = None
+    count_result_message: Callable[[dict], int] | None = None
+    admit_result: Callable[[ToolResult], bool] | None = None
+
+    def __post_init__(self):
+        if not callable(self.count_units):
+            raise ValueError("artifact_page_counter_unavailable")
+        if self.count_result_message is not None and not callable(self.count_result_message):
+            raise ValueError("artifact_page_message_counter_invalid")
+        if self.admit_result is not None and not callable(self.admit_result):
+            raise ValueError("artifact_page_admission_invalid")
+        if self.max_payload_bytes is not None and (
+            type(self.max_payload_bytes) is not int or self.max_payload_bytes < 1024
+        ):
+            raise ValueError("artifact_page_payload_limit_invalid")
+        if self.source_group_size is not None and (
+            type(self.source_group_size) is not int or self.source_group_size < 1
+            or self.max_payload_bytes is None
+        ):
+            raise ValueError("artifact_page_feedback_binding_invalid")
+        invalid = tuple(label for n, label in (
+            (self.max_units, "source_group_units"), (self.max_result_units, "result_group_units")
+        ) if type(n) is not int or n < 1)
+        if invalid:
+            raise ArtifactPageCapacityError(
+                "artifact_page_budget_unavailable", source_group_size=self.source_group_size,
+                page_limits=invalid,
+            )
+
+    def _cost(self, text):
+        cost = self.count_units(text)
+        if type(cost) is not int or cost < 0 or (text and cost == 0):
+            raise ValueError("artifact_page_counter_invalid")
+        return cost
+
+    def _exceeded_limits(self, page: dict, *, check_admission=True) -> tuple[str, ...]:
+        # Tool JSON is itself quoted as message text. Charge real escaped
+        # source, locator and cursor metadata, not just a character count.
+        envelope = json.dumps({"status": "ok", "content": page}, ensure_ascii=False)
+        # ArtifactRead returns no content blocks. Include their empty framing
+        # nevertheless: outer result governance measures this complete payload,
+        # not just the source characters or the model-facing envelope above.
+        exceeded = []
+        if self._cost(page["content"]) > self.max_units:
+            exceeded.append("source_group_units")
+        result_cost = (self.count_result_message(page) if self.count_result_message is not None
+                       else self._cost(json.dumps(envelope, ensure_ascii=False)))
+        if type(result_cost) is not int or result_cost < 1:
+            raise ValueError("artifact_page_counter_invalid")
+        if result_cost > self.max_result_units:
+            exceeded.append("result_group_units")
+        if self.max_payload_bytes is not None:
+            payload = json.dumps(
+                {"status": "ok", "content": page, "content_blocks": []},
+                ensure_ascii=False, sort_keys=True, separators=(",", ":"),
+            )
+            if len(payload.encode("utf-8")) > self.max_payload_bytes:
+                exceeded.append("host_payload_bytes")
+        if (check_admission and self.admit_result is not None
+                and self.admit_result(ToolResult(status="ok", content=page)) is not True):
+            exceeded.append("next_request_units")
+        return tuple(exceeded)
+
+    def fits(self, page: dict, *, check_admission=True) -> bool:
+        return not self._exceeded_limits(page, check_admission=check_admission)
+
+    def unavailable(self, page: dict, *, check_admission=True) -> ArtifactPageCapacityError:
+        return ArtifactPageCapacityError(
+            "artifact_page_budget_unavailable", source_group_size=self.source_group_size,
+            page_limits=self._exceeded_limits(page, check_admission=check_admission),
+        )
+
+    def select(self, page: dict) -> dict:
+        exceeded = set(self._exceeded_limits(page))
+        if not exceeded:
+            return dict(page)
+        text, offset = page["content"], page["offset_chars"]
+
+        def prefix(length):
+            value = {**page, "content": text[:length], "next_offset_chars": offset + length,
+                     "complete": page["complete"] and length == len(text)}
+            if self.source_group_size is not None:
+                value["page_limits"] = sorted(exceeded)
+                if self.source_group_size > 1 and exceeded.difference({"host_payload_bytes"}):
+                    value["next_read_shape"] = "fewer_sources_per_call_group"
+            return value
+
+        while True:
+            low, high = 0, len(text)
+            while low < high:
+                middle = (low + high + 1) // 2
+                if self.fits(prefix(middle)):
+                    low = middle
+                else:
+                    high = middle - 1
+            if not low or not self.fits(prefix(low)):
+                raise self.unavailable(prefix(min(1, len(text))))
+            # Feedback is part of both budgets before sealing. Its framing
+            # can activate another constraint; include that cause and repack.
+            # The cause set only grows and has at most four members.
+            more = set(self._exceeded_limits(prefix(low + 1))) if low < len(text) else set()
+            if self.source_group_size is None or more.issubset(exceeded):
+                return prefix(low)
+            exceeded.update(more)
+
+
+@dataclass(frozen=True)
+class ArtifactPagePolicy:
+    digest: str
+    resolve: Callable[[ToolRequest, tuple[ToolDefinition, ...]], ArtifactPageBudget]
+    bind_configuration: Callable[[RunConfiguration], ArtifactPagePolicy] | None = None
+
+    def __post_init__(self):
+        if (not isinstance(self.digest, str)
+                or not re.fullmatch(r"sha256:[0-9a-f]{64}", self.digest)):
+            raise ValueError("artifact_page_policy_identity_invalid")
+        if not callable(self.resolve):
+            raise ValueError("artifact_page_policy_unavailable")
+        if self.bind_configuration is not None and not callable(self.bind_configuration):
+            raise ValueError("artifact_page_configuration_binding_invalid")
+
+
+__all__ = ["ArtifactPageBudget", "ArtifactPageCapacityError", "ArtifactPagePolicy"]

ksadk/harness/artifact_adapters/native_search.py

@@ -0,0 +1,249 @@
+"""Bounded literal search of a Run's already earned artifact references.
+
+This is the scoped equivalent of searching persisted tool output. It neither
+opens workspace paths nor interprets task semantics or verifies delivery.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+
+from ksadk.harness.native.artifact_search_contract import (
+    ARTIFACT_SEARCH_DEFINITION as ARTIFACT_SEARCH_DEFINITION,
+)
+from ksadk.harness.native.artifact_search_contract import (
+    ARTIFACT_SEARCH_NAME as ARTIFACT_SEARCH_NAME,
+)
+from ksadk.harness.native.ports import (
+    ArtifactPort,
+    ArtifactReadRequest,
+    ToolPort,
+    ToolRequest,
+    ToolResult,
+)
+from ksadk.harness.native.tool_recovery import query_sealed_tool_result
+from ksadk.tools.captured_source_artifact import CAPTURED_SOURCE_MIME, decode_captured_source
+
+from .native_search_budget import search_definition
+
+_MAX_SCAN_BYTES = 1024 * 1024
+_MAX_EXCERPT_CHARS = 8192
+
+
+def _argument_error(args):
+    """Diagnose only public schema constraints, never argument values or keys."""
+    def failure(field, constraint, expected, *, items=False):
+        return {
+            "code": "invalid_artifact_search",
+            "constraint": constraint,
+            "schema_path": (
+                f"/properties/{field}" + ("/items" if items else "") + f"/{constraint}"
+                if field and constraint != "required" else f"/{constraint}"
+            ),
+            **({"field": field} if field else {}),
+            ("expected_type" if constraint == "type" else constraint): expected,
+            "instruction": "Correct arguments against this tool schema before retrying.",
+        }
+
+    if set(args).difference({"uris", "query", "max_matches", "context_chars"}):
+        return failure(None, "additionalProperties", False)
+    for field in ("uris", "query"):
+        if field not in args:
+            return failure(field, "required", True)
+    uris, query = args["uris"], args["query"]
+    if not isinstance(uris, list):
+        return failure("uris", "type", "array")
+    if not 1 <= len(uris) <= 8:
+        return failure("uris", "minItems", 1) if not uris else failure("uris", "maxItems", 8)
+    for uri in uris:
+        if not isinstance(uri, str):
+            return failure("uris", "type", "string", items=True)
+        if not uri:
+            return failure("uris", "minLength", 1, items=True)
+    if len(set(uris)) != len(uris):
+        return failure("uris", "uniqueItems", True)
+    if not isinstance(query, str):
+        return failure("query", "type", "string")
+    if not 1 <= len(query) <= 1024:
+        return (
+            failure("query", "minLength", 1)
+            if not query else failure("query", "maxLength", 1024)
+        )
+    for field, default, low, high in (("max_matches", 16, 1, 16), ("context_chars", 120, 0, 256)):
+        value = args.get(field, default)
+        if type(value) is not int:
+            return failure(field, "type", "integer")
+        if value < low:
+            return failure(field, "minimum", low)
+        if value > high:
+            return failure(field, "maximum", high)
+    return None
+
+
+def _source(text, mime_type=None):
+    """Decode a known source carrier; its metadata remains untrusted tool data."""
+    if mime_type == CAPTURED_SOURCE_MIME:
+        source = decode_captured_source(text)
+        if source is not None:
+            body, path, span = source
+            return body, path, span["start"]
+        return text, None, None
+    try:
+        raw = json.loads(text)["content"]
+        carrier = raw["requested_source"]
+        path, span, body = carrier["path"], carrier["read_range"], carrier["content"]
+        if (
+            raw.get("ok") is True
+            and raw.get("path") == path
+            and isinstance(path, str)
+            and isinstance(body, str)
+            and body
+            and isinstance(span, dict)
+            and set(span) == {"start", "end"}
+            and all(type(v) is int for v in span.values())
+            and 1 <= span["start"] <= span["end"]
+            and len(body.splitlines()) == span["end"] - span["start"] + 1
+        ):
+            return body, path, span["start"]
+    except (ValueError, TypeError, KeyError, AttributeError):
+        pass
+    return text, None, None
+
+
+class NativeArtifactSearchPort:
+    def __init__(self, delegate: ToolPort, artifacts: ArtifactPort, *,
+                 search_policy=None, definitions=()):
+        self.delegate, self.artifacts = delegate, artifacts
+        self.search_policy, self.definitions = search_policy, definitions
+
+    async def _query(self, request, method):
+        return await query_sealed_tool_result(
+            self.delegate,
+            request,
+            owned_names=(ARTIFACT_SEARCH_NAME,),
+            method=method,
+        )
+
+    async def reconcile(self, request):
+        return await self._query(request, "reconcile")
+
+    async def recover_prepared(self, request):
+        return await self._query(request, "recover_prepared")
+
+    async def resume_prepared(self, request):
+        return await self._query(request, "resume_prepared")
+
+    async def resume_checkpoint(self, request):
+        return await self._query(request, "resume_checkpoint")
+
+    async def execute(self, request: ToolRequest) -> ToolResult:
+        if request.call.name != ARTIFACT_SEARCH_NAME:
+            return await self.delegate.execute(request)
+        if request.definition != search_definition(self.search_policy):
+            return ToolResult(status="error", content={"code": "invalid_artifact_search"})
+        args = request.call.arguments
+        error = _argument_error(args)
+        if error is not None:
+            return ToolResult(status="error", content=error)
+        uris, query = args.get("uris"), args.get("query")
+        limit, context = args.get("max_matches", 16), args.get("context_chars", 120)
+        allowed = {ref.uri: ref for ref in request.available_artifacts}
+        if any(uri not in allowed for uri in uris):
+            return ToolResult(status="error", content={"code": "artifact_not_available"})
+        budget = None
+        if self.search_policy is not None:
+            try:
+                budget = self.search_policy.resolve(request, self.definitions)
+            except ValueError:
+                return ToolResult(
+                    status="error", content={"code": "artifact_search_capacity_unavailable"},
+                )
+        results, fingerprints, remaining, characters = [], [], limit, _MAX_EXCERPT_CHARS
+        for uri in uris:
+            ref = allowed[uri]
+            if ref.size_bytes > _MAX_SCAN_BYTES:
+                results.append({"uri": uri, "complete": False, "code": "artifact_search_too_large"})
+                continue
+            try:
+                chunks, offset = [], 0
+                while True:
+                    page = await self.artifacts.read(
+                        ArtifactReadRequest(
+                            scope=request.scope,
+                            run_id=request.run_id,
+                            ref=ref,
+                            offset_chars=offset,
+                            limit_chars=32000,
+                        )
+                    )
+                    if (
+                        page.ref != ref
+                        or page.offset_chars != offset
+                        or page.next_offset_chars != offset + len(page.content)
+                        or len(page.content) > 32000
+                        or (not page.complete and not page.content)
+                    ):
+                        raise ValueError("artifact page mismatch")
+                    chunks.append(page.content)
+                    offset = page.next_offset_chars
+                    if offset > _MAX_SCAN_BYTES:
+                        raise ValueError("artifact scan limit")
+                    if page.complete:
+                        break
+                text = "".join(chunks)
+                encoded = text.encode("utf-8")
+                if len(encoded) != ref.size_bytes or (
+                    "sha256:" + hashlib.sha256(encoded).hexdigest() != ref.content_hash
+                ):
+                    raise ValueError("artifact content mismatch")
+            except Exception:
+                results.append({"uri": uri, "complete": False, "code": "artifact_search_failed"})
+                continue
+            body, path, start = _source(text, ref.mime_type)
+            matches, cursor = [], 0
+            while (found := body.find(query, cursor)) >= 0 and remaining and characters:
+                excerpt = body[max(0, found - context) : found + len(query) + context]
+                clipped = len(excerpt) > characters
+                excerpt = excerpt[:characters]
+                matches.append(
+                    {
+                        "offset_chars": found,
+                        "excerpt": excerpt,
+                        "excerpt_truncated": clipped,
+                        **({"source_line": start + body.count("\n", 0, found)} if start else {}),
+                    }
+                )
+                remaining -= 1
+                characters -= len(excerpt)
+                cursor = found + len(query)
+            complete = body.find(query, cursor) < 0 and not any(
+                m["excerpt_truncated"] for m in matches
+            )
+            item = {
+                "uri": uri,
+                "matches": matches,
+                "complete": complete,
+                "coordinate_space": "captured_source" if path else "artifact",
+            }
+            if path:
+                item["source_path"] = path
+            results.append(item)
+            fingerprints.append([ref.content_hash, query, matches, complete])
+        result = ToolResult(
+            status="ok",
+            content={
+                "observation_type": "scoped-artifact-search/v1",
+                "query": query,
+                "results": results,
+                "complete": all(r["complete"] for r in results),
+            },
+            progress_observation_digest="sha256:"
+            + hashlib.sha256(
+                json.dumps(fingerprints, ensure_ascii=False, sort_keys=True).encode()
+            ).hexdigest()
+            if fingerprints
+            else None,
+        )
+
+        return budget.select(result) if budget is not None else result

ksadk/harness/artifact_adapters/native_search_budget.py

@@ -0,0 +1,134 @@
+"""Host-bound, before-seal Search result selection. No artifact mutation."""
+
+import hashlib
+import json
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import Callable
+
+from ksadk.harness.native.artifact_search_contract import ARTIFACT_SEARCH_DEFINITION
+from ksadk.harness.native.ports import ToolResult
+
+
+def digest(value):
+    return (
+        "sha256:"
+        + hashlib.sha256(json.dumps(value, sort_keys=True, ensure_ascii=False).encode()).hexdigest()
+    )
+
+
+def search_definition(policy):
+    return (
+        ARTIFACT_SEARCH_DEFINITION
+        if policy is None
+        else ARTIFACT_SEARCH_DEFINITION.model_copy(
+            update={
+                "feedback_profile_digest": digest(
+                    {
+                        "search": ARTIFACT_SEARCH_DEFINITION.feedback_profile_digest,
+                        "capacity": policy.digest,
+                    }
+                )
+            }
+        )
+    )
+
+
+@dataclass(frozen=True)
+class ArtifactSearchPolicy:
+    digest: str
+    resolve: Callable
+    bind_configuration: Callable | None = None
+
+    def __post_init__(self):
+        if (
+            not isinstance(self.digest, str)
+            or len(self.digest) != 71
+            or not self.digest.startswith("sha256:")
+            or any(c not in "0123456789abcdef" for c in self.digest[7:])
+            or not callable(self.resolve)
+            or (self.bind_configuration is not None and not callable(self.bind_configuration))
+        ):
+            raise ValueError("artifact_search_policy_invalid")
+
+
+@dataclass(frozen=True)
+class ArtifactSearchBudget:
+    result_message_units: int
+    count_result_message: Callable
+    max_payload_bytes: int
+
+    def __post_init__(self):
+        if (
+            type(self.result_message_units) is not int
+            or not callable(self.count_result_message)
+            or type(self.max_payload_bytes) is not int
+            or not 1024 <= self.max_payload_bytes <= 4 * 1024 * 1024
+        ):
+            raise ValueError("artifact_search_capacity_invalid")
+
+    def fits(self, result):
+        return (
+            self.count_result_message(result) <= self.result_message_units
+            and len(
+                json.dumps(
+                    {"status": result.status, "content": result.content, "content_blocks": []},
+                    ensure_ascii=False,
+                ).encode()
+            )
+            <= self.max_payload_bytes
+        )
+
+    def select(self, result):
+        if self.fits(result):
+            return result
+        content = deepcopy(result.content)
+        content["complete"] = False
+        content["capacity_limited"] = True
+        content["continuation"] = (
+            "Complete original bytes remain at these earned URIs (ArtifactRead)."
+        )
+
+        def candidate():
+            content["complete"] = all(row["complete"] for row in content["results"])
+            return result.model_copy(
+                update={
+                    "content": deepcopy(content),
+                    "progress_observation_digest": digest(content),
+                }
+            )
+
+        # Keep the longest tested original excerpt prefix that fits. Each
+        # candidate is measured in full; tokenizer costs need not be monotonic.
+        # No excerpt is reconstructed or attributed to a different match.
+        originals = [
+            [m.get("excerpt", "") for m in row.get("matches", ())]
+            for row in result.content["results"]
+        ]
+        maximum = max((len(text) for row in originals for text in row), default=0)
+        lengths = []
+        size = maximum // 2
+        while size:
+            lengths.append(size)
+            size //= 2
+        for size in (*lengths, 0):
+            for row, texts in zip(content["results"], originals):
+                for match, text in zip(row.get("matches", ()), texts):
+                    if len(text) > size:
+                        match["excerpt"] = text[:size]
+                        match["excerpt_truncated"] = True
+                        row["complete"] = False
+            value = candidate()
+            if self.fits(value):
+                return value
+        # Drop only visible matches, retaining each original URI and coordinate
+        # system. Empty+complete=false is not a statement that no match exists.
+        for row in reversed(content["results"]):
+            while row.get("matches"):
+                row["matches"].pop()
+                row["complete"] = False
+                value = candidate()
+                if self.fits(value):
+                    return value
+        # The error makes no fit/coverage claim and may leave Context blocked.
+        return ToolResult(status="error", content={"code": "artifact_search_capacity_unavailable"})

ksadk/harness/artifact_adapters/native_store.py

@@ -0,0 +1,115 @@
+"""Scoped Native adapter over the existing local ArtifactStore."""
+
+from __future__ import annotations
+
+import hashlib
+
+from ksadk.harness.artifact_store import ArtifactStore
+from ksadk.harness.native.adapters import _snapshot
+from ksadk.harness.native.ports import (
+    ArtifactReadRequest,
+    ArtifactReadResult,
+    ArtifactRef,
+    ArtifactWriteRequest,
+)
+from ksadk.harness.native.state import RunScope
+
+
+class NativeArtifactStorePort:
+    """Bind one local store to an authenticated scope without a second ledger."""
+
+    def __init__(self, store: ArtifactStore, *, scope: RunScope) -> None:
+        if not isinstance(store, ArtifactStore):
+            raise ValueError("native artifact adapter requires ArtifactStore")
+        self._store = store
+        self._scope = _snapshot(scope)
+        self._scope_key = hashlib.sha256(self._scope.model_dump_json().encode()).hexdigest()[:24]
+
+    def _run_key(self, run_id: str) -> str:
+        digest = hashlib.sha256(run_id.encode()).hexdigest()[:32]
+        return f"{self._scope_key}-{digest}"
+
+    @staticmethod
+    def _ref(record) -> ArtifactRef:
+        return ArtifactRef(
+            uri=record.uri,
+            content_hash=record.content_hash,
+            size_bytes=record.bytes,
+            mime_type=record.mime,
+        )
+
+    async def usage_bytes(self, scope: RunScope, run_id: str) -> int:
+        """Count this Run's durable artifacts, including writes before a crash."""
+        if _snapshot(scope) != self._scope:
+            raise ValueError("artifact scope mismatch")
+        return sum(record.bytes for record in self._store.list(self._run_key(run_id)))
+
+    async def write(self, request: ArtifactWriteRequest) -> ArtifactRef:
+        sealed = _snapshot(request)
+        if sealed.scope != self._scope:
+            raise ValueError("artifact scope mismatch")
+        run_key = self._run_key(sealed.run_id)
+        identity = hashlib.sha256(
+            f"{sealed.operation_key}\0{sealed.tool_call_id}".encode()
+        ).hexdigest()[:48]
+        name = f"tool-result-{identity}"
+        encoded = sealed.content.encode("utf-8")
+        existing = self._store.latest(run_key, name)
+        if existing is not None:
+            ref = self._ref(existing)
+            if (
+                ref.content_hash != "sha256:" + hashlib.sha256(encoded).hexdigest()
+                or ref.size_bytes != len(encoded)
+                or ref.mime_type != sealed.mime_type
+                or self._store.read(existing) != encoded
+            ):
+                raise ValueError("artifact operation identity conflict")
+            return ref
+        record = self._store.save(
+            run_id=run_key,
+            name=name,
+            content=encoded,
+            mime=sealed.mime_type,
+        )
+        return self._ref(record)
+
+    async def read(self, request: ArtifactReadRequest) -> ArtifactReadResult:
+        sealed = _snapshot(request)
+        if sealed.scope != self._scope:
+            raise ValueError("artifact scope mismatch")
+        # Current-turn writes use a scope-prefixed run key. Inherited refs are
+        # allowed only when
+        # the runtime placed their exact typed ref in available_artifacts; this
+        # adapter still requires the same authenticated scope prefix.
+        prefix = f"artifact://{self._scope_key}-"
+        if not sealed.ref.uri.startswith(prefix):
+            raise ValueError("artifact reference is outside the bound scope")
+        records = [
+            record
+            for record in self._store.list(
+                sealed.ref.uri[len("artifact://") :].split("/", 1)[0]
+            )
+            if record.uri == sealed.ref.uri
+        ]
+        if len(records) != 1 or self._ref(records[0]) != sealed.ref:
+            raise ValueError("artifact reference is unknown or changed")
+        encoded = self._store.read(records[0])
+        if len(encoded) != sealed.ref.size_bytes or (
+            "sha256:" + hashlib.sha256(encoded).hexdigest() != sealed.ref.content_hash
+        ):
+            raise ValueError("artifact content integrity mismatch")
+        text = encoded.decode("utf-8")
+        if sealed.offset_chars > len(text):
+            raise ValueError("artifact offset is beyond content")
+        content = text[sealed.offset_chars : sealed.offset_chars + sealed.limit_chars]
+        next_offset = sealed.offset_chars + len(content)
+        return ArtifactReadResult(
+            ref=sealed.ref,
+            content=content,
+            offset_chars=sealed.offset_chars,
+            next_offset_chars=next_offset,
+            complete=next_offset == len(text),
+        )
+
+
+__all__ = ["NativeArtifactStorePort"]