Workspace, storage, and schemas

icLens uses strict current schemas. Unknown fields and unsupported versions are rejected. In storage keys and records a workspace is called a Source: data is addressed by Source, network, and principal, and a matching principal in another Source is not an interchangeable record.

Resource overlays retain scoped pin and color metadata. The retired Network screen’s networkDependencies field is no longer part of the current format. An import containing it is rejected. An unreadable cached profile stays intact; icLens does not replace it with an empty saved workspace.

Browser records across app updates

Saved user data, drafts, receipts and operation journals use the shared guarded storage layer. Missing records, unreadable JSON, unsupported formats and storage access failures remain distinct. Reading an unsupported or corrupt record does not move or delete it. New writes validate both the proposed value and the retained record against the owning producer’s current schema and scope.

An older tab cannot replace a newer unsupported format through these guards. Writes and normal clears also reject changes since the last validated read; operation workflows retain their existing browser locks and durable replay IDs. These byte checks are not a cross-tab transaction. Related multi-record changes must not be described as atomic. Already running code from before these guards must be reloaded.

An unreadable workspace disables its autosave and displays the existing App banner with a reload or Browser data action. Browser data reuses its save/discard review for preserved user records, including earlier quarantined copies. Explicit discard rechecks the exact reviewed bytes and never includes pending-operation journals or receipts. Inaccessible receipt history is not treated as empty, and failure to save a receipt is reported instead of acknowledging persistence.

Disposable presentation preferences can use defaults. Authentication storage is owned by its SDK. Schema versions change with stored formats, independently of App versions; there is no automatic whole-origin wipe. Browser storage is not a permanent backup: the browser or its user can remove it.

Current browser formats

Purpose	Current identifier
Workspace cache schema	iclens.workspace-cache.v1
Workspace cache storage key	iclens.workspaceCache.v1
Local Registry schema	iclens.workspace-local-registry.v1
Local Registry storage key	iclens.workspaceLocalRegistry.v1
Workspace persistence preference	iclens.workspacePersistenceEnabled.v1
Portable JSON backup kind	iclens.workspace-backup.v3
Backup checkpoint marker	iclens.workspaceBackupMarker.v1
Default Agent selection	iclens.defaultAgent.v1
Local replica gateway and Internet Identity pair	iclens.localReplica.v1
Dashboard document schema	iclens.metra-dashboard.v2
Manual Reserve recovery identity	iclens.reserveTopUp.v1: followed by the encoded runtime scope
Registry metadata draft	iclens.inventoryMetadataDraft.v1: followed by encoded Source, network, caller, endpoint, Agent, record and action
Shared inventory view submitted review	iclens.inventorySavedViewReview.v1: followed by the encoded exact runtime scope
Shared inventory view editing draft	The same exact scope with the :editing suffix
Deletion recovery journal (run as You)	iclens.directDeletion.v1. followed by encoded Source, network, endpoint, caller and target
Recent fixed time ranges	iclens.timeRange.recent.v1
Recently opened workspaces, newest first	iclens.shell.recentWorkspaces.v1
Public beta notice seen in this browser	iclens.shell.betaNotice.v1
Agent add draft (waiting for a controller)	iclens.agentAddDraft.v1: followed by encoded Source, network, caller, endpoint, Agent and canister

These identify validated formats, not an invitation to edit browser storage by hand. Use the supported export, import, and reset controls.

The Local replica record has exactly version: 1, gatewayUrl and identityProviderUrl (strings). The strings are both empty for automatic addresses or form one normalized, safe matching Local gateway and authorization pair. Unknown fields, records in any other shape, unsupported versions and partial or mismatched pairs are rejected. Missing or unusable data falls back to automatic addresses. The record never selects a network: Local is chosen only through the reviewed switch, stored in iclens.icNetwork.v1.

Each update writes the complete record once. A rejected write retains the prior serialized pair. Successful writes and storage events synchronize the existing Session provider; no separate endpoint keys or fallback records are read. A selected Preferences import applies the whole validated Local replica record; the file itself grants no network transition or page trust. Reset applies the default record only after a reviewed Mainnet transition when needed. Settled Mainnet identity is retained; Local and pending authentication still use guarded revocation and initialization. Local trust comes from the current page.

