sonorance 0.1.0-beta.4.1

package/src/feedback.mjs

@@ -0,0 +1,151 @@
+/**
+ * feedback.mjs — the platform feedback client (shared by the UI panel and `/deliberate feedback`).
+ *
+ * Feedback is the one channel that MAY carry user text — because it is explicit and user-authored
+ * (they typed it to send you). So, unlike telemetry (which has no free-text field), a feedback
+ * record carries the user's verbatim `message`. Design (feedback-ux spec):
+ *
+ *   - The user's `message` is the source of truth — stored EXACTLY as typed, never reworded. JTBD
+ *     distillation happens founder-side at review, not here.
+ *   - It travels over OTLP too (the founder's final call): as an OpenTelemetry LOG record named
+ *     `feedback`, carrying the consented content as attributes, sharing the SAME anonymous
+ *     `install_id` as telemetry so a bug report joins to "what this install actually did".
+ *   - It ALWAYS writes a durable local mirror first (`.sonorance/local/feedback.jsonl`) — files-first,
+ *     and the offline record if the endpoint is unset/unreachable.
+ *   - It works even when passive telemetry is OFF (the user chose to submit); only the local-test
+ *     switch (SONORANCE_TELEMETRY=console) diverts it to stdout instead of the wire.
+ *   - Only the bug `diagnostics` blob is scrubbed (a pasted log/stack); the user's words are not.
+ */
+import { appendFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { FEEDBACK_CATEGORIES, TELEMETRY_SCHEMA_VERSION } from './telemetry-schema.mjs';
+import { ensureInstallId, projectKey, ensureProjectKey, coarseEnv } from './identity.mjs';
+import { sonoranceHome } from './vault-registry.mjs';
+import { scrub } from './scrubber.mjs';
+import { encodeLogs, sendOtlp } from './otlp.mjs';
+import { resolveMode, resolveTransport } from './telemetry.mjs';
+import { encodeFeedbackEnvelope, sendAzure } from './azure-monitor.mjs';
+
+const RATINGS = new Set(['up', 'down', 'excited']);
+
+// The per-vault feedback mirror (committed-adjacent but machine-local); a home fallback when there
+// is no vault. Content-full by design (it is YOUR copy) — never committed (it lives under local/).
+export const feedbackMirrorPath = (vaultDir) =>
+  vaultDir ? join(vaultDir, '.sonorance', 'local', 'feedback.jsonl')
+           : join(sonoranceHome(), 'local', 'feedback.jsonl');
+
+const clampStr = (v, n) => (typeof v === 'string' ? v.slice(0, n) : '');
+
+// Normalise an incoming record into the content-safe, verbatim-first shape (feedback-ux §7).
+export function normalizeFeedback(input = {}, { surface = 'ui', product = 'sonorance', version = '0', vaultDir = null } = {}) {
+  const category = FEEDBACK_CATEGORIES.has(input.category) ? input.category : 'other';
+  let rating = null;
+  if (typeof input.rating === 'number' && input.rating >= 1 && input.rating <= 5) rating = Math.round(input.rating);
+  else if (RATINGS.has(input.rating)) rating = input.rating;
+
+  const install_id = ensureInstallId().id;
+  const project_key = vaultDir ? (projectKey(vaultDir) || ensureProjectKey(vaultDir)) : null;
+
+  const rec = {
+    type: 'feedback',
+    id: 'fb_' + randomBytes(4).toString('hex'),
+    schema: TELEMETRY_SCHEMA_VERSION,
+    ts: new Date().toISOString(),
+    install_id, project_key,
+    surface, product, version: String(version || '0'),
+    category, rating,
+    message: clampStr(input.message, 8000),               // VERBATIM — never reworded
+    context: input.context ? clampStr(input.context, 4000) : null,     // the user's answer to the one nudge
+    context_auto: sanitizeAutoContext(input.context_auto),            // coarse, content-free capture context
+    agent_context: input.agent_context ? clampStr(input.agent_context, 4000) : null, // agent-drafted, previewed
+    solution_hint: input.solution_hint ? clampStr(input.solution_hint, 4000) : null,
+    bug: category === 'bug' ? normalizeBug(input.bug) : null,
+    priority: input.priority ? clampStr(input.priority, 40) : null,
+    needs_framing: !!input.needs_framing,
+    contact: input.contact ? clampStr(input.contact, 200) : null,      // only if they asked for a reply
+  };
+  return rec;
+}
+
+// The optional coarse capture context: enums only (a command name, a stage, a surface, an error
+// class) — everything else is dropped. Never free text.
+function sanitizeAutoContext(c) {
+  if (!c || typeof c !== 'object') return null;
+  const out = {};
+  for (const k of ['command', 'stage', 'surface', 'error_class']) {
+    const v = c[k];
+    if (typeof v === 'string' && /^[A-Za-z0-9._-]{1,40}$/.test(v)) out[k] = v;
+  }
+  return Object.keys(out).length ? out : null;
+}
+
+// A bug's structured fields; the free-text `diagnostics` blob is SCRUBBED (paths/secrets/emails).
+function normalizeBug(bug) {
+  if (!bug || typeof bug !== 'object') return null;
+  return {
+    steps: clampStr(bug.steps, 4000) || null,
+    expected: clampStr(bug.expected, 2000) || null,
+    actual: clampStr(bug.actual, 2000) || null,
+    frequency: bug.frequency ? clampStr(bug.frequency, 40) : null,
+    diagnostics: bug.diagnostics ? scrub(bug.diagnostics, { max: 4000 }) : null,
+  };
+}
+
+// The OTLP log attributes for a feedback record — the consented content (allowed ONLY here).
+function feedbackLogAttributes(rec) {
+  const a = {
+    'feedback.id': rec.id,
+    'feedback.category': rec.category,
+    'feedback.message': rec.message,
+  };
+  if (rec.rating != null) a['feedback.rating'] = String(rec.rating);
+  if (rec.context) a['feedback.context'] = rec.context;
+  if (rec.agent_context) a['feedback.agent_context'] = rec.agent_context;
+  if (rec.solution_hint) a['feedback.solution_hint'] = rec.solution_hint;
+  if (rec.priority) a['feedback.priority'] = rec.priority;
+  if (rec.needs_framing) a['feedback.needs_framing'] = true;
+  if (rec.contact) a['feedback.contact'] = rec.contact;
+  if (rec.context_auto) for (const [k, v] of Object.entries(rec.context_auto)) a[`feedback.ctx.${k}`] = v;
+  if (rec.bug) for (const [k, v] of Object.entries(rec.bug)) if (v != null) a[`feedback.bug.${k}`] = v;
+  return a;
+}
+
+/**
+ * Persist + deliver a feedback record. Always writes the local mirror; then, unless the local-test
+ * switch diverts it, exports it as an OTLP log record. Returns `{ id }`. Never throws.
+ */
+export async function submitFeedback(input, opts = {}) {
+  const rec = normalizeFeedback(input, opts);
+  // 1) durable local mirror first (files-first + offline record).
+  const mirror = feedbackMirrorPath(opts.vaultDir);
+  try { await mkdir(mirror.replace(/[^/\\]+$/, ''), { recursive: true }); await appendFile(mirror, JSON.stringify(rec) + '\n'); } catch { /* best-effort */ }
+
+  // 2) Delivery over the ACTIVE transport (feedback works even when passive telemetry is off — the
+  //    user chose to submit). Azure Monitor by default (a content-full custom event), OTLP if an
+  //    OTLP endpoint is set, the local-test switch prints it, and local-only writes just the mirror.
+  const resource = {
+    telemetry_schema: TELEMETRY_SCHEMA_VERSION,
+    install_id: rec.install_id, project_key: rec.project_key,
+    product: rec.product, version: rec.version, surface: rec.surface,
+    ...coarseEnv(),
+  };
+  const attributes = feedbackLogAttributes(rec);
+  const mode = resolveMode(opts.vaultDir);
+  const transport = resolveTransport();
+  if (mode === 'console') {
+    try {
+      const line = transport.kind === 'azure'
+        ? `[telemetry:azure] ${JSON.stringify([encodeFeedbackEnvelope(attributes, resource)])}`
+        : `[telemetry:logs] ${JSON.stringify(encodeLogs([{ name: 'feedback', ts: Date.parse(rec.ts) || Date.now(), attributes }], resource))}`;
+      process.stderr.write(line + '\n');
+    } catch { /* ignore */ }
+  } else if (transport.kind === 'azure') {
+    await sendAzure([encodeFeedbackEnvelope(attributes, resource)], { endpoint: transport.endpoint }).catch(() => {});
+  } else if (transport.kind === 'otlp') {
+    const payload = encodeLogs([{ name: 'feedback', ts: Date.parse(rec.ts) || Date.now(), attributes }], resource);
+    await sendOtlp('logs', payload, { endpoint: transport.endpoint }).catch(() => {});
+  }
+  // transport 'none' → the durable local mirror (written above) is the record; nothing is sent.
+  return { id: rec.id, ok: true, needs_framing: rec.needs_framing };
+}

package/src/gitignore.mjs

@@ -0,0 +1,27 @@
+/**
+ * gitignore.mjs — keep a project's machine state out of git.
+ *
+ * `ensureGitignore(root, entries)` adds each entry to `<root>/.gitignore` — but ONLY if that
+ * file already exists (we never create one; a project that doesn't use .gitignore is left
+ * alone). Idempotent: an entry already present (with or without a trailing slash) is not
+ * re-added. Returns the entries actually written.
+ *
+ * This runs both from the CLI `init` and from `startServer` (whenever the app initiates a
+ * project in a folder — i.e. creates its `.sonorance/`), so machine state is ignored no matter
+ * how the project first came to be. The entries themselves are supplied by the host engine
+ * (`engine.gitignoreEntries(project)`): the generic app ignores `.sonorance/`; Deliberate also
+ * ignores any hidden subfolder under `deliberate/`.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function ensureGitignore(root, entries) {
+  const gi = join(root, '.gitignore');
+  if (!existsSync(gi)) return [];
+  const txt = readFileSync(gi, 'utf8');
+  const present = new Set(txt.split(/\r?\n/).map(l => l.trim().replace(/\/+$/, '')).filter(Boolean));
+  const missing = (entries || []).filter(e => e && !present.has(e.replace(/\/+$/, '')));
+  if (!missing.length) return [];
+  writeFileSync(gi, txt + (txt === '' || txt.endsWith('\n') ? '' : '\n') + missing.join('\n') + '\n');
+  return missing;
+}

package/src/grammar.mjs

@@ -0,0 +1,55 @@
+/**
+ * grammar.mjs — the SINGLE SOURCE OF TRUTH for Sonorance's command + on-disk surface.
+ *
+ * Sonorance is the app/platform: a local agent-review workbench over a Markdown folder, and the
+ * surface skills (like Deliberate) run on. Three grammars are described here:
+ *   - SKILL_COMMANDS — the harness-facing `/sonorance` grammar (what a user types).
+ *   - CLI_COMMANDS   — the `sonorance` binary (src/cli.mjs) the skill shells into.
+ *   - FS_LAYOUT      — where Sonorance keeps its platform state on disk (no database).
+ *
+ * Tests keep this registry, src/cli.mjs, and the shipped skill in lock-step. To add, rename, or
+ * remove a command, edit this file and update those surfaces in the same change.
+ */
+
+// Each entry: [command, one-line description]. `<folder>` defaults to the current directory.
+// Kept sorted alphabetically by command.
+export const SKILL_COMMANDS = [
+  ['/sonorance address', 'Work through open in-record comments in the running workbench — answer each question here, or edit the referenced file, then resolve it.'],
+  ['/sonorance open', 'Open the local agent-review workbench over the current folder.'],
+];
+
+// Each entry: [invocation, one-line description]. Mirrors the `dispatch` table in src/cli.mjs.
+// Kept sorted alphabetically by invocation.
+export const CLI_COMMANDS = [
+  ['comment list', 'The open in-record comments from the running editor, as JSON (the comment bridge — the skill parses it).'],
+  ['comment <commentId> resolve [--note "<text>"] [--revised]', 'Mark a comment resolved back to the editor (--revised if you edited the file; --note records what you did).'],
+  ['init [<folder>] [--name <name>]', 'Scaffold a Sonorance project — the hidden .sonorance/config.json (identity · settings) + hand-editable .sonorance/sources.md; name = folder.'],
+  ['install-skill [--here | --project <dir>]', 'Install the /sonorance skill (global, or into a repo’s .github/skills).'],
+  ['open [<folder>] [--name <name>]', 'Register a folder as a vault in ~/.sonorance and make it current, so it appears in the workbench vault switcher.'],
+  ['serve [<folder>] [--port <n>] [--open]', 'Start the local agent-review workbench over a folder (default: the current directory); --open launches the browser.'],
+  ['source [list | add <location> ["<description>"] [--section <section>] | remove <location>]', 'List / manage categorized shared grounding sources (the hand-editable .sonorance/sources.md, readable by every skill on the project).'],
+  ['telemetry [status | on | off | show | reset-id | test]', 'View or control the anonymous, content-free product telemetry (opt-out): show status + destination, turn it on/off, print the local audit trail, rotate the install id, or test the telemetry pipeline locally (Azure Monitor by default; set SONORANCE_TELEMETRY=console to watch the raw payload).'],
+];
+
+// The distinct top-level verbs the CLI must dispatch (first token of each command).
+export const CLI_COMMAND_NAMES = [...new Set(CLI_COMMANDS.map(([c]) => c.split(' ')[0]))];
+
+// Each entry: [path, description]. Paths are relative to the folder Sonorance is opened over
+// (the "vault") unless noted. Sonorance is files-first: everything is plain Markdown/JSON.
+// Kept sorted alphabetically by path.
+export const FS_LAYOUT = [
+  ['.sonorance/', 'Hidden Sonorance platform state at the folder root — shared, cross-skill project configuration. Committed to git.'],
+  ['.sonorance/config.json', 'Per-vault identity (id, name, created_at) + settings. Committed. Don’t hand-edit.'],
+  ['.sonorance/local/', 'Machine-local runtime state — gitignored. Disposable/regenerable; never shared across machines.'],
+  ['.sonorance/local/comments.jsonl', 'In-record comments (annotations on any file) — the store behind the comment bridge (address/resolve).'],
+  ['.sonorance/local/feedback.jsonl', 'Your local mirror of feedback submitted from this vault — content-full (your own copy), machine-local + gitignored. The durable record even offline.'],
+  ['.sonorance/local/serve.json', 'The running-editor pointer (port) — written on `serve`, read by `address` / `resolve` to find the live app.'],
+  ['.sonorance/local/state.json', 'Disposable editor state — open tabs, active tab, Explorer collapse/expand. Regenerable; safe to delete.'],
+  ['.sonorance/plugins.json', 'Enabled bundled plugin ids — e.g. `{ plugins: [{ id: "deliberate", enabled: true }] }`; contributions compose additively at serve time. Committed.'],
+  ['.sonorance/sources.md', 'The project’s categorized grounding sources — hand-editable Markdown grouped into product, code, data, customer, go-to-market, and other sections. Committed.'],
+  ['<folder>/', 'Any folder of Markdown files that Sonorance opens; the folder itself is the project.'],
+  ['<folder>/**/*.md', 'Your Markdown documents — what Sonorance renders, edits (WYSIWYG, autosaved), and diffs against git.'],
+  ['~/.sonorance/', 'The global Sonorance home (override with SONORANCE_HOME) — the platform state that spans folders.'],
+  ['~/.sonorance/config.json', 'The vault registry: { vaults: […absolute folder paths…], current } + the anonymous install_id and telemetry consent — powers the workbench vault switcher (open / switch / remove).'],
+  ['~/.sonorance/telemetry.jsonl', 'The local, human-readable telemetry audit trail — every content-free event is appended here before any network (files-first: read what we send). `sonorance telemetry show` prints it.'],
+];

package/src/identity.mjs

@@ -0,0 +1,126 @@
+/**
+ * identity.mjs — the anonymous ids that let feedback correlate with telemetry WITHOUT PII.
+ *
+ * Three opaque, random, PII-free ids (implementation spec §1), built on the identity primitives
+ * the platform already has (`~/.sonorance/config.json` home; per-vault `.sonorance/config.json`):
+ *
+ *   - install_id  — a random UUID minted once per install, stored in the home config. The
+ *                   correlation key: it rides every telemetry signal AND every feedback record,
+ *                   so the founder can join "this bug reporter" ↔ "what they actually did". The
+ *                   user can rotate it (`sonorance telemetry reset-id`) — a privacy control that
+ *                   deliberately breaks future correlation (the forget-me mechanism).
+ *   - project_key — a random hex added to the COMMITTED per-vault `.sonorance/config.json`, so a
+ *                   team's clones share it (active-projects + collaboration metrics) while each
+ *                   person's install_id still separates them. Random → safe to commit + send;
+ *                   crucially NOT the vault `id` (which is slug(folderName) and leaks the name).
+ *   - session_id  — a random per-process id, NEVER persisted. Sequences a session's events into a
+ *                   journey/trace, then evaporates.
+ *
+ * The home config is also where the telemetry preference lives (`telemetry: true|false`);
+ * undefined uses the default-on posture. Reads/writes here are merge-safe: the registry owns
+ * `vaults`/`current` in the same file, so we never clobber sibling keys.
+ */
+import { randomUUID, randomBytes } from 'node:crypto';
+import { readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { release } from 'node:os';
+import { registryConfigPath, sonoranceHome } from './vault-registry.mjs';
+
+// ---- generic merge-safe JSON config helpers (atomic write, never throws) ----
+const readJson = (p) => { try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return {}; } };
+const writeJson = (p, obj) => {
+  mkdirSync(dirname(p), { recursive: true });
+  const tmp = `${p}.tmp-${process.pid}`;
+  writeFileSync(tmp, JSON.stringify(obj, null, 2) + '\n');
+  renameSync(tmp, p);                                    // atomic: readers see old-or-new whole
+};
+// Read-modify-write ONE key without disturbing the rest of the file (the registry owns others).
+const patchJson = (p, key, value) => { const c = readJson(p); c[key] = value; writeJson(p, c); return c[key]; };
+
+const vaultConfig = (vaultDir) => join(vaultDir, '.sonorance', 'config.json');
+
+// ---- install_id (home config) ----
+// The stable, anonymous install identifier. Minted once (returns { id, fresh } so the caller can
+// fire `install.created` exactly on first mint). Pure random UUIDv4 — never derived from
+// hostname/MAC/user.
+export function ensureInstallId() {
+  const p = registryConfigPath();
+  const c = readJson(p);
+  if (c.install_id && typeof c.install_id === 'string') return { id: c.install_id, fresh: false };
+  const id = randomUUID();
+  patchJson(p, 'install_id', id);
+  return { id, fresh: true };
+}
+export const installId = () => ensureInstallId().id;
+
+// Rotate the install_id — a privacy control (and the local "forget me"): a fresh random id that
+// deliberately breaks correlation with everything sent before. Returns the new id.
+export function resetInstallId() {
+  const id = randomUUID();
+  patchJson(registryConfigPath(), 'install_id', id);
+  return id;
+}
+
+// ---- consent (home config) ----
+// undefined = use the default-on posture; true/false = an explicit user choice.
+export function getConsent() {
+  const v = readJson(registryConfigPath()).telemetry;
+  return typeof v === 'boolean' ? v : undefined;
+}
+export function setConsent(on) {
+  patchJson(registryConfigPath(), 'telemetry', !!on);
+  return !!on;
+}
+
+// ---- project_key (per-vault committed config) ----
+// A random per-vault key added to the COMMITTED `.sonorance/config.json`. Merge-safe: preserves
+// the identity (id/name/created_at) + any other keys the vault config holds. Null if no vaultDir.
+export function ensureProjectKey(vaultDir) {
+  if (!vaultDir) return null;
+  const p = vaultConfig(vaultDir);
+  const c = readJson(p);
+  if (c.project_key && typeof c.project_key === 'string') return c.project_key;
+  const key = randomBytes(16).toString('hex');
+  // Only write if the vault already exists as a project (has identity) OR create the key beside
+  // whatever is there — never invent identity here (that is init's job); just add the key.
+  patchJson(p, 'project_key', key);
+  return key;
+}
+// Read-only: the project_key if one has been minted, else null (no write — for hot resolvers).
+export function projectKey(vaultDir) {
+  if (!vaultDir) return null;
+  const k = readJson(vaultConfig(vaultDir)).project_key;
+  return typeof k === 'string' ? k : null;
+}
+
+// ---- session_id (ephemeral, per process) ----
+// A 32-hex value so it doubles as a valid OTLP trace id (the client strips the `s_` prefix):
+// "the session IS a trace" (implementation spec §2.1). Never persisted.
+let _sessionId = null;
+export function sessionId() {
+  if (!_sessionId) _sessionId = 's_' + randomBytes(16).toString('hex');
+  return _sessionId;
+}
+
+// ---- coarse, content-free environment context ----
+export function coarseEnv() {
+  const nodeMajor = Number(String(process.versions.node || '').split('.')[0]) || null;
+  const osMajor = Number(String(release() || '').split('.')[0]) || null;
+  return {
+    os: process.platform,                                // darwin | linux | win32
+    os_major: osMajor,
+    node_major: nodeMajor,
+    harness: harnessHint(),
+  };
+}
+// A best-effort, coarse hint at the agent harness the CLI runs under — env-var sniffing only,
+// never anything identifying. Extend as new harnesses appear.
+function harnessHint() {
+  const e = process.env;
+  if (e.COPILOT_AGENT_ID || e.GITHUB_COPILOT_CLI || e.COPILOT_CLI) return 'copilot-cli';
+  if (e.CLAUDECODE || e.CLAUDE_CODE) return 'claude-code';
+  if (e.CURSOR_TRACE_ID || e.CURSOR) return 'cursor';
+  return null;
+}
+
+export { sonoranceHome };

package/src/otlp.mjs

@@ -0,0 +1,166 @@
+/**
+ * otlp.mjs — a small, dependency-free OTLP/HTTP+JSON exporter (encoders + sender).
+ *
+ * Why hand-rolled and not the full `@opentelemetry/sdk-node`: the wire format is what makes
+ * telemetry vendor-agnostic ("won't have to migrate off"), and OTLP/HTTP+JSON is a stable,
+ * published protocol. Emitting it directly keeps the app dependency-light and zero-build (the
+ * house style) while staying 100% OTLP — the SAME bytes any OTLP backend (Azure Monitor, Grafana,
+ * Honeycomb) or the official OpenTelemetry Collector ingests. This is the *client exporter*, NOT a
+ * collector: the heavy aggregation/redaction/fan-out tier is the off-the-shelf `otelcol`, which
+ * this can export to unchanged by pointing the endpoint at it.
+ *
+ * Three signals are encoded: log records (events + feedback), metrics (aggregate rollups), and
+ * spans (a session trace + command spans). The telemetry client owns buffering + the resource;
+ * this module is pure: shape in → OTLP JSON out, plus a fire-and-forget POST.
+ */
+
+// ---- primitives -------------------------------------------------------------
+// OTLP timestamps are uint64 nanoseconds as a STRING. Derive from JS milliseconds.
+export const nanos = (ms = Date.now()) => String(BigInt(Math.round(ms)) * 1000000n);
+
+// Encode a flat { key: value } map into OTLP's KeyValue[] (skipping null/undefined). Numbers that
+// are integers use intValue (int64-as-string per spec); non-integers use doubleValue.
+export function toAttributes(obj = {}) {
+  const out = [];
+  for (const [key, v] of Object.entries(obj)) {
+    if (v == null) continue;
+    let value;
+    if (typeof v === 'boolean') value = { boolValue: v };
+    else if (typeof v === 'number') value = Number.isInteger(v) ? { intValue: String(v) } : { doubleValue: v };
+    else value = { stringValue: String(v) };
+    out.push({ key, value });
+  }
+  return out;
+}
+
+const SCOPE = { name: 'sonorance', version: '1' };
+// A session_id like `s_<32hex>` → the 32-hex OTLP trace id; anything else → undefined (no link).
+export const traceIdOf = (sessionId) => {
+  const hex = String(sessionId || '').replace(/^s_/, '');
+  return /^[0-9a-f]{32}$/i.test(hex) ? hex.toLowerCase() : undefined;
+};
+
+// ---- encoders ---------------------------------------------------------------
+// records: [{ name, ts, attributes, traceId? }] → OTLP ExportLogsServiceRequest.
+export function encodeLogs(records, resourceAttrs) {
+  return {
+    resourceLogs: [{
+      resource: { attributes: toAttributes(resourceAttrs) },
+      scopeLogs: [{
+        scope: SCOPE,
+        logRecords: records.map(r => {
+          const rec = {
+            timeUnixNano: nanos(r.ts),
+            severityNumber: r.name === 'error' ? 17 : 9,   // ERROR : INFO
+            severityText: r.name === 'error' ? 'ERROR' : 'INFO',
+            body: { stringValue: r.name },
+            attributes: toAttributes(r.attributes || {}),
+          };
+          if (r.traceId) rec.traceId = r.traceId;
+          return rec;
+        }),
+      }],
+    }],
+  };
+}
+
+// metrics: counters + gauges + histograms → OTLP ExportMetricsServiceRequest.
+// Counters/histograms use DELTA temporality; gauges are the latest current-value snapshot.
+export function encodeMetrics({ counters = [], gauges = [], histograms = [] } = {}, resourceAttrs, { start, end } = {}) {
+  const startNano = nanos(start), endNano = nanos(end);
+  const metrics = [];
+  for (const c of counters) {
+    metrics.push({
+      name: c.name, unit: '1',
+      sum: {
+        aggregationTemporality: 1, isMonotonic: true,
+        dataPoints: [{ asInt: String(Math.round(c.value || 0)), startTimeUnixNano: startNano, timeUnixNano: endNano, attributes: toAttributes(c.attributes || {}) }],
+      },
+    });
+  }
+  for (const g of gauges) {
+    metrics.push({
+      name: g.name, unit: '1',
+      gauge: {
+        dataPoints: [{ asInt: String(Math.round(g.value || 0)), timeUnixNano: endNano, attributes: toAttributes(g.attributes || {}) }],
+      },
+    });
+  }
+  for (const h of histograms) {
+    metrics.push({
+      name: h.name, unit: 'ms',
+      histogram: {
+        aggregationTemporality: 1,
+        dataPoints: [{
+          count: String(h.count || 0), sum: h.sum || 0,
+          explicitBounds: h.bounds || [], bucketCounts: (h.buckets || []).map(String),
+          startTimeUnixNano: startNano, timeUnixNano: endNano, attributes: toAttributes(h.attributes || {}),
+        }],
+      },
+    });
+  }
+  return { resourceMetrics: [{ resource: { attributes: toAttributes(resourceAttrs) }, scopeMetrics: [{ scope: SCOPE, metrics }] }] };
+}
+
+// spans: [{ name, traceId, spanId, parentSpanId?, start, end, attributes, ok }] → OTLP traces.
+export function encodeTraces(spans, resourceAttrs) {
+  return {
+    resourceSpans: [{
+      resource: { attributes: toAttributes(resourceAttrs) },
+      scopeSpans: [{
+        scope: SCOPE,
+        spans: spans.map(s => {
+          const span = {
+            traceId: s.traceId, spanId: s.spanId,
+            name: s.name, kind: 1,                          // INTERNAL
+            startTimeUnixNano: nanos(s.start), endTimeUnixNano: nanos(s.end ?? s.start),
+            attributes: toAttributes(s.attributes || {}),
+            status: { code: s.ok === false ? 2 : 0 },        // ERROR : UNSET
+          };
+          if (s.parentSpanId) span.parentSpanId = s.parentSpanId;
+          return span;
+        }),
+      }],
+    }],
+  };
+}
+
+// ---- sender -----------------------------------------------------------------
+// Resolve the base OTLP/HTTP endpoint. Honours the standard OTel env vars so the founder can point
+// it at Azure Monitor (or a local collector) with no code change; defaults to the collector's
+// conventional localhost port (4318) for the local-test path.
+export function otlpEndpoint() {
+  return process.env.SONORANCE_OTLP_ENDPOINT
+    || process.env.OTEL_EXPORTER_OTLP_ENDPOINT
+    || 'http://localhost:4318';
+}
+// Parse OTEL_EXPORTER_OTLP_HEADERS ("k1=v1,k2=v2") into a headers object.
+export function otlpHeaders() {
+  const raw = process.env.SONORANCE_OTLP_HEADERS || process.env.OTEL_EXPORTER_OTLP_HEADERS || '';
+  const h = { 'content-type': 'application/json' };
+  for (const pair of raw.split(',')) {
+    const i = pair.indexOf('='); if (i < 0) continue;
+    const k = pair.slice(0, i).trim(); const v = pair.slice(i + 1).trim();
+    if (k) h[k] = v;
+  }
+  return h;
+}
+
+const SIGNAL_PATH = { logs: '/v1/logs', metrics: '/v1/metrics', traces: '/v1/traces' };
+
+/**
+ * POST one signal's OTLP JSON payload. Fire-and-forget by design: resolves `{ ok }` and NEVER
+ * throws or blocks the caller for long (a hard timeout aborts a stuck request). Failures are
+ * swallowed — the client keeps its local JSONL as the audit/offline trail.
+ */
+export async function sendOtlp(signal, payload, { endpoint = otlpEndpoint(), headers = otlpHeaders(), timeoutMs = 3000 } = {}) {
+  const url = endpoint.replace(/\/$/, '') + (SIGNAL_PATH[signal] || `/v1/${signal}`);
+  const ac = new AbortController();
+  const t = setTimeout(() => ac.abort(), timeoutMs); t.unref?.();
+  try {
+    const res = await fetch(url, { method: 'POST', headers, body: JSON.stringify(payload), signal: ac.signal });
+    return { ok: !!res && res.ok, status: res?.status };
+  } catch (e) {
+    return { ok: false, error: e?.name || 'error' };
+  } finally { clearTimeout(t); }
+}

package/src/plugins/deliberate/contribute.mjs

@@ -0,0 +1,28 @@
+/**
+ * contribute.mjs — the Deliberate PLUGIN's additive contribution to the Sonorance engine.
+ *
+ * Sonorance is the host/platform; Deliberate is a per-vault plugin bundled inside this package (for
+ * extensibility) that LAYERS capabilities on top of the generic engine — it never replaces it. The
+ * host builds the default engine for every vault, then, for a vault that enables this plugin (in its
+ * `.sonorance/plugins.json`), merges these contributions:
+ *
+ *   - `KINDS`          — the document-kind registry (cases, one-pagers, briefs) that drives the
+ *                        inbox sections + per-file badges. The base engine contributes none.
+ *   - `openVault`      — the Deliberate record store (cases/briefs/context/competitors/ecosystem), overlaid
+ *                        on the base store so generic vault/comment/state machinery stays app-owned.
+ *   - `gitignoreEntries` — also keep any hidden `deliberate/` subfolder out of git.
+ *
+ * Identity (name/serve/address) is deliberately NOT contributed: the app is always Sonorance.
+ */
+import { KINDS } from './kinds.mjs';
+import { openVault } from './vault.mjs';
+import { vaultIgnoreEntries } from './gitignore.mjs';
+
+// The additive contribution the host composes onto the base engine for a Deliberate vault.
+export function contribute() {
+  return {
+    KINDS,
+    openVault,
+    gitignoreEntries: (project) => vaultIgnoreEntries(project.dir),
+  };
+}

package/src/plugins/deliberate/domain.mjs

@@ -0,0 +1,40 @@
+/**
+ * domain.mjs — shared vocabulary for the whole engine: the case lifecycle
+ * states, per-stage statuses, score thresholds, and the sentinel used to record
+ * the "current" project. Centralised here so CLI, server, store and pipeline
+ * agree on the same string literals instead of repeating them (and risking typos).
+ *
+ * Zero dependencies — safe to import from any layer, including the store.
+ */
+
+// Case lifecycle state (cases.state). 'new' is the initial state; while a run is
+// in flight the state holds the name of the stage currently executing; 'done'/'error'
+// are terminal. (There are no manual triage states — a case is managed as a file.)
+export const STATE = Object.freeze({
+  NEW: 'new',
+  ERROR: 'error',
+  DONE: 'done',
+});
+
+// Per-stage execution status (stages.status).
+export const STATUS = Object.freeze({
+  PENDING: 'pending',
+  RUNNING: 'running',
+  DONE: 'done',
+  ERROR: 'error',
+});
+
+// Inbox score colour bands (0–10 scale). A case at/above GOOD is green, at/above
+// OK is amber, below is red. These match the score advance/shelve/reject bands
+// and the UI's `sccls` helper (src/ui/index.html). scoreClass() returns the
+// matching CSS class ('g'|'y'|'r') or null.
+export const SCORE_GOOD = 7;
+export const SCORE_OK = 5;
+export function scoreClass(score) {
+  if (score == null) return null;
+  return score >= SCORE_GOOD ? 'g' : score >= SCORE_OK ? 'y' : 'r';
+}
+
+// The "current project" pointer is stored as a config row under a sentinel
+// project id ('_'), so both the CLI and the daemon resolve the same selection.
+export const CURRENT = Object.freeze({ project: '_', key: 'last' });