sonorance 0.1.0-beta.4.1

package/LICENSE

@@ -0,0 +1,174 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and do not
+          modify the License. You may add Your own attribution notices
+          within Derivative Works, alongside or as an addendum to the NOTICE
+          text from the Work, provided that such additional attribution
+          notices cannot be construed as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or for
+      any such Derivative Works as a whole, provided Your use, reproduction,
+      and distribution of the Work otherwise complies with the conditions
+      stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer, and
+      charge a fee for, acceptance of support, warranty, indemnity, or
+      other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

package/README.md

@@ -0,0 +1,103 @@
+# Sonorance
+
+Sonorance is a local web application for reviewing and addressing work stored in Markdown files. It provides an Explorer, editing, search, git diff, inline comments, and a comment bridge for coding agents.
+
+## Run it
+
+Node.js 22.5 or newer is required.
+
+```bash
+npx sonorance init
+npx sonorance serve /path/to/folder --open
+
+# From a source checkout:
+npm install
+node src/cli.mjs init
+node src/cli.mjs serve /path/to/folder --open
+```
+
+Every visible `.md` file appears in the Explorer. Frontmatter is preserved and hidden from the editor, links open separately, images resolve relative to their file, and autosave writes to disk. Git repositories also expose changed files, per-file diffs, and guarded discard.
+
+## Project state
+
+```text
+.sonorance/
+  config.json          project identity and settings
+  plugins.json         enabled bundled plugin ids
+  sources.md           hand-editable grounding sources
+  local/
+    state.json         machine-local tabs and Explorer state
+    comments.jsonl     machine-local inline comments
+    serve.json         running-server discovery
+```
+
+Only `.sonorance/local/` is disposable and gitignored.
+
+```bash
+node src/cli.mjs source add <location> ["<description>"]
+node src/cli.mjs source list
+node src/cli.mjs source remove <location>
+```
+
+## Review workflow
+
+1. Select text and leave a comment.
+2. Run `/sonorance address` in the coding agent.
+3. The agent reads the open comments, answers or edits the referenced file, and resolves completed items.
+4. Review the result in Document or Diff mode.
+
+The low-level bridge is:
+
+```bash
+node src/cli.mjs comment list
+node src/cli.mjs comment <commentId> resolve [--note "…"] [--revised]
+```
+
+Transport, HTTP, payload, server, and response-schema failures exit nonzero.
+
+## Plugins
+
+Sonorance resolves enabled bundled plugins from `.sonorance/plugins.json`:
+
+```json
+{ "plugins": [{ "id": "deliberate", "enabled": true }] }
+```
+
+Plugins contribute document kinds, record storage, and gitignore behavior to the generic engine. They cannot load executable paths from vault configuration, replace the engine, or change the application identity.
+
+```js
+import { startServer } from 'sonorance';
+import { resolveEngine } from 'sonorance/plugins';
+
+const engine = await resolveEngine(process.cwd());
+await startServer({ engine, port: 7777 });
+```
+
+## Privacy and telemetry
+
+Privacy is foundational to Sonorance. Anonymous usage telemetry is on by default in the official npm package so we can understand which features help, improve performance, fix issues, and keep developing the product.
+
+Sonorance collects only a small amount of content-free data: feature usage, performance measurements, and redacted error signals. All exported telemetry is anonymized, allow-listed, and stripped of sensitive information. Sonorance never logs your work—not even project, file, or folder names. File and document contents, titles, paths, prompts, completions, error messages, and stack traces always stay private.
+
+Telemetry is written to a local JSONL audit trail before export so you can inspect what Sonorance records. You can turn telemetry off at any time in Settings, through the CLI/environment, or with a committed project policy. Feedback is separate and is sent only when you explicitly submit it.
+
+Source checkouts have no embedded destination. To export from a source checkout or override the package destination:
+
+```sh
+export APPLICATIONINSIGHTS_CONNECTION_STRING="InstrumentationKey=…;IngestionEndpoint=https://<region>.in.applicationinsights.azure.com/"
+# Or:
+export SONORANCE_OTLP_ENDPOINT=https://collector.example
+```
+
+`SONORANCE_TELEMETRY=off`, `DO_NOT_TRACK=1`, CI, and a project policy with `"telemetry": false` all disable export.
+
+## Repository map
+
+- `src/server/` — local HTTP API, SSE, git, files, comments, and telemetry ingestion.
+- `src/ui/` — source shell/app, editor integration, Markdown conversion, comments, diff, and interaction plugins.
+- `src/engine-default.mjs` — generic folder engine.
+- `src/plugins.mjs` — bundled-id additive plugin composition.
+- `src/plugins/deliberate/` — the Deliberate contribution and file-backed record store.
+- `src/cli.mjs` and `src/grammar.mjs` — CLI implementation and command/filesystem grammar.
+- `skill/` — the shipped `/sonorance` skill.
+- `test/` — engine, server, CLI, telemetry, and jsdom UI coverage.

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "sonorance",
+  "version": "0.1.0-beta.4.1",
+  "type": "module",
+  "description": "Sonorance — a local agent-review workbench over Markdown: Explorer, editing, git diff, inline comments, search, and additive product plugins.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sonorance/sonorance.git"
+  },
+  "homepage": "https://github.com/Sonorance/sonorance#readme",
+  "bugs": {
+    "url": "https://github.com/Sonorance/sonorance/issues"
+  },
+  "keywords": [
+    "markdown",
+    "agent",
+    "review",
+    "workbench"
+  ],
+  "bin": {
+    "sonorance": "src/cli.mjs"
+  },
+  "exports": {
+    ".": "./src/server/index.mjs",
+    "./server": "./src/server/index.mjs",
+    "./engine-default": "./src/engine-default.mjs",
+    "./vault-registry": "./src/vault-registry.mjs",
+    "./telemetry.mjs": "./src/telemetry.mjs",
+    "./telemetry-schema.mjs": "./src/telemetry-schema.mjs",
+    "./feedback.mjs": "./src/feedback.mjs",
+    "./comment-client.mjs": "./src/comment-client.mjs",
+    "./identity.mjs": "./src/identity.mjs",
+    "./scrubber.mjs": "./src/scrubber.mjs",
+    "./plugins": "./src/plugins.mjs",
+    "./plugins/deliberate/*": "./src/plugins/deliberate/*"
+  },
+  "scripts": {
+    "build": "node scripts/build-ui.mjs",
+    "start": "npm run build && node src/cli.mjs serve",
+    "pretest": "npm run build",
+    "test": "node --test --test-force-exit --import ./test-setup.mjs",
+    "prepack": "npm run build",
+    "verify-package": "node scripts/verify-package.mjs"
+  },
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.1",
+    "jsdom": "^29.1.1"
+  },
+  "allowScripts": {
+    "esbuild@0.28.1": true
+  },
+  "dependencies": {
+    "@tiptap/core": "^3.27.3",
+    "@tiptap/extension-link": "^3.27.3",
+    "@tiptap/extension-placeholder": "^3.27.3",
+    "@tiptap/extension-table": "^3.27.3",
+    "@tiptap/extension-table-cell": "^3.27.3",
+    "@tiptap/extension-table-header": "^3.27.3",
+    "@tiptap/extension-table-row": "^3.27.3",
+    "@tiptap/extension-task-item": "^3.27.3",
+    "@tiptap/extension-task-list": "^3.27.3",
+    "@tiptap/pm": "^3.27.3",
+    "@tiptap/starter-kit": "^3.27.3",
+    "@tiptap/suggestion": "^3.27.3",
+    "mdast-util-gfm": "^3.1.0",
+    "mdast-util-to-markdown": "^2.1.2",
+    "remark-frontmatter": "^5.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-parse": "^11.0.0",
+    "unified": "^11.0.5"
+  },
+  "files": [
+    "build/icon.png",
+    "src",
+    "skill",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: sonorance
+description: 'Use when the user wants to address, resolve, or act on comments and review notes they left in the Sonorance app. Sonorance is a local agent-review workbench over Markdown: readers select a span, leave a question or change request, inspect agent edits in Diff mode, and close the loop. This skill fetches open comments, answers or edits the referenced file, and marks each addressed comment resolved. Triggers — address comments, resolve comments, work through my review notes, act on the notes I left in the app.'
+version: '0.1.0'
+user-invocable: true
+argument-hint: '[address | open]'
+license: Apache-2.0
+---
+
+# Sonorance — address review comments with the agent
+
+Sonorance is a local agent-review workbench over a folder of Markdown. A reader selects any span and leaves an inline question or change request; this skill lets the coding agent work through those comments, make grounded edits, and resolve the review loop.
+
+## Setup
+
+Define the launcher once per session:
+
+```
+LAUNCHER = node .github/skills/sonorance/scripts/sonorance.mjs
+```
+
+Run everything below as `LAUNCHER <args>` (Node ≥ 22). The launcher talks to the running Sonorance app; start it with `sonorance serve` in the folder when needed.
+
+## `address` — work through open comments
+
+1. **Fetch.** Run `LAUNCHER comment list` → `{ comments: [ { id, file, anchor:{quote,heading}, body, addressing? }, ... ], count }`. Each open comment names the folder-relative `file` it annotates. If the command exits nonzero, surface the app/transport error; never treat failure as an empty queue.
+2. **Address each comment.** Open the file and locate the quote under its heading. Answer a question in this conversation without changing the file. For a change request, edit the referenced file; confirm first when the edit is material or ambiguous. Follow any `addressing` guidance attached by a document kind.
+3. **Resolve.** Run `LAUNCHER comment <commentId> resolve`; add `--revised` after editing and optionally `--note "<what you did>"`. Resolve only after the comment was actually addressed.
+4. **Review.** Tell the user what you answered or changed. They inspect the resulting file and git diff in Sonorance.
+
+## `open` — open the review workbench
+
+Run `LAUNCHER serve --open` from the current folder. This starts Sonorance over that folder and opens the browser; it does not create a Deliberate workflow or reinterpret the files.
+
+## Rules
+
+- **Ground every answer and edit** in the file and the user's comment. Never invent content.
+- **Files are the deliverable.** Edit the user's Markdown; their git records the revision.
+- **Resolve only completed work.** Questions answered here and edits applied may be resolved; untouched comments remain open.
+- **Keep the scope focused.** Address the reader's comments and preserve the existing document workflow.
+- **Be concise.** Report what changed, not a wall of process text.

package/skill/scripts/sonorance.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * sonorance.mjs — launcher the skill shells into. Resolves the Sonorance CLI and forwards
+ * all args + stdio to it, so SKILL.md never hard-codes an engine path. Resolution order:
+ *   1. $SONORANCE_ENGINE (explicit override)
+ *   2. ./engine.json  { "engine": "/abs/path/to/src/cli.mjs" }  (written by `sonorance install-skill`)
+ *   3. ../../src/cli.mjs  (in-repo dev: skill/scripts → package root)
+ * The spawned CLI inherits cwd, so `address`/`resolve` act on the folder the user is in.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+function enginePath() {
+  const env = process.env.SONORANCE_ENGINE;
+  if (env && existsSync(env)) return env;
+  const cfg = join(here, 'engine.json');
+  if (existsSync(cfg)) { try { const e = JSON.parse(readFileSync(cfg, 'utf8')).engine; if (e && existsSync(e)) return e; } catch { /* ignore */ } }
+  return resolve(here, '../../src/cli.mjs');
+}
+
+const engine = enginePath();
+if (!existsSync(engine)) {
+  console.error(`sonorance: engine not found at ${engine}. Set SONORANCE_ENGINE or re-run \`sonorance install-skill\`.`);
+  process.exit(1);
+}
+const r = spawnSync(process.execPath, [engine, ...process.argv.slice(2)], { stdio: 'inherit' });
+process.exit(r.status ?? 1);

package/src/azure-monitor.mjs

@@ -0,0 +1,221 @@
+/**
+ * azure-monitor.mjs — a small, dependency-free Azure Monitor / Application Insights exporter.
+ *
+ * This is the "Path B" transport: the client instruments with OpenTelemetry semantics (see
+ * telemetry.mjs) but exports straight to Azure Monitor's classic ingestion ("Breeze") endpoint
+ * using a caller-provided connection string — NO collector, NO gateway, NO Entra auth.
+ *
+ * Why hand-rolled and not `@azure/monitor-opentelemetry`: the house style is dependency-light and
+ * zero-build (see otlp.mjs). The Breeze envelope is a small, stable JSON contract, so we encode it
+ * directly and keep the app free of the heavy Azure SDK dependency tree. The OTLP exporter
+ * (otlp.mjs) still exists for the vendor-agnostic path (a self-hosted collector or any OTLP
+ * backend); the transport is chosen at flush time (telemetry.mjs → resolveTransport).
+ *
+ * Mapping OTel → App Insights tables:
+ *   - product events  → EventData        (customEvents)
+ *   - the `error` event → ExceptionData   (exceptions; typeName only, NEVER a message/stack)
+ *   - metric rollups  → MetricData        (customMetrics)
+ *   - the session span → RequestData      (requests)
+ *   - command/stage spans → RemoteDependencyData (dependencies), correlated by operation id.
+ */
+import { traceIdOf } from './otlp.mjs';
+import { RELEASE_AZURE_CONNECTION_STRING } from './release-config.mjs';
+
+// ---- connection string ------------------------------------------------------
+// Public source keeps this empty. The official npm release injects its destination while packing.
+export const DEFAULT_CONNECTION_STRING = RELEASE_AZURE_CONNECTION_STRING;
+
+export function azureConnectionString() {
+  return process.env.APPLICATIONINSIGHTS_CONNECTION_STRING
+    || process.env.SONORANCE_AZURE_CONNECTION_STRING
+    || DEFAULT_CONNECTION_STRING;
+}
+
+// Parse `Key=Value;…` into { ikey, ingestionEndpoint }. Tolerant of casing/whitespace/order.
+export function parseConnectionString(cs = azureConnectionString()) {
+  const map = {};
+  for (const part of String(cs || '').split(';')) {
+    const i = part.indexOf('='); if (i < 0) continue;
+    map[part.slice(0, i).trim().toLowerCase()] = part.slice(i + 1).trim();
+  }
+  const ikey = map.instrumentationkey || '';
+  // Modern connection strings always carry IngestionEndpoint; fall back to the legacy global dc.
+  let ingest = map.ingestionendpoint || (ikey ? 'https://dc.services.visualstudio.com' : '');
+  return { ikey, ingestionEndpoint: ingest.replace(/\/+$/, '') };
+}
+
+// The classic ingestion ("Breeze") track URL, or null if the connection string is unusable.
+export function azureTrackUrl(cs = azureConnectionString()) {
+  const { ikey, ingestionEndpoint } = parseConnectionString(cs);
+  if (!ikey || !ingestionEndpoint) return null;
+  return `${ingestionEndpoint}/v2.1/track`;
+}
+
+// ---- envelope primitives ----------------------------------------------------
+// AI item name: `Microsoft.ApplicationInsights.<ikey-no-hyphens>.<Type>`.
+const itemName = (ikey, type) => `Microsoft.ApplicationInsights.${String(ikey || '').replace(/-/g, '')}.${type}`;
+
+// A .NET-style timespan `[d.]hh:mm:ss.fff` from a millisecond duration (AI request/dependency).
+export function msToTimeSpan(ms) {
+  let n = Number(ms); if (!Number.isFinite(n) || n < 0) n = 0;
+  const pad = (v, l = 2) => String(v).padStart(l, '0');
+  const days = Math.floor(n / 86400000);
+  const hh = Math.floor((n / 3600000) % 24);
+  const mm = Math.floor((n / 60000) % 60);
+  const ss = Math.floor((n / 1000) % 60);
+  const fff = Math.floor(n % 1000);
+  const base = `${pad(hh)}:${pad(mm)}:${pad(ss)}.${pad(fff, 3)}`;
+  return days > 0 ? `${days}.${base}` : base;
+}
+
+// Split a flat prop map into AI's { properties (strings), measurements (numbers) }.
+function splitProps(props = {}) {
+  const properties = {}, measurements = {};
+  for (const [k, v] of Object.entries(props || {})) {
+    if (v == null) continue;
+    if (typeof v === 'number' && Number.isFinite(v)) measurements[k] = v;
+    else properties[k] = typeof v === 'boolean' ? String(v) : String(v);
+  }
+  return { properties, measurements };
+}
+
+// The well-known AI context tags that become first-class columns (user_Id, session_Id,
+// operation_Id, application_Version, cloud_RoleName) — the correlation + segmentation backbone.
+function baseTags(r = {}) {
+  const t = {};
+  if (r.install_id) { t['ai.user.id'] = String(r.install_id); t['ai.device.id'] = String(r.install_id); }
+  if (r.session_id) t['ai.session.id'] = String(r.session_id);
+  const opId = traceIdOf(r.session_id);
+  if (opId) t['ai.operation.id'] = opId;
+  if (r.version != null) t['ai.application.ver'] = String(r.version);
+  const role = [r.product, r.surface].filter(Boolean).join(':');
+  if (role) t['ai.cloud.role'] = role;
+  t['ai.internal.sdkVersion'] = 'sonorance:1';
+  return t;
+}
+
+// The identity/context that rides EVERY item as customDimensions (content-free, low-cardinality),
+// so any table can be sliced by product/surface/version/os without a join.
+function baseProps(r = {}) {
+  const p = {};
+  for (const k of ['telemetry_schema', 'install_id', 'project_key', 'product', 'version', 'surface', 'os', 'harness']) {
+    if (r[k] != null) p[k] = String(r[k]);
+  }
+  if (r.os_major != null) p.os_major = String(r.os_major);
+  if (r.node_major != null) p.node_major = String(r.node_major);
+  return p;
+}
+
+function envelope(shortType, baseType, baseData, ts, ikey, tags) {
+  return {
+    name: itemName(ikey, shortType),
+    time: new Date(ts || Date.now()).toISOString(),
+    iKey: ikey,
+    tags: tags || {},
+    data: { baseType, baseData },
+  };
+}
+
+// ---- per-signal envelope builders -------------------------------------------
+function eventEnvelope(name, props, ts, ikey, tags, commonProps) {
+  const { properties, measurements } = splitProps(props);
+  return envelope('Event', 'EventData', {
+    ver: 2, name,
+    properties: { ...commonProps, ...properties },
+    measurements,
+  }, ts, ikey, tags);
+}
+
+// The `error` event → an Exception. typeName is the error CLASS only; the message/stack is NEVER
+// carried (privacy invariant — the class is low-cardinality, the message could be content).
+function exceptionEnvelope(props, ts, ikey, tags, commonProps) {
+  const { properties } = splitProps(props);
+  const typeName = properties.class || 'Error';
+  return envelope('Exception', 'ExceptionData', {
+    ver: 2,
+    exceptions: [{ id: 1, typeName, message: '', hasFullStack: false, parsedStack: [] }],
+    severityLevel: 3,
+    properties: { ...commonProps, ...properties },
+  }, ts, ikey, tags);
+}
+
+function metricEnvelope(name, agg, ts, ikey, tags, commonProps) {
+  const dp = { name, kind: 1, value: Number(agg.value) || 0, count: Number(agg.count) || 1 };
+  if (agg.min != null) dp.min = agg.min;
+  if (agg.max != null) dp.max = agg.max;
+  return envelope('Metric', 'MetricData', {
+    ver: 2, metrics: [dp], properties: commonProps,
+  }, ts, ikey, tags);
+}
+
+function spanEnvelope(s, ikey, tags, commonProps) {
+  const dur = msToTimeSpan((s.end ?? s.start) - s.start);
+  const localTags = { ...tags };
+  if (s.traceId) localTags['ai.operation.id'] = s.traceId;
+  if (s.parentSpanId) localTags['ai.operation.parentId'] = s.parentSpanId;
+  const { properties } = splitProps(s.attributes || {});
+  const props = { ...commonProps, ...properties };
+  if (!s.parentSpanId) {
+    // The root session span → a Request (the "session" operation).
+    return envelope('Request', 'RequestData', {
+      ver: 2, id: s.spanId, name: s.name, duration: dur,
+      responseCode: s.ok === false ? '1' : '0', success: s.ok !== false,
+      properties: props,
+    }, s.start, ikey, localTags);
+  }
+  // A command/stage span → an in-process dependency, linked to the session operation.
+  return envelope('RemoteDependency', 'RemoteDependencyData', {
+    ver: 2, id: s.spanId, name: s.name, duration: dur,
+    resultCode: s.ok === false ? '1' : '0', success: s.ok !== false,
+    type: 'InProc', properties: props,
+  }, s.start, ikey, localTags);
+}
+
+// ---- the encoder ------------------------------------------------------------
+// Neutral buffers (the SAME shapes the OTLP path drains) → an array of AI envelopes.
+export function encodeEnvelopes({ events = [], spans = [], counters = [], gauges = [], histograms = [], window } = {}, resource = {}, cs = azureConnectionString()) {
+  const { ikey } = parseConnectionString(cs);
+  const tags = baseTags(resource);
+  const commonProps = baseProps(resource);
+  const metricTs = window?.end || Date.now();
+  const out = [];
+  for (const e of events) {
+    if (e.name === 'error') out.push(exceptionEnvelope(e.props || e.attributes, e.ts, ikey, tags, commonProps));
+    else out.push(eventEnvelope(e.name, e.props || e.attributes, e.ts, ikey, tags, commonProps));
+  }
+  for (const s of spans) out.push(spanEnvelope(s, ikey, tags, commonProps));
+  for (const c of counters) out.push(metricEnvelope(c.name, { value: c.value, count: 1 }, metricTs, ikey, tags, commonProps));
+  for (const g of gauges) out.push(metricEnvelope(g.name, { value: g.value, count: 1, min: g.value, max: g.value }, metricTs, ikey, tags, commonProps));
+  for (const h of histograms) out.push(metricEnvelope(h.name, { value: h.sum, count: h.count, min: h.min, max: h.max }, metricTs, ikey, tags, commonProps));
+  return out;
+}
+
+// A single feedback record → an EventData custom event named `feedback`. Feedback is the one
+// content-full channel (consented, user-authored): the message rides as a customDimension.
+export function encodeFeedbackEnvelope(attributes = {}, resource = {}, cs = azureConnectionString()) {
+  const { ikey } = parseConnectionString(cs);
+  return eventEnvelope('feedback', attributes, Date.now(), ikey, baseTags(resource), baseProps(resource));
+}
+
+// ---- sender -----------------------------------------------------------------
+/**
+ * POST a batch of envelopes to the Breeze track endpoint. Fire-and-forget by design: resolves
+ * `{ ok }`, never throws, and a hard timeout aborts a stuck request. Failures are swallowed — the
+ * caller keeps its local JSONL audit trail as the durable/offline record.
+ */
+export async function sendAzure(envelopes, { endpoint = azureTrackUrl(), timeoutMs = 3000 } = {}) {
+  if (!endpoint || !Array.isArray(envelopes) || !envelopes.length) return { ok: false, error: 'no-endpoint-or-empty' };
+  const ac = new AbortController();
+  const t = setTimeout(() => ac.abort(), timeoutMs); t.unref?.();
+  try {
+    const res = await fetch(endpoint, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(envelopes),
+      signal: ac.signal,
+    });
+    return { ok: !!res && res.ok, status: res?.status };
+  } catch (e) {
+    return { ok: false, error: e?.name || 'error' };
+  } finally { clearTimeout(t); }
+}