john/tractatus
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat: add comprehensive governance services API documentation

Browse source 
Task 12 Progress - Governance Services Documentation Complete:

Added comprehensive documentation for all 6 governance services:

1. InstructionPersistenceClassifier
   - POST /api/governance/classify
   - Quadrant classification (STRATEGIC/OPERATIONAL/TACTICAL/SYSTEM)
   - Persistence levels (HIGH/MEDIUM/LOW)
   - Request/response examples with quadrant types table

2. CrossReferenceValidator
   - POST /api/governance/validate
   - Prevents training pattern override (27027 failure mode)
   - Validation status types (APPROVED/REJECTED/WARNING)
   - Conflict detection and recommendations

3. BoundaryEnforcer
   - POST /api/governance/enforce
   - Values decision blocking (privacy, ethics, sovereignty)
   - Boundary categories and alternatives
   - Human approval requirements

4. ContextPressureMonitor
   - POST /api/governance/pressure
   - Multi-factor session health tracking
   - Pressure levels (NORMAL/ELEVATED/HIGH/CRITICAL/DANGEROUS)
   - Checkpoint recommendations

5. MetacognitiveVerifier
   - POST /api/governance/verify
   - AI self-checks for complex operations
   - Scope creep detection
   - Confidence scoring and alternatives

6. AuditLogger
   - GET /api/audit/audit-logs (with filtering)
   - GET /api/audit/audit-analytics
   - Comprehensive audit trail
   - Aggregated analytics

Changes:
- api-reference.html: 17KB → 37KB (880 lines)
- Updated sidebar navigation with governance services
- All endpoints documented with request/response examples
- Status types, decision categories, and lookup tables included

Future Work:
- docs/plans/TRANSLATION_APPROACH.md: DeepL translation strategy for Task 19
- Remaining: OpenAPI spec, code examples (JS/Python), rate limiting docs

Deployed to: https://agenticgovernance.digital/api-reference.html
This commit is contained in:
TheFlow 2025-10-12 11:02:26 +13:00
parent 14cb0c5b6c
commit 69023be713
2 changed files with 713 additions and 7 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

233
docs/plans/TRANSLATION_APPROACH.md Normal file
View file

