@teevee98/synapse-hub 4.2.0 → 4.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (109) hide show
  1. package/.agents/skills/01-web-automation/auth-session-and-cookie-manager/SKILL.md +46 -2
  2. package/.agents/skills/01-web-automation/bats-testing-patterns/SKILL.md +49 -4
  3. package/.agents/skills/01-web-automation/clean-pom-crafter/SKILL.md +56 -66
  4. package/.agents/skills/01-web-automation/e2e-testing-patterns/SKILL.md +48 -3
  5. package/.agents/skills/01-web-automation/katalon-cli-runner/SKILL.md +56 -11
  6. package/.agents/skills/01-web-automation/lam-script-generator/SKILL.md +49 -7
  7. package/.agents/skills/01-web-automation/mobile-appium-som/SKILL.md +54 -11
  8. package/.agents/skills/01-web-automation/playwright-live-interaction/SKILL.md +48 -90
  9. package/.agents/skills/01-web-automation/playwright-webapp-testing/SKILL.md +53 -10
  10. package/.agents/skills/01-web-automation/web-agent-gym-benchmarking/SKILL.md +44 -3
  11. package/.agents/skills/02-test-design/architecture-decision-records/SKILL.md +49 -8
  12. package/.agents/skills/02-test-design/gherkin-to-suite/SKILL.md +49 -8
  13. package/.agents/skills/02-test-design/rbt-manual-testing/SKILL.md +49 -7
  14. package/.agents/skills/02-test-design/review-spec/SKILL.md +46 -5
  15. package/.agents/skills/02-test-design/tot-exploratory-testing/SKILL.md +44 -3
  16. package/.agents/skills/03-api-and-contracts/api-network-mocking-interception/SKILL.md +50 -4
  17. package/.agents/skills/03-api-and-contracts/api-spec-to-e2e-matrix/SKILL.md +47 -6
  18. package/.agents/skills/03-api-and-contracts/consumer-driven-contract-testing/SKILL.md +79 -34
  19. package/.agents/skills/04-performance-and-load/backend-load-and-stress-patterns/SKILL.md +47 -4
  20. package/.agents/skills/04-performance-and-load/lean-impact-scoreboard/SKILL.md +46 -5
  21. package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/SKILL.md +44 -2
  22. package/.agents/skills/05-security-and-compliance/security-dast-sentinel/SKILL.md +57 -13
  23. package/.agents/skills/05-security-and-compliance/skillspector-security-guard/SKILL.md +45 -4
  24. package/.agents/skills/05-security-and-compliance/wcag-audit-patterns/SKILL.md +48 -3
  25. package/.agents/skills/06-healing-and-resilience/agentless-qa-repair/SKILL.md +45 -4
  26. package/.agents/skills/06-healing-and-resilience/antigravity-test-sentinel/SKILL.md +47 -5
  27. package/.agents/skills/06-healing-and-resilience/failure-autopsy-and-healing/SKILL.md +48 -7
  28. package/.agents/skills/06-healing-and-resilience/flaky-test-sentinel-and-quarantine/SKILL.md +54 -23
  29. package/.agents/skills/06-healing-and-resilience/self-healing-locator/SKILL.md +46 -5
  30. package/.agents/skills/06-healing-and-resilience/systematic-debugging/SKILL.md +50 -9
  31. package/.agents/skills/06-healing-and-resilience/test-driven-development/SKILL.md +52 -11
  32. package/.agents/skills/06-healing-and-resilience/verification-before-completion/SKILL.md +52 -11
  33. package/.agents/skills/06-healing-and-resilience/visual-regression-sentinel/SKILL.md +47 -4
  34. package/.agents/skills/07-data-and-state/db-state-verifier-and-seeder/SKILL.md +50 -4
  35. package/.agents/skills/07-data-and-state/file-and-report-validator/SKILL.md +47 -3
  36. package/.agents/skills/07-data-and-state/synthetic-test-data-generator/SKILL.md +52 -4
  37. package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/SKILL.md +51 -10
  38. package/.agents/skills/08-code-quality/graphify-impact-analyzer/SKILL.md +78 -34
  39. package/.agents/skills/08-code-quality/graphify-impact-analyzer/examples/dependency_blast_radius.json +3 -4
  40. package/.agents/skills/08-code-quality/lean-code-ladder/SKILL.md +49 -9
  41. package/.agents/skills/08-code-quality/repo-quality-audit/SKILL.md +45 -5
  42. package/.agents/skills/08-code-quality/senior-code-review/SKILL.md +48 -6
  43. package/.agents/skills/08-code-quality/surgical-coding-principles/SKILL.md +49 -9
  44. package/.agents/skills/08-code-quality/technical-debt-harvester/SKILL.md +47 -4
  45. package/.agents/skills/09-ci-and-devops/github-actions-templates/SKILL.md +48 -16
  46. package/.agents/skills/09-ci-and-devops/github-actions-templates/examples/matrix_test_pipeline.yml +2 -1
  47. package/.agents/skills/10-agent-orchestration/actor-qa-swarm/SKILL.md +44 -3
  48. package/.agents/skills/10-agent-orchestration/agent-orchestration-multi-agent-optimize/SKILL.md +47 -6
  49. package/.agents/skills/10-agent-orchestration/event-stream-qa-orchestrator/SKILL.md +44 -3
  50. package/.agents/skills/10-agent-orchestration/persistent-planning-files/SKILL.md +52 -12
  51. package/.agents/skills/10-agent-orchestration/qa-memory-os/SKILL.md +45 -4
  52. package/.agents/skills/11-ai-and-prompting/meta-prompt-crafter/SKILL.md +51 -9
  53. package/.agents/skills/11-ai-and-prompting/mipro-prompt-compiler/SKILL.md +44 -3
  54. package/.agents/skills/11-ai-and-prompting/qa-aci-interface/SKILL.md +44 -3
  55. package/.agents/skills/11-ai-and-prompting/token-and-context-optimizer/SKILL.md +49 -8
  56. package/.cursor/rules/synapse-qa.mdc +20 -7
  57. package/.cursorrules +19 -5
  58. package/.windsurfrules +18 -3
  59. package/AGENTS.md +51 -65
  60. package/CLAUDE.md +38 -24
  61. package/README.en.md +2 -2
  62. package/README.md +2 -2
  63. package/agentskills.json +1 -1
  64. package/docs/ARCHITECTURE.en.md +1 -1
  65. package/docs/ARCHITECTURE.md +1 -1
  66. package/docs/CLIENT_SUPPORT_MATRIX.md +44 -0
  67. package/docs/SIDE_EFFECTING_TOOLS_INVENTORY.md +233 -0
  68. package/package.json +1 -1
  69. package/plugin.json +1 -1
  70. package/skills_manifest.json +1 -1
  71. package/synapse.config.json +1 -1
  72. package/templates/ai_bridges/CLAUDE.md +29 -26
  73. package/templates/ai_bridges/copilot-instructions.md +14 -5
  74. package/templates/ai_bridges/cursor_synapse_qa.mdc +16 -7
  75. package/templates/ai_bridges/windsurfrules +14 -3
  76. package/tools/TOOLS_RUNBOOK.md +1 -1
  77. package/tools/__init__.py +1 -1
  78. package/tools/api_fuzzer.py +295 -41
  79. package/tools/benchmark_swarm_context.py +11 -4
  80. package/tools/browser_helpers.js +2 -2
  81. package/tools/bump_version.py +2 -2
  82. package/tools/cli.py +4 -4
  83. package/tools/core/bm25_retriever.py +1 -1
  84. package/tools/core/i18n.py +1 -1
  85. package/tools/core/provider_usage_adapter.py +66 -0
  86. package/tools/core/token_estimator.py +39 -1
  87. package/tools/count_tokens.py +2 -2
  88. package/tools/dashboard_generator.py +8 -8
  89. package/tools/db_sandbox.py +182 -43
  90. package/tools/distill_log.py +1 -1
  91. package/tools/distill_skill.py +17 -2
  92. package/tools/git_pre_commit_guard.py +190 -1
  93. package/tools/hub_publisher.py +2 -12
  94. package/tools/mcp_docx_server.py +1 -1
  95. package/tools/mcp_excel_server.py +1 -1
  96. package/tools/mcp_server.py +33 -5
  97. package/tools/micro_mutator.py +30 -1
  98. package/tools/pentest_scope_guard.py +288 -15
  99. package/tools/project_state.py +29 -5
  100. package/tools/reversible_sandbox.py +58 -13
  101. package/tools/rules_router.py +80 -27
  102. package/tools/skill_canonical_digest.py +60 -2
  103. package/tools/sync_agent_rules.py +187 -61
  104. package/tools/task_memory_manager.py +16 -1
  105. package/tools/ui_server.py +3 -1
  106. package/tools/update_sentinel.py +3 -3
  107. package/tools/validate_skills_schema.py +349 -56
  108. package/tools/verify_all.py +98 -4
  109. package/tools/welcome_page.py +1 -1