The recent time ranges record has exactly version: 1 and ranges: at most three entries of startNanos and endNanos (decimal strings, start before end) and timezone (browser or utc), newest first. It holds no identity, Agent or evidence. Unknown fields or versions are rejected and the record is ignored.

Clearing recovery data cannot undo a payment

The manual Reserve checkpoint retains only its operation ID and exact Source, network, caller, execution mode, Agent and endpoint binding. It contains no payment arguments or credentials. An unresolved ID cannot be replaced by a new payment. Unreadable data is preserved and continues to block payment until the retained operation is investigated; clearing browser data does not prove that a payment failed.

A terminal response received after leaving its captured Source retains the original checkpoint until it can be inspected in that context. Terminal cleanup renews the current-context guard inside its acquired browser lock. A confirmed receipt remains visible if cleanup fails; a failed cleanup never authorizes a replacement payment.

Shared inventory view drafts retain bounded names, filters, sort and pin state; submitted reviews also retain the exact view ID and revision. They contain no credentials or identity material. Editing and submitted records are distinct: changing a draft cannot replace an unresolved submitted review. Writes and outcome recovery are serialized across tabs for that exact scope. Corrupt records are preserved and block new changes; a failed storage write cannot count as retained input or a cleared outcome.

The deletion journal (run as You) uses schema 1 and the same browser staging lock as other code and snapshot operations run as You. It retains a stable operation ID, the immutable review fingerprint, a canonical current-Candid receipt, and an optional Agent self-deletion preparation job ID. Receipt encoding is bounded to 32 KiB. The receipt distinguishes an unknown stop, a retained stop acknowledgement awaiting status, and a once-verified stopped version. The review version and fingerprint never change. A snapshot callback retains its exact ID before metadata verification; later drift cannot replace the stopped baseline. Strict decoding rejects extra fields, other schemas and a receipt whose caller, target or review differs from its retained scope. It stores no identity material, private arguments or Wasm bytes. A pending or uncertain financial effect remains retained across reloads; clearing browser storage does not establish failure or authorize another deposit. The browser lock serializes active operations, but does not prevent a controller from issuing a separate management call outside that operation. The Demo uses its resettable simulated job collection and does not write production recovery journals.

Workspace backup envelope

Field	Meaning
kind	Exact backup-kind discriminator above
app	icLens
exportedAt	Export timestamp
workspace	Sanitized current Workspace profile and Source context
localNetwork	Optional reviewed gatewayUrl and identityProviderUrl
localRegistry.records	Personal Source records
agents	Portable saved Agent connections, including a saved deployment-provided Agent
defaultAgentId	A valid saved default reference or null
categories	Nonempty, unique current selection: saved-canisters, agent-connections, receipts, drafts, preferences
receipts	Current-owner direct receipt population with original actors and networks
drafts	Typed current Create, Registry metadata, Move, Deploy, Agent add and Rules records with exact producer keys
preferences	Colour, motion, one Local replica record and strictly scoped persisted Metra query histories

Agent pointers contain ID, name, canister principal, network, and timestamps. They do not carry membership, credentials, or live access authority. Saved deployment connections are portable; disabled deployment discovery opt-outs stay in Source configuration without becoming active connection pointers. Exact Source IDs and enabled preferences persist, including Sources needed by retained recovery records. Agent health, capabilities and Registry contents remain live caller-scoped data and are stripped from browser persistence. Export excludes remote Agent data. Import validates identity ownership and replacement before applying the browser scope. Registry revisions and nanosecond timestamps use decimal strings in JSON and revive as bigint without conversion through Number. Unknown fields and previous formats are rejected. Unselected categories do not write their local records.

Device receipts use iclens.timeline.device-receipts.v1, retain at most 160 records and have network plus an optional actor, with no Source field. The catalog cannot assign Source or caller provenance to actor-less records. Persisted Metra histories use iclens.metra.recent-queries.v3. followed by encoded Source, network, principal, mode and Agent. The existing strict v2 record validator and a maximum of 50 entries apply; delimiter splitting is not a scope decoder. Dashboard query documents retain iclens.metra-dashboard.v2 validation.

