arcane-os 0.92.0 → 0.93.0

package/docs/reference/native-diagnostics.md

@@ -0,0 +1,167 @@
+# Native application diagnostics
+
+Native diagnostics retain errors from the actual packaged application's top-level
+document in its native host session. Read them through the existing app-control
+connection, without foregrounding a window, desktop input, or arbitrary script
+execution. This is a developer inspection surface, separate from ordinary product
+status and saved conversation history.
+
+The Windows WebView2 host installs the fixed observer at document creation, before
+the ordinary Core client and application scripts. It captures `window.error` and
+`unhandledrejection` events and accepts explicit reports of application-caught
+errors. It leaves the browser's ordinary error behavior intact. It does not
+intercept console output, inspect application state, collect resource/request
+bodies, or capture errors from other applications or frame documents.
+
+## Report a caught application error
+
+```js
+import {reportNativeError} from 'arcane-os/core/native-diagnostics';
+
+const receipt = await reportNativeError(error, {
+    details: {operation: 'source.load', sourceId}
+});
+// receipt: {accepted: true, sessionId, sequence}
+```
+
+`error` is the actual caught value, including non-Error rejection values.
+`details` is optional application-selected diagnostic context. Supply diagnostic
+information only; credentials, secrets, user documents and provider/tool payloads
+do not belong in this report. The SDK adds document/session metadata outside the
+reported values and does not rewrite their text. Reporting does not change the
+application's own handling of the original failure.
+
+The promise resolves after the native host retains the record. A missing document
+observer or native handler rejects with
+`ARCANE_NATIVE_DIAGNOSTICS_UNAVAILABLE`. A negative host acknowledgement rejects
+with `ARCANE_NATIVE_DIAGNOSTIC_REJECTED`, preserving the complete host reply in
+`details` and its error in `cause`. Reflection, encoding and native transport
+failures reject with their actual error. A lost reply can leave the caller's
+outcome unknown; the SDK does not automatically retry and duplicate the report.
+
+Automatic capture observes its own reporting failures through the existing
+console, with the original error, without recursively manufacturing an unhandled
+rejection. Console output remains ordinary console output; it is not retained
+diagnostic history. Applications must observe explicit reporting promises.
+
+## Retrieve retained errors
+
+Use the endpoint of the selected running app from its existing app-control launch
+configuration. Connecting does not launch the application.
+
+```js
+import {connectAppControl} from 'arcane-os/core/app-control';
+
+const control = await connectAppControl({endpoint});
+try {
+    const snapshot = await control.diagnostics();
+    console.dir(snapshot, {depth: null});
+} finally {
+    await control.close();
+}
+```
+
+`control.diagnostics({afterSequence?, documentId?}, {signal?})` invokes
+`app.control.diagnostics`. Omitted filters return every retained error.
+`afterSequence` selects records with a greater session sequence;
+`documentId` selects one actual document. Retrieval is non-consuming: independent
+inspectors can read the same complete records. Connection/cancellation behavior is
+the existing app-control contract. Retrieval does not wait for renderer, Core,
+model or application readiness and does not evaluate a script in the document.
+
+The result is:
+
+```js
+{
+    sessionId,
+    captureStartedAt,
+    captureInstalled,
+    latestSequence,
+    documents: [{documentId, documentUrl, time, receivedAt}],
+    records: [{
+        sequence, receivedAt, documentId, documentUrl, time,
+        kind, error, details, valueFormat, values, location, message
+    }]
+}
+```
+
+`sessionId` identifies this native window/host lifetime. `captureStartedAt` is the
+time its in-memory ledger was created. `captureInstalled` means document-start
+script registration completed; it does not prove that any application failure
+occurred or that a particular operation succeeded. `documents` records actual
+ingress from observed documents. Each document has one identity, shared with app
+control, independent of Core bridge generations. A cancelled navigation that
+leaves the same document alive keeps that identity.
+
+`sequence` is assigned when an error is retained, in host arrival order.
+`latestSequence` describes the whole session even when filters select fewer
+records. `time` comes from document capture; `receivedAt` comes from the host.
+`kind` is `window.error`, `unhandledrejection`, or `application`. Window errors
+include `location: {file, line, column}` when the browser exposes those fields.
+Their browser `message` is retained separately from `error`, preserving a null
+or undefined error value rather than replacing it with that message.
+`details` and `location` are otherwise omitted.
+
+Records survive document navigation and Core transport failure within the host
+session. Closing the inspector leaves them retained. Closing the native host ends
+the session; this API does not persist, migrate, prune, or recover records across
+host restarts. An empty snapshot means no matching records were retained in this
+session, not that earlier failures never occurred. Errors before capture existed,
+handled failures never explicitly reported, errors the browser does not expose,
+and vanished documents whose pending reports never reached the host remain
+unavailable. Earlier never-retained failures cannot be reconstructed through this API.
+
+## Complete error property representation
+
+Each record uses `valueFormat: 'arcane.diagnostic-value/1'`. `error` and optional
+`details` are roots into the single `values` graph. JSON-native primitives remain
+their original values. Undefined, bigint, non-finite numbers and negative zero
+have explicit typed representations. `{ref: id}` identifies a graph node.
+Repeated references and cycles retain the same identity within the record.
+
+Object nodes retain every own property descriptor, including non-enumerable and
+symbol-keyed fields. This includes full Error messages and stacks, `cause`,
+AggregateError members and custom diagnostic details. Standard error fields
+inherited from a prototype appear in `inherited`. Data descriptors contain
+`value`; accessor descriptors contain references for `get` and `set` without
+invoking either function. An accessor supplied as the `details` option is likewise
+represented rather than called. No `toJSON` method on reported content is called.
+Maps and sets retain their entries, dates their numeric time, and regular
+expressions their source and flags, alongside their own properties.
+
+This is a diagnostic property representation, not an executable object snapshot:
+functions retain their property identity, not executable closures; platform-private
+internal state and private class fields are not observable properties. The host
+stores and returns the graph without reconstructing or executing those objects.
+An object that rejects reflection causes an observable reporting failure rather
+than a silently incomplete success. Inspect the complete graph in developer
+diagnostics; do not flatten it into ordinary chat or user-facing status.
+
+## Host ownership and availability
+
+`installNativeDiagnostics(globalThis)` installs one observer per document and
+returns its owner `{documentId, ready, report}`. `ready` resolves after the document
+announcement is accepted, and `report` has the same report contract. Importing
+the ESM module alone installs no observer. The packaged native host owns
+installation and lifetime; ordinary applications use `reportNativeError`.
+
+`createNativeDiagnosticsSource()` from
+`arcane-os/core/native-diagnostics-source` projects that same canonical helper
+into the top-level document-start script. It adds no second observer or serializer.
+Windows binds the script to the dedicated `arcaneDiagnostics.Send` host object.
+This route is independent of `arcaneBridge` and the Core subprocess. Host close
+stops new ingress and removes the object/script during existing shutdown.
+
+The implementation here supplies Windows WebView2 capture and app-control
+retrieval. macOS, Linux and Android require their native host ingress/session and
+app-control adapters; this source change does not claim those adapters exist.
+The helper recognizes the same fixed-name WebKit reply handler when a host
+provides it; that transport seam is not platform availability. A browser preview
+cannot establish actual native acceptance.
+
+Native delivery requires the corresponding rebuilt SDK Windows host asset and
+consumer adoption through the published SDK package. Source inspection, authored
+fixtures and configured capture are distinct from executed built-application
+verification. Existing host stderr/log diagnostics, live Core events, readiness
+replay and `Arcane.diagnostics.recentErrors/get` retain their existing semantics;
+this API does not turn them into a historical error service.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.92.0",
+  "version": "0.93.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -65,6 +65,8 @@
     "./core/stdio": "./src/core/stdio.mjs",
     "./core/host": "./src/core/host.mjs",
     "./core/app-control": "./src/core/app-control.mjs",