@@ -80,11 +80,77 @@ class ProviderUsageRecord:
80
80
  commit: str
81
81
  raw_usage: Dict[str, Any]
82
82
 
83
+ def __post_init__(self) -> None:
84
+ if self.measurement_kind != "provider_observed":
85
+ raise ValueError(
86
+ f"ProviderUsageRecord requires measurement_kind == 'provider_observed', got {self.measurement_kind!r}"
87
+ )
88
+
89
+ def to_dict(self) -> Dict[str, Any]:
90
+ """Converts to dictionary representation."""
91
+ return asdict(self)
92
+
93
+
94
+ @dataclass
95
+ class TokenMeasurementRecord:
96
+ """Standardized record of token measurements with full provenance metadata."""
97
+ measurement_kind: str # "provider_observed" | "synthetic_estimate"
98
+ token_count: int
99
+ model_name: str
100
+ encoding: str
101
+ is_fallback: bool
102
+ commit_sha: str
103
+ input_hash: str
104
+ timestamp: float
105
+
83
106
  def to_dict(self) -> Dict[str, Any]:
84
107
  """Converts to dictionary representation."""
85
108
  return asdict(self)
86
109
 
87
110
 
111
+ def serialize_provider_usage(record: Any) -> Dict[str, Any]:
112
+ """
113
+ Serializes a TokenMeasurementRecord or ProviderUsageRecord into provider usage fields.
114
+ Strictly enforces that synthetic estimates or non-provider-observed measurements
115
+ cannot be serialized into provider billing fields.
116
+
117
+ Raises:
118
+ ValueError: If record.measurement_kind != 'provider_observed'.
119
+ """
120
+ kind = getattr(record, "measurement_kind", None)
121
+ if isinstance(record, dict):
122
+ kind = record.get("measurement_kind")
123
+
124
+ if kind != "provider_observed":
125
+ raise ValueError(
126
+ f"Cannot serialize non-provider-observed record into provider usage fields: "
127
+ f"measurement_kind={kind!r}"
128
+ )
129
+
130
+ if isinstance(record, ProviderUsageRecord):
131
+ return record.to_dict()
132
+
133
+ if isinstance(record, TokenMeasurementRecord):
134
+ return {
135
+ "measurement_kind": "provider_observed",
136
+ "provider_reported_input_tokens": record.token_count,
137
+ "provider_reported_output_tokens": 0,
138
+ "provider_cached_tokens": None,
139
+ "total_provider_tokens": record.token_count,
140
+ "model": record.model_name,
141
+ "encoding": record.encoding,
142
+ "is_fallback": record.is_fallback,
143
+ "commit_sha": record.commit_sha,
144
+ "input_hash": record.input_hash,
145
+ "timestamp": record.timestamp,
146
+ }
147
+
148
+ if isinstance(record, dict):
149
+ return dict(record)
150
+
151
+ raise ValueError(f"Unsupported record type: {type(record).__name__}")
152
+
153
+
88
154
  def create_unobserved_provider_record(
89
155
  measurement_kind: str = "static_estimate",
90
156
  note: str = "No live LLM provider usage observed; fields remain null.",
@@ -21,6 +21,7 @@ Key Capabilities:
21
21
 
22
22
  from __future__ import annotations
23
23
 
24
+ from datetime import datetime, timezone
24
25
  import glob
25
26
  import hashlib
26
27
  import json
@@ -40,6 +41,15 @@ try:
40
41
  except ImportError:
41
42
  _TIKTOKEN_ENCODER = None
42
43
 
44
+ try:
45
+ from tools.core.provider_usage_adapter import get_repo_version_and_commit
46
+ except ImportError:
47
+ try:
48
+ from core.provider_usage_adapter import get_repo_version_and_commit
49
+ except ImportError:
50
+ def get_repo_version_and_commit(repo_root=None):
51
+ return "1.0.0", "unversioned"
52
+
43
53
  # Cache mapping canonical manifest_path -> (mtime, parsed_manifest)
44
54
  _SKILLS_MANIFEST_CACHE: Dict[str, Any] = {}
45
55
 
@@ -231,9 +241,23 @@ def calculate_hydration_payload(
231
241
 
232
242
  catalog_skill_tokens = count_tokens("\n".join(catalog_lines)) if catalog_lines else 0
233
243
 
244
+ info = get_estimator_info()
245
+ version, commit_sha = get_repo_version_and_commit(repo_root)
246
+ input_str = f"rules:{','.join(sorted(rules))};skills:{','.join(sorted(skills))}"
247
+ input_hash = hashlib.sha256(input_str.encode("utf-8")).hexdigest()
248
+ now_iso = datetime.now(timezone.utc).isoformat()
249
+ is_fallback = not info.get("is_exact", False)
250
+ encoding = info.get("encoding", "cl100k_base")
251
+
234
252
  return {
235
253
  "measurement_kind": "static_estimate",
236
254
  "static_estimated_tokens": rule_tokens + full_skill_tokens,
255
+ "commit_sha": commit_sha,
256
+ "timestamp": now_iso,
257
+ "input_hash": input_hash,
258
+ "is_fallback": is_fallback,
259
+ "encoding": encoding,
260
+ "tokenizer_engine": info.get("engine", "heuristic_polyglot"),
237
261
  "provider_reported_input_tokens": None,
238
262
  "provider_reported_output_tokens": None,
239
263
  "provider_cached_tokens": None,
@@ -291,9 +315,23 @@ def get_full_unrouted_baseline(repo_root: str) -> Dict[str, Any]:
291
315
 
292
316
  total_cat_tokens = count_tokens("\n".join(catalog_lines)) if catalog_lines else 0
293
317
 
318
+ info = get_estimator_info()
319
+ version, commit_sha = get_repo_version_and_commit(repo_root)
320
+ input_str = f"rules:{','.join(sorted(all_rule_files))};skills:{','.join(sorted(all_skill_ids))}"
321
+ input_hash = hashlib.sha256(input_str.encode("utf-8")).hexdigest()
322
+ now_iso = datetime.now(timezone.utc).isoformat()
323
+ is_fallback = not info.get("is_exact", False)
324
+ encoding = info.get("encoding", "cl100k_base")
325
+
294
326
  return {
295
327
  "measurement_kind": "static_estimate",
296
328
  "static_estimated_tokens": total_rule_tokens + total_skill_tokens,
329
+ "commit_sha": commit_sha,
330
+ "timestamp": now_iso,
331
+ "input_hash": input_hash,
332
+ "is_fallback": is_fallback,
333
+ "encoding": encoding,
334
+ "tokenizer_engine": info.get("engine", "heuristic_polyglot"),
297
335
  "provider_reported_input_tokens": None,
298
336
  "provider_reported_output_tokens": None,
299
337
  "provider_cached_tokens": None,
@@ -310,7 +348,7 @@ def get_full_unrouted_baseline(repo_root: str) -> Dict[str, Any]:
310
348
  "total_full_bytes": total_rule_bytes + total_skill_bytes,
311
349
  "all_rules": all_rule_files,
312
350
  "all_skills": all_skill_ids,
313
- "estimator_info": get_estimator_info(),
351
+ "estimator_info": info,
314
352
  }
315
353
 
316
354
 
@@ -732,10 +732,10 @@ def calculate_hub_savings(input_tokens: int, cache_tokens: int, output_tokens: i
732
732
  """
733
733
  Empirical Hub Savings Model:
734
734
  Compares actual Synapse-Hub execution against vanilla/non-Hub agent execution:
735
- 1. Log Distillation (Observation Masking): Hub cuts CLI noise by 95% (raw vs distilled).
735
+ 1. Log Distillation (Observation Masking): Hub compresses CLI noise (raw vs distilled logs).
736
736
  2. Sparse Retrieval (Repo Map): 500-token AST map vs reading full 4,000-line classes.
737
737
  3. Compact AOM: <500-token interactive tree vs 15,000-token raw HTML DOM.
738
- 4. KV-Cache Alignment: 95%+ Cache Hit vs <15% without prefix stability.
738
+ 4. KV-Cache Alignment: High Cache Hit rates via prefix stability.
739
739
  5. Lean Telemetry Badge: ~180 tokens/turn saved by omitting verbose footer.
740
740
  """
741
741
  pricing = PRICING_TABLE.get(model_key, PRICING_TABLE[DEFAULT_MODEL])
@@ -605,8 +605,8 @@ def build_swarm_timeline_html(default_lang: str = "vi") -> str:
605
605
  "name_vi": "3. Thực Thi Headless, API & Tải",
606
606
  "name_en": "3. Headless Run, API & Load",
607
607
  "agent": "test-runner / perf-engineer / api-engineer",
608
- "desc_vi": "Thực thi test headless qua CLI (E2E Playwright, API Newman & Tải k6/JMeter), tinh lọc log 95%",
609
- "desc_en": "Headless CLI (E2E, API & k6/JMeter Load), distill logs 95%, isolate failures",
608
+ "desc_vi": "Thực thi test headless qua CLI (E2E Playwright, API Newman & Tải k6/JMeter), tinh lọc log",
609
+ "desc_en": "Headless CLI (E2E, API & k6/JMeter Load), distill logs, isolate failures",
610
610
  "icon": "⚡",
611
611
  "badge": "PASS",
612
612
  },
@@ -1350,7 +1350,7 @@ def _build_target_translations(
1350
1350
  "th_step_status": "Trạng Thái",
1351
1351
  "th_step_details": "Chi Tiết Kỹ Thuật (OTel & AST)",
1352
1352
 
1353
- "footer_text": "Báo cáo được khởi tạo tự động bởi Synapse-Hub v4.2.0 &bull; Bản quyền &copy; Thế Vị (@TeeVee98) &bull; Chuẩn Clean POM & Kiểm Thử Tự Chủ",
1353
+ "footer_text": "Báo cáo được khởi tạo tự động bởi Synapse-Hub v4.2.2 &bull; Bản quyền &copy; Thế Vị (@TeeVee98) &bull; Chuẩn Clean POM & Kiểm Thử Tự Chủ",
1354
1354
  }
1355
1355
 
1356
1356
  translations_en = {
@@ -1428,7 +1428,7 @@ def _build_target_translations(
1428
1428
  "th_step_status": "Status",
1429
1429
  "th_step_details": "Technical Details (OTel & AST)",
1430
1430
 
1431
- "footer_text": "Generated automatically by Synapse-Hub v4.2.0 &bull; Copyright &copy; Thế Vị (@TeeVee98) &bull; Clean POM & Autonomous Testing",
1431
+ "footer_text": "Generated automatically by Synapse-Hub v4.2.2 &bull; Copyright &copy; Thế Vị (@TeeVee98) &bull; Clean POM & Autonomous Testing",
1432
1432
  }
1433
1433
 
1434
1434
  _inject_gate_translations(translations_vi, translations_en, gates)
@@ -1917,7 +1917,7 @@ def _build_hub_translations(
1917
1917
  """Builds bilingual dictionaries for Hub Dashboard."""
1918
1918
  translations_vi = {
1919
1919
  "header_title": "Bảng Điều Hành Chất Lượng Doanh Nghiệp",
1920
- "header_subtitle": "Synapse-Hub v4.2.0 &bull; Hệ Sinh Thái Kiểm Thử AI Agent Tự Chủ",
1920
+ "header_subtitle": "Synapse-Hub v4.2.2 &bull; Hệ Sinh Thái Kiểm Thử AI Agent Tự Chủ",
1921
1921
  "nav_welcome": "Giới Thiệu",
1922
1922
  "meta_mode": "🏷️ Chế độ: <strong>HỆ SINH THÁI QA HUB</strong>",
1923
1923
  "meta_gen": f"🕒 Khởi tạo: <strong>{now_str}</strong>",
@@ -1987,12 +1987,12 @@ def _build_hub_translations(
1987
1987
  "th_sk_ver": "Phiên Bản",
1988
1988
  "th_sk_cap": "Khả Năng Nghiệp Vụ Cốt Lõi",
1989
1989
 
1990
- "footer_text": "Bảng Điều Hành Chất Lượng Doanh Nghiệp &bull; Synapse-Hub v4.2.0 &bull; Bản quyền &copy; Thế Vị (@TeeVee98) &bull; Hệ Thống Kiểm Thử AI Agent Tự Chủ",
1990
+ "footer_text": "Bảng Điều Hành Chất Lượng Doanh Nghiệp &bull; Synapse-Hub v4.2.2 &bull; Bản quyền &copy; Thế Vị (@TeeVee98) &bull; Hệ Thống Kiểm Thử AI Agent Tự Chủ",
1991
1991
  }
1992
1992
 
1993
1993
  translations_en = {
1994
1994
  "header_title": "Enterprise QA Executive Dashboard",
1995
- "header_subtitle": "Synapse-Hub v4.2.0 &bull; Autonomous AI Agent Testing Ecosystem",
1995
+ "header_subtitle": "Synapse-Hub v4.2.2 &bull; Autonomous AI Agent Testing Ecosystem",
1996
1996
  "nav_welcome": "Welcome",
1997
1997
  "meta_mode": "🏷️ Mode: <strong>QA HUB ECOSYSTEM</strong>",
1998
1998
  "meta_gen": f"🕒 Generated: <strong>{now_str}</strong>",
@@ -2062,7 +2062,7 @@ def _build_hub_translations(
2062
2062
  "th_sk_ver": "Version",
2063
2063
  "th_sk_cap": "Core Capabilities",
2064
2064
 
2065
- "footer_text": "Enterprise QA Executive Dashboard &bull; Synapse-Hub v4.2.0 &bull; Copyright &copy; Thế Vị (@TeeVee98) &bull; Autonomous AI Agent Testing Ecosystem",
2065
+ "footer_text": "Enterprise QA Executive Dashboard &bull; Synapse-Hub v4.2.2 &bull; Copyright &copy; Thế Vị (@TeeVee98) &bull; Autonomous AI Agent Testing Ecosystem",
2066
2066
  }
2067
2067
 
2068
2068
  _inject_gate_translations(translations_vi, translations_en, gates)
@@ -34,12 +34,21 @@ import json
34
34
  import shutil
35
35
  import socket
36
36
  import sqlite3
37
+ import tempfile
37
38
  import argparse
38
39
  import subprocess
39
40
  import urllib.request
40
41
  import urllib.error
41
42
  from typing import Dict, Any, List, Tuple, Optional
42
43
 
44
+ from pentest_scope_guard import (
45
+ resolve_contained_path,
46
+ PathContainmentError,
47
+ create_consent_grant,
48
+ verify_granular_grant,
49
+ is_consent_grant,
50
+ )
51
+
43
52
  # Enforce UTF-8 stdout encoding for Windows console compatibility
44
53
  if hasattr(sys.stdout, 'reconfigure'):
45
54
  try:
@@ -71,7 +80,13 @@ SNAPSHOT_DIR = _resolve_snapshot_dir()
71
80
  class DBSandbox:
72
81
  """Zero-pollution ephemeral database management."""
73
82
 
74
- def __init__(self, db_type: str = "sqlite", db_path: str = "", snapshot_dir: Optional[str] = None):
83
+ def __init__(
84
+ self,
85
+ db_type: str = "sqlite",
86
+ db_path: str = "",
87
+ snapshot_dir: Optional[str] = None,
88
+ sandbox_root: Optional[str] = None
89
+ ):
75
90
  clean_path = (db_path or "").strip()
76
91
  lowered_path = clean_path.lower()
77
92
  if lowered_path.startswith(("postgresql://", "postgres://")):
@@ -82,12 +97,11 @@ class DBSandbox:
82
97
  self.db_type = "oracle"
83
98
  else:
84
99
  self.db_type = db_type.lower().strip() or "sqlite"
85
- self.db_path = clean_path
100
+
86
101
  self.snapshot_dir = snapshot_dir if snapshot_dir is not None else _resolve_snapshot_dir()
87
102
  try:
88
103
  os.makedirs(self.snapshot_dir, exist_ok=True)
89
104
  except OSError as err:
90
- import tempfile
91
105
  sys.stderr.write(f"Notice: Snapshot dir creation fallback: {err}\n")
92
106
  self.snapshot_dir = os.path.join(tempfile.gettempdir(), ".synapse", "snapshots")
93
107
  try:
@@ -95,6 +109,43 @@ class DBSandbox:
95
109
  except OSError as ferr:
96
110
  sys.stderr.write(f"Notice: Snapshot dir fallback failed: {ferr}\n")
97
111
 
112
+ # Determine sandbox root containment
113
+ if sandbox_root:
114
+ self.sandbox_root = os.path.realpath(os.path.abspath(sandbox_root))
115
+ else:
116
+ self.sandbox_root = os.path.realpath(os.path.abspath(self.snapshot_dir))
117
+
118
+ # Path containment validation for SQLite database file paths
119
+ if self.db_type == "sqlite" and clean_path and not clean_path.startswith(":memory:"):
120
+ allowed_roots = [self.sandbox_root]
121
+ if not sandbox_root:
122
+ allowed_roots.extend([
123
+ os.path.realpath(os.path.abspath(os.path.dirname(self.snapshot_dir))),
124
+ os.path.realpath(os.path.abspath(os.getcwd())),
125
+ os.path.realpath(os.path.abspath(QA_HUB_ROOT)),
126
+ os.path.realpath(os.path.abspath(tempfile.gettempdir())),
127
+ ])
128
+
129
+ contained = None
130
+ last_err = None
131
+ if not os.path.isabs(clean_path):
132
+ # Relative path: strictly resolve and contain against self.sandbox_root
133
+ contained = resolve_contained_path(self.sandbox_root, clean_path)
134
+ else:
135
+ for root in allowed_roots:
136
+ try:
137
+ contained = resolve_contained_path(root, clean_path)
138
+ break
139
+ except PathContainmentError as pce:
140
+ last_err = pce
141
+ continue
142
+
143
+ if contained is None:
144
+ raise last_err or PathContainmentError(f"Database path '{clean_path}' escapes sandbox root containment.")
145
+ self.db_path = contained
146
+ else:
147
+ self.db_path = clean_path
148
+
98
149
  # -------------------------------------------------------------------------
99
150
  # 1. SNAPSHOT & RAPID RESTORE
100
151
  # -------------------------------------------------------------------------
@@ -221,28 +272,35 @@ class DBSandbox:
221
272
  "snapshot_id": clean_id,
222
273
  "target_db": target_path,
223
274
  "dry_run": True,
224
- "message": f"DRY-RUN PREVIEW: Would restore database snapshot '{clean_id}' to '{target_path}'. Pass dry_run=False and consent=True to execute."
275
+ "message": f"DRY-RUN PREVIEW: Would restore database snapshot '{clean_id}' to '{target_path}'. Pass dry_run=False and a valid ConsentGrant (or --confirm on CLI) to execute."
225
276
  }
226
277
 
227
278
  # 2. Authorization / Consent enforcement at action execution boundary
228
- has_consent = (
229
- bool(consent)
230
- or os.environ.get("SYNAPSE_FORCE_RESTORE", "").strip().lower() in ("1", "true", "yes")
231
- or os.environ.get("PENTEST_CONSENT_ACKNOWLEDGED", "").strip().lower() in ("1", "true", "yes")
232
- )
233
- if not has_consent:
279
+ # Generic boolean consent (consent=True) and shared environment variables are strictly eliminated.
280
+ if consent is None or isinstance(consent, bool) or not consent:
234
281
  return {
235
282
  "status": "ERROR",
236
- "message": "Destructive database restore requires explicit consent bound to target sandbox. Pass consent=True (or scoped consent dict) or set SYNAPSE_FORCE_RESTORE=1.",
283
+ "message": "Destructive database restore requires explicit consent bound to target sandbox. Generic boolean consent and shared environment variables are rejected.",
237
284
  "snapshot_id": clean_id,
238
285
  "target_db": target_path,
239
286
  "zero_pollution_guaranteed": False
240
287
  }
241
288
 
242
- # Scoped consent check: ensure consent for Sandbox A cannot be reused to restore Sandbox B
243
- if isinstance(consent, dict):
244
- c_target = consent.get("target_sandbox") or consent.get("target_db")
245
- if c_target:
289
+ # Granular consent verification: ensure consent is bound to target and operation
290
+ if is_consent_grant(consent) or isinstance(consent, dict):
291
+ c_target = (
292
+ consent.target if is_consent_grant(consent)
293
+ else (consent.get("target_sandbox") or consent.get("target_db") or consent.get("target"))
294
+ )
295
+ if not c_target or not str(c_target).strip():
296
+ return {
297
+ "status": "ERROR",
298
+ "message": "Consent grant missing required target sandbox binding.",
299
+ "snapshot_id": clean_id,
300
+ "target_db": target_path,
301
+ "zero_pollution_guaranteed": False
302
+ }
303
+ try:
246
304
  norm_c = os.path.realpath(os.path.abspath(c_target)).lower()
247
305
  norm_target = os.path.realpath(os.path.abspath(target_path)).lower()
248
306
  if norm_c != norm_target:
@@ -253,8 +311,20 @@ class DBSandbox:
253
311
  "target_db": target_path,
254
312
  "zero_pollution_guaranteed": False
255
313
  }
256
- c_action = consent.get("operation") or consent.get("action")
257
- if c_action and c_action.lower() != "restore":
314
+ except Exception as p_err:
315
+ return {
316
+ "status": "ERROR",
317
+ "message": f"Consent target resolution error: {p_err}",
318
+ "snapshot_id": clean_id,
319
+ "target_db": target_path,
320
+ "zero_pollution_guaranteed": False
321
+ }
322
+
323
+ c_action = (
324
+ consent.action if is_consent_grant(consent)
325
+ else (consent.get("operation") or consent.get("action"))
326
+ )
327
+ if c_action and str(c_action).lower() not in ("restore", "db:restore"):
258
328
  return {
259
329
  "status": "ERROR",
260
330
  "message": f"Consent operation mismatch: consent granted for '{c_action}', but requested operation is 'restore'.",
@@ -263,6 +333,23 @@ class DBSandbox:
263
333
  "zero_pollution_guaranteed": False
264
334
  }
265
335
 
336
+ if not verify_granular_grant(consent, expected_action="db:restore", expected_target=target_path):
337
+ return {
338
+ "status": "ERROR",
339
+ "message": "Consent grant validation failed: grant is invalid, expired, or replayed.",
340
+ "snapshot_id": clean_id,
341
+ "target_db": target_path,
342
+ "zero_pollution_guaranteed": False
343
+ }
344
+ else:
345
+ return {
346
+ "status": "ERROR",
347
+ "message": "Destructive database restore requires explicit consent bound to target sandbox. Invalid consent grant.",
348
+ "snapshot_id": clean_id,
349
+ "target_db": target_path,
350
+ "zero_pollution_guaranteed": False
351
+ }
352
+
266
353
  if os.path.exists(meta_file):
267
354
  try:
268
355
  with open(meta_file, "r", encoding="utf-8") as f:
@@ -458,16 +545,11 @@ class DBSandbox:
458
545
  """
459
546
  target_path = self.db_path or os.path.join(self.snapshot_dir, "active_test.db")
460
547
  if not dry_run:
461
- has_consent = (
462
- bool(consent)
463
- or os.environ.get("SYNAPSE_FORCE_PURGE", "").strip().lower() in ("1", "true", "yes")
464
- or os.environ.get("SYNAPSE_FORCE_RESTORE", "").strip().lower() in ("1", "true", "yes")
465
- or os.environ.get("PENTEST_CONSENT_ACKNOWLEDGED", "").strip().lower() in ("1", "true", "yes")
466
- )
467
- if not has_consent:
548
+ # 1. Reject missing or generic boolean consent
549
+ if consent is None or isinstance(consent, bool) or not consent:
468
550
  return {
469
551
  "status": "ERROR",
470
- "message": "Destructive database purge requires explicit consent bound to target sandbox. Pass consent=True, --confirm, or set SYNAPSE_FORCE_PURGE=1.",
552
+ "message": "Destructive database purge requires explicit consent bound to target sandbox. Generic boolean consent and shared environment variables are rejected.",
471
553
  "tables_audited": 0,
472
554
  "total_purged_rows": 0,
473
555
  "purge_details": [],
@@ -475,10 +557,23 @@ class DBSandbox:
475
557
  "dry_run": False
476
558
  }
477
559
 
478
- # Scoped consent check: ensure consent for Sandbox A cannot be reused to purge Sandbox B
479
- if isinstance(consent, dict):
480
- c_target = consent.get("target_sandbox") or consent.get("target_db")
481
- if c_target:
560
+ # 2. Granular consent verification: ensure consent is bound to target and operation
561
+ if is_consent_grant(consent) or isinstance(consent, dict):
562
+ c_target = (
563
+ consent.target if is_consent_grant(consent)
564
+ else (consent.get("target_sandbox") or consent.get("target_db") or consent.get("target"))
565
+ )
566
+ if not c_target or not str(c_target).strip():
567
+ return {
568
+ "status": "ERROR",
569
+ "message": "Consent grant missing required target sandbox binding.",
570
+ "tables_audited": 0,
571
+ "total_purged_rows": 0,
572
+ "purge_details": [],
573
+ "zero_pollution_achieved": False,
574
+ "dry_run": False
575
+ }
576
+ try:
482
577
  norm_c = os.path.realpath(os.path.abspath(c_target)).lower()
483
578
  norm_target = os.path.realpath(os.path.abspath(target_path)).lower()
484
579
  if norm_c != norm_target:
@@ -491,8 +586,22 @@ class DBSandbox:
491
586
  "zero_pollution_achieved": False,
492
587
  "dry_run": False
493
588
  }
494
- c_action = consent.get("operation") or consent.get("action")
495
- if c_action and c_action.lower() not in ("purge", "audit_and_purge"):
589
+ except Exception as p_err:
590
+ return {
591
+ "status": "ERROR",
592
+ "message": f"Consent target resolution error: {p_err}",
593
+ "tables_audited": 0,
594
+ "total_purged_rows": 0,
595
+ "purge_details": [],
596
+ "zero_pollution_achieved": False,
597
+ "dry_run": False
598
+ }
599
+
600
+ c_action = (
601
+ consent.action if is_consent_grant(consent)
602
+ else (consent.get("operation") or consent.get("action"))
603
+ )
604
+ if c_action and str(c_action).lower() not in ("purge", "db:purge", "audit_and_purge"):
496
605
  return {
497
606
  "status": "ERROR",
498
607
  "message": f"Consent operation mismatch: consent granted for '{c_action}', but requested operation is 'purge'.",
@@ -502,6 +611,27 @@ class DBSandbox:
502
611
  "zero_pollution_achieved": False,
503
612
  "dry_run": False
504
613
  }
614
+
615
+ if not verify_granular_grant(consent, expected_action="db:purge", expected_target=target_path):
616
+ return {
617
+ "status": "ERROR",
618
+ "message": "Consent grant validation failed: grant is invalid, expired, or replayed.",
619
+ "tables_audited": 0,
620
+ "total_purged_rows": 0,
621
+ "purge_details": [],
622
+ "zero_pollution_achieved": False,
623
+ "dry_run": False
624
+ }
625
+ else:
626
+ return {
627
+ "status": "ERROR",
628
+ "message": "Destructive database purge requires explicit consent bound to target sandbox. Invalid consent grant.",
629
+ "tables_audited": 0,
630
+ "total_purged_rows": 0,
631
+ "purge_details": [],
632
+ "zero_pollution_achieved": False,
633
+ "dry_run": False
634
+ }
505
635
  if not self.db_path:
506
636
  candidate = os.path.join(self.snapshot_dir, "active_test.db")
507
637
  if os.path.exists(candidate):
@@ -759,10 +889,10 @@ def main():
759
889
  return 0 if res.get("status") != "ERROR" else 1
760
890
 
761
891
  elif args.command == "restore":
762
- if not args.confirm and not os.environ.get("SYNAPSE_FORCE_RESTORE"):
892
+ if not args.confirm:
763
893
  err_msg = (
764
894
  "Refusing to execute destructive database restore without explicit confirmation. "
765
- "Pass --confirm (or set SYNAPSE_FORCE_RESTORE=1) if target is an isolated sandbox."
895
+ "Pass --confirm if target is an isolated sandbox."
766
896
  )
767
897
  res = {
768
898
  "status": "ERROR",
@@ -777,7 +907,14 @@ def main():
777
907
  print(f"❌ [DB RESTORE BLOCKED] ID: {args.id}")
778
908
  print(f" Error: {err_msg}")
779
909
  return 1
780
- res = sandbox.restore_snapshot(args.id, consent=args.confirm or bool(os.environ.get("SYNAPSE_FORCE_RESTORE")))
910
+ grant = create_consent_grant(
911
+ action="db:restore",
912
+ target=sandbox.db_path,
913
+ caller_session=f"cli_{os.getpid()}",
914
+ db_identity=sandbox.db_path,
915
+ ttl_seconds=300
916
+ )
917
+ res = sandbox.restore_snapshot(args.id, consent=grant)
781
918
  if args.json:
782
919
  print(json.dumps(res, indent=2))
783
920
  else:
@@ -810,17 +947,12 @@ def main():
810
947
  if args.apply:
811
948
  effective_dry_run = False
812
949
 
950
+ grant = None
813
951
  if not effective_dry_run:
814
- has_confirm = (
815
- args.confirm
816
- or os.environ.get("SYNAPSE_FORCE_PURGE", "").strip().lower() in ("1", "true", "yes")
817
- or os.environ.get("SYNAPSE_FORCE_RESTORE", "").strip().lower() in ("1", "true", "yes")
818
- or os.environ.get("PENTEST_CONSENT_ACKNOWLEDGED", "").strip().lower() in ("1", "true", "yes")
819
- )
820
- if not has_confirm:
952
+ if not args.confirm:
821
953
  err_msg = (
822
954
  "Refusing to execute destructive database purge without explicit confirmation. "
823
- "Pass --confirm (or set SYNAPSE_FORCE_PURGE=1) if target is an isolated sandbox."
955
+ "Pass --confirm if target is an isolated sandbox."
824
956
  )
825
957
  res = {
826
958
  "status": "ERROR",
@@ -837,8 +969,15 @@ def main():
837
969
  print("❌ [DB PURGE BLOCKED]")
838
970
  print(f" Error: {err_msg}")
839
971
  return 1
972
+ grant = create_consent_grant(
973
+ action="db:purge",
974
+ target=sandbox.db_path,
975
+ caller_session=f"cli_{os.getpid()}",
976
+ db_identity=sandbox.db_path,
977
+ ttl_seconds=300
978
+ )
840
979
 
841
- res = sandbox.audit_and_purge_pollution(dry_run=effective_dry_run, consent=args.confirm)
980
+ res = sandbox.audit_and_purge_pollution(dry_run=effective_dry_run, consent=grant)
842
981
  if args.json:
843
982
  print(json.dumps(res, indent=2))
844
983
  else:
@@ -15,7 +15,7 @@ Key Guarantees:
15
15
  clean 0 with failure text -> CONFLICTING_SIGNALS).
16
16
  3. Informational logging filter ([INFO], [DEBUG]) preventing false-positive assertion detection.
17
17
  4. Genuine token_budget enforcement via calibrated tokenizer (default: 800 tokens).
18
- 5. 15-line block bounding and noise suppression, compressing 95% of log volume.
18
+ 5. 15-line block bounding and noise suppression, compressing repetitive log volume.
19
19
  6. Provenance retention: points back to raw log file for forensic tracing.
20
20
  """
21
21
 
@@ -19,7 +19,15 @@ import argparse
19
19
  import os
20
20
  import re
21
21
  import sys
22
- from typing import Dict, List, Optional, Tuple
22
+ from typing import Any, Dict, List, Optional, Tuple
23
+
24
+ try:
25
+ from tools.validate_skills_schema import parse_yaml_frontmatter
26
+ except ImportError:
27
+ try:
28
+ from validate_skills_schema import parse_yaml_frontmatter
29
+ except ImportError:
30
+ parse_yaml_frontmatter = None
23
31
 
24
32
  PERSONA_KEYWORDS = {
25
33
  "identity", "role", "tone", "communication", "telemetry", "badge",
@@ -34,8 +42,15 @@ PROCEDURE_KEYWORDS = {
34
42
  }
35
43
 
36
44
 
37
- def parse_frontmatter(content: str) -> Tuple[Dict[str, str], str]:
45
+ def parse_frontmatter(content: str) -> Tuple[Dict[str, Any], str]:
38
46
  """Extracts YAML frontmatter if present and returns (frontmatter_dict, remaining_body)."""
47
+ if parse_yaml_frontmatter is not None:
48
+ data, body, _ = parse_yaml_frontmatter(content)
49
+ if data is not None:
50
+ return data, body
51
+ if not content.startswith("---"):
52
+ return {}, content
53
+
39
54
  match = re.match(r"^---\s*\n(.*?)\n---\s*\n(.*)$", content, re.DOTALL)
40
55
  if not match:
41
56
  return {}, content