yosoi.surface
yosoi.surface
Bounded evidence navigation over Rust-owned immutable surfaces.
Document and video readers never grant browser control. Native references and shared references are distinct types; continuations stay bound to their original observation and operation. Video processing requires the surface-video wheel feature and local FFmpeg/FFprobe executables.
Shared identity and token types accept 1–1,024 UTF-8 bytes with no control characters. Their spelling is opaque and does not establish cross-capture entity identity or permission to act.
Source: python/yosoi/surface.py:1
| Name | Summary |
|---|---|
ActionLease |
Owned one-action permit. Dropping or closing it preserves uncertain dispatch. |
ActionReceipt |
Adapter-reported outcome preserving dispatch uncertainty separately. |
AddressToken |
Producer-issued opaque address bound to its accompanying observation. |
ArchiveLimits |
Retention bounds separate from live history and response budgets. |
ArchivedSource |
Exact source bytes and interpretation, independent of a source file path. |
BrowserSurface |
An isolated live browser with source-specific actions and archive support. |
Budget |
Bounds on the complete Rust JSON result, before a transport envelope. |
Capability |
Advertised operation with explicit read or control access. |
Continuation |
Opaque native-index continuation. Copy it unchanged into the same read. |
ContinuationToken |
Producer-issued opaque continuation bound to a read, scope and observation. |
Coordinate |
Representation-specific locator coordinates retained by the index. |
Coverage |
Source completeness, independent of how many entries fit on a page. |
Cursor |
Owned navigation cursor. Close it to release watches and hot authority. |
CursorState |
Observable cursor status, never a transferable control capability. |
DecodedFrame |
Immutable Rust-owned PNG evidence, restored without a decoder when archived. |
Descriptor |
Continuing source representation and the operations it actually supports. |
Entry |
Representation-neutral hint for choosing the next region to inspect. |
Event |
One retained event with optional cursor, watch and reference provenance. |
EventBatch |
Unread bounded session history with an explicit missed-events flag. |
Expand |
Request direct structural or temporal children of exact evidence. |
FrameArchiveRef |
Normal Archive Document retaining actual PNG bytes and FrameInfo. |
FrameInfo |
Actual PNG provenance, separating requested time from measured source PTS. |
ImageCrop |
Actual PNG evidence cropped from an indexed immutable image region. |
IndexMetadata |
Preparation summary, not a current live-source status. |
Inspect |
Request source-backed text detail, possibly split across chunks. |
Inspection |
Shared source-backed text fragment; it may be incomplete serialized JSON. |
InspectionResult |
Tagged shared detail result. |
Limits |
Task-independent document preparation bounds, enforced by Rust. |
NativeEntry |
One structural routing hint backed by document evidence. |
NativeInspection |
Source-backed detail chunk; concatenate all chunks before parsing JSON. |
NativePage |
A bounded document-index window with explicit paging and coverage. |
NativeReference |
Exact document-index address; it does not grant action permission. |
Observation |
One immutable interpretation of a continuing surface. |
ObservationId |
Rust-validated identity of one immutable interpretation. |
Outcome |
Portable evidence and receipts, without live session or action authority. |
OutcomeRef |
Typed immutable reference selecting an outcome through Archive.read. |
Overview |
Request a bounded set of routing regions. |
Page |
Shared bounded region window; coverage and pagination are independent. |
PageResult |
Tagged shared routing result. |
Parent |
Request a structural parent where that relation is supported. |
ParentResult |
Tagged parent result; a root has no parent. |
PixelRect |
Crop in full decoded-frame pixels; source-video dimensions may differ. |
Position |
Saved navigation state without granting live access or control. |
ReadRequest |
One shared request passed unchanged to either Rust-backed reader. |
Reference |
Representation-neutral evidence address, scoped to one observation. |
Search |
Request literal search when advertised by this representation. |
Session |
In-memory evidence session for an external live adapter. |
SessionPolicy |
Bounds for in-memory readers, subscriptions, history and one hot owner. |
SourceId |
Rust-validated opaque source identity, without access or control authority. |
SourceInterpretation |
Interpreter for an exact document, image or named observation bundle. |
SourceReference |
Binding from a combined index to one original independently captured view. |
Surface |
Reusable immutable index of any supported Document class. |
SurfaceConnection |
Shared lifecycle for a source-specific browser or video connection. |
SurfaceId |
Rust-validated identity of a continuing representation of one source. |
SurfacePolicy |
Evidence retention and output bounds shared across source connections. |
SurfaceRead |
Common pure reading contract; frame decoding and effects are capabilities. |
VideoArchiveRef |
Normal Archive Document retaining source bytes and interpretation profile. |
VideoMetadata |
Primary video stream metadata captured from the frozen source. |
VideoPolicy |
Snapshot and decoder limits. Rust validates the supported combinations. |
VideoSession |
Read-only stateful exploration around a frozen VideoSurface. |
VideoSurface |
Frozen local video with a lazy timeline and read-only frame capabilities. |
WatchState |
One explicit subscription to captured regional evidence. |
WebSurface |
Shared read protocol over an immutable HTML or rendered-DOM index. |
Functions
Section titled “Functions”| Name | Summary |
|---|---|
export |
Package a saved handle into one immutable portable flat file through Rust. |
replay |
Reconstruct a saved handle or portable file without live source processes. |
rerun_browser |
Rerun a sealed browser recipe with explicit source display selection. |
Aliases
Section titled “Aliases”| Name | Summary |
|---|---|
Access |
Whether a capability only reads evidence or may change an external source. |
ActionStatus |
Adapter-reported outcome, kept distinct from whether dispatch occurred. |
ArchivePolicy |
Whether a session retains a bounded portable outcome for explicit Archive saving. |
CursorId |
Session-local diagnostic integer. A copied ID never grants cursor authority. |
EventKind |
Observed session transition; application memory is outside this evidence. |
ExecutionError |
Shared runtime preparation, execution, retention or cleanup failure. |
Freshness |
Evidence status relative to the session, independent of action eligibility. |
ReadOperation |
Tagged navigation operation; capabilities determine which variants are supported. |
ReadResult |
Tagged result of a shared read. Contains evidence, never action authority. |
SurfaceError |
Rust preparation, reference, budget or authority failure with Rust metadata. |
VideoError |
Native video I/O, decoder, timeout, bounds or missing-frame failure. |
WatchId |
Session-local subscription integer, checked against the owning Rust cursor. |