pluribus-context 0.3.22 → 0.3.26

package/examples/context-input-evidence/convert-compaction-log.mjs

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+import { createHash } from 'node:crypto';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const inputPath = process.argv[2] ? resolve(process.argv[2]) : join(here, 'sample-compaction-log.jsonl');
+const receiptPath = process.argv[3] ? resolve(process.argv[3]) : join(here, 'compaction-receipt.ndjson');
+const tracePath = process.argv[4] ? resolve(process.argv[4]) : join(here, 'compaction-otel-trace.json');
+
+function sha256(value) {
+  return `sha256:${createHash('sha256').update(value ?? '').digest('hex')}`;
+}
+
+function hashRef(value) {
+  return sha256(value ?? '').slice(0, 19);
+}
+
+function readJsonl(path) {
+  return readFileSync(path, 'utf8')
+    .trim()
+    .split('\n')
+    .filter(Boolean)
+    .map((line, index) => {
+      try {
+        return JSON.parse(line);
+      } catch (error) {
+        throw new Error(`Invalid JSONL at ${path}:${index + 1}: ${error.message}`);
+      }
+    });
+}
+
+function unixNano(isoTimestamp) {
+  return `${BigInt(Date.parse(isoTimestamp)) * 1_000_000n}`;
+}
+
+function otelValue(value) {
+  if (typeof value === 'boolean') return { boolValue: value };
+  if (typeof value === 'number' && Number.isInteger(value)) return { intValue: String(value) };
+  if (typeof value === 'number') return { doubleValue: value };
+  if (value == null) return { stringValue: '' };
+  return { stringValue: String(value) };
+}
+
+function attributesToOtel(attributes) {
+  return Object.entries(attributes).map(([key, value]) => ({ key, value: otelValue(value) }));
+}
+
+function tokenBucket(value) {
+  if (value < 1_000) return 'under_1k';
+  if (value < 10_000) return 'under_10k';
+  if (value < 50_000) return 'under_50k';
+  return 'over_50k';
+}
+
+const records = readJsonl(inputPath);
+const session = records.find((record) => record.type === 'session.start');
+const start = records.find((record) => record.type === 'context.compaction.start');
+const items = records.filter((record) => record.type === 'context.item.evaluated');
+const completed = records.find((record) => record.type === 'context.compaction.completed');
+
+if (!session || !start || !completed || items.length === 0) {
+  throw new Error(`Expected session.start, context.compaction.start, context.item.evaluated, and context.compaction.completed records in ${inputPath}`);
+}
+
+const traceSeed = `${session.session_id}:${start.time}:context-compaction`;
+const traceId = sha256(traceSeed).replace('sha256:', '').slice(0, 32);
+const spanId = sha256(`${traceSeed}:span`).replace('sha256:', '').slice(0, 16);
+const compactionId = hashRef(`${session.session_id}:${start.time}:${completed.time}`);
+
+const startEvent = {
+  trace_id: traceId,
+  span_id: spanId,
+  name: 'context.compaction.started',
+  time: start.time,
+  attributes: {
+    'session.id': session.session_id,
+    'gen_ai.conversation.id': session.conversation_id,
+    'agent.name': session.agent,
+    'context.compaction.id_hash': compactionId,
+    'context.compaction.reason': start.reason,
+    'context.compaction.trigger': start.trigger,
+    'context.compaction.token_count.before_bucket': tokenBucket(start.token_count_before),
+    'context.compaction.token_threshold_bucket': tokenBucket(start.token_threshold),
+    'context.compaction.window_bucket': start.window_bucket,
+    'context.compaction.objective.before_hash': sha256(start.raw_recent_task),
+    'privacy.raw_prompt_recorded': false,
+    'privacy.raw_context_recorded': false,
+    'privacy.raw_tool_output_recorded': false
+  }
+};
+
+const itemEvents = items.map((item) => ({
+  trace_id: traceId,
+  span_id: spanId,
+  name: 'context.compaction.item.evaluated',
+  time: item.time,
+  attributes: {
+    'session.id': session.session_id,
+    'gen_ai.conversation.id': session.conversation_id,
+    'context.compaction.id_hash': compactionId,
+    'context.item.id_hash': hashRef(item.item_id),
+    'context.item.kind': item.kind,
+    'context.item.source': item.source,
+    'context.item.source.hash': sha256(item.source),
+    'context.item.semantic_role': item.semantic_role,
+    'context.item.action': item.action,
+    'context.item.token_count_bucket': tokenBucket(item.token_count),
+    'context.item.summary_token_count_bucket': item.summary_token_count ? tokenBucket(item.summary_token_count) : '',
+    'context.item.drop_reason': item.drop_reason ?? '',
+    'context.item.raw_text_hash': sha256(item.raw_text),
+    'context.item.raw_text_recorded': false,
+    'context.item.reconstructable_from_hash': item.action === 'dropped' || item.action === 'preserved_hash_only',
+    'privacy.raw_context_recorded': false,
+    'privacy.raw_tool_output_recorded': false
+  }
+}));
+
+const completedEvent = {
+  trace_id: traceId,
+  span_id: spanId,
+  name: 'context.compaction.completed',
+  time: completed.time,
+  attributes: {
+    'session.id': session.session_id,
+    'gen_ai.conversation.id': session.conversation_id,
+    'context.compaction.id_hash': compactionId,
+    'context.compaction.token_count.after_bucket': tokenBucket(completed.token_count_after),
+    'context.compaction.summary.hash': sha256(completed.summary_hash_basis),
+    'context.compaction.objective.after_hash': sha256(completed.objective_hash_basis),
+    'context.compaction.item.count': items.length,
+    'context.compaction.items.dropped': completed.dropped_count,
+    'context.compaction.items.summarized': completed.summarized_count,
+    'context.compaction.items.preserved': completed.preserved_count,
+    'context.compaction.audit_gap': 'cannot_prove_semantic_equivalence_without_eval',
+    'privacy.raw_summary_recorded': false,
+    'privacy.raw_prompt_recorded': false,
+    'privacy.raw_context_recorded': false,
+    'privacy.raw_tool_output_recorded': false
+  }
+};
+
+const events = [startEvent, ...itemEvents, completedEvent]
+  .sort((left, right) => Date.parse(left.time) - Date.parse(right.time));
+
+writeFileSync(receiptPath, `${events.map((event) => JSON.stringify(event)).join('\n')}\n`);
+
+const trace = {
+  resourceSpans: [
+    {
+      resource: {
+        attributes: attributesToOtel({
+          'service.name': 'pluribus-context-compaction-receipt-demo',
+          'service.version': '0.0.0-fixture',
+          'deployment.environment.name': 'local-fixture'
+        })
+      },
+      scopeSpans: [
+        {
+          scope: {
+            name: 'pluribus.context_input_evidence.compaction_demo',
+            version: '0.0.0-fixture'
+          },
+          spans: [
+            {
+              traceId,
+              spanId,
+              parentSpanId: '',
+              name: 'agent.session.context.compaction',
+              kind: 1,
+              startTimeUnixNano: unixNano(start.time),
+              endTimeUnixNano: unixNano(completed.time),
+              attributes: attributesToOtel({
+                'session.id': session.session_id,
+                'gen_ai.conversation.id': session.conversation_id,
+                'agent.name': session.agent,
+                'workspace.name': session.workspace,
+                'gen_ai.request.model': session.model,
+                'context.compaction.id_hash': compactionId,
+                'context.compaction.reason': start.reason,
+                'context.compaction.trigger': start.trigger
+              }),
+              events: events.map((event) => ({
+                name: event.name,
+                timeUnixNano: unixNano(event.time),
+                attributes: attributesToOtel(event.attributes)
+              }))
+            }
+          ]
+        }
+      ]
+    }
+  ]
+};
+
+writeFileSync(tracePath, `${JSON.stringify(trace, null, 2)}\n`);
+
+const forbiddenRawStrings = [
+  'private customer checkout failures',
+  'never log customer payment tokens',
+  'vendor URLs, internal commands',
+  'customer-like fixture data',
+  'root cause previously suspected',
+  'avoid symptom patch'
+];
+const exportedText = `${events.map((event) => JSON.stringify(event)).join('\n')}\n${JSON.stringify(trace)}`;
+const rawTextCopiedToReceipt = forbiddenRawStrings.some((value) => exportedText.includes(value));
+const actionCounts = Object.fromEntries(items.map((item) => [item.action, items.filter((candidate) => candidate.action === item.action).length]));
+
+const summary = {
+  schema: 'pluribus.contextCompactionReceipt.demo.v0',
+  eventCount: events.length,
+  itemEvents: itemEvents.length,
+  actionCounts,
+  includesObjectiveHashes: Boolean(startEvent.attributes['context.compaction.objective.before_hash'] && completedEvent.attributes['context.compaction.objective.after_hash']),
+  includesAuditGap: completedEvent.attributes['context.compaction.audit_gap'],
+  rawTextCopiedToReceipt,
+  receiptPath: 'examples/context-input-evidence/compaction-receipt.ndjson',
+  tracePath: 'examples/context-input-evidence/compaction-otel-trace.json',
+  lesson: 'Context compaction needs receipts for trigger, item-level preserve/summarize/drop decisions, objective continuity, and audit gaps; green tests alone do not prove the original task survived compaction.'
+};
+
+console.log(JSON.stringify(summary, null, 2));

