@modelprofile.com/browser-runtime 5.1.0 → 5.2.0

package/readme.hints.md

@@ -1,60 +0,0 @@
-# readme.hints.md
-
-Durable implementation findings for `@modelprofile.com/browser-runtime`.
-
-## Ownership and lifecycle
-
-- Host-runtime liveness is owned by SmartIPC `NamedMutex` using a namespace bound to the UID and secured runtime-directory device, inode, and path hash. Its permanent private `runtime.mutex` anchor directory and file stay on the runtime directory's trusted local filesystem. Clean native contention is `LOCKED`; backend, anchor, lock, or release uncertainty is `FENCED`.
-- Persistent, fsynced `runtime.lock` metadata is a downgrade fence, not the live mutex, and is never removed by normal shutdown. Every start owns one metadata-named generation containing private profile and artifact roots.
-- Metadata-generation recovery performs no lock-descriptor scan. It removes only the exact named generation after checking every same-UID process for an absolute `--user-data-dir` equal to or below that profile root; this check is process-generic, not Chromium-specific.
-- Process ownership comes from all four `/proc/<pid>/status` `Uid:` values, not `/proc/<pid>` directory ownership. Only an exact same-UID or definite other-UID classification is actionable; mixed, unreadable, malformed, symlinked, wrongly owned/mode, hard-linked, ambiguous, or uncontained ownership state remains fenced.
-- An empty process command line triggers one status revalidation. A conclusively departed PID (both status and PID directory missing), definite other UID, or exact same-UID zombie is clear. A still-present PID with missing/unreadable status, ambiguous UID, or malformed/duplicate state remains fenced; exit between command-line and status reads does not block startup.
-- Legacy zero-byte locks alone use SmartIPC's consuming kernel probe for other read/write open descriptions. Adoption additionally requires birth, change, and modification timestamps strictly before bounded `/proc/stat` `btime`, plus no same-UID process using the exact or descendant legacy profile root. After an exclusive probe, Runtime reopens and revalidates the exact original inode, ownership, mode, link count, zero size, and timestamps. Probe contention is locked; probe or reopen uncertainty, same-boot, malformed, or ambiguous state remains fenced against the 3.2 close-before-unlink race. `O_PATH` descriptors do not contend.
-- A clean 3.2 stopped layout has no lock and may retain private empty top-level profile and artifact roots. The native-mutex winner validates, process-checks, and removes only those roots. Before metadata fsync succeeds, failure cleanup may unlink only the exact lock inode that acquisition just created; preexisting locks are never removed.
-- Shutdown attempts artifact and ownership cleanup after peer, revocation, or resource failures, retains retryable local slot state, and blocks restart until that state clears. Automatic ownership-loss cleanup gets one bounded retry; stale active metadata remains a fail-closed recovery fence.
-- Controller durable truth is a logical resource with immutable `projectId`, stable random `browserResourceId`, and a revisioned attachment binding. Runtime state is process-local and must be re-registered after every restart.
-- A resource slot owns its browser incarnation, transition mutex, generations, exact participant leases, shared bounded FIFO, independent viewer frame windows, authenticated egress proxy, private profile, and idle timer. Joining or releasing a participant does not change the resource arbitration generation.
-- `terminateResource()` and idle termination remove only the incarnation. They preserve registration, attachment, capabilities, and artifacts. `retireResource()` permanently fences, revokes, terminates, purges exact-resource artifacts, then unregisters only after all cleanup succeeds. Durable retirement remains Controller truth; Runtime tombstones are bounded and process-local.
-- Failed retirement retains a fenced, retryable registration. Unknown profile, lock, or artifact ownership remains fail closed.
-- Launch quota admission uses synchronous pending reservations across global and per-project running-resource limits.
-
-## Attachment and capability boundary
-
-- Attachment revision is independent from incarnation and arbitration generations. Equal revisions are idempotent only for an identical binding; lower or conflicting equal revisions fail.
-- Any `sessionId: null` binding is detached; revision zero is the initial detached/no-agent-authority state. Attachment transitions fence and revoke only agent authority. Human viewers keep resource access. An agent operation that cannot quiesce still requires terminating that resource's incarnation.
-- Agent capabilities require the exact current qualified session. Human issuance validates the attachment current at issuance, but subsequent human operations authorize the exact project/resource/actor/peer independently from agent attachment changes. Flex run channels use trusted pipes; independently authenticated MCP bindings support OpenCode, Codex, and Flex session IDs without impersonating a Flex run channel.
-- Capability tokens are returned once. Runtime records retain only SHA-256 digests and use `timingSafeEqual`. Authorization is rechecked after asynchronous host authorization, during lease acquisition, and before and after every operation.
-- Capability, audit, and lease identity includes immutable project, resource, attachment authority and revision, actor, peer, role, source, qualified agent session, and Flex scope/channel/run where applicable.
-- All participant operations share a resource FIFO with per-lease and aggregate bounds. A released participant's cleanup joins that same FIFO with exact retained lease identity, bypasses user-operation authorization only for resource-owned input release/viewport recomputation, and retains lifecycle cancellation and operation timeout enforcement.
-- Human frame refresh enters the shared FIFO, captures the initiating subscription, clears viewer windows, waits for producer acknowledgements, and validates one constant-sized new-generation boundary. A running open tab may refresh while streaming is false. New frames fan out to all participants.
-- `beforeOperation` reserves the exact resource and lets the host persist policy/audit through an awaited fail-closed gate. Runtime then atomically revalidates lease, attachment, session, arbitration generation, and incarnation before starting the side effect. Both host hooks carry the same exact operation ID and classification; terminal audit remains best effort and runs after bounded cleanup releases or fences the exact reservation.
-- Lease authority snapshots are immutable process-local revalidation tokens. They expose `authorityGeneration` and bind the runtime instance, incarnation, exact `capabilityId`, exact `leaseId`, and attachment, but never replace Controller durable attachment truth.
-
-- Viewport preferences are per human lease. Effective width, height and DSF use the componentwise minimum; results carry the actual viewport revision, including unchanged-size responses. Departure expands the viewport through serialized resource-owned cleanup and retains its cleanup marker until the resize succeeds, so failed cleanup remains retryable. Input ownership is bounded to 64 keys and 5 buttons per participant, and departure preserves another participant's held input.
-
-## Browser confinement
-
-- Production session options are assembled only inside `BrowserRuntime`: sandbox required, random private per-resource user data directory, one authenticated proxy per running resource, fixed network-reduction arguments, denied downloads/file choosers/permissions, and HTTP(S)-only public navigation.
-- `allowEvaluation` exists only for the private confinement probe. No runtime lease, framed message, Flex tool, or MCP tool exposes evaluation.
-- The production probe verifies loopback denial, synthetic `.invalid` traversal, and forced WebRTC suppression through the resource's proxy.
-
-## Egress and artifacts
-
-- HTTP absolute-form, WebSocket Upgrade, and CONNECT use one fail-closed target resolver. Every DNS answer must be public unicast and the selected answer is dialed numerically.
-- Egress proxies carry immutable `projectId` and `browserResourceId`; credentials are private and one proxy exists per running resource.
-- Artifact identity is `(projectId, browserResourceId, artifactId)`. Paths use keyed project and resource digests, and quotas apply per resource, per project, and globally.
-- Artifact writes are private, temporary, synced, and atomically renamed. Reads use no-follow handles and verify size plus SHA-256. Human leases can read or delete artifacts only from their exact resource.
-
-## Adapter boundary
-
-- Framed messages contain no identity selectors. The parent binds project, resource, attachment authority/revision, actor, peer, role, source, qualified session, Flex scope, channel, and exact run out of band.
-- One qualified session can own multiple resource-specific framed channels. Capability revocation owns server-peer disconnect; peer-initiated release/close revokes only that channel's capability without recursively disconnecting itself.
-- Framed request counts and queued write bytes are bounded. Runtime shutdown has a bounded caller-visible cleanup deadline while retaining in-flight cleanup ownership for retry.
-- Each viewer has a bounded exact-identity frame map. Each incoming frame starts one bounded producer ACK whose outcome is shared by viewer records. Producer ACK promises have a separate hard bound; viewer lag and eviction cannot re-ACK or block Chrome. Producer failures fence the exact incarnation regardless of which participants subsequently joined it. A failure from an older incarnation cannot fence its replacement.
-- Late viewer acknowledgements and oldest-first eviction only retire the local map entry. A throwing listener revokes its own participant. Neither event routes through resource-wide producer failure handling.
-- A frame above `maxFrameBytes` advances the resource sequence watermark, is acknowledged once and dropped, and reports nonfatal `FRAME_TOO_LARGE` to viewers. During refresh it also fails the refresh boundary with `FRAME_TOO_LARGE`.
-- `screencast` (`quality` 0..100 default 70, `maxWidth`/`maxHeight` 1..4096 each with `maxWidth * maxHeight <= 8_294_400` and defaults 2560/1600, `everyNthFrame` 1..60 default 1, `firstFrameTimeoutMs` 1000..60000 default left to SmartPuppeteer) is validated in the constructor with `validateExactKeys` plus the integer validators and forwarded to `LiveBrowserSession` next to `maxOutstandingFrames`. The ceilings deliberately match `@push.rocks/smartpuppeteer` 2.6's `LiveBrowserSession` validation (`maxViewportPixelArea = 8294400`, `maxTimeoutMs = 60000`); a looser runtime bound would let `new BrowserRuntime()` succeed and every incarnation launch fail instead. Without `quality`/`maxWidth`/`maxHeight`, SmartPuppeteer's defaults (quality 80, unbounded size) produced multi-megabyte frames on device-pixel-ratio 2 viewers.
-- Refresh records track bounded producer ACK work independently of viewer windows. Producer failure cleanup is coalesced by exact session; affected operation completion waits for the fence and process cleanup. Closing an initiating subscription abandons its refresh without revoking other viewers.
-- Runtime state/error messages are bounded to 2,048 characters. Fatal producer errors revoke every current participant synchronously before captured error delivery; released participants receive no duplicate fatal notification.
-- Flex resolves only a capability token, and the provider's run must exactly match its trusted framed client. SmartAgent exposes exactly navigate, snapshot, screenshot, click, fill, and press.
-- MCP independent authentication returns the complete expected binding. The binding is retained in server-owned auth context and tool schemas expose no resource, session, revision, or authority selector.