@ -0,0 +1,233 @@
# Translation Approach for Task 19: Te Reo Māori & Multilanguage Support
**Date:** October 12, 2025
**Status:** Planning - To be implemented after Task 12 (API Documentation)
**Priority:** CRITICAL (Values - Te Tiriti commitment)
---
## Translation Service: DeepL
**Decision:** Use DeepL API for translation services instead of i18next manual translations
### Deployment Architecture
**Local Development (Port 9000):**
- DeepL API integration in Node.js
- Local environment variable: `DEEPL_API_KEY`
- Translation caching in MongoDB
**Production Server (vps-93a693da.vps.ovh.net):**
- DeepL API integration deployed
- Secure environment variable configuration
- Production translation cache
---
## Implementation Plan
### 1. DeepL API Integration
```javascript
// Example integration approach
const deepl = require('deepl-node');
const translator = new deepl.Translator(process.env.DEEPL_API_KEY);
async function translateContent(text, targetLang) {
const result = await translator.translateText(text, null, targetLang);
return result.text;
}
```
### 2. Language Selector UI
- **Location:** Navigation bar (all pages)
- **Languages:** English (en), Te Reo Māori (mi)
- **Storage:** Browser localStorage + cookie
- **Behavior:** Persist selection across sessions
### 3. Translation Cache
**MongoDB Collection:** `translations`
```javascript
{
source_text: String,
source_lang: String,
target_lang: String,
translated_text: String,
verified: Boolean,
created_at: Date,
updated_at: Date
}
```
**Benefits:**
- Reduces API calls
- Faster page loads
- Cost optimization
- Human verification workflow
### 4. Priority Pages for Translation
**Phase 1 (Task 19):**
- Homepage (index.html)
- About/Values page (about.html)
- Core Framework Documentation
**Phase 2 (Future):**
- All audience paths (researcher, implementer, advocate)
- Interactive demos
- Blog posts
- API documentation
### 5. Māori Language Consultation
**Critical:** Despite using DeepL, Māori language consultation is REQUIRED
**Why:**
- Cultural appropriateness review
- Technical term accuracy
- Idiomatic expressions
- Values alignment
**Process:**
1. DeepL generates initial translation
2. Store in database as `verified: false`
3. Submit to Māori language consultant
4. Update with corrections
5. Mark as `verified: true`
### 6. Rate Limiting & Cost Management
**DeepL API Limits:**
- Free tier: 500,000 characters/month
- Pro tier: Pay per character
**Strategy:**
- Cache all translations
- Batch translation requests
- Monitor character usage
- Set monthly budget alerts
---
## Technical Implementation
### Routes
```javascript
// POST /api/translate
// Translate text to specified language
router.post('/translate', async (req, res) => {
const { text, targetLang } = req.body;
// Check cache first
const cached = await Translation.findOne({
source_text: text,
target_lang: targetLang,
verified: true
});
if (cached) {
return res.json({ translation: cached.translated_text });
}
// Call DeepL API
const translation = await translateContent(text, targetLang);
// Store in cache
await Translation.create({
source_text: text,
source_lang: 'en',
target_lang: targetLang,
translated_text: translation,
verified: false
});
res.json({ translation });
});
```
### Frontend Integration
```javascript
// Language selector component
class LanguageSelector {
constructor() {
this.currentLang = localStorage.getItem('lang') || 'en';
}
async switchLanguage(lang) {
localStorage.setItem('lang', lang);
await this.translatePage(lang);
}
async translatePage(lang) {
if (lang === 'en') {
// Reload original content
location.reload();
return;
}
// Translate all translatable elements
const elements = document.querySelectorAll('[data-translate]');
for (const el of elements) {
const originalText = el.textContent;
const translation = await this.translate(originalText, lang);
el.textContent = translation;
}
}
}
```
---
## Configuration
### Environment Variables
**Development (.env):**
```bash
DEEPL_API_KEY=your_dev_key
DEEPL_API_FREE_TIER=true
TRANSLATION_CACHE_ENABLED=true
```
**Production (remote):**
```bash
DEEPL_API_KEY=your_prod_key
DEEPL_API_FREE_TIER=false
TRANSLATION_CACHE_ENABLED=true
TRANSLATION_VERIFICATION_REQUIRED=true
```
---
## Success Criteria
- [ ] DeepL API integrated on both dev and production
- [ ] Language selector functional in navigation
- [ ] Translation caching working
- [ ] Homepage, About, Core Docs translated to Te Reo Māori
- [ ] Māori language consultant review completed
- [ ] All translations marked as verified
- [ ] User preference persists across sessions
- [ ] Performance: <500ms translation load time (cached)
---
## Notes
- **Cost Estimate:** Homepage + About + Core Docs ≈ 50,000 characters
- **DeepL Free Tier:** Sufficient for Phase 1
- **Future:** Add more languages (Samoan, Tongan, Cook Islands Māori, etc.)
- **Accessibility:** Ensure `lang` attribute updated on `<html>` tag
- **SEO:** Consider separate URLs vs. client-side switching
---
**To Be Implemented:** After Task 12 (API Documentation) completion
**Dependencies:** DeepL API account, MongoDB translations collection, Māori language consultant
**Timeline:** 5-7 days estimated

487
public/api-reference.html
View file