package/examples/context-input-evidence/convert-context-selection-log.mjs

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+import { createHash } from 'node:crypto';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const inputPath = process.argv[2] ? resolve(process.argv[2]) : join(here, 'sample-context-selection-log.jsonl');
+const receiptPath = process.argv[3] ? resolve(process.argv[3]) : join(here, 'context-selection-receipt.ndjson');
+const tracePath = process.argv[4] ? resolve(process.argv[4]) : join(here, 'context-selection-otel-trace.json');
+
+function sha256(value) {
+  return `sha256:${createHash('sha256').update(String(value)).digest('hex')}`;
+}
+
+function readJsonl(path) {
+  return readFileSync(path, 'utf8')
+    .trim()
+    .split('\n')
+    .filter(Boolean)
+    .map((line, index) => {
+      try {
+        return JSON.parse(line);
+      } catch (error) {
+        throw new Error(`Invalid JSONL at ${path}:${index + 1}: ${error.message}`);
+      }
+    });
+}
+
+function unixNano(isoTimestamp) {
+  return `${BigInt(Date.parse(isoTimestamp)) * 1_000_000n}`;
+}
+
+function otelValue(value) {
+  if (Array.isArray(value)) return { arrayValue: { values: value.map((item) => otelValue(item)) } };
+  if (typeof value === 'boolean') return { boolValue: value };
+  if (typeof value === 'number' && Number.isInteger(value)) return { intValue: String(value) };
+  if (typeof value === 'number') return { doubleValue: value };
+  if (typeof value === 'string') {
+    if (value === 'true' || value === 'false') return { boolValue: value === 'true' };
+    if (/^-?\d+$/.test(value)) return { intValue: value };
+    return { stringValue: value };
+  }
+  if (value == null) return { stringValue: '' };
+  return { stringValue: JSON.stringify(value) };
+}
+
+function attributesToOtel(attributes) {
+  return Object.entries(attributes).map(([key, value]) => ({ key, value: otelValue(value) }));
+}
+
+const records = readJsonl(inputPath);
+const selection = records.find((record) => record.type === 'context.selection');
+if (!selection) {
+  throw new Error(`No context.selection record found in ${inputPath}`);
+}
+
+const inputs = records.filter((record) => record.type === 'context.input');
+if (inputs.length === 0) {
+  throw new Error(`No context.input records found in ${inputPath}`);
+}
+
+const relevance = records.find((record) => record.type === 'context.decision.relevance');
+const sessionId = selection.session_id ?? 'demo-session-context-selection';
+const conversationId = selection.conversation_id ?? sessionId;
+const traceId = sha256(`${sessionId}:trace`).replace('sha256:', '').slice(0, 32);
+const spanId = sha256(`${sessionId}:span`).replace('sha256:', '').slice(0, 16);
+
+const inputEvents = inputs.map((record) => {
+  const sourceIdentity = record.source_id ?? 'unknown-source';
+  const sourceHash = sha256(sourceIdentity);
+  const deliveredHash = sha256(`${sessionId}:${sourceIdentity}:${record.selection_rank ?? 'unknown'}:${record.token_bucket ?? 'unknown'}`);
+
+  return {
+    trace_id: traceId,
+    span_id: spanId,
+    name: 'context.input.loaded',
+    time: record.time,
+    attributes: {
+      'session.id': sessionId,
+      'gen_ai.conversation.id': conversationId,
+      'context.input.kind': record.kind ?? 'unknown',
+      'context.input.source.id_hash': sourceHash,
+      'context.input.source.role': record.source_role ?? 'unknown',
+      'context.input.selection.rank': record.selection_rank ?? 0,
+      'context.input.selection.status': record.selection_status ?? 'unknown',
+      'context.input.delivery.status': record.delivery_status ?? 'unknown',
+      'context.input.delivered.hash': deliveredHash,
+      'context.input.token_bucket': record.token_bucket ?? 'unknown',
+      'context.input.audit_gap': 'hashes and counts prove selected/delivered identity, not semantic usefulness'
+    }
+  };
+});
+
+const selectionEvent = {
+  trace_id: traceId,
+  span_id: spanId,
+  name: 'context.input.selection.evaluated',
+  time: selection.time,
+  attributes: {
+    'session.id': sessionId,
+    'gen_ai.conversation.id': conversationId,
+    'context.selection.strategy': selection.selection_strategy ?? 'unknown',
+    'context.selection.policy': selection.selection_policy ?? 'unknown',
+    'context.input.candidate_count': selection.candidate_count ?? inputs.length,
+    'context.input.selected_count': selection.selected_count ?? inputs.length,
+    'context.input.suppressed_count': selection.suppressed_count ?? 0,
+    'context.input.delivered_hash_count': selection.delivered_hash_count ?? inputEvents.length,
+    'context.input.selected_token_bucket': selection.selected_token_bucket ?? 'unknown',
+    'context.input.suppressed_token_bucket': selection.suppressed_token_bucket ?? 'unknown',
+    'context.selection.operator_question': selection.operator_question ?? 'did_we_load_too_much_or_the_wrong_context',
+    'context.decision.relevance_evaluator': selection.decision_relevance_evaluator ?? 'not_available_yet',
+    'context.selection.audit_gap': selection.audit_gap ?? 'selection receipt proves delivery pressure, not semantic relevance'
+  }
+};
+
+const events = [selectionEvent, ...inputEvents];
+
+if (relevance) {
+  const selectedCount = relevance.selected_count ?? selection.selected_count ?? inputs.length;
+  const decisiveRanks = relevance.decisive_selection_ranks ?? [];
+  const supportingRanks = relevance.supporting_selection_ranks ?? relevance.relevant_selection_ranks ?? [];
+  const unusedRanks = relevance.unused_selection_ranks ?? [];
+  const unknownRanks = relevance.unknown_selection_ranks ?? [];
+  const decisiveCount = decisiveRanks.length;
+  const supportingCount = supportingRanks.length;
+  const unusedCount = unusedRanks.length;
+  const unknownCount = unknownRanks.length;
+  const accountedCount = decisiveCount + supportingCount + unusedCount + unknownCount;
+
+  if (decisiveCount + supportingCount > selectedCount) {
+    throw new Error(`Invalid relevance receipt: decisive_count + supporting_count (${decisiveCount + supportingCount}) exceeds selected_count (${selectedCount})`);
+  }
+
+  if (accountedCount !== selectedCount) {
+    throw new Error(`Invalid relevance receipt: selected_count (${selectedCount}) must equal decisive + supporting + unused + unknown (${accountedCount}) so over-selection does not disappear into a generic bucket`);
+  }
+
+  const decisionInputRanks = [...decisiveRanks, ...supportingRanks];
+  const decisionInputHashes = inputs
+    .filter((input) => decisionInputRanks.includes(input.selection_rank))
+    .map((input) => sha256(`${sessionId}:${input.source_id}:${input.selection_rank}:${input.token_bucket}`));
+
+  events.push({
+    trace_id: traceId,
+    span_id: spanId,
+    name: 'context.decision.relevance.evaluated',
+    time: relevance.time,
+    attributes: {
+      'session.id': sessionId,
+      'gen_ai.conversation.id': conversationId,
+      'decision.id_hash': sha256(relevance.decision_id ?? 'unknown-decision'),
+      'context.input.selected_count': selectedCount,
+      'context.input.suppressed_count': relevance.suppressed_count ?? selection.suppressed_count ?? 0,
+      'context.input.delivered_hash_count': relevance.delivered_hash_count ?? selection.delivered_hash_count ?? inputEvents.length,
+      'context.decision.input_hashes': decisionInputHashes,
+      'context.decision.relevance.decisive_count': decisiveCount,
+      'context.decision.relevance.supporting_count': supportingCount,
+      'context.decision.relevance.unused_count': unusedCount,
+      'context.decision.relevance.unknown_count': unknownCount,
+      'context.decision.relevance.accounted_count': accountedCount,
+      'context.decision.relevance.invariant': 'selected_count == decisive_count + supporting_count + unused_count + unknown_count; decisive_count + supporting_count <= selected_count',
+      'context.decision.relevance.outcome': relevance.relevance_outcome ?? 'unknown',
+      'context.decision.evaluator': relevance.decision_relevance_evaluator ?? 'unknown',
+      'context.decision.audit_gap': relevance.audit_gap ?? 'relevance is evaluator-derived; loaded receipts only prove delivery'
+    }
+  });
+}
+
+writeFileSync(receiptPath, `${events.map((event) => JSON.stringify(event)).join('\n')}\n`);
+
+const eventTimes = events.map((event) => Date.parse(event.time)).filter(Number.isFinite);
+const startTimeMs = Math.min(...eventTimes);
+const endTimeMs = Math.max(...eventTimes) + 1;
+
+const otlpTrace = {
+  resourceSpans: [
+    {
+      resource: {
+        attributes: attributesToOtel({
+          'service.name': 'pluribus-context-selection-demo',
+          'service.version': '0.0.0-fixture',
+          'deployment.environment.name': 'local-fixture'
+        })
+      },
+      scopeSpans: [
+        {
+          scope: { name: 'pluribus.context_selection.demo', version: '0.0.0-fixture' },
+          spans: [
+            {
+              traceId,
+              spanId,
+              parentSpanId: '',
+              name: 'agent.session',
+              kind: 1,
+              startTimeUnixNano: `${BigInt(startTimeMs) * 1_000_000n}`,
+              endTimeUnixNano: `${BigInt(endTimeMs) * 1_000_000n}`,
+              attributes: attributesToOtel({
+                'session.id': sessionId,
+                'gen_ai.conversation.id': conversationId,
+                'gen_ai.agent.name': selection.agent ?? 'unknown',
+                'gen_ai.operation.name': 'agent_session'
+              }),
+              events: events.map((event) => ({
+                name: event.name,
+                timeUnixNano: unixNano(event.time),
+                attributes: attributesToOtel(event.attributes)
+              }))
+            }
+          ]
+        }
+      ]
+    }
+  ]
+};
+
+writeFileSync(tracePath, `${JSON.stringify(otlpTrace, null, 2)}\n`);
+
+const rawLeakNeedles = [
+  'Acme-Co',
+  'Stripe prod incident',
+  '/private/work/acme',
+  'sk_live_private_demo',
+  'private-demo-token',
+  'customer request payload'
+];
+const receiptText = readFileSync(receiptPath, 'utf8');
+const traceText = readFileSync(tracePath, 'utf8');
+const leakedNeedles = rawLeakNeedles.filter((needle) => receiptText.includes(needle) || traceText.includes(needle));
+if (leakedNeedles.length > 0) {
+  throw new Error(`Raw private fixture strings leaked into receipt/trace: ${leakedNeedles.join(', ')}`);
+}
+
+console.log(JSON.stringify({
+  schema: 'pluribus.contextSelectionOverSelectionDemo.v0',
+  inputPath,
+  receiptPath,
+  tracePath,
+  sessionId,
+  eventCount: events.length,
+  selectedCount: selection.selected_count,
+  suppressedCount: selection.suppressed_count,
+  deliveredHashCount: selection.delivered_hash_count,
+  hasDecisionRelevanceEvent: Boolean(relevance),
+  privacyDefault: 'outputs hashes, buckets, counts, ranks, categorical fields, and audit gaps; does not copy raw prompts, customer names, private paths, secrets, tool output, or memory bodies',
+  lesson: 'The cheap first signal is over-selection: selected_count and delivered_hash_count can show too much context crossed the boundary before any relevance evaluator exists. When relevance exists, decisive/supporting/unused/unknown counts must account for selected_count so over-selection stays explicit.'
+}, null, 2));