@piagent/platform 1.0.0

package/scripts/profile-doctor.sh

@@ -0,0 +1,238 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ $# -lt 1 ]]; then
+  echo "Usage: $0 <project-path> [profile-json]"
+  exit 2
+fi
+
+PROJECT_PATH="$1"
+PROFILE_PATH="${2:-"$PROJECT_PATH/.pi/piagent-profile.json"}"
+
+if [[ ! -d "$PROJECT_PATH" ]]; then
+  echo "FAIL: project path does not exist: $PROJECT_PATH"
+  exit 1
+fi
+
+if [[ ! -f "$PROFILE_PATH" ]]; then
+  echo "FAIL: profile not found: $PROFILE_PATH"
+  exit 1
+fi
+
+node --input-type=module - "$PROJECT_PATH" "$PROFILE_PATH" <<'NODE'
+import fs from "node:fs";
+import path from "node:path";
+
+const [projectPath, profilePath] = process.argv.slice(2);
+const profile = JSON.parse(fs.readFileSync(profilePath, "utf8"));
+
+const errors = [];
+const warnings = [];
+
+function requireArray(name) {
+  if (!Array.isArray(profile[name])) {
+    errors.push(`${name} must be an array`);
+    return [];
+  }
+  return profile[name];
+}
+
+function optionalArray(name) {
+  if (profile[name] === undefined) return [];
+  if (!Array.isArray(profile[name])) {
+    errors.push(`${name} must be an array when provided`);
+    return [];
+  }
+  return profile[name];
+}
+
+function warnShellOnlyProtectedPaths(shellProtectedPaths, protectedPaths, readOnlyPaths) {
+  const writeGuardedPaths = new Set([...protectedPaths, ...readOnlyPaths]);
+  for (const candidate of shellProtectedPaths) {
+    if (typeof candidate !== "string" || candidate.trim().length === 0) continue;
+    if (writeGuardedPaths.has(candidate)) continue;
+    warnings.push(`shellProtectedPaths-only path ${candidate} blocks shell access only; add it to protectedPaths to block read/write, or readOnlyPaths to allow read but block write/shell`);
+  }
+}
+
+if (profile.schemaVersion !== 1) errors.push("schemaVersion must be 1");
+if (!profile.projectId) errors.push("projectId is required");
+if (!profile.displayName) errors.push("displayName is required");
+if (!profile.mode) errors.push("mode is required");
+
+const rootMarkers = requireArray("rootMarkers");
+const protectedPaths = requireArray("protectedPaths");
+const shellProtectedPaths = optionalArray("shellProtectedPaths");
+const readOnlyPaths = optionalArray("readOnlyPaths");
+const requiredContext = requireArray("requiredContext");
+const mcpCapabilities = requireArray("mcpCapabilities");
+
+warnShellOnlyProtectedPaths(shellProtectedPaths, protectedPaths, readOnlyPaths);
+
+const capabilityPacks = profile.capabilityPacks ?? [];
+if (!Array.isArray(capabilityPacks)) {
+  errors.push("capabilityPacks must be an array");
+} else {
+  const seenPacks = new Set();
+  for (const [index, pack] of capabilityPacks.entries()) {
+    if (!pack || typeof pack !== "object" || Array.isArray(pack)) {
+      errors.push(`capabilityPacks[${index}] must be an object`);
+      continue;
+    }
+    if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(pack.name ?? "")) {
+      errors.push(`capabilityPacks[${index}].name is invalid`);
+    }
+    if (!/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/.test(pack.version ?? "")) {
+      errors.push(`capabilityPacks[${index}].version is invalid`);
+    }
+    const key = `${pack.name}@${pack.version}`;
+    if (seenPacks.has(key)) errors.push(`capabilityPacks contains duplicate ${key}`);
+    seenPacks.add(key);
+  }
+}
+
+const defaultCapabilityPolicy = {
+  allowedOwners: [],
+  allowedLifecycles: [],
+  allowedFilesystemRead: [],
+  allowedFilesystemWrite: [],
+  allowedNetworkDomains: [],
+  allowedExternalActions: []
+};
+const capabilityPolicy = profile.capabilityPolicy && typeof profile.capabilityPolicy === "object" && !Array.isArray(profile.capabilityPolicy)
+  ? profile.capabilityPolicy
+  : defaultCapabilityPolicy;
+if (profile.capabilityPolicy !== undefined && capabilityPolicy === defaultCapabilityPolicy) errors.push("capabilityPolicy must be an object");
+for (const key of ["allowedOwners", "allowedLifecycles", "allowedFilesystemRead", "allowedFilesystemWrite", "allowedNetworkDomains", "allowedExternalActions"]) {
+  if (!Array.isArray(capabilityPolicy[key])) errors.push(`capabilityPolicy.${key} must be an array`);
+}
+for (const lifecycle of Array.isArray(capabilityPolicy.allowedLifecycles) ? capabilityPolicy.allowedLifecycles : []) {
+  if (!["experimental", "stable", "deprecated"].includes(lifecycle)) {
+    errors.push(`capabilityPolicy.allowedLifecycles contains invalid value ${lifecycle}`);
+  }
+}
+
+if (!profile.verifyCommands || typeof profile.verifyCommands !== "object" || Array.isArray(profile.verifyCommands)) {
+  errors.push("verifyCommands must be an object");
+}
+
+const existingRootMarkers = rootMarkers.filter((marker) => fs.existsSync(path.join(projectPath, marker)));
+if (existingRootMarkers.length === 0) {
+  warnings.push(`no rootMarkers found in project: ${rootMarkers.join(", ")}`);
+}
+
+for (const contextPath of requiredContext) {
+  if (contextPath.includes("<")) {
+    warnings.push(`requiredContext has placeholder: ${contextPath}`);
+    continue;
+  }
+  if (!fs.existsSync(path.join(projectPath, contextPath))) {
+    warnings.push(`requiredContext missing in project: ${contextPath}`);
+  }
+}
+
+if (protectedPaths.length === 0) warnings.push("protectedPaths is empty");
+if (mcpCapabilities.length === 0) warnings.push("mcpCapabilities is empty");
+
+const defaultRuntimePolicy = {
+  execPolicy: "enforce",
+  contextBudget: "enforce",
+  toolRegistry: "advisory",
+  finalGate: "advisory"
+};
+const runtimePolicyOverrides = profile.runtimePolicy === undefined
+  ? {}
+  : profile.runtimePolicy && typeof profile.runtimePolicy === "object" && !Array.isArray(profile.runtimePolicy)
+    ? profile.runtimePolicy
+    : {};
+if (profile.runtimePolicy !== undefined && runtimePolicyOverrides !== profile.runtimePolicy) errors.push("runtimePolicy must be an object");
+const runtimePolicy = { ...defaultRuntimePolicy, ...runtimePolicyOverrides };
+for (const [key, value] of Object.entries(runtimePolicy)) {
+  if (!["off", "advisory", "enforce"].includes(value)) {
+    errors.push(`runtimePolicy.${key} must be off, advisory, or enforce`);
+  }
+}
+
+const contextIndexDefaults = {
+  enabled: true,
+  path: ".pi/context-index.json",
+  writePolicy: "onboarding-record",
+  requireCitations: true,
+  maxNodes: 120,
+  maxEdges: 240,
+  includeTechStack: true,
+  includeMemoryPointers: true
+};
+let contextIndex = contextIndexDefaults;
+if (profile.contextIndex !== undefined) {
+  if (!profile.contextIndex || typeof profile.contextIndex !== "object" || Array.isArray(profile.contextIndex)) {
+    errors.push("contextIndex must be an object");
+  } else {
+    contextIndex = { ...contextIndexDefaults, ...profile.contextIndex };
+    if (typeof contextIndex.enabled !== "boolean") errors.push("contextIndex.enabled must be boolean");
+    if (typeof contextIndex.path !== "string" || contextIndex.path.trim().length === 0) errors.push("contextIndex.path must be a non-empty string");
+    if (!["onboarding-record", "approved-workflow", "off"].includes(contextIndex.writePolicy)) {
+      errors.push("contextIndex.writePolicy must be onboarding-record, approved-workflow, or off");
+    }
+    if (typeof contextIndex.requireCitations !== "boolean") errors.push("contextIndex.requireCitations must be boolean");
+    if (!Number.isInteger(contextIndex.maxNodes) || contextIndex.maxNodes < 1 || contextIndex.maxNodes > 500) errors.push("contextIndex.maxNodes must be an integer from 1 to 500");
+    if (!Number.isInteger(contextIndex.maxEdges) || contextIndex.maxEdges < 0 || contextIndex.maxEdges > 1000) errors.push("contextIndex.maxEdges must be an integer from 0 to 1000");
+    if (typeof contextIndex.includeTechStack !== "boolean") errors.push("contextIndex.includeTechStack must be boolean");
+    if (typeof contextIndex.includeMemoryPointers !== "boolean") errors.push("contextIndex.includeMemoryPointers must be boolean");
+  }
+}
+
+if (contextIndex.enabled && contextIndex.writePolicy !== "off") {
+  const indexPath = path.resolve(projectPath, contextIndex.path);
+  const relativeIndexPath = path.relative(projectPath, indexPath);
+  if (relativeIndexPath.startsWith("..") || path.isAbsolute(relativeIndexPath)) {
+    errors.push(`contextIndex.path escapes project root: ${contextIndex.path}`);
+  } else if (!fs.existsSync(indexPath)) {
+    warnings.push(`context index missing: ${contextIndex.path}; run /onboard-project or record piagent_context_index_record`);
+  }
+}
+
+const verifyEntries = Object.entries(profile.verifyCommands ?? {});
+if (verifyEntries.length === 0) {
+  errors.push("verifyCommands has no entries");
+}
+for (const [key, commands] of verifyEntries) {
+  if (!Array.isArray(commands) || commands.length === 0) {
+    errors.push(`verifyCommands.${key} must be a non-empty array`);
+    continue;
+  }
+  for (const command of commands) {
+    if (typeof command !== "string" || command.trim().length === 0) {
+      errors.push(`verifyCommands.${key} contains an empty command`);
+    }
+  }
+}
+
+const report = {
+  projectPath,
+  profilePath,
+  projectId: profile.projectId,
+  mode: profile.mode,
+  rootMarkersFound: existingRootMarkers,
+  requiredContextCount: requiredContext.length,
+  protectedPathCount: protectedPaths.length,
+  shellProtectedPathCount: shellProtectedPaths.length,
+  readOnlyPathCount: readOnlyPaths.length,
+  verifyProfiles: verifyEntries.map(([key]) => key),
+  mcpCapabilities,
+  capabilityPacks: Array.isArray(capabilityPacks)
+    ? capabilityPacks
+      .filter((pack) => pack && typeof pack === "object" && !Array.isArray(pack))
+      .map((pack) => `${String(pack.name ?? "<invalid>")}@${String(pack.version ?? "<invalid>")}`)
+    : [],
+  capabilityPolicy,
+  runtimePolicy,
+  contextIndex,
+  warnings,
+  errors
+};
+
+console.log(JSON.stringify(report, null, 2));
+
+if (errors.length > 0) process.exit(1);
+NODE