+    "./core/native-diagnostics": "./browser-runtime/core/native-diagnostics.mjs",
+    "./core/native-diagnostics-source": "./src/core-native-diagnostics-source.mjs",
     "./codex/app-server": "./src/codex/app-server.mjs",
     "./mcp/stdio": "./src/mcp/stdio-server.mjs",
     "./core/repositories": "./src/core/repositories.mjs",

package/src/core/app-control.mjs

@@ -15,6 +15,7 @@ export async function connectAppControl({endpoint, signal, onError = reportAppCo
         endpoint,
         closed: connection.closed,
         status(options) { return client.invoke('app.control.status', {}, options); },
+        diagnostics(parameters = {}, options) { return client.invoke('app.control.diagnostics', parameters, options); },
         inspect(parameters = {}, options) { return client.invoke('app.control.inspect', parameters, options); },
         capture(parameters = {}, options) { return client.invoke('app.control.capture', parameters, options); },
         act(parameters, options) { return client.invoke('app.control.act', parameters, options); },

package/src/core/hosts/windows/ArcaneAppControl.cs

@@ -452,7 +452,7 @@ namespace Arcane.Core.Hosts.Windows
                         try
                         {
                             cancellation.Token.ThrowIfCancellationRequested();
-                            if (method != "app.control.status" && method != "app.control.inspect"
+                            if (method != "app.control.status" && method != "app.control.diagnostics" && method != "app.control.inspect"
                                 && method != "app.control.capture" && method != "app.control.act"
                                 && method != "app.control.key" && method != "app.control.resize")
                                 throw new NotSupportedException("The app does not expose " + method + ".");

package/src/core/hosts/windows/ArcaneHost.cs

@@ -24,6 +24,7 @@ namespace Arcane.Core.Hosts.Windows
         public string Title { get; set; }
         public string IconPath { get; set; }
         public string ClassicClientSource { get; set; }
+        public string NativeDiagnosticsSource { get; set; }
         public string AppControlEndpoint { get; set; }
         public string AppControlSource { get; set; }
         public string CoreExecutable { get; set; }
@@ -102,15 +103,20 @@ namespace Arcane.Core.Hosts.Windows
         private readonly Action<string> onDiagnostic;
         private readonly Action<Exception> onError;
         private readonly WebView2 webView;
+        private readonly ArcaneNativeDiagnostics nativeDiagnostics;
         private readonly object stateLock = new object();
         private readonly Queue<CoreDelivery> pending = new Queue<CoreDelivery>();
         private readonly Dictionary<string, long> requestGenerations = new Dictionary<string, long>();
+        private readonly Dictionary<string, DesktopNotificationRequest> desktopNotificationRequests =
+            new Dictionary<string, DesktopNotificationRequest>();
         private readonly List<Exception> failures = new List<Exception>();
         private readonly List<Task> failureNotifications = new List<Task>();
         private readonly TaskCompletionSource<object> ready = new TaskCompletionSource<object>();
         private readonly TaskCompletionSource<object> initialized = new TaskCompletionSource<object>();
         private readonly TaskCompletionSource<object> completion = new TaskCompletionSource<object>();
         private ArcaneCoreProcess core;
+        private ArcaneNotifications desktopNotifications;
+        private Task desktopNotificationsClosing;
         private ArcaneBridge bridge;
         private ArcaneBridge activeBridge;
         private Task initialization;
@@ -119,6 +125,8 @@ namespace Arcane.Core.Hosts.Windows
         private Task iconLoading;
         private Icon applicationIcon;
         private string injectedScript;
+        private string nativeDiagnosticsScript;
+        private bool nativeDiagnosticsRegistered;
         private Exception transportFailure;
         private long generation;
         private long nextGeneration;
@@ -144,6 +152,7 @@ namespace Arcane.Core.Hosts.Windows
             this.options = options;
             this.onDiagnostic = onDiagnostic;
             this.onError = onError;
+            nativeDiagnostics = new ArcaneNativeDiagnostics(Report);
             ready.Task.ContinueWith(ObserveReportedFailure, TaskContinuationOptions.OnlyOnFaulted);
             completion.Task.ContinueWith(ObserveReportedFailure, TaskContinuationOptions.OnlyOnFaulted);
             Text = options.Title;
@@ -494,6 +503,10 @@ namespace Arcane.Core.Hosts.Windows
                 browser.SetVirtualHostNameToFolderMapping(options.OriginHost, applicationRoot,
                     CoreWebView2HostResourceAccessKind.Allow);
                 InstallDocumentBridge(generation);
+                // Register the diagnostic observer first so failures in the
+                // ordinary client itself use an ingress independent of Core.
+                await InstallNativeDiagnosticsAsync(browser);
+                if (closing) return;
                 // The selected generator uses replayRuntimeState:true. Both RPC
                 // installation and the shared event owner remain SDK-owned.
                 Task scripts = Task.WhenAll(InstallClassicClientAsync(browser), InstallAppControlAsync(browser));
@@ -523,6 +536,15 @@ namespace Arcane.Core.Hosts.Windows
             injectedScript = await browser.AddScriptToExecuteOnDocumentCreatedAsync(options.ClassicClientSource);
         }
 
+        private async Task InstallNativeDiagnosticsAsync(CoreWebView2 browser)
+        {
+            if (String.IsNullOrEmpty(options.NativeDiagnosticsSource)) return;
+            browser.AddHostObjectToScript("arcaneDiagnostics", nativeDiagnostics);
+            nativeDiagnosticsRegistered = true;
+            nativeDiagnosticsScript = await browser.AddScriptToExecuteOnDocumentCreatedAsync(options.NativeDiagnosticsSource);
+            nativeDiagnostics.Installed();
+        }
+
         private void NavigationStarting(object sender, CoreWebView2NavigationStartingEventArgs args)
         {
             if (nextGeneration != 0 && navigationId == args.NavigationId) return;
@@ -561,6 +583,33 @@ namespace Arcane.Core.Hosts.Windows
                 if (documentGeneration != generation || closing)
                     throw new InvalidOperationException("The requesting document is no longer connected.");
                 string method = EnvelopeString(envelope, "method");
+                if (EnvelopeString(envelope, "protocol") == "arcane/1")
+                {
+                    if (requestId != null && (method == "notifications.status" || method == "notifications.show"
+                        || method == "notifications.state" || method == "notifications.close"))
+                    {
+                        DesktopNotificationRequest operation = new DesktopNotificationRequest(documentGeneration);
+                        desktopNotificationRequests.Add(requestId, operation);
+                        operation.Completion = CompleteDesktopNotificationAsync(envelope, requestId, method, operation);
+                        operation.Completion.ContinueWith(ObserveUnexpectedFailure, TaskContinuationOptions.OnlyOnFaulted);
+                        // Bridge acceptance means this host owns the request;
+                        // the correlated response carries its native outcome.
+                        return Task.FromResult<object>(null);
+                    }
+                    if (EnvelopeString(envelope, "type") == "control")
+                    {
+                        string control = EnvelopeString(envelope, "control");
+                        DesktopNotificationRequest selected;
+                        if (control == "request.cancel" && desktopNotificationRequests.TryGetValue(
+                            EnvelopeString(envelope, "requestId") ?? String.Empty, out selected)
+                            && selected.Generation == documentGeneration)
+                        {
+                            selected.Cancellation.Cancel();
+                            return Task.FromResult<object>(null);
+                        }
+                        if (control == "requests.cancelAll") CancelDesktopNotificationRequests(documentGeneration);
+                    }
+                }
                 if (requestId != null && EnvelopeString(envelope, "protocol") == "arcane/1"
                     && (method == "window.setTheme" || method == "window.state" || method == "window.setState"))
                 {
@@ -584,6 +633,115 @@ namespace Arcane.Core.Hosts.Windows
             }
         }
 
+        private async Task CompleteDesktopNotificationAsync(Dictionary<string, object> request,
+            string id, string method, DesktopNotificationRequest operation)
+        {
+            try
+            {
+                Dictionary<string, object> response = new Dictionary<string, object>
+                {
+                    { "protocol", "arcane/1" }, { "type", "response" }, { "id", id }
+                };
+                try
+                {
+                    object value;
+                    Dictionary<string, object> parameters = request.TryGetValue("parameters", out value)
+                        ? value as Dictionary<string, object> : new Dictionary<string, object>();
+                    if (parameters == null) throw new ArgumentException("Supply a notification request object.");
+                    if (desktopNotifications == null)
+                        desktopNotifications = new ArcaneNotifications(options.ApplicationId, options.ProfileDirectory,
+                            options.Title, options.IconPath, DesktopNotificationChanged);
+                    Dictionary<string, object> result = await desktopNotifications.InvokeAsync(
+                        method, parameters, operation.Cancellation.Token).ConfigureAwait(false);
+                    // Cancellation after native submission does not rewrite an
+                    // accepted result. Its record also remains in host state.
+                    response["ok"] = true;
+                    response["result"] = result;
+                }
+                catch (Exception error)
+                {
+                    string code = error.Data["code"] as string;
+                    if (code == null) code = error is OperationCanceledException ? "CANCELLED"
+                        : error is ArgumentException ? "INVALID_ARGUMENT" : "ARCANE_NOTIFICATION_FAILED";
+                    response["ok"] = false;
+                    response["error"] = ArcaneHost.ErrorRecord(error, code);
+                }
+                response["time"] = DateTime.UtcNow.ToString("o");
+                string json = ArcaneHost.Serializer().Serialize(response);
+                lock (stateLock) pending.Enqueue(new CoreDelivery(operation.Generation, json));
+                ScheduleDelivery();
+            }
+            catch (Exception error)
+            {
+                // A bridge-accepted request must receive its response or the
+                // owning transport failure, including serialization failures.
+                CoreFailed(error);
+            }
+            finally
+            {
+                lock (stateLock)
+                {
+                    desktopNotificationRequests.Remove(id);
+                    operation.Cancellation.Dispose();
+                }
+            }
+        }
+
+        private void DesktopNotificationChanged(Dictionary<string, object> record)
+        {
+            string json = ArcaneHost.Serializer().Serialize(new Dictionary<string, object>
+            {
+                { "protocol", "arcane/1" }, { "type", "event" },
+                { "event", "notifications.state" }, { "data", record }, { "time", DateTime.UtcNow.ToString("o") }
+            });
+            lock (stateLock) pending.Enqueue(new CoreDelivery(generation, json));
+            ScheduleDelivery();
+        }
+
+        private void CancelDesktopNotificationRequests(long? documentGeneration)
+        {
+            lock (stateLock)
+            {
+                // Cancellation can settle a queued operation synchronously;
+                // iterate a snapshot while its completion removes correlation.
+                foreach (DesktopNotificationRequest operation in
+                    new List<DesktopNotificationRequest>(desktopNotificationRequests.Values))
+                    if (!documentGeneration.HasValue || operation.Generation == documentGeneration.Value)
+                        operation.Cancellation.Cancel();
+            }
+        }
+
+        private void StopDesktopNotifications()
+        {
+            CancelDesktopNotificationRequests(null);
+            if (desktopNotifications == null || desktopNotificationsClosing != null) return;
+            try { desktopNotificationsClosing = desktopNotifications.CloseAsync(); }
+            catch (Exception error) { Report(error); }
+        }
+
+        private async Task DrainDesktopNotificationsAsync()
+        {
+            List<Task> operations = new List<Task>();
+            lock (stateLock)
+            {
+                foreach (DesktopNotificationRequest operation in desktopNotificationRequests.Values)
+                    operations.Add(operation.Completion);
+            }
+            if (desktopNotificationsClosing != null) operations.Add(desktopNotificationsClosing);
+            Task settled = Task.WhenAll(operations);
+            try { await settled; }
+            catch (Exception error) { ReportTaskFailure(settled, error); }
+        }
+
+        private sealed class DesktopNotificationRequest
+        {
+            internal readonly long Generation;
+            internal readonly CancellationTokenSource Cancellation = new CancellationTokenSource();
+            internal Task Completion;
+
+            internal DesktopNotificationRequest(long generation) { Generation = generation; }
+        }
+
         private async Task LoadApplicationIconAsync()
         {
             if (String.IsNullOrEmpty(options.IconPath)) return;
@@ -762,12 +920,14 @@ namespace Arcane.Core.Hosts.Windows
         private void DocumentConnected(long documentGeneration)
         {
             ArcaneBridge previous;
+            long previousGeneration;
             lock (stateLock)
             {
                 if (closing) return;
                 if (documentGeneration == generation && documentReady) return;
                 if (documentGeneration != registeredGeneration) return;
                 previous = activeBridge;
+                previousGeneration = generation;
                 generation = documentGeneration;
                 activeBridge = bridge;
                 documentReady = true;
@@ -775,6 +935,7 @@ namespace Arcane.Core.Hosts.Windows
             if (previous != null && previous != activeBridge)
             {
                 previous.Stop(new OperationCanceledException("The previous document has navigated away."));
+                CancelDesktopNotificationRequests(previousGeneration);
                 if (transportFailure == null)
                 {
                     try { ObserveSend(core.SendAsync(CancelRendererRequests)); }
@@ -960,6 +1121,7 @@ namespace Arcane.Core.Hosts.Windows
             if (IsDisposed) return;
             if (bridge != null) bridge.Stop(transportFailure);
             if (activeBridge != null) activeBridge.Stop(transportFailure);
+            CancelDesktopNotificationRequests(null);
             NotifyTransportFailure();
             if (core != null) core.CloseAsync();
             ScheduleDelivery();
@@ -1010,10 +1172,12 @@ namespace Arcane.Core.Hosts.Windows
         {
             if (closing) return;
             lock (stateLock) closing = true;
+            nativeDiagnostics.Stop();
             if (!started) initialized.TrySetResult(null);
             if (bridge != null) bridge.Stop(new InvalidOperationException("The application window is closing."));
             if (activeBridge != null) activeBridge.Stop(new InvalidOperationException("The application window is closing."));
             StopAppControl();
+            StopDesktopNotifications();
             WindowStateTransition.ReleasePending(this);
             shutdown = DrainAndCloseAsync();
             shutdown.ContinueWith(ObserveUnexpectedFailure, TaskContinuationOptions.OnlyOnFaulted);
@@ -1042,6 +1206,7 @@ namespace Arcane.Core.Hosts.Windows
                 }
             }
             await DrainAppControlAsync();
+            await DrainDesktopNotificationsAsync();
             // Joining the independent image owner belongs after Core input has
             // closed; image I/O must never delay accepted service work draining.
             if (iconLoading != null)
@@ -1069,6 +1234,8 @@ namespace Arcane.Core.Hosts.Windows
                 if (!browserProcessExited && webView.CoreWebView2 != null)
                 {
                     webView.CoreWebView2.RemoveHostObjectFromScript("arcaneBridge");
+                    if (nativeDiagnosticsRegistered) webView.CoreWebView2.RemoveHostObjectFromScript("arcaneDiagnostics");
+                    if (nativeDiagnosticsScript != null) webView.CoreWebView2.RemoveScriptToExecuteOnDocumentCreated(nativeDiagnosticsScript);
                     if (injectedScript != null) webView.CoreWebView2.RemoveScriptToExecuteOnDocumentCreated(injectedScript);
                     if (appControlScript != null) webView.CoreWebView2.RemoveScriptToExecuteOnDocumentCreated(appControlScript);
                 }

package/src/core/hosts/windows/ArcaneLauncher.cs

@@ -101,6 +101,7 @@ namespace Arcane.Core.Hosts.Windows
                     InitialWindowState = OptionalWindowState(windowOptions),
                     IconPath = String.IsNullOrEmpty(icon) ? null : Path.Combine(directory, icon),
                     ClassicClientSource = File.ReadAllText(Path.Combine(directory, RequiredString(client, "source"))),
+                    NativeDiagnosticsSource = File.ReadAllText(Path.Combine(directory, "arcane-native-diagnostics.js")),
                     AppControlEndpoint = appControl == null ? null : RequiredString(appControl, "endpoint"),
                     AppControlSource = appControl == null ? null : File.ReadAllText(Path.Combine(directory, "arcane-app-control.js")),
                     CoreExecutable = Path.Combine(directory, "runtime", "ArcaneCore.exe"),

package/src/core/hosts/windows/ArcaneNativeDiagnostics.cs

@@ -0,0 +1,137 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Runtime.InteropServices;
+
+namespace Arcane.Core.Hosts.Windows
+{
+    /// <summary>
+    /// One host-session ledger, independent of Core and renderer readiness.
+    /// The dedicated document-start ingress acknowledges only retained records.
+    /// Diagnostic property graphs are data; the host never evaluates their fields.
+    /// </summary>
+    [ComVisible(true)]
+    [ClassInterface(ClassInterfaceType.AutoDual)]
+    public sealed class ArcaneNativeDiagnostics
+    {
+        private readonly object stateLock = new object();
+        private readonly string sessionId = Guid.NewGuid().ToString();
+        private readonly string captureStartedAt = DateTime.UtcNow.ToString("o");
+        private readonly List<Dictionary<string, object>> records = new List<Dictionary<string, object>>();
+        private readonly Dictionary<string, Dictionary<string, object>> documents =
+            new Dictionary<string, Dictionary<string, object>>();
+        private readonly Action<Exception> onFailure;
+        private long sequence;
+        private bool captureInstalled;
+        private bool stopped;
+
+        internal ArcaneNativeDiagnostics(Action<Exception> onFailure) { this.onFailure = onFailure; }
+
+        public string Send(string json)
+        {
+            try
+            {
+                Dictionary<string, object> frame = ArcaneHost.Serializer().DeserializeObject(json) as Dictionary<string, object>;
+                if (frame == null || Text(frame, "protocol") != "arcane.native-diagnostics/1")
+                    throw new InvalidDataException("Expected an Arcane native diagnostic envelope.");
+                string type = Text(frame, "type");
+                string documentId = Text(frame, "documentId");
+                string documentUrl = Text(frame, "documentUrl");
+                string time = Text(frame, "time");
+                if (documentId == null || documentUrl == null || time == null)
+                    throw new InvalidDataException("The diagnostic envelope needs its document identity, URL and time.");
+                object value;
+                Dictionary<string, object> record = frame.TryGetValue("record", out value)
+                    ? value as Dictionary<string, object> : null;
+                if (type != "document" && (type != "error" || record == null))
+                    throw new InvalidDataException("Expected a document announcement or an error record.");
+
+                Dictionary<string, object> result = new Dictionary<string, object>
+                {
+                    { "accepted", true }, { "sessionId", sessionId }
+                };
+                lock (stateLock)
+                {
+                    if (stopped) throw new InvalidOperationException("The native diagnostic session is closing.");
+                    string receivedAt = DateTime.UtcNow.ToString("o");
+                    if (!documents.ContainsKey(documentId))
+                        documents.Add(documentId, new Dictionary<string, object>
+                        {
+                            { "documentId", documentId }, { "documentUrl", documentUrl },
+                            { "time", time }, { "receivedAt", receivedAt }
+                        });
+                    if (type == "error")
+                    {
+                        Dictionary<string, object> retained = new Dictionary<string, object>(record);
+                        retained["sequence"] = ++sequence;
+                        retained["receivedAt"] = receivedAt;
+                        retained["documentId"] = documentId;
+                        retained["documentUrl"] = documentUrl;
+                        retained["time"] = time;
+                        records.Add(retained);
+                        result["sequence"] = sequence;
+                    }
+                }
+                return ArcaneHost.Serializer().Serialize(result);
+            }
+            catch (Exception error)
+            {
+                onFailure(error);
+                return ArcaneHost.Serializer().Serialize(new Dictionary<string, object>
+                {
+                    { "accepted", false },
+                    { "error", ArcaneHost.ErrorRecord(error, "ARCANE_NATIVE_DIAGNOSTIC_CAPTURE_FAILED") }
+                });
+            }
+        }
+
+        internal object Snapshot(Dictionary<string, object> parameters)
+        {
+            object selected;
+            long afterSequence = 0;
+            if (parameters.TryGetValue("afterSequence", out selected))
+            {
+                if (!(selected is int || selected is long || selected is decimal || selected is double))
+                    throw new ArgumentException("afterSequence must be a nonnegative integer.");
+                afterSequence = Convert.ToInt64(selected);
+                if (afterSequence < 0 || Convert.ToDouble(selected) != afterSequence)
+                    throw new ArgumentException("afterSequence must be a nonnegative integer.");
+            }
+            string documentId = null;
+            if (parameters.TryGetValue("documentId", out selected))
+            {
+                documentId = selected as string;
+                if (documentId == null) throw new ArgumentException("documentId must be a string.");
+            }
+            lock (stateLock)
+            {
+                List<object> found = new List<object>();
+                foreach (Dictionary<string, object> record in records)
+                {
+                    if ((long)record["sequence"] <= afterSequence) continue;
+                    if (documentId != null && (string)record["documentId"] != documentId) continue;
+                    found.Add(record);
+                }
+                List<object> observedDocuments = new List<object>();
+                foreach (KeyValuePair<string, Dictionary<string, object>> document in documents)
+                    if (documentId == null || document.Key == documentId) observedDocuments.Add(document.Value);
+                return new Dictionary<string, object>
+                {
+                    { "sessionId", sessionId }, { "captureStartedAt", captureStartedAt },
+                    { "captureInstalled", captureInstalled }, { "latestSequence", sequence },
+                    { "documents", observedDocuments }, { "records", found }
+                };
+            }
+        }
+
+        internal void Installed() { lock (stateLock) captureInstalled = true; }
+
+        internal void Stop() { lock (stateLock) stopped = true; }
+
+        private static string Text(Dictionary<string, object> record, string key)
+        {
+            object value;
+            return record.TryGetValue(key, out value) ? value as string : null;
+        }
+    }
+}