@ -46,7 +46,13 @@
<h3 class="text-sm font-semibold text-gray-900 mb-2">Contents</h3>
<a href="#authentication" class="block py-2 px-3 text-sm text-gray-600 hover:text-gray-900 hover:bg-gray-100 rounded">Authentication</a>
<a href="#documents" class="block py-2 px-3 text-sm text-gray-600 hover:text-gray-900 hover:bg-gray-100 rounded">Documents</a>
<a href="#governance" class="block py-2 px-3 text-sm text-gray-600 hover:text-gray-900 hover:bg-gray-100 rounded">Governance</a>
<a href="#governance" class="block py-2 px-3 text-sm text-gray-600 hover:text-gray-900 hover:bg-gray-100 rounded font-semibold">Governance Services</a>
<a href="#governance" class="block py-2 px-3 pl-6 text-sm text-gray-500 hover:text-gray-900 hover:bg-gray-100 rounded">1. Classifier</a>
<a href="#governance" class="block py-2 px-3 pl-6 text-sm text-gray-500 hover:text-gray-900 hover:bg-gray-100 rounded">2. Validator</a>
<a href="#governance" class="block py-2 px-3 pl-6 text-sm text-gray-500 hover:text-gray-900 hover:bg-gray-100 rounded">3. BoundaryEnforcer</a>
<a href="#governance" class="block py-2 px-3 pl-6 text-sm text-gray-500 hover:text-gray-900 hover:bg-gray-100 rounded">4. Pressure Monitor</a>
<a href="#governance" class="block py-2 px-3 pl-6 text-sm text-gray-500 hover:text-gray-900 hover:bg-gray-100 rounded">5. Verifier</a>
<a href="#governance" class="block py-2 px-3 pl-6 text-sm text-gray-500 hover:text-gray-900 hover:bg-gray-100 rounded">6. AuditLogger</a>
<a href="#admin" class="block py-2 px-3 text-sm text-gray-600 hover:text-gray-900 hover:bg-gray-100 rounded">Admin</a>
<a href="#errors" class="block py-2 px-3 text-sm text-gray-600 hover:text-gray-900 hover:bg-gray-100 rounded">Error Codes</a>
</nav>
@ -233,16 +239,27 @@
</div>
</section>
<!-- Governance -->
<!-- Governance Services -->
<section id="governance" class="mb-12">
<h2 class="text-3xl font-bold text-gray-900 mb-6">Governance</h2>
<h2 class="text-3xl font-bold text-gray-900 mb-6">Governance Services</h2>
<div class="bg-white rounded-lg shadow-md p-6">
<div class="bg-blue-50 border-l-4 border-blue-500 p-4 mb-6">
<p class="text-sm text-blue-800">
<strong>Note:</strong> All governance endpoints require admin authentication. These services implement architectural AI safety through runtime enforcement.
</p>
</div>
<!-- Framework Status -->
<div class="bg-white rounded-lg shadow-md p-6 mb-6">
<div class="flex items-center mb-4">
<span class="endpoint-badge method-GET">GET</span>
<code class="ml-3 text-gray-900">/governance</code>
<span class="ml-2 text-xs text-gray-500">🔒 Admin Only</span>
</div>
<p class="text-gray-600 mb-4">Get governance framework status.</p>
<p class="text-gray-600 mb-4">Get overall governance framework status.</p>
<h4 class="text-sm font-semibold text-gray-900 mb-2">Headers</h4>
<pre class="bg-gray-900 text-gray-100 p-4 rounded-lg overflow-x-auto mb-4"><code>Authorization: Bearer {admin_token}</code></pre>
<h4 class="text-sm font-semibold text-gray-900 mb-2">Response</h4>
<pre class="bg-gray-900 text-gray-100 p-4 rounded-lg overflow-x-auto"><code>{
@ -256,11 +273,467 @@
"pressure": { "enabled": true, "status": "operational" },
"metacognitive": { "enabled": true, "status": "selective" }
},
"instruction_count": 7,
"last_validation": "2025-10-07T12:00:00Z"
"instruction_count": 28,
"last_validation": "2025-10-12T10:00:00Z"
}
}</code></pre>
</div>
<!-- InstructionPersistenceClassifier -->
<h3 class="text-2xl font-bold text-gray-900 mb-4 mt-8">1. InstructionPersistenceClassifier</h3>
<p class="text-gray-600 mb-6">Classifies instructions by quadrant (STRATEGIC/OPERATIONAL/TACTICAL/SYSTEM) and assigns persistence levels.</p>
<div class="bg-white rounded-lg shadow-md p-6 mb-6">
<div class="flex items-center mb-4">
<span class="endpoint-badge method-POST">POST</span>
<code class="ml-3 text-gray-900">/governance/classify</code>
<span class="ml-2 text-xs text-gray-500">🔒 Admin Only</span>
</div>
<p class="text-gray-600 mb-4">Classify an instruction and get its quadrant, persistence level, and temporal scope.</p>
<h4 class="text-sm font-semibold text-gray-900 mb-2">Request Body</h4>
<pre class="bg-gray-900 text-gray-100 p-4 rounded-lg overflow-x-auto mb-4"><code>{
"text": "Always use MongoDB on port 27027",
"context": {
"source": "user",
"session_id": "sess_123"
}
}</code></pre>
<h4 class="text-sm font-semibold text-gray-900 mb-2">Response</h4>
<pre class="bg-gray-900 text-gray-100 p-4 rounded-lg overflow-x-auto mb-4"><code>{
"success": true,
"classification": {
"quadrant": "SYSTEM",
"persistence": "HIGH",
"temporal_scope": "PROJECT",
"verification_required": "MANDATORY",
"reasoning": "Port configuration affects system infrastructure",
"confidence": 0.95
}
}</code></pre>
<h4 class="text-sm font-semibold text-gray-900 mb-2">Quadrant Types</h4>
<table class="w-full text-sm">
<tbody>
<tr class="border-b">
<td class="py-2 font-mono text-gray-900">STRATEGIC</td>
<td class="py-2 text-gray-600">Values, ethics, mission, Te Tiriti commitments</td>
</tr>
<tr class="border-b">
<td class="py-2 font-mono text-gray-900">OPERATIONAL</td>
<td class="py-2 text-gray-600">Architecture, deployment, configuration</td>
</tr>
<tr class="border-b">
<td class="py-2 font-mono text-gray-900">TACTICAL</td>
<td class="py-2 text-gray-600">Bug fixes, features, code changes</td>
</tr>
<tr class="border-b">
<td class="py-2 font-mono text-gray-900">SYSTEM</td>
<td class="py-2 text-gray-600">Environment, infrastructure, database, tooling</td>
</tr>
<tr>
<td class="py-2 font-mono text-gray-900">STOCHASTIC</td>
<td class="py-2 text-gray-600">One-off requests, experimental, temporary</td>
</tr>
</tbody>
</table>
</div>
<!-- CrossReferenceValidator -->
<h3 class="text-2xl font-bold text-gray-900 mb-4 mt-8">2. CrossReferenceValidator</h3>
<p class="text-gray-600 mb-6">Prevents training pattern override ("27027 failure mode") by validating actions against stored instructions.</p>
<div class="bg-white rounded-lg shadow-md p-6 mb-6">
<div class="flex items-center mb-4">
<span class="endpoint-badge method-POST">POST</span>
<code class="ml-3 text-gray-900">/governance/validate</code>
<span class="ml-2 text-xs text-gray-500">🔒 Admin Only</span>
</div>
<p class="text-gray-600 mb-4">Validate a proposed action against instruction history to detect conflicts.</p>
<h4 class="text-sm font-semibold text-gray-900 mb-2">Request Body</h4>
<pre class="bg-gray-900 text-gray-100 p-4 rounded-lg overflow-x-auto mb-4"><code>{
"action": {
"type": "database_config",
"target": "MongoDB",
"parameters": {
"port": 27017
}
},
"context": {
"messages": [],
"session_id": "sess_123"
}
}</code></pre>
<h4 class="text-sm font-semibold text-gray-900 mb-2">Response (Conflict Detected)</h4>
<pre class="bg-gray-900 text-gray-100 p-4 rounded-lg overflow-x-auto mb-4"><code>{
"success": true,
"validation": {
"status": "REJECTED",
"reason": "Pattern recognition override detected",
"conflicts": [
{
"instruction_id": "inst_008",
"text": "Always use MongoDB on port 27027",
"quadrant": "SYSTEM",
"persistence": "HIGH"
}
],
"recommendation": "Use port 27027 as explicitly instructed"
}
}</code></pre>
<h4 class="text-sm font-semibold text-gray-900 mb-2">Validation Status Types</h4>
<table class="w-full text-sm">
<tbody>
<tr class="border-b">
<td class="py-2 font-mono text-gray-900">APPROVED</td>
<td class="py-2 text-gray-600">No conflicts, proceed safely</td>
</tr>
<tr class="border-b">
<td class="py-2 font-mono text-gray-900">REJECTED</td>
<td class="py-2 text-gray-600">Conflicts with HIGH persistence instructions</td>
</tr>
<tr>
<td class="py-2 font-mono text-gray-900">WARNING</td>
<td class="py-2 text-gray-600">Potential conflicts, proceed with caution</td>
</tr>
</tbody>
</table>
</div>
<!-- BoundaryEnforcer -->
<h3 class="text-2xl font-bold text-gray-900 mb-4 mt-8">3. BoundaryEnforcer</h3>
<p class="text-gray-600 mb-6">Blocks values decisions requiring human judgment (privacy, ethics, strategic direction).</p>
<div class="bg-white rounded-lg shadow-md p-6 mb-6">
<div class="flex items-center mb-4">
<span class="endpoint-badge method-POST">POST</span>
<code class="ml-3 text-gray-900">/governance/enforce</code>
<span class="ml-2 text-xs text-gray-500">🔒 Admin Only</span>
</div>
<p class="text-gray-600 mb-4">Check if a decision crosses into values territory and requires human approval.</p>
<h4 class="text-sm font-semibold text-gray-900 mb-2">Request Body</h4>
<pre class="bg-gray-900 text-gray-100 p-4 rounded-lg overflow-x-auto mb-4"><code>{
"action": {
"type": "policy_change",
"description": "Update privacy policy to enable more tracking",
"impact": "user_privacy"
},
"context": {
"requested_by": "user",
"reason": "improve analytics"
}
}</code></pre>
<h4 class="text-sm font-semibold text-gray-900 mb-2">Response (Blocked)</h4>
<pre class="bg-gray-900 text-gray-100 p-4 rounded-lg overflow-x-auto mb-4"><code>{
"success": true,
"enforcement": {
"decision": "BLOCK",
"category": "VALUES_DECISION",
"reason": "Privacy vs. analytics trade-off requires human judgment",
"boundary_crossed": "privacy",
"requires_approval": true,
"alternatives": [
"Implement privacy-preserving analytics (Plausible/Fathom)",
"Consult user on acceptable tracking level",
"Review compliance with sovereignty principles"
]
}
}</code></pre>
<h4 class="text-sm font-semibold text-gray-900 mb-2">Boundary Categories</h4>
<table class="w-full text-sm">
<tbody>
<tr class="border-b">
<td class="py-2 font-mono text-gray-900">privacy</td>
<td class="py-2 text-gray-600">User data, tracking, surveillance</td>
</tr>
<tr class="border-b">
<td class="py-2 font-mono text-gray-900">ethics</td>
<td class="py-2 text-gray-600">Moral trade-offs, fairness, harm</td>
</tr>
<tr class="border-b">
<td class="py-2 font-mono text-gray-900">sovereignty</td>
<td class="py-2 text-gray-600">Indigenous rights, Te Tiriti, CARE principles</td>
</tr>
<tr>
<td class="py-2 font-mono text-gray-900">strategic</td>
<td class="py-2 text-gray-600">Mission changes, major pivots</td>
</tr>
</tbody>
</table>
</div>
<!-- ContextPressureMonitor -->
<h3 class="text-2xl font-bold text-gray-900 mb-4 mt-8">4. ContextPressureMonitor</h3>
<p class="text-gray-600 mb-6">Multi-factor session health tracking to detect degradation before failures occur.</p>
<div class="bg-white rounded-lg shadow-md p-6 mb-6">
<div class="flex items-center mb-4">
<span class="endpoint-badge method-POST">POST</span>
<code class="ml-3 text-gray-900">/governance/pressure</code>
<span class="ml-2 text-xs text-gray-500">🔒 Admin Only</span>
</div>
<p class="text-gray-600 mb-4">Analyze session context pressure across multiple factors.</p>
<h4 class="text-sm font-semibold text-gray-900 mb-2">Request Body</h4>
<pre class="bg-gray-900 text-gray-100 p-4 rounded-lg overflow-x-auto mb-4"><code>{
"context": {
"tokenUsage": 120000,
"tokenBudget": 200000,
"messageCount": 45,
"errorCount": 3,
"complexOperations": 8,
"sessionDuration": 3600
}
}</code></pre>
<h4 class="text-sm font-semibold text-gray-900 mb-2">Response</h4>
<pre class="bg-gray-900 text-gray-100 p-4 rounded-lg overflow-x-auto mb-4"><code>{
"success": true,
"pressure": {
"level": "ELEVATED",
"score": 62.5,
"factors": {
"token_usage": { "value": 60, "weight": 0.4, "status": "ELEVATED" },
"message_depth": { "value": 45, "weight": 0.2, "status": "NORMAL" },
"error_rate": { "value": 6.7, "weight": 0.3, "status": "ELEVATED" },
"complexity": { "value": 8, "weight": 0.1, "status": "HIGH" }
},
"recommendation": "INCREASE_VERIFICATION",
"actions": [
"Review recent errors for patterns",
"Consider session checkpoint at 75% tokens",
"Reduce concurrent complex operations"
],
"next_checkpoint": 150000
}
}</code></pre>
<h4 class="text-sm font-semibold text-gray-900 mb-2">Pressure Levels</h4>
<table class="w-full text-sm">
<tbody>
<tr class="border-b">
<td class="py-2 font-mono text-gray-900">NORMAL</td>
<td class="py-2 text-gray-600">0-40% - Standard operation</td>
</tr>
<tr class="border-b">
<td class="py-2 font-mono text-gray-900">ELEVATED</td>
<td class="py-2 text-gray-600">41-60% - Increase verification</td>
</tr>
<tr class="border-b">
<td class="py-2 font-mono text-gray-900">HIGH</td>
<td class="py-2 text-gray-600">61-80% - Consider checkpoint</td>
</tr>
<tr class="border-b">
<td class="py-2 font-mono text-gray-900">CRITICAL</td>
<td class="py-2 text-gray-600">81-95% - Session handoff recommended</td>
</tr>
<tr>
<td class="py-2 font-mono text-gray-900">DANGEROUS</td>
<td class="py-2 text-gray-600">96-100% - Quality degradation likely</td>
</tr>
</tbody>
</table>
</div>
<!-- MetacognitiveVerifier -->
<h3 class="text-2xl font-bold text-gray-900 mb-4 mt-8">5. MetacognitiveVerifier</h3>
<p class="text-gray-600 mb-6">AI self-checks for complex operations to detect scope creep and misalignment.</p>
<div class="bg-white rounded-lg shadow-md p-6 mb-6">
<div class="flex items-center mb-4">
<span class="endpoint-badge method-POST">POST</span>
<code class="ml-3 text-gray-900">/governance/verify</code>
<span class="ml-2 text-xs text-gray-500">🔒 Admin Only</span>
</div>
<p class="text-gray-600 mb-4">Verify proposed action through metacognitive self-assessment.</p>
<h4 class="text-sm font-semibold text-gray-900 mb-2">Request Body</h4>
<pre class="bg-gray-900 text-gray-100 p-4 rounded-lg overflow-x-auto mb-4"><code>{
"action": {
"type": "refactor",
"scope": "Refactor 47 files across 5 system areas",
"complexity": "high"
},
"reasoning": {
"intent": "Improve code organization",
"approach": "Extract shared utilities, consolidate duplicates",
"risks": "Potential breaking changes"
},
"context": {
"requested": "Refactor authentication module",
"original_scope": "single module"
}
}</code></pre>
<h4 class="text-sm font-semibold text-gray-900 mb-2">Response</h4>
<pre class="bg-gray-900 text-gray-100 p-4 rounded-lg overflow-x-auto mb-4"><code>{
"success": true,
"verification": {
"decision": "REQUIRE_REVIEW",
"confidence": 0.45,
"concerns": [
{
"type": "SCOPE_CREEP",
"severity": "HIGH",
"detail": "Proposed scope (47 files, 5 areas) exceeds request (1 module)"
},
{
"type": "COMPLEXITY",
"severity": "MEDIUM",
"detail": "High-risk refactoring without test coverage verification"
}
],
"criteria": {
"alignment": 0.3,
"coherence": 0.8,
"completeness": 0.9,
"safety": 0.4,
"alternatives_considered": 0.5
},
"recommendation": "Reduce scope to requested authentication module first",
"alternatives": [
"Refactor authentication module only (aligned with request)",
"Create phased refactoring plan with user approval",
"Run comprehensive tests before broader refactoring"
]
}
}</code></pre>
<h4 class="text-sm font-semibold text-gray-900 mb-2">Verification Decisions</h4>
<table class="w-full text-sm">
<tbody>
<tr class="border-b">
<td class="py-2 font-mono text-gray-900">APPROVED</td>
<td class="py-2 text-gray-600">High confidence (>0.85), proceed</td>
</tr>
<tr class="border-b">
<td class="py-2 font-mono text-gray-900">REQUIRE_REVIEW</td>
<td class="py-2 text-gray-600">Medium confidence (0.5-0.85), seek approval</td>
</tr>
<tr>
<td class="py-2 font-mono text-gray-900">REJECTED</td>
<td class="py-2 text-gray-600">Low confidence (<0.5), do not proceed</td>
</tr>
</tbody>
</table>
</div>
<!-- AuditLogger -->
<h3 class="text-2xl font-bold text-gray-900 mb-4 mt-8">6. AuditLogger</h3>
<p class="text-gray-600 mb-6">Comprehensive audit trail of all governance decisions and framework activity.</p>
<div class="bg-white rounded-lg shadow-md p-6 mb-6">
<div class="flex items-center mb-4">
<span class="endpoint-badge method-GET">GET</span>
<code class="ml-3 text-gray-900">/audit/audit-logs</code>
<span class="ml-2 text-xs text-gray-500">🔒 Admin Only</span>
</div>
<p class="text-gray-600 mb-4">Retrieve audit logs with filtering and pagination.</p>
<h4 class="text-sm font-semibold text-gray-900 mb-2">Query Parameters</h4>
<table class="w-full text-sm mb-4">
<tbody>
<tr class="border-b">
<td class="py-2 font-mono text-gray-900">limit</td>
<td class="py-2 text-gray-600">Number of results (default: 50, max: 100)</td>
</tr>
<tr class="border-b">
<td class="py-2 font-mono text-gray-900">skip</td>
<td class="py-2 text-gray-600">Pagination offset (default: 0)</td>
</tr>
<tr class="border-b">
<td class="py-2 font-mono text-gray-900">service</td>
<td class="py-2 text-gray-600">Filter by service (classifier, validator, etc.)</td>
</tr>
<tr class="border-b">
<td class="py-2 font-mono text-gray-900">status</td>
<td class="py-2 text-gray-600">Filter by status (APPROVED, REJECTED, etc.)</td>
</tr>
<tr>
<td class="py-2 font-mono text-gray-900">from</td>
<td class="py-2 text-gray-600">Start date (ISO 8601 format)</td>
</tr>
</tbody>
</table>
<h4 class="text-sm font-semibold text-gray-900 mb-2">Response</h4>
<pre class="bg-gray-900 text-gray-100 p-4 rounded-lg overflow-x-auto"><code>{
"success": true,
"logs": [
{
"_id": "672f8xxx",
"service": "CrossReferenceValidator",
"action": "validate_action",
"status": "REJECTED",
"details": {
"conflict": "Pattern override detected (port 27017 vs 27027)",
"instruction_id": "inst_008"
},
"timestamp": "2025-10-12T10:15:30Z",
"session_id": "sess_123"
},
{
"_id": "672f8yyy",
"service": "BoundaryEnforcer",
"action": "enforce_boundary",
"status": "BLOCKED",
"details": {
"category": "VALUES_DECISION",
"boundary": "privacy"
},
"timestamp": "2025-10-12T09:45:22Z",
"session_id": "sess_122"
}
],
"total": 145,
"limit": 50,
"skip": 0
}</code></pre>
</div>
<div class="bg-white rounded-lg shadow-md p-6">
<div class="flex items-center mb-4">
<span class="endpoint-badge method-GET">GET</span>
<code class="ml-3 text-gray-900">/audit/audit-analytics</code>
<span class="ml-2 text-xs text-gray-500">🔒 Admin Only</span>
</div>
<p class="text-gray-600 mb-4">Get aggregated analytics on audit activity.</p>
<h4 class="text-sm font-semibold text-gray-900 mb-2">Response</h4>
<pre class="bg-gray-900 text-gray-100 p-4 rounded-lg overflow-x-auto"><code>{
"success": true,
"analytics": {
"total_events": 1245,
"by_service": {
"CrossReferenceValidator": 425,
"BoundaryEnforcer": 78,
"ContextPressureMonitor": 312,
"InstructionPersistenceClassifier": 298,
"MetacognitiveVerifier": 132
},
"by_status": {
"APPROVED": 1089,
"REJECTED": 78,
"WARNING": 45,
"BLOCKED": 33
},
"rejection_rate": 6.3,
"period": {
"start": "2025-10-01T00:00:00Z",
"end": "2025-10-12T23:59:59Z",
"days": 12
}
}
}</code></pre>
</div>
</section>
<!-- Admin -->