osyra_ome.gated

Private pre-release / network boundary: The currently usable customer surface is offline verification of an existing signed artifact against an out-of-band trust anchor. Memory/network RPC APIs and host snippets on this page describe protocol and interface shape; the public Edge bridge, package publication, and release acceptance remain pending. Do not treat api.osyra.ai:443 examples as a released customer route.

Attested-memory-gate producer client (ENG-2547 S6 / ADR-284 D1+D8).

The OSYRA SDK memory-I/O producer. Routes an agent's memory reads/writes through the attested-memory GATE — the edge's ``gatedMemoryWrite`` / ``gatedMemoryRead`` GraphQL mutations (AP00001-edge), which proxy AP00011-ome's ``GatedMemoryWrite`` / ``GatedMemoryRead``. The gate re-decides cap ∧ policy ∧ attestation and records an ``amgate_decisions`` row (admit OR deny) the attested-memory-I/O dashboard renders.

Why a SEPARATE client (not ``OmeClient.memory``): the gate is a different surface than the ``SignAndInsert`` claim path — a different transport (edge GraphQL over HTTP, NOT OME gRPC), a different endpoint, and a different trust model (the edge holds the mTLS service identity the gate RPCs require; an SDK cannot reach them directly). Keeping it standalone leaves the gRPC client untouched.

A policy DENY is a normal RESULT, not an error: ``gated_write`` returns ``committed=False`` / ``gated_read`` returns ``admitted=False`` with the decision so the caller (and the dashboard) sees the enforcement. Only transport / auth / malformed-response failures raise.

HONEST-SCOPE (ADR-177 D5): channel-enforcement — which reads are admitted (input-provenance)

• which writes are committed (output-receipt) — NOT a claim about model cognition.

Classes

class GatedCapabilityGrant

Bases: BaseModel

One delegated-capability grant: the agent may perform ``action`` on ``key``.

The §3 L1 capability leg. ``action`` is ``"read"`` | ``"write"``.

Attributes

| Name | Type | Default | | --- | --- | --- | | action | str | | | key | str | |

class GatedDecision

Bases: BaseModel

The sanitized gate decision projection (mirrors the edge ``AmgateDecision`` type).

Every field is carried on the wire — the SDK fabricates nothing. ``allowed`` is the admit/deny verdict; ``stage`` / ``code`` / ``reason`` explain it (``reason`` is server-sanitized and never leaks secrets).

Attributes

| Name | Type | Default | | --- | --- | --- | | allowed | bool | | | code | str | | | decision_id | str | Field(alias='decisionId') | | key | str | | | op | str | | | reason | str | | | stage | str | | | timestamp | str | |

class GatedMemoryClient

A producer client for the attested-memory gate over the edge GraphQL surface.

Construct with the edge GraphQL URL + the same bearer JWT the gRPC ``OmeClient`` uses; the edge derives the workspace server-authoritatively from that token. Pass an ``http_client`` to inject a custom (or mock) transport; otherwise the client owns one and closes it on :meth:`close` / context exit.

Methods

__init__

def __init__(self, edge_url: str, *, token: str | None = None, workspace_id: str | None = None, timeout_seconds: float = DEFAULT_TIMEOUT_SECONDS, http_client: httpx.Client | None = None) -> None

close

def close(self) -> None

Close the owned HTTP client (a no-op for an injected ``http_client``).

gated_read

def gated_read(self, key: str, *, capability: list[GatedCapabilityGrant] | None = None, source_kind: str | None = None) -> GatedReadResult

Read ``key`` through the attested-memory READ-gate.

Returns the gate outcome (``admitted`` + the base64-decoded ``value`` iff admitted + the decision). A denied read returns ``admitted=False`` / ``value=None`` — not an exception. The confused-deputy request-supplied key/epoch probe is intentionally unreachable from this surface (the schema has no such field).

gated_write

def gated_write(self, key: str, value: bytes, *, capability: list[GatedCapabilityGrant] | None = None) -> GatedWriteResult

Commit ``value`` at ``key`` through the attested-memory WRITE-gate.

Returns the gate outcome (``committed`` + the decision). A policy deny returns ``committed=False`` — NOT an exception. Raises :class:`OmeAuthError` / :class:`OmeTransportError` / etc. on auth / transport / malformed-response failures.

class GatedReadResult

Bases: BaseModel

The outcome of a gated read.

``value`` is present iff ``admitted`` (a denied read carries none).

Attributes

| Name | Type | Default | | --- | --- | --- | | admitted | bool | | | decision | GatedDecision | | | value | bytes | None | |

class GatedWriteResult

Bases: BaseModel

The outcome of a gated write. A denied write is a provable no-op (``committed=False``).

Attributes

| Name | Type | Default | | --- | --- | --- | | committed | bool | | | decision | GatedDecision | | | epoch | str | |