Reset and import check the actual durable owner and original seat lifetime. Acknowledged incomplete or ambiguous records are preserved. Browser keys are checked separately; they are not a universally atomic transaction across tabs. Rollback restores accepted unchanged writes and notifies mounted readers only after actual restoration. A rejected or concurrent restoration remains explicit.

Selected Workspace bounds

Field or collection	Limit
Backup input	5,000,000 bytes
Sources	50
Overlays	2,000
Recent resources	200
Tags per item	50
Name	120 UTF-16 code units
Notes / description	2,000 UTF-16 code units
URL	2,048 UTF-16 code units
Default / maximum Workspace page size	50 / 200

Agent Registry bounds are separate: see Agent API. A corrupt or unsupported current Workspace record is preserved rather than silently decoded as a different schema. Settings › Browser data lists unreadable saved records and earlier set-aside copies, saves them to a file and removes them only after an explicit choice and only if they are unchanged since the review. Receipts, drafts and operation journals are never offered there.

Query cache and recent queries

Live operational query caching is memory-only by default. Query keys include the exact Source, network, principal or anonymous seat, execution mode, selected Agent, and resource context. Cache reuse does not cross those authority boundaries.

Explore’s recent-query history is a distinct browser feature. Its key is:

iclens.metra.recent-queries.v3.{sourceId}.{network}.{principal}.{executionMode}.{agentId}

Each coordinate is URI-encoded. History retains at most 50 entries and records the native/PromQL query, range, timezone, resolution, panel kind, star state, and last-use time. A saved dashboard lives on the Agent instead.

Agent-owned state

The Agent stores its Registry, membership, Metra data, Custra configuration and results, dashboards and versions, reports, Timeline, jobs, audit, funding records, AI state, and storage/release state.

Storage views distinguish logical, allocated, and high-water bytes. Retention and cleanup affect future availability of historical results. Cleanup must preserve unresolved financial and external-effect evidence; it is not a general-purpose erase-and-retry mechanism.

Use Workspace backup for browser portability and Agent storage for remote maintenance.

Agent storage controls

The Metra arena ceiling is an optional host Region-growth limit: a positive Nat64 in 8 MiB multiples, constrained by already allocated or reserved space and any occupied-byte retention budget. Fresh Agents default to 4 GiB. Blank removes it. Platform capacity and cycles still constrain growth; changing the ceiling does not shrink allocation. Review binds exact Agent, Source, network, caller, and revision and renews them before execution.

Metric retention replaces the complete policy at its exact revision: maximum age in whole days, optional occupied-byte budget in MiB, and reject-new-writes or expire-oldest pressure behavior. Blank age/budget removes that constraint. A configured host ceiling bounds the byte budget; without one, that bound does not apply. Expiry runs through bounded maintenance and is irreversible; an uncertain response requires reading current policy before another review.

Custra logical usage estimates come from bounded counts and record budgets, without serializing complete state or write-only credentials. Its protected funding journal retains cumulative movements, rolling spend, and unresolved exposure independently of prunable transfer history.

Storage reviews bind the original signed-in seat, Source, network, host, and permission. Signing out and back in creates a new seat even for the same principal. Admission loss retires the local review and masks private cached evidence. Same-seat refresh can retain an observation for presentation but does not itself grant fresh mutation authority. Follow the cleanup guide for preview and recovery.

Agent storage planning

The numbers behind Agent › Storage: maintenance presets, capacity planning and maintenance cost.

Engine maintenance timing

In Engine maintenance, an Admin can review a preset and optional bounded overrides. Saving checks the current configuration revision and records the outcome in audit. Maintenance starts enabled. Pausing it leaves retained data readable, but expired Logs and Traces can keep occupying capacity. Quiescing also stops new intake. Neither control changes Metra’s native maintenance, Monitor or collected-log intervals.

Preset	Maximum ordinary grouping	Derived trace work	Reassessment backstop
Economy	One hour	Up to five minutes	Six hours
Balanced (default)	60 seconds	No deliberate delay	One hour
Responsive	Five seconds	No deliberate delay	15 minutes