package/scripts/quality-benchmark.sh

@@ -0,0 +1,185 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  scripts/quality-benchmark.sh <project-path> --init
+  scripts/quality-benchmark.sh <project-path> --record --scenario <name> --surface <name> --result <pass|fail|partial> [options]
+
+Options:
+  --task-file <path>      File containing task prompt/spec.
+  --verify <command>      Verification command used for the run.
+  --tokens <number>       Total tokens reported by the agent/provider.
+  --cost <number>         Cost reported for the run.
+  --duration <seconds>    Wall-clock duration.
+  --notes <text>          Short notes or quality observations.
+  --agent <name>          Backward-compatible alias for --surface.
+
+Output:
+  <project-path>/.pi/benchmarks/quality-runs.jsonl
+USAGE
+}
+
+if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+  usage
+  exit 0
+fi
+
+PROJECT_PATH="${1:-}"
+if [[ -z "$PROJECT_PATH" ]]; then
+  usage
+  exit 2
+fi
+shift || true
+
+PROJECT_PATH="$(cd "$PROJECT_PATH" && pwd)"
+MODE=""
+SCENARIO=""
+SURFACE=""
+RESULT=""
+TASK_FILE=""
+VERIFY_CMD=""
+TOKENS=""
+COST=""
+DURATION=""
+NOTES=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --init)
+      MODE="init"
+      shift
+      ;;
+    --record)
+      MODE="record"
+      shift
+      ;;
+    --scenario)
+      SCENARIO="${2:-}"
+      shift 2
+      ;;
+    --surface|--agent)
+      SURFACE="${2:-}"
+      shift 2
+      ;;
+    --result)
+      RESULT="${2:-}"
+      shift 2
+      ;;
+    --task-file)
+      TASK_FILE="${2:-}"
+      shift 2
+      ;;
+    --verify)
+      VERIFY_CMD="${2:-}"
+      shift 2
+      ;;
+    --tokens)
+      TOKENS="${2:-}"
+      shift 2
+      ;;
+    --cost)
+      COST="${2:-}"
+      shift 2
+      ;;
+    --duration)
+      DURATION="${2:-}"
+      shift 2
+      ;;
+    --notes)
+      NOTES="${2:-}"
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      usage
+      exit 2
+      ;;
+  esac
+done
+
+BENCHMARK_DIR="$PROJECT_PATH/.pi/benchmarks"
+mkdir -p "$BENCHMARK_DIR"
+
+if [[ "$MODE" == "init" ]]; then
+  cat > "$BENCHMARK_DIR/quality-scenarios.md" <<'SCENARIOS'
+# Agent quality benchmark scenarios
+
+Use the same scenario, acceptance criteria, and verification command across approved agent surfaces before making quality, token, or cost claims.
+
+## Scenario 1: read-only scout
+
+- Goal: inspect repo structure and produce implementation plan.
+- Must not edit files.
+- Evidence: context files read, plan, risks, verify command proposal.
+
+## Scenario 2: bounded source fix
+
+- Goal: implement a small bugfix with clear acceptance criteria.
+- Evidence: changed files, verify command exit 0, trace/handoff.
+
+## Scenario 3: backend-readonly to frontend implementation
+
+- Goal: scout backend/spec read-only, implement frontend mapping only.
+- Evidence: backend contract snapshot, frontend changed files, frontend verify pass.
+SCENARIOS
+  echo "Initialized benchmark scenarios: $BENCHMARK_DIR/quality-scenarios.md"
+  exit 0
+fi
+
+if [[ "$MODE" != "record" || -z "$SCENARIO" || -z "$SURFACE" || -z "$RESULT" ]]; then
+  usage
+  exit 2
+fi
+
+case "$RESULT" in
+  pass|fail|partial) ;;
+  *)
+    echo "--result must be pass, fail, or partial" >&2
+    exit 2
+    ;;
+esac
+
+export PI_BENCHMARK_PROJECT_PATH="$PROJECT_PATH"
+export PI_BENCHMARK_SCENARIO="$SCENARIO"
+export PI_BENCHMARK_SURFACE="$SURFACE"
+export PI_BENCHMARK_RESULT="$RESULT"
+export PI_BENCHMARK_TASK_FILE="$TASK_FILE"
+export PI_BENCHMARK_VERIFY="$VERIFY_CMD"
+export PI_BENCHMARK_TOKENS="$TOKENS"
+export PI_BENCHMARK_COST="$COST"
+export PI_BENCHMARK_DURATION="$DURATION"
+export PI_BENCHMARK_NOTES="$NOTES"
+
+node --input-type=module <<'NODE'
+import fs from "node:fs";
+import path from "node:path";
+
+const root = process.env.PI_BENCHMARK_PROJECT_PATH;
+const target = path.join(root, ".pi", "benchmarks", "quality-runs.jsonl");
+const numberOrNull = (value) => {
+  if (!value) return null;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+};
+const payload = {
+  schemaVersion: 1,
+  recordedAt: new Date().toISOString(),
+  scenario: process.env.PI_BENCHMARK_SCENARIO,
+  surface: process.env.PI_BENCHMARK_SURFACE,
+  result: process.env.PI_BENCHMARK_RESULT,
+  taskFile: process.env.PI_BENCHMARK_TASK_FILE || null,
+  verifyCommand: process.env.PI_BENCHMARK_VERIFY || null,
+  tokens: numberOrNull(process.env.PI_BENCHMARK_TOKENS),
+  cost: numberOrNull(process.env.PI_BENCHMARK_COST),
+  durationSeconds: numberOrNull(process.env.PI_BENCHMARK_DURATION),
+  notes: process.env.PI_BENCHMARK_NOTES || null
+};
+fs.appendFileSync(target, `${JSON.stringify(payload)}\n`);
+console.log(`Recorded benchmark run: ${target}`);
+NODE

