96f4baba4f
Apply the same contrast fixes from the homepage audit to 10 additional pages. All changes are one shade darker within the same hue family: - text-teal-600 → text-teal-700 (4.08:1 → 5.31:1) - text-emerald-600 → text-emerald-700 (4.52:1 → 5.94:1) - text-gray-500 → text-gray-600 on gray backgrounds (3.77:1 → 5.27:1) Files: architecture, village-case-study, implementer, leader, timeline, api-reference, koha, koha/transparency, gdpr, agent-lightning Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
877 lines
37 KiB
HTML
877 lines
37 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<title>API Reference | Tractatus Framework</title>
|
|
<meta name="description" content="Complete API reference for Tractatus Framework - endpoints, authentication, request/response formats, and examples.">
|
|
<link rel="stylesheet" href="/css/tailwind.css?v=0.1.2.1770743517007">
|
|
<link rel="stylesheet" href="/css/tractatus-theme.min.css?v=0.1.2.1770743517007">
|
|
<style>
|
|
.endpoint-badge {
|
|
@apply inline-block px-2 py-1 rounded text-xs font-mono font-semibold;
|
|
}
|
|
.method-GET { @apply bg-blue-100 text-blue-800; }
|
|
.method-POST { @apply bg-green-100 text-green-800; }
|
|
.method-PUT { @apply bg-yellow-100 text-yellow-800; }
|
|
.method-DELETE { @apply bg-red-100 text-red-800; }
|
|
</style>
|
|
|
|
<!-- Auto-reload on service worker update -->
|
|
</head>
|
|
<body class="bg-gray-50">
|
|
|
|
<!-- Navigation -->
|
|
<nav class="bg-white border-b border-gray-200">
|
|
<div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
|
|
<div class="flex justify-between h-16">
|
|
<div class="flex items-center">
|
|
<a href="/" class="text-xl font-bold text-gray-900">Tractatus Framework</a>
|
|
<span class="ml-4 text-gray-400">|</span>
|
|
<span class="ml-4 text-gray-600">API Reference</span>
|
|
</div>
|
|
<div class="flex items-center space-x-4 sm:space-x-6">
|
|
<a href="/docs.html" class="text-gray-600 hover:text-gray-900 text-sm sm:text-base">Documentation</a>
|
|
<a href="/implementer.html" class="text-gray-600 hover:text-gray-900 text-sm sm:text-base">Implementation Guide</a>
|
|
<a href="/" class="text-gray-600 hover:text-gray-900 text-sm sm:text-base">Home</a>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</nav>
|
|
|
|
<!-- Sidebar + Content Layout -->
|
|
<div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-8">
|
|
<div class="grid grid-cols-1 lg:grid-cols-4 gap-8">
|
|
|
|
<!-- Sidebar TOC -->
|
|
<aside class="lg:col-span-1">
|
|
<nav class="sticky top-8 space-y-1">
|
|
<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 font-semibold">Governance Services</a>
|
|
<a href="#governance" class="block py-2 px-3 pl-6 text-sm text-gray-600 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-600 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-600 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-600 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-600 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-600 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>
|
|
</aside>
|
|
|
|
<!-- Main Content -->
|
|
<main class="lg:col-span-3">
|
|
|
|
<!-- Introduction -->
|
|
<div class="mb-12">
|
|
<h1 class="text-4xl font-bold text-gray-900 mb-4">API Reference</h1>
|
|
<p class="text-lg text-gray-600">
|
|
Complete reference for the Tractatus Framework REST API. All endpoints return JSON and require proper authentication where indicated.
|
|
</p>
|
|
<div class="mt-6 bg-blue-50 border-l-4 border-blue-500 p-4">
|
|
<p class="text-sm text-blue-800">
|
|
<strong>Base URL:</strong> <code class="bg-blue-100 px-2 py-1 rounded">http://localhost:9000/api</code>
|
|
</p>
|
|
</div>
|
|
|
|
<div class="mt-4 bg-green-50 border-l-4 border-green-500 p-4">
|
|
<p class="text-sm text-green-800">
|
|
<strong>📄 OpenAPI Specification:</strong> <a href="/docs/api/openapi.yaml" class="underline hover:text-green-900 font-semibold" download>Download OpenAPI 3.0 YAML</a>
|
|
</p>
|
|
<p class="text-xs text-green-700 mt-1">
|
|
Use this specification with Swagger UI, Postman, or any OpenAPI-compatible tool for interactive API exploration.
|
|
</p>
|
|
</div>
|
|
|
|
<div class="mt-4 bg-purple-50 border-l-4 border-purple-500 p-4">
|
|
<p class="text-sm text-purple-800">
|
|
<strong>💻 Code Examples:</strong>
|
|
<a href="/docs/api/examples-javascript.md" class="underline hover:text-purple-900 font-semibold">JavaScript</a>
|
|
<span class="mx-2 text-purple-600">|</span>
|
|
<a href="/docs/api/examples-python.md" class="underline hover:text-purple-900 font-semibold">Python</a>
|
|
</p>
|
|
<p class="text-xs text-purple-700 mt-1">
|
|
Complete integration examples for authentication, documents, governance services, and audit logs.
|
|
</p>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- Authentication -->
|
|
<section id="authentication" class="mb-12">
|
|
<h2 class="text-3xl font-bold text-gray-900 mb-6">Authentication</h2>
|
|
|
|
<!-- Login -->
|
|
<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">/auth/login</code>
|
|
</div>
|
|
<p class="text-gray-600 mb-4">Authenticate and receive JWT token.</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>{
|
|
"email": "admin@tractatus.local",
|
|
"password": "your_password"
|
|
}</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>{
|
|
"success": true,
|
|
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
|
"user": {
|
|
"email": "admin@tractatus.local",
|
|
"role": "admin"
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
|
|
<!-- Verify Token -->
|
|
<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">/auth/me</code>
|
|
<span class="ml-2 text-xs text-gray-500">🔒 Requires Auth</span>
|
|
</div>
|
|
<p class="text-gray-600 mb-4">Get current user information.</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 {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>{
|
|
"success": true,
|
|
"user": {
|
|
"id": "68e3a6fb21af2fd194bf4b50",
|
|
"email": "admin@tractatus.local",
|
|
"role": "admin"
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</section>
|
|
|
|
<!-- Documents -->
|
|
<section id="documents" class="mb-12">
|
|
<h2 class="text-3xl font-bold text-gray-900 mb-6">Documents</h2>
|
|
|
|
<!-- List Documents -->
|
|
<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">/documents</code>
|
|
</div>
|
|
<p class="text-gray-600 mb-4">Get list of all documents.</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)</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">quadrant</td>
|
|
<td class="py-2 text-gray-600">Filter by quadrant (STRATEGIC, OPERATIONAL, etc.)</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,
|
|
"documents": [
|
|
{
|
|
"_id": "672f821b6e820c0c7a0e0d55",
|
|
"title": "Introduction to the Tractatus Framework",
|
|
"slug": "introduction-to-the-tractatus-framework",
|
|
"quadrant": "STRATEGIC",
|
|
"content_html": "<h1>Introduction</h1>...",
|
|
"toc": [{ "level": 1, "text": "Introduction", "slug": "introduction" }],
|
|
"created_at": "2025-10-07T10:30:00Z"
|
|
}
|
|
],
|
|
"total": 12
|
|
}</code></pre>
|
|
</div>
|
|
|
|
<!-- Get Single Document -->
|
|
<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">/documents/:identifier</code>
|
|
</div>
|
|
<p class="text-gray-600 mb-4">Get document by ID or slug.</p>
|
|
|
|
<h4 class="text-sm font-semibold text-gray-900 mb-2">Parameters</h4>
|
|
<table class="w-full text-sm mb-4">
|
|
<tbody>
|
|
<tr>
|
|
<td class="py-2 font-mono text-gray-900">identifier</td>
|
|
<td class="py-2 text-gray-600">Document ID or slug</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,
|
|
"document": {
|
|
"_id": "672f821b6e820c0c7a0e0d55",
|
|
"title": "Introduction to the Tractatus Framework",
|
|
"slug": "introduction-to-the-tractatus-framework",
|
|
"content_html": "<h1>Introduction</h1><p>The Tractatus framework...</p>",
|
|
"toc": [...]
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
|
|
<!-- Search Documents -->
|
|
<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">/documents/search</code>
|
|
</div>
|
|
<p class="text-gray-600 mb-4">Full-text search across documents.</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>
|
|
<td class="py-2 font-mono text-gray-900">q</td>
|
|
<td class="py-2 text-gray-600">Search query (required)</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,
|
|
"results": [
|
|
{
|
|
"title": "Core Concepts",
|
|
"slug": "core-concepts",
|
|
"score": 0.92,
|
|
"excerpt": "...boundary enforcement..."
|
|
}
|
|
]
|
|
}</code></pre>
|
|
</div>
|
|
</section>
|
|
|
|
<!-- Governance Services -->
|
|
<section id="governance" class="mb-12">
|
|
<h2 class="text-3xl font-bold text-gray-900 mb-6">Governance Services</h2>
|
|
|
|
<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 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>{
|
|
"success": true,
|
|
"governance": {
|
|
"active": true,
|
|
"services": {
|
|
"classifier": { "enabled": true, "status": "operational" },
|
|
"validator": { "enabled": true, "status": "operational" },
|
|
"boundary": { "enabled": true, "status": "operational" },
|
|
"pressure": { "enabled": true, "status": "operational" },
|
|
"metacognitive": { "enabled": true, "status": "selective" }
|
|
},
|
|
"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 -->
|
|
<section id="admin" class="mb-12">
|
|
<h2 class="text-3xl font-bold text-gray-900 mb-6">Admin Endpoints</h2>
|
|
|
|
<div class="bg-amber-50 border-l-4 border-amber-500 p-4 mb-6">
|
|
<p class="text-sm text-amber-800">
|
|
All admin endpoints require authentication with admin role.
|
|
</p>
|
|
</div>
|
|
|
|
<!-- Admin Stats -->
|
|
<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">/admin/stats</code>
|
|
<span class="ml-2 text-xs text-gray-500">🔒 Admin Only</span>
|
|
</div>
|
|
<p class="text-gray-600 mb-4">Get dashboard statistics.</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,
|
|
"documents": 12,
|
|
"pending": 3,
|
|
"approved": 45,
|
|
"users": 5
|
|
}</code></pre>
|
|
</div>
|
|
|
|
<!-- Moderation Queue -->
|
|
<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">/admin/moderation</code>
|
|
<span class="ml-2 text-xs text-gray-500">🔒 Admin Only</span>
|
|
</div>
|
|
<p class="text-gray-600 mb-4">Get items in moderation queue.</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,
|
|
"items": [
|
|
{
|
|
"_id": "672f8xxx",
|
|
"type": "blog_post",
|
|
"title": "Understanding Boundary Enforcement",
|
|
"status": "pending",
|
|
"submitted_at": "2025-10-07T11:00:00Z"
|
|
}
|
|
]
|
|
}</code></pre>
|
|
</div>
|
|
</section>
|
|
|
|
<!-- Error Codes -->
|
|
<section id="errors" class="mb-12">
|
|
<h2 class="text-3xl font-bold text-gray-900 mb-6">Error Codes</h2>
|
|
|
|
<div class="bg-white rounded-lg shadow-md overflow-x-auto">
|
|
<table class="w-full">
|
|
<thead class="bg-gray-50 border-b">
|
|
<tr>
|
|
<th class="px-6 py-3 text-left text-xs font-medium text-gray-600 uppercase">Code</th>
|
|
<th class="px-6 py-3 text-left text-xs font-medium text-gray-600 uppercase">Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody class="divide-y divide-gray-200">
|
|
<tr>
|
|
<td class="px-6 py-4 font-mono text-sm text-gray-900">400</td>
|
|
<td class="px-6 py-4 text-sm text-gray-600">Bad Request - Invalid parameters</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="px-6 py-4 font-mono text-sm text-gray-900">401</td>
|
|
<td class="px-6 py-4 text-sm text-gray-600">Unauthorized - Missing or invalid token</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="px-6 py-4 font-mono text-sm text-gray-900">403</td>
|
|
<td class="px-6 py-4 text-sm text-gray-600">Forbidden - Insufficient permissions</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="px-6 py-4 font-mono text-sm text-gray-900">404</td>
|
|
<td class="px-6 py-4 text-sm text-gray-600">Not Found - Resource does not exist</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="px-6 py-4 font-mono text-sm text-gray-900">409</td>
|
|
<td class="px-6 py-4 text-sm text-gray-600">Conflict - Duplicate resource (e.g., slug)</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="px-6 py-4 font-mono text-sm text-gray-900">500</td>
|
|
<td class="px-6 py-4 text-sm text-gray-600">Internal Server Error</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
|
|
<div class="mt-6 bg-gray-50 border-l-4 border-gray-400 p-4">
|
|
<h4 class="text-sm font-semibold text-gray-900 mb-2">Error Response Format</h4>
|
|
<pre class="bg-gray-900 text-gray-100 p-4 rounded-lg overflow-x-auto"><code>{
|
|
"success": false,
|
|
"message": "Error description",
|
|
"error": "ERROR_CODE"
|
|
}</code></pre>
|
|
</div>
|
|
</section>
|
|
|
|
</main>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- Footer -->
|
|
<!-- Footer Component -->
|
|
<script src="/js/components/footer.js?v=0.1.2.1770743517007"></script>
|
|
|
|
</body>
|
|
</html>
|