These are maximum deliberate delays, not fixed polling intervals. Idle engines do not run upkeep. Native eligibility, verification, storage pressure and dependencies can require earlier work or prevent progress. The backstop checks control facts; it does not unconditionally execute maintenance. Other Agent duties can still wake the shared timer.

Pending work keeps its original age and planned deadline. A shorter setting can bring it forward; a longer setting does not extend its deadline. The longer allowance applies when new work becomes pending. Partial progress, more writes and pause/resume do not grant an old backlog a fresh delay.

Overrides allow ordinary grouping through two hours, derived-work lag through five minutes, a 15-minute–24-hour backstop and one or two engine admissions per dispatch round. Each engine retains its own invocation allowance. Lumera uses a measured instruction budget; Veyra uses count budgets and initially exposes only the combined-Agent one-block / 16-tuple profile. Larger profiles require separate measurements before admission.

While nonempty canister logs arrive every five minutes, Balanced ordinarily runs Lumera maintenance about once per collection interval. That is useful work. Economy can group maintenance across several fetches; each fetch’s logs are still appended immediately. Collection sampling and metrics are unchanged.

Expand maintenance diagnostics to inspect pending deadlines, pressure, blocked reasons and measured instructions. Missing measurements remain unknown. These ordinary query results are operator evidence, not certified execution or a throughput guarantee.

Combined Agent capacity plan

Fresh Wasm installs initialize none of the optional engines. The creation review defaults to Metrics only; select Logs and Traces explicitly, or leave all three off. Every engine can later be enabled by an active Admin in Storage. Custra stays core. The defaults below apply on first enable, not as upfront allocations or subnet reservations.

Store	Default and practical capacity	Control and refusal
Metra	4 GiB finite arena; unlimited age and no occupied-byte retention budget by default. Duration depends on cardinality and encoding.	Admin, 8 MiB ceiling steps, never below current physical allocation or occupied plus reserved space. Optional positive retention limits; refusal by default at the occupied budget.
Lumera	4 GiB / 64 segment slots shared across eight namespaces, including the reserved collected-log namespace. Seven-day default: about 585 MiB/day encoded, before slack, metadata and maintenance lag.	Admin, 64 MiB ceiling steps through 16 GiB, never below current segment reservations. The store-wide setting owns retention for every namespace; changes affect new blocks while older blocks retain their expiry. Full-store refusal remains.
Veyra	64 GiB block budget / 32,768 blocks / 65,536 receipts / 64 scopes. Seven-day estimates: about 54 spans/s at 1,000 spans/block or 888 at 16,384 spans/block. These are slot arithmetic, not measured throughput.	Admin chooses a 2 MiB budget step through 64 GiB and one to 64 scopes at first enable. Capacity is immutable afterward; pinned Veyra cannot resize safely. Full slots/receipts refuse intake. The block budget is not a hard physical Region ceiling.
Custra	Count-bounded heap: 64 sources, 1,024 rules, 1,024 receivers, 65,536 instances, 4,096 deliveries/transfers and 10,000 events; configuration at most 2 MiB.	Native bounds and retention. Allow 256 MiB within the heap plan as an estimate; Monitor stays paused by default. Dedicated remote sources remain independent of embedded Metrics.

All three default budgets total 72 GiB. Agent management enforces a finite bulk planning limit of 84 GiB, leaving at least 12 GiB working allowance plus 4 GiB bookkeeping/recovery headroom within Motoko’s 100 GiB Region limit. For an initialized active or retiring store its contribution is the greater of its configured budget and measured physical allocation. A parked store contributes its retained physical allocation; an uninitialized store contributes zero. Scratch allocation is included where measured. Configuration/growth admission cannot deliberately exceed the plan; retirement remains possible. Actual Veyra allocation, keep-tier copies, allocator slack and workload can still exceed estimates: this is not a combined native hard physical quota. The platform permits more stable memory than this compiler’s Region limit, and subnet availability may be lower than either limit.

Each engine is Not enabled, Enabled, Retiring, or Disabled — storage retained. Retirement refuses new intake and revokes lanes without changing retention or deleting history. Native evidence must prove parking safe; pause, insufficient cycles, retained receipts or unlimited retention can leave it Retiring indefinitely. Re-enable uses the same state and Regions; old producer grants are not resurrected. Traces capacity remains fixed.