package/scripts/redaction-benchmark.mjs

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+import { performance } from "node:perf_hooks";
+import { pathToFileURL } from "node:url";
+import {
+  redactForStorage,
+  redactSensitiveText
+} from "../packages/piagent-core/security/sensitive-data.js";
+
+const REDACTION = "[REDACTED_SECRET]";
+const join = (...parts) => parts.join("");
+
+const contextualCases = [
+  ["aws-assignment", "assignment", join("AWS_SECRET_ACCESS_KEY=", "wJalrXUtnFEMI/", "K7MDENG/bPxRfiCYEXAMPLEKEY")],
+  ["aws-whitespace", "assignment", join("aws_secret_access_key ", "wJalrXUtnFEMI/", "K7MDENG/bPxRfiCYEXAMPLEKEY")],
+  ["github-fine", "vendor", join("github_pat_", "11AAAAAAA0", "abcdefghijklmnopqrstuvwxyz")],
+  ["github-classic", "vendor", join("ghp_", "abcdefghijklmnopqrstuvwxyz1234567890")],
+  ["openai-project", "vendor", join("sk-", "proj-", "abcdefghijklmnopqrstuvwxyz1234567890")],
+  ["stripe-live", "vendor", join("sk_", "live_", "51NxTExampleSecretValue123456")],
+  ["slack-bot", "vendor", join("xoxb-", "123456789012-123456789012-", "AbCdEfGhIjKlMnOp")],
+  ["google-api", "vendor", join("AIza", "SyDExampleKeyWithEnoughLength123456")],
+  ["jwt", "vendor", join("eyJhbGciOiJIUzI1NiJ9.", "eyJzdWIiOiIxMjM0NTY3ODkwIn0.", "signature123456")],
+  ["pem-pkcs8", "private-key", join("-----BEGIN ", "PRIVATE KEY-----\nabc123\n-----END PRIVATE KEY-----")],
+  ["pem-openssh", "private-key", join("-----BEGIN ", "OPENSSH PRIVATE KEY-----\nabc123\n-----END OPENSSH PRIVATE KEY-----")],
+  ["postgres-url", "credential-url", "postgres://app:synthetic-pass-42@db.example.invalid/prod"],
+  ["mysql-url", "credential-url", "mysql://app:synthetic-pass-42@db.example.invalid/prod"],
+  ["mariadb-url", "credential-url", "mariadb://app:synthetic-pass-42@db.example.invalid/prod"],
+  ["mongodb-url", "credential-url", "mongodb://app:synthetic-pass-42@db.example.invalid/prod"],
+  ["redis-url", "credential-url", "redis://app:synthetic-pass-42@cache.example.invalid/0"],
+  ["http-userinfo", "credential-url", "https://robot:synthetic-http-pass-42@example.invalid/api"],
+  ["ftp-userinfo", "credential-url", "ftp://robot:synthetic-ftp-pass-42@example.invalid/archive"],
+  ["bearer", "authorization", "Authorization: Bearer syntheticBearerToken_1234567890"],
+  ["basic-auth", "authorization", "Authorization: Basic dXNlcjpzeW50aGV0aWMtcGFzcy00Mg=="],
+  ["token-auth", "authorization", "Authorization: Token synthetic-auth-token-123"],
+  ["api-key-auth", "authorization", "Authorization: ApiKey synthetic-auth-key-123"],
+  ["digest-auth", "authorization", "Authorization: Digest username=robot, response=synthetic-response-123"],
+  ["password-key", "assignment", "PASSWORD=synthetic-pass-42"],
+  ["pwd-key", "assignment", "pwd: synthetic-pass-42"],
+  ["api-key-json", "assignment", "{\"api_key\":\"synthetic-key-123456\"}"],
+  ["client-secret", "assignment", "client_secret=synthetic-client-123"],
+  ["access-token", "assignment", "access_token=synthetic-access-123"],
+  ["refresh-token", "assignment", "refresh_token=synthetic-refresh-123"],
+  ["credential-key", "assignment", "credential: synthetic-credential-123"],
+  ["prefixed-token", "assignment", "CI_JOB_TOKEN=synthetic-job-token-123"],
+  ["alphabetic-token", "assignment", "token=abcdefghijklmnopqrstuvwx"],
+  ["alphabetic-api-key", "assignment", "apiKey=ABCDEFGHIJKLMNOPQRSTUVWXYZ"],
+  ["alphabetic-authorization", "authorization", "Authorization: Token abcdefghijklmnopqrstuvwx"],
+  ["webhook-secret", "assignment", "WEBHOOK_SECRET=synthetic-webhook-123"],
+  ["session-token", "assignment", "session_token=synthetic-session-123"],
+  ["query-token", "assignment", "https://example.invalid/callback?access_token=synthetic-query-token-123"],
+  ["query-refresh-token", "assignment", "https://example.invalid/callback?refresh_token=synthetic-query-refresh-123&ok=1"],
+  ["hyphen-header", "assignment", "X-Api-Key: synthetic-header-key-123"],
+  ["private-token-header", "assignment", "PRIVATE-TOKEN: synthetic-private-token-123"],
+  ["camel-api-key", "assignment", "{\"apiKey\":\"synthetic-camel-key-123\"}"],
+  ["camel-client-secret", "assignment", "{\"clientSecret\":\"synthetic-camel-secret-123\"}"],
+  ["camel-access-token", "assignment", "{\"accessToken\":\"synthetic-camel-access-123\"}"],
+  ["passphrase", "assignment", "passphrase=synthetic-passphrase-123"],
+  ["private-key-field", "assignment", "{\"private_key\":\"synthetic-private-material-123\"}"],
+  ["signing-key-field", "assignment", "signingKey=synthetic-signing-material-123"],
+  ["quoted-export", "assignment", "export TOKEN='synthetic-export-token-123'"],
+  ["quoted-password-spaces", "assignment", "password=\"Correct Horse Battery 42\""],
+  ["quoted-client-secret-spaces", "assignment", "clientSecret='synthetic client secret 123'"],
+  ["quoted-password-escape", "assignment", "password=\"Correct \\\"Horse\\\" Battery 42\""],
+  ["quoted-secret-escape", "assignment", "secret='synthetic \\'quoted\\' secret 123'"],
+  ["multiline", "assignment", "name=service\npassword=synthetic-multiline-42\nstatus=ok"]
+].map(([name, category, text]) => ({ name, category, text }));
+
+const unlabeledEntropyCases = [
+  ["base64-32", "QWxhZGRpbjpvcGVuIHNlc2FtZTEyMzQ1Njc4"],
+  ["urlsafe-40", "Hf8_3nQvZ0sL1aYp7Tt9mK2rW4xC6bD8eF0gJ5hN"],
+  ["mixed-48", "aB9xP2mN7qR4tV8zK1cD6fG0hJ3lS5wY9uE2iO7p"],
+  ["hex-64", "9f86d081884c7d659a2feaa0c55ad015bf4f1b2b0b822cd15d6c15b0f00a08aa"],
+  ["base32-52", "JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXPJBSQ"],
+  ["opaque-id", "01J4Z3N8K2Q7V5X9C1B6M0R4T8Y2W7S5"]
+].map(([name, text]) => ({ name, text }));
+
+const benignCases = [
+  ["prose-secret", "The secret: always run tests before final."],
+  ["null-token", "token: null"],
+  ["placeholder", "api_key: placeholder"],
+  ["short-password", "password: short"],
+  ["unset-secret", "clientSecret=<not-set>"],
+  ["source-code", "if (token === undefined) return;"],
+  ["git-sha", "commit 4431c9edaf7c72b56943d0c74c17ee0214690eb5"],
+  ["sha256", "sha256:d8a46b50ea37b68544add1e73ccb382b9ba06f6fe673dd82c50b294fdf412ec6"],
+  ["uuid", "request_id=123e4567-e89b-12d3-a456-426614174000"],
+  ["example-url", "https://example.invalid/docs"],
+  ["package-integrity", "integrity sha512-AbCdEfGhIjKlMnOpQrStUvWxYz0123456789+/=="],
+  ["public-key", "-----BEGIN PUBLIC KEY-----\nabc123\n-----END PUBLIC KEY-----"],
+  ["artifact-id", "artifact_id=Hf8_3nQvZ0sL1aYp7Tt9mK2rW4xC6bD8"],
+  ["trace-id", "trace_id=aB9xP2mN7qR4tV8zK1cD6fG0hJ3lS5wY9uE2"],
+  ["checksum", "checksum=9f86d081884c7d659a2feaa0c55ad015"],
+  ["model-id", "model=provider-model-2026-07-21"],
+  ["file-name", "generated file auth.json.example"],
+  ["command-doc", "Run npm test and tsc --noEmit."],
+  ["boolean-secret", "secret=false"],
+  ["redacted-marker", "password=[REDACTED_SECRET]"],
+  ["quoted-redacted-marker", "password=\"[REDACTED_SECRET]\""],
+  ["authorization-placeholder", "Authorization: Token placeholder"],
+  ["quoted-placeholder", "clientSecret='not-set'"],
+  ["your-key", "Set apiKey=your-key-here before local testing."],
+  ["ordinary-number", "retry_token_count=12"],
+  ["semantic-token-name", "The parser emits a token node."],
+  ["password-policy", "Password policy requires twelve characters."],
+  ["credential-doc", "Credential rotation is required quarterly."],
+  ["password-policy-field", "passwordPolicy=minimum-length"],
+  ["semantic-token-type-field", "semanticTokenType=namespace-declaration"]
+].map(([name, text]) => ({ name, text }));
+
+const structuredInput = {
+  password: "synthetic-structured-pass-42",
+  apiKey: "synthetic-structured-key-42",
+  nested: {
+    clientSecret: "synthetic-structured-client-42",
+    sessionToken: "synthetic-structured-session-42"
+  },
+  tokens: ["synthetic-array-token-123"],
+  apiKeys: ["synthetic-array-key-123"],
+  passwords: ["hunter42"],
+  credentials: ["userpass"],
+  id: "Hf8_3nQvZ0sL1aYp7Tt9mK2rW4xC6bD8",
+  checksum: "9f86d081884c7d659a2feaa0c55ad015",
+  labels: ["provider-model-2026-07-21"],
+  semanticTokens: ["namespace-declaration-123"],
+  colorTokens: ["primary-blue-500"],
+  passwordPolicy: "minimum-length",
+  semanticTokenType: "namespace-declaration"
+};
+
+function percentage(value, total) {
+  return total === 0 ? 1 : value / total;
+}
+
+export function evaluateRedactionBenchmark(options = {}) {
+  const contextualMisses = contextualCases
+    .filter(({ text }) => !redactSensitiveText(text).redacted)
+    .map(({ name }) => name);
+  const entropyDetected = unlabeledEntropyCases
+    .filter(({ text }) => redactSensitiveText(text).redacted)
+    .map(({ name }) => name);
+  const falsePositives = benignCases
+    .filter(({ text }) => redactSensitiveText(text).redacted)
+    .map(({ name }) => name);
+  const safeStructured = redactForStorage(structuredInput);
+  const structuredSensitiveChecks = [
+    safeStructured.password === REDACTION,
+    safeStructured.apiKey === REDACTION,
+    safeStructured.nested?.clientSecret === REDACTION,
+    safeStructured.nested?.sessionToken === REDACTION,
+    safeStructured.tokens?.[0] === REDACTION,
+    safeStructured.apiKeys?.[0] === REDACTION,
+    safeStructured.passwords?.[0] === REDACTION,
+    safeStructured.credentials?.[0] === REDACTION
+  ];
+  const structuredBenignChecks = [
+    safeStructured.id === structuredInput.id,
+    safeStructured.checksum === structuredInput.checksum,
+    safeStructured.labels?.[0] === structuredInput.labels[0],
+    safeStructured.semanticTokens?.[0] === structuredInput.semanticTokens[0],
+    safeStructured.colorTokens?.[0] === structuredInput.colorTokens[0],
+    safeStructured.passwordPolicy === structuredInput.passwordPolicy,
+    safeStructured.semanticTokenType === structuredInput.semanticTokenType
+  ];
+
+  const iterations = Math.max(1, Math.min(Number(options.iterations ?? 250), 10_000));
+  const workload = [...contextualCases, ...unlabeledEntropyCases, ...benignCases];
+  const started = performance.now();
+  for (let iteration = 0; iteration < iterations; iteration += 1) {
+    for (const { text } of workload) redactSensitiveText(text);
+  }
+  const durationMs = performance.now() - started;
+  const evaluations = iterations * workload.length;
+  const largeOutput = `${"ordinary build output\n".repeat(8_192)}X-Api-Key: synthetic-large-output-key-123`;
+  const largeStarted = performance.now();
+  const largeResult = redactSensitiveText(largeOutput);
+  const largeDurationMs = performance.now() - largeStarted;
+
+  const result = {
+    contextual: {
+      total: contextualCases.length,
+      detected: contextualCases.length - contextualMisses.length,
+      recall: percentage(contextualCases.length - contextualMisses.length, contextualCases.length),
+      missed: contextualMisses
+    },
+    unlabeledEntropy: {
+      total: unlabeledEntropyCases.length,
+      detected: entropyDetected.length,
+      observationalRecall: percentage(entropyDetected.length, unlabeledEntropyCases.length),
+      detectedCases: entropyDetected,
+      gated: false
+    },
+    benign: {
+      total: benignCases.length,
+      falsePositives: falsePositives.length,
+      falsePositiveRate: percentage(falsePositives.length, benignCases.length),
+      cases: falsePositives
+    },
+    structured: {
+      sensitiveTotal: structuredSensitiveChecks.length,
+      sensitiveRedacted: structuredSensitiveChecks.filter(Boolean).length,
+      benignTotal: structuredBenignChecks.length,
+      benignPreserved: structuredBenignChecks.filter(Boolean).length
+    },
+    performance: {
+      iterations,
+      evaluations,
+      durationMs: Number(durationMs.toFixed(3)),
+      averageMicroseconds: Number(((durationMs * 1000) / evaluations).toFixed(3))
+    },
+    largeOutput: {
+      bytes: Buffer.byteLength(largeOutput),
+      durationMs: Number(largeDurationMs.toFixed(3)),
+      sensitiveValueRedacted: largeResult.redacted && !largeResult.text.includes("synthetic-large-output-key-123")
+    }
+  };
+  result.ok = result.contextual.recall === 1
+    && result.benign.falsePositives === 0
+    && result.structured.sensitiveRedacted === result.structured.sensitiveTotal
+    && result.structured.benignPreserved === result.structured.benignTotal
+    && result.largeOutput.sensitiveValueRedacted;
+  return result;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const result = evaluateRedactionBenchmark();
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  if (!result.ok) process.exitCode = 1;
+}