@systima/aiact-audit-log 0.1.0

package/COMPLIANCE.md

@@ -0,0 +1,180 @@
+# COMPLIANCE.md
+
+Compliance mapping for `@systima/aiact-audit-log` against the EU AI Act (Regulation (EU) 2024/1689).
+
+This document defines the precise boundary of what the library covers and what it does not.
+
+## 1. Scope of Compliance Claims
+
+### 1.1 This package satisfies
+
+- **Article 12(1)**: The technical capability requirement for automatic recording of events. Once configured, the logger captures events without manual intervention and operates over the lifetime of the system. The middleware integration strengthens this by intercepting LLM calls automatically.
+- **Article 12(2)**: The traceability enablement requirement. The schema captures sufficient detail to enable risk identification (12(2)(a)), facilitate post-market monitoring (12(2)(b)), and support deployer monitoring (12(2)(c)).
+- **Article 19(1)**: The minimum retention floor, when correctly configured. The logger enforces a 180-day minimum and stores logs in customer-controlled infrastructure.
+
+### 1.2 This package supports but does not implement
+
+- **Article 9**: Risk management system. The logger provides raw data that feeds into risk management, but does not define what constitutes a risk for a given system, does not implement risk scoring, and does not generate risk assessments.
+- **Article 14**: Human oversight design. The logger records human interventions when they occur, but does not design the oversight mechanism, define when human review is required, or enforce oversight procedures.
+- **Article 72**: Post-market monitoring procedures. The logger provides the data layer for monitoring (via stats, query, and export), but does not define monitoring KPIs, alert thresholds, or escalation procedures.
+- **Annex IV**: Technical documentation. The logger's COMPLIANCE.md and schema documentation contribute to technical documentation, but do not constitute the complete technical documentation package required by Annex IV.
+- **Articles 43-44**: Conformity assessment. The hash chain and verification tooling provide evidence for conformity assessment, but the assessment itself is conducted by a notified body or through internal procedures, not by a logging library.
+
+### 1.3 What correct integration requires
+
+Installing the package is not sufficient for Article 12 compliance. The deploying organisation must also:
+
+1. **Ensure coverage**: all relevant events must be logged. This includes every inference call, tool invocation, system error, human override, configuration change, and session boundary. The middleware integration automates capture for LLM calls; other event types require explicit instrumentation. The coverage diagnostic helps identify gaps.
+2. **Define "relevant events"**: Article 12(2)(a) requires logging events "relevant for identifying situations that may result in the AI system presenting a risk." What constitutes a relevant event depends on the system's risk profile and intended purpose. The organisation must define this, not the library.
+3. **Maintain operational governance**: the library validates configuration on startup and provides health checks, but cannot prevent an operations team from deleting S3 lifecycle policies, disabling Object Lock, or misconfiguring IAM permissions. Ongoing compliance depends on operational discipline.
+4. **Integrate with broader compliance architecture**: the logs must feed into the organisation's risk management system (Article 9), post-market monitoring plan (Article 72), and technical documentation (Annex IV).
+
+## 2. What This Package Does Not Cover
+
+The following obligations require organisational processes that a logging library cannot provide:
+
+| Article | Obligation | Why the library cannot implement it |
+|---|---|---|
+| Article 9 | Risk management system | Requires defining risk criteria specific to the system's intended purpose, performing risk assessments, and implementing mitigation measures. These are organisational and domain-specific decisions. |
+| Article 14 | Human oversight design | Requires designing oversight mechanisms, defining intervention criteria, and training personnel. The library records interventions; it cannot design or enforce them. |
+| Article 72 | Post-market monitoring | Requires defining KPIs, setting alert thresholds, establishing escalation procedures, and reporting to authorities. The library provides data; the monitoring procedure is organisational. |
+| Annex IV | Technical documentation | Requires a comprehensive documentation package covering system description, design choices, training data, validation methods, and more. The audit log schema documentation is one input among many. |
+| Article 13 | Transparency and information | Requires providing information to deployers about the system's capabilities, limitations, and intended purpose. Outside the scope of a logging library. |
+| Article 15 | Accuracy, robustness, cybersecurity | Requires technical measures for system performance. The logger's hash chain provides integrity evidence; it does not implement accuracy testing or cybersecurity measures. |
+
+## 3. Article-by-Article Field Mapping
+
+### Article 12(1): Automatic recording of events
+
+> "High-risk AI systems shall technically allow for the automatic recording of events (logs) over the lifetime of the system."
+
+| Schema field | How it satisfies the requirement |
+|---|---|
+| `entryId` (UUIDv7) | Unique identification of each recorded event |
+| `systemId` | Identifies which AI system produced the log |
+| `timestamp` (ISO 8601) | Records when each event occurred |
+| `seq` (monotonic integer) | Establishes event ordering |
+| `prevHash` + `hash` (SHA-256) | Provides tamper evidence for trustworthy recording |
+| `captureMethod` | Documents how the event was captured (middleware = automatic) |
+
+The middleware integration (`auditMiddleware`) satisfies the "automatic" requirement for LLM calls by intercepting every model invocation without manual instrumentation.
+
+### Article 12(2)(a): Risk identification
+
+> "...events relevant for identifying situations that may result in the high-risk AI system presenting a risk..."
+
+| Schema field | How it satisfies the requirement |
+|---|---|
+| `eventType` | Categorises events for risk pattern detection |
+| `modelId` | Tracks which model version produced each output |
+| `input` | Captures what the system received (raw or hashed) |
+| `output` | Captures what the system produced (raw or hashed) |
+| `error` | Records error states that may indicate risk |
+| `parameters` | Records model configuration at inference time |
+| `decisionId` | Correlates related events for decision-level risk analysis |
+| `toolCall` | Records tool invocations (key risk vector in agentic systems) |
+| `humanIntervention` | Records when humans intervened in system decisions |
+
+### Article 12(2)(b): Post-market monitoring
+
+> "...facilitating the post-market monitoring referred to in Article 72..."
+
+| Schema field | How it satisfies the requirement |
+|---|---|
+| `latencyMs` | Enables performance degradation detection |
+| `usage` (token counts) | Enables cost and usage trend analysis |
+| `error` | Enables error rate monitoring |
+| `modelId` | Enables model version drift tracking |
+| `output.finishReason` | Enables output quality monitoring |
+
+The `stats` API and CLI command aggregate these fields for monitoring dashboards.
+
+### Article 12(2)(c): Deployer monitoring
+
+> "...monitoring the operation of high-risk AI systems referred to in Article 26(5)."
+
+| Schema field | How it satisfies the requirement |
+|---|---|
+| All fields | The entire schema is documented and export-friendly (JSON Lines) |
+| `metadata` | Extensible key-value pairs for deployer-specific context |
+| `humanIntervention` | Records deployer oversight activities |
+
+The `query`, `export`, and `stats` APIs enable deployers to monitor system operation using the logs the system generates.
+
+### Article 12(3)(a): Usage period recording
+
+> "...recording of the period of each use of the system (start date and time and end date and time of each use)..."
+
+| Schema field | How it satisfies the requirement |
+|---|---|
+| `eventType: 'session_start'` | Records the start of a usage session |
+| `eventType: 'session_end'` | Records the end of a usage session |
+| `timestamp` | Provides the date and time for each boundary |
+
+### Article 12(3)(b-d): Biometric system requirements
+
+| Schema field | How it satisfies the requirement |
+|---|---|
+| `referenceDatabase` | 12(3)(b): identifies the reference database checked |
+| `matchResult` | 12(3)(c): records whether input matched a database record |
+| `humanIntervention.userId` | 12(3)(d): identifies the natural person who verified results |
+
+These fields are optional; they apply to systems covered by Annex III, point 1(a).
+
+### Article 19(1): Log retention
+
+> "...the logs shall be kept for a period appropriate to the intended purpose of the high-risk AI system, of at least six months..."
+
+| Mechanism | How it satisfies the requirement |
+|---|---|
+| `retention.minimumDays` default of 180 | Enforces the six-month floor |
+| `ComplianceConfigError` on sub-minimum | Refuses to initialise below 180 days without explicit acknowledgement |
+| S3 lifecycle policy management | Automates retention enforcement at the storage layer |
+| Health check: `lifecycle_policy_exists` | Detects post-deployment drift in retention configuration |
+
+### Article 19(2): Financial services
+
+> "...providers that are financial institutions subject to requirements regarding their internal governance...shall maintain the logs...as part of the documentation kept under the relevant financial services law."
+
+Supported via `retention.minimumDays: 2555` (7 years) for MiFID II compliance. The logs are stored in S3-compatible storage that can be integrated with existing financial services record-keeping infrastructure.
+
+## 4. Hash Chain Integrity
+
+Each log entry participates in a SHA-256 hash chain:
+
+1. The genesis entry's `prevHash` is the SHA-256 of `@systima/aiact-audit-log:genesis:{systemId}`
+2. Each subsequent entry's `prevHash` is the `hash` of the previous entry
+3. Each entry's `hash` is the SHA-256 of the entry serialised with deterministic key ordering (excluding the `hash` field itself)
+
+If any entry is modified, deleted, or inserted:
+- The `hash` of the modified entry will not match its content
+- The `prevHash` of the next entry will not match the `hash` of the modified entry
+- The `verify` CLI command reports the break at the exact position
+
+Combined with S3 Object Lock (Compliance mode), this provides strong evidence of log integrity for conformity assessment under Articles 43-44.
+
+## 5. Coverage Diagnostic
+
+The coverage diagnostic (`coverage` command / `analyseCoverage` API) addresses the real compliance risk: not the schema, but incomplete instrumentation. It analyses logs and reports:
+
+- Event type distribution (what is logged, what is missing)
+- Capture method distribution (middleware vs. manual)
+- Warnings for common gaps (no human interventions, no session boundaries, tool call/result mismatches, long gaps)
+- Recommendations for improving coverage
+
+### Warning rules
+
+| Code | Severity | Condition |
+|---|---|---|
+| `NO_HUMAN_INTERVENTIONS` | medium | Zero `human_intervention` events in period |
+| `NO_SESSION_BOUNDARIES` | medium | Zero `session_start`/`session_end` events |
+| `TOOL_CALL_RESULT_MISMATCH` | high | Tool call count differs from tool result count by >5% |
+| `NO_SYSTEM_EVENTS` | low | Zero `system_event` entries |
+| `ALL_MANUAL_CAPTURE` | medium | 100% of entries have `captureMethod: 'manual'` |
+| `NO_ERROR_EVENTS` | low | Zero error entries across >1,000 entries |
+| `SINGLE_MODEL_ID` | low | Only one model across >100 inference entries |
+| `LONG_GAP` | high | Gap of >24 hours between consecutive weekday entries |
+
+## 6. From Logging to Full Compliance
+
+The audit log is the data layer. For a compliance assessment of your specific system covering risk management (Article 9), human oversight design (Article 14), monitoring procedures (Article 72), and technical documentation (Annex IV), contact [Systima](https://systima.ai).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Systima
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,406 @@
+# @systima/aiact-audit-log
+
+Structured, tamper-evident audit logging for AI systems. Technical logging capability for EU AI Act Article 12 compliance.
+
+- **Schema mapped to Article 12**: every field documents which paragraph it satisfies
+- **SHA-256 hash chains**: tamper-evident log integrity that a regulator can independently verify
+- **S3-native storage**: logs stay in your infrastructure, under your control
+- **AI SDK middleware**: automatic capture for every LLM call via [Vercel AI SDK](https://sdk.vercel.ai)
+- **AsyncLocalStorage context**: correlate multi-step decisions without manual threading
+- **CLI tooling**: query, reconstruct, verify, coverage diagnostics, and compliance export
+- **Retention enforcement**: configurable minimum retention with Article 19(1) floor (180 days)
+
+```
+npm install @systima/aiact-audit-log
+```
+
+> **Important**: this package provides the **technical logging capability** required by Article 12. It is necessary infrastructure for compliance, not sufficient compliance in itself. See [From Logging to Compliance](#from-logging-to-compliance) and [COMPLIANCE.md](./COMPLIANCE.md).
+
+## Quick Start
+
+```typescript
+import { AuditLogger } from '@systima/aiact-audit-log'
+
+const logger = new AuditLogger({
+  systemId: 'loan-scorer-v2',
+  storage: {
+    type: 's3',
+    bucket: 'my-audit-logs',
+    region: 'eu-west-1',
+  },
+})
+
+await logger.log({
+  decisionId: 'dec_abc123',
+  eventType: 'inference',
+  modelId: 'anthropic/claude-sonnet-4-5-20250929',
+  providerId: 'anthropic',
+  input: { value: 'Assess credit risk for application #12345' },
+  output: { value: 'Risk score: 0.72, recommendation: approve with conditions' },
+  latencyMs: 342,
+  usage: { promptTokens: 150, completionTokens: 80, totalTokens: 230 },
+  parameters: { temperature: 0.7 },
+  error: null,
+})
+
+// Flush on shutdown
+await logger.close()
+```
+
+### Automatic Capture with AI SDK Middleware
+
+```typescript
+import { auditMiddleware } from '@systima/aiact-audit-log/ai-sdk/middleware'
+import { anthropic } from '@ai-sdk/anthropic'
+import { generateText, streamText } from 'ai'
+
+const model = auditMiddleware(anthropic('claude-sonnet-4-5-20250929'), {
+  logger,
+})
+
+// Every call through the wrapped model is automatically logged
+const result = await generateText({
+  model,
+  prompt: 'Assess the credit risk for application #12345',
+})
+
+// Streaming works too; the log entry is written when the stream completes
+const stream = streamText({
+  model,
+  prompt: 'Explain the assessment criteria',
+})
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk)
+}
+```
+
+### Context Propagation
+
+```typescript
+import { withAuditContext } from '@systima/aiact-audit-log'
+
+await withAuditContext(
+  { decisionId: 'dec_loan_12345', metadata: { endpoint: '/api/score' } },
+  async () => {
+    // All middleware-captured and manual log calls inherit the context
+    const result = await generateText({ model, prompt: 'Score this application' })
+
+    await logger.log({
+      eventType: 'human_intervention',
+      modelId: null,
+      providerId: null,
+      input: { value: '' },
+      output: { value: 'Approved with modified terms' },
+      latencyMs: null,
+      usage: null,
+      parameters: null,
+      error: null,
+      humanIntervention: {
+        type: 'modification',
+        userId: 'reviewer_hash_a1b2c3',
+        reason: 'Additional documentation provided',
+        timestamp: new Date().toISOString(),
+      },
+    })
+  }
+)
+```
+
+## API Reference
+
+### `AuditLogger`
+
+The core class for structured, tamper-evident audit logging.
+
+```typescript
+const logger = new AuditLogger({
+  // Required
+  systemId: 'loan-scorer-v2',
+  storage: {
+    type: 's3',
+    bucket: 'my-audit-logs',
+    region: 'eu-west-1',
+    prefix: 'aiact-logs',           // Default: 'aiact-logs'
+  },
+
+  // Compliance settings (safe defaults)
+  retention: {
+    minimumDays: 180,               // Default: 180 (Article 19 floor)
+    autoConfigureLifecycle: true,    // Default: true
+  },
+
+  // Privacy / GDPR
+  pii: {
+    hashInputs: false,              // Store SHA-256 hashes instead of raw inputs
+    hashOutputs: false,             // Store SHA-256 hashes instead of raw outputs
+    redactPatterns: [],             // Regex patterns to redact before logging
+  },
+
+  // Performance
+  batching: {
+    maxSize: 100,                   // Flush after N entries
+    maxDelayMs: 5000,               // Flush after N milliseconds
+  },
+
+  // Error handling
+  onError: 'log-and-continue',     // 'log-and-continue' | 'throw' | (error) => void
+
+  // Immutability
+  objectLock: {
+    enabled: false,                 // Set true if bucket has Object Lock
+    mode: 'GOVERNANCE',             // 'GOVERNANCE' | 'COMPLIANCE'
+  },
+
+  // Periodic health checks
+  healthCheck: {
+    enabled: false,                 // Set true to enable
+    intervalMs: 3_600_000,          // Default: 1 hour
+    onDrift: 'warn',               // 'warn' | 'throw' | (drift) => void
+  },
+})
+```
+
+#### `logger.log(input)`
+
+Log a single event. Returns the complete `AuditLogEntryExtended` with hash chain fields.
+
+If no `decisionId` is provided and no `withAuditContext` scope is active, throws `MissingDecisionIdError`.
+
+#### `logger.flush()`
+
+Force flush all buffered entries to storage.
+
+#### `logger.close()`
+
+Flush remaining entries and release all resources. Call on shutdown.
+
+#### `logger.healthCheck()`
+
+Run a health check against the storage backend. Returns `HealthCheckResult` with individual check statuses.
+
+### `AuditLogReader`
+
+Query, reconstruct, verify, and analyse audit logs.
+
+```typescript
+import { AuditLogReader } from '@systima/aiact-audit-log'
+
+const reader = new AuditLogReader({
+  storage: { type: 's3', bucket: 'my-audit-logs', region: 'eu-west-1' },
+  systemId: 'loan-scorer-v2',
+})
+```
+
+#### `reader.query(options?)`
+
+Search logs by time range, event type, decision ID, with optional limit.
+
+```typescript
+const entries = await reader.query({
+  from: '2026-03-01T00:00:00Z',
+  to: '2026-03-15T23:59:59Z',
+  eventType: 'inference',
+  limit: 1000,
+})
+```
+
+#### `reader.reconstruct(decisionId)`
+
+Reconstruct a complete decision trace from a single identifier. Returns all entries, a human-readable timeline, and integrity verification.
+
+```typescript
+const trace = await reader.reconstruct('dec_abc123')
+// { decisionId, entries, timeline, integrity: { valid, entriesChecked } }
+```
+
+#### `reader.verifyChain(options?)`
+
+Validate hash chain integrity across all entries or a time range.
+
+```typescript
+const result = await reader.verifyChain({
+  from: '2026-03-01T00:00:00Z',
+  to: '2026-03-31T23:59:59Z',
+})
+// { valid: boolean, entriesChecked: number, firstBreak: { seq, expectedPrevHash, actualPrevHash } | null }
+```
+
+#### `reader.stats(options?)`
+
+Aggregate metrics for post-market monitoring (Article 72).
+
+```typescript
+const stats = await reader.stats({ from: '2026-03-01T00:00:00Z', to: '2026-03-31T23:59:59Z' })
+// { totalEntries, byEventType, byModel, errorRate, avgLatencyMs, p95LatencyMs, p99LatencyMs, tokenUsage }
+```
+
+### `withAuditContext(context, callback)`
+
+Propagate decision IDs and metadata through async call chains using `AsyncLocalStorage`.
+
+```typescript
+await withAuditContext(
+  { decisionId: 'dec_abc123', metadata: { endpoint: '/api/score' } },
+  async () => {
+    // All logger.log() and middleware calls inherit context
+  }
+)
+```
+
+### `getAuditContext()`
+
+Read the current context (returns `undefined` if no context is active).
+
+### `analyseCoverage(entries, options?)`
+
+Analyse logs for completeness gaps. Returns event type distribution, capture method distribution, warnings, and recommendations.
+
+```typescript
+import { analyseCoverage } from '@systima/aiact-audit-log'
+
+const report = analyseCoverage(entries, { from: '2026-03-01', to: '2026-03-31' })
+```
+
+### AI SDK Helper
+
+Post-call helper for manual logging of AI SDK results (alternative to middleware):
+
+```typescript
+import { logFromAISDKResult } from '@systima/aiact-audit-log/ai-sdk'
+
+const result = await generateText({ model: anthropic('claude-sonnet-4-5-20250929'), prompt })
+await logFromAISDKResult(logger, { decisionId: 'dec_123', prompt, result })
+```
+
+### AI SDK Middleware
+
+Automatic capture middleware:
+
+```typescript
+import { auditMiddleware } from '@systima/aiact-audit-log/ai-sdk/middleware'
+
+const model = auditMiddleware(anthropic('claude-sonnet-4-5-20250929'), {
+  logger,
+  captureInputs: true,       // Default: true
+  captureOutputs: true,       // Default: true
+  captureToolCalls: true,     // Default: true
+  captureParameters: true,    // Default: true
+})
+```
+
+**What the middleware logs automatically**: every `generateText`, `streamText`, and `generateObject` call (including errors and tool calls).
+
+**What requires manual `logger.log()`**: `human_intervention`, `session_start`, `session_end`, `system_event`, `tool_result` from external execution, and custom business logic events.
+
+## CLI
+
+```bash
+npx @systima/aiact-audit-log <command> [options]
+```
+
+All commands accept `--bucket`, `--region`, `--prefix`, `--endpoint`, and `--system-id` flags, or read from `AIACT_S3_BUCKET`, `AIACT_S3_REGION`, `AIACT_S3_PREFIX`, `AIACT_S3_ENDPOINT`, and `AIACT_SYSTEM_ID` environment variables.
+
+### Commands
+
+```bash
+# Query logs
+npx @systima/aiact-audit-log query \
+  --system-id loan-scorer-v2 \
+  --from 2026-03-01 --to 2026-03-15 \
+  --event-type inference --format json
+
+# Reconstruct a decision trace
+npx @systima/aiact-audit-log reconstruct \
+  --system-id loan-scorer-v2 \
+  --decision-id dec_abc123 --format timeline
+
+# Verify hash chain integrity
+npx @systima/aiact-audit-log verify \
+  --system-id loan-scorer-v2 \
+  --from 2026-03-01 --to 2026-03-31
+
+# Aggregate statistics
+npx @systima/aiact-audit-log stats \
+  --system-id loan-scorer-v2 \
+  --from 2026-03-01 --to 2026-03-31
+
+# Coverage diagnostic
+npx @systima/aiact-audit-log coverage \
+  --system-id loan-scorer-v2 \
+  --from 2026-03-01 --to 2026-03-31
+
+# Health check
+npx @systima/aiact-audit-log health \
+  --system-id loan-scorer-v2
+
+# Export compliance evidence package
+npx @systima/aiact-audit-log export \
+  --system-id loan-scorer-v2 \
+  --from 2026-03-01 --to 2026-03-31 \
+  --include-verification --include-coverage \
+  --output ./compliance-evidence/
+```
+
+## Schema
+
+Every log entry follows a schema explicitly mapped to Article 12 paragraphs. Required fields:
+
+| Field | Type | Article Reference |
+|---|---|---|
+| `schemaVersion` | `'v1'` | Forward compatibility |
+| `entryId` | UUIDv7 | 12(1) unique event identification |
+| `decisionId` | string | 12(2)(a) risk identification |
+| `systemId` | string | 12(1) system identification |
+| `timestamp` | ISO 8601 | 12(1), 12(3)(a) automatic recording |
+| `eventType` | enum | 12(2)(a) risk situation identification |
+| `modelId` | string or null | 12(2)(a), 72 model version tracking |
+| `providerId` | string or null | Provider identification |
+| `input` | `{ type, value }` | 12(2)(a), 12(2)(c), 12(3)(c) |
+| `output` | `{ type, value }` or null | 12(2)(a), 12(2)(b) |
+| `latencyMs` | number or null | 12(2)(b), 72 performance monitoring |
+| `usage` | token counts or null | 72 post-market monitoring |
+| `error` | `{ code, message }` or null | 12(2)(a) risk identification |
+| `parameters` | object or null | 12(2)(a) configuration tracking |
+| `captureMethod` | `'middleware'` / `'manual'` / `'context'` | Coverage analysis |
+| `seq` | number | 12(1) event ordering |
+| `prevHash` | SHA-256 hex | Tamper evidence |
+| `hash` | SHA-256 hex | Tamper evidence |
+
+Extended fields (optional): `humanIntervention`, `stepIndex`, `parentEntryId`, `toolCall`, `referenceDatabase`, `matchResult`, `metadata`.
+
+Event types: `inference`, `tool_call`, `tool_result`, `human_intervention`, `system_event`, `session_start`, `session_end`.
+
+## Sector-Specific Configuration
+
+| Sector | Recommended `retention.minimumDays` | Basis |
+|---|---|---|
+| General (default) | 180 | Article 19(1) floor |
+| Financial services | 2555 (7 years) | MiFID II record-keeping |
+| Healthcare | 3650 (10 years) | Clinical record retention |
+| Employment | 1095 (3 years) | Tribunal limitation periods |
+
+For systems processing personal data, enable `pii.hashInputs` and `pii.hashOutputs` to store SHA-256 hashes instead of raw content (GDPR Article 5(1)(c) data minimisation).
+
+## From Logging to Compliance
+
+This package provides the **technical logging capability** required by Article 12. Full EU AI Act compliance for a high-risk system also requires:
+
+- **Risk management system** (Article 9): defining what constitutes a risk for your specific system, implementing risk scoring, and generating risk assessments. The audit log provides raw data that feeds into risk management; it does not define what constitutes a risk.
+- **Human oversight design** (Article 14): designing and documenting oversight mechanisms, defining when human review is required. The audit log records human interventions when they occur; it does not design the oversight mechanism.
+- **Post-market monitoring procedures** (Article 72): defining monitoring KPIs, alert thresholds, and escalation procedures. The audit log provides the data layer for monitoring (via `stats`, `query`, and `export`); it does not define monitoring procedures.
+- **Technical documentation** (Annex IV): the complete documentation package required for conformity assessment. The audit log's schema documentation and COMPLIANCE.md contribute to this; they do not constitute the full package.
+
+The audit log is the data layer. It provides the raw material that feeds into all of the above. It does not implement them.
+
+For a compliance assessment of your specific system covering risk management, human oversight design, monitoring procedures, and technical documentation, visit [systima.ai](https://systima.ai).
+
+## Requirements
+
+- Node.js >= 18
+- `@aws-sdk/client-s3` ^3.x (peer dependency)
+- `ai` ^4.x (optional peer dependency, for AI SDK integration)
+
+## Licence
+
+[MIT](./LICENSE)