Prometheus reader credentials remain independently revocable: an Admin can disable and clear them even while Metrics is off, using the current reader revision. New reader grants require enabled Metrics.

Deleting data isn’t available yet; data expires through retention. Allocated storage stays charged and is retained for reuse; disabling does not return pages. Missing native measurements stay Unknown. Lifecycle, configured ceilings, used/allocated/reusable bytes, retention and maintenance on/off are readable through the existing Storage APIs. Changes are Admin-only, revision-bound, synchronous and audited. After an ambiguous response reconcile the original operation; never automatically resubmit against a newer revision.

Keep the heap separately below its 6 GiB wasm64 platform limit: plan 2 GiB for engine metadata/indexes and queries (including Custra’s 256 MiB allowance), 2 GiB for Agent configuration, journals, audit and other histories, and 2 GiB for GC, in-flight messages and recovery. These are planning allowances, not measured worst-case bounds; byte ceilings do not guarantee heap safety for every cardinality, tiny-packet workload or enabled keep tier. Monitor actual heap, physical Region usage and cycles before raising limits. Platform limits are described in the ICP memory model.

The 64 GiB trace default matches Veyra’s native block/receipt defaults and is also the host maximum: larger live blocks would consume the combined Agent’s 100 GiB Region headroom. It stays below Veyra’s compiled 131,072-block and 1,048,576-receipt maxima. The compiler limit is verified against the pinned binary’s --max-stable-pages default; see the Motoko compiler reference. Its 64 scopes match the native default (maximum 1,024). The pinned engine fixes immutable configuration and block/scope arrays at initialization and exposes no resizing operation. Changing these capacities in place would require replacing native state; the Agent offers no such action. Increasing retained capacity requires a future native resize API; the Agent does not rebuild engine state to emulate one.

Eight log namespaces are shared policy/isolation partitions, not an eight-app limit: resource attributes identify applications within each namespace. The 32 producer lanes bound admission scan, quotas and grants; collectors may multiplex applications in one lane. Creating all 64 trace scopes does not grant 64 producer lanes. These bounded shared controls are retained deliberately.

observabilityStorage reports defaults, permitted ceilings, configured block, receipt and scope totals, used counts, namespace/lane totals and usage, the Lumera ceiling, maintenance and quiesce state. Scope counting visits at most 64 entries; it never calls Veyra’s slot-walking status(). Metra’s existing status/capacity queries report its configured arena ceiling and used capacity; Custra’s snapshot reports native limits and usage. Veyra allocated extent bytes include 4 KiB padding; logical occupied bytes are unknown. Physical high-water bytes never imply that allocated Regions shrink after retirement. Missing measurements stay unknown. Retention upkeep starts enabled, independently of Monitor alert evaluation. It remains bounded and shares the scheduler, so expiry can lag. An active Admin can pause it or quiesce intake/upkeep; the existing 500 billion cycle floor also stops upkeep. Restore funding and resume maintenance to reclaim expired space. Pausing can leave stores full. Full stores do not gain a new eviction policy.

Interpret maintenance costs

Retention upkeep can run while Monitor is paused. Lumera and Veyra each expose five-second upkeep deadlines; the Agent arms its shared timer for the earliest actionable deadline. This is not a universal five-second Monitor collection interval. Their dispatches can share a single wake. Pausing upkeep also stops retirement, so it is not a cost-free operating recommendation.

Use the epoch-bound scheduler diagnostics to measure actual wakes and duty admissions. Native-body instruction counts omit the surrounding asynchronous messages and transport. A balance delta includes execution, storage rent and refunds; it must not be presented as an instruction count or extrapolated from a cold first write into funding advice. Development measurements in the integration ledger use disposable local Agents and synthetic cycles, and do not establish mainnet prices or worst-case costs.

Collected canister logs cannot be selected for manual cleanup. Removing or re-pointing a collection hides its payloads until their recorded expiry; the per-minute line and trap telemetry remains independently retained. See log storage bounds.