@vauban-org/agent-sdk 1.0.0 → 1.3.0

package/src/ports/citadel-action.ts

@@ -0,0 +1,174 @@
+/**
+ * CitadelActionPort — host adapter for Citadel governance operations.
+ *
+ * Implements tiered access control (T1-T4) per BYOA (Bring Your Own Agent) framework.
+ * Only T3+ agents can seal sprints, T1 is read-only, T4 requires on-chain signing.
+ *
+ * Source: MASTER-PLAN-v5.md §1.3 (CC service layer) + vauban-gouvernance/rules/ai/tiered-gates.md
+ */
+
+// ─── Types ─────────────────────────────────────────────────────────────────
+
+export type AgentTier = "T1" | "T2" | "T3" | "T4";
+export type TaskStatus =
+  | "todo"
+  | "in_progress"
+  | "done"
+  | "blocked"
+  | "rejected";
+
+export interface SprintInput {
+  readonly name: string;
+  readonly goal?: string;
+  readonly start_date?: string; // ISO 8601
+  readonly end_date?: string;
+  readonly project_slug: string;
+}
+
+export interface TaskRef {
+  readonly ref: string; // format: "project:sprint-N:task-id"
+  readonly project: string;
+  readonly sprint: string;
+  readonly task_id: string;
+}
+
+export interface VerificationEvidence {
+  readonly passed: boolean;
+  readonly evidence_text: string;
+  readonly evidence_hash: string; // sha256 hex
+}
+
+export interface DecisionInput {
+  readonly decision: string;
+  readonly context: string;
+  readonly options: readonly string[];
+  readonly chosen: string;
+  readonly rationale: string;
+  readonly tags?: readonly string[];
+}
+
+export interface ActionContext {
+  readonly agentId: string;
+  readonly agentTier: AgentTier;
+  readonly runId: string;
+  readonly tenantId?: string;
+}
+
+// ─── Results ─────────────────────────────────────────────────────────────────
+
+export interface SprintRef {
+  readonly sprint_id: string;
+  readonly project_slug: string;
+  readonly name: string;
+  readonly created_at: Date;
+}
+
+export interface SealedSprintClaim {
+  readonly sprint_id: string;
+  readonly sealed_at: Date;
+  readonly verification_evidence_hash: string;
+  readonly sealed_by_agent: string;
+  readonly anchor_id?: string; // L3 blockchain anchor
+}
+
+export interface DecisionClaim {
+  readonly decision_id: string;
+  readonly created_at: Date;
+  readonly archived_to_brain: boolean;
+  readonly cascade_triggered?: boolean; // ADR cascade hook
+}
+
+// ─── Port interface ────────────────────────────────────────────────────────
+
+export interface CitadelActionPort {
+  /**
+   * Create a new sprint in a project.
+   * T2+ only. T1 throws CitadelTierViolationError.
+   */
+  createSprint(input: SprintInput, ctx: ActionContext): Promise<SprintRef>;
+
+  /**
+   * Update task status within a sprint.
+   * T2+ can transition: todo→in_progress, in_progress→done, *→blocked.
+   * T3+ can seal (→done with verification).
+   */
+  updateTaskStatus(
+    ref: TaskRef,
+    status: TaskStatus,
+    ctx: ActionContext
+  ): Promise<void>;
+
+  /**
+   * Seal a completed sprint with verification evidence.
+   * T3+ only. Emits SealedSprintClaim (anchor to L3 deferred Phase 1+).
+   * Verification evidence hash proves execution of verification_scenario.
+   */
+  sealSprint(
+    sprintId: string,
+    evidence: VerificationEvidence,
+    ctx: ActionContext
+  ): Promise<SealedSprintClaim>;
+
+  /**
+   * Record a decision to governance layer.
+   * T2+ can record. T3+ triggers optional ADR cascade hook.
+   * Returns DecisionClaim with Brain archive status.
+   */
+  recordDecision(
+    decision: DecisionInput,
+    ctx: ActionContext
+  ): Promise<DecisionClaim>;
+}
+
+// ─── Typed errors ─────────────────────────────────────────────────────────
+
+export class CitadelTierViolationError extends Error {
+  constructor(
+    message: string,
+    public readonly required_tier: AgentTier,
+    public readonly actual_tier: AgentTier,
+    public readonly operation: string,
+    public readonly cause?: unknown
+  ) {
+    super(message);
+    this.name = "CitadelTierViolationError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class CitadelTaskRefNotFoundError extends Error {
+  constructor(
+    public readonly task_ref: string,
+    public readonly cause?: unknown
+  ) {
+    super(`Task not found: ${task_ref}`);
+    this.name = "CitadelTaskRefNotFoundError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class CitadelSprintNotActiveError extends Error {
+  constructor(
+    public readonly sprint_id: string,
+    public readonly current_status: string,
+    public readonly cause?: unknown
+  ) {
+    super(
+      `Sprint ${sprint_id} is not active (status: ${current_status}). Cannot seal.`
+    );
+    this.name = "CitadelSprintNotActiveError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class CitadelInvalidStateTransitionError extends Error {
+  constructor(
+    public readonly current_status: TaskStatus,
+    public readonly requested_status: TaskStatus,
+    public readonly cause?: unknown
+  ) {
+    super(`Invalid state transition: ${current_status} → ${requested_status}`);
+    this.name = "CitadelInvalidStateTransitionError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}

package/src/ports/compliance-contract.ts

@@ -0,0 +1,191 @@
+/**
+ * ComplianceContractPort — runtime compliance gate for the Vauban Integration Spine.
+ *
+ * Implements the G-2 Cedar pivot from S5 spec:
+ * - pre-step: block or warn before capability invocation
+ * - post-step: audit trail after invocation
+ * - validateManifest: conflict detection at registration
+ *
+ * Cedar policy bundles: eu.gdpr / eu.mica / eu.tfr (V0 scope per S5 Q5.1).
+ */
+
+// ─── Jurisdictions ────────────────────────────────────────────────────────────
+
+export type Jurisdiction = "FR.v1" | "EU.v1" | "CH.v1" | "UK.v1" | "SG.v1";
+
+export const SUPPORTED_JURISDICTIONS_V0: Jurisdiction[] = ["FR.v1", "EU.v1"];
+
+// ─── Legal basis refs (S5 §4 encoding) ───────────────────────────────────────
+
+export type LegalBasisRef =
+  | "gdpr.art6_1_a" // consent
+  | "gdpr.art6_1_b" // contract performance
+  | "gdpr.art6_1_c" // legal obligation
+  | "gdpr.art6_1_f" // legitimate interests
+  | "mica.art14" // MiCA disclosure obligation
+  | "tfr.art4" // TFR data retention obligation
+  | "cjeu.c520_21"; // CJEU C-520/21 mandate path
+
+export type LegalBasisDomain =
+  | "processing"
+  | "retention"
+  | "transfer"
+  | "consent";
+
+export interface LegalBasisDecl {
+  domain: LegalBasisDomain;
+  basis: LegalBasisRef;
+  scope?: Jurisdiction[];
+}
+
+// ─── Data classification ──────────────────────────────────────────────────────
+
+export type DataClass = "public" | "internal" | "confidential" | "secret";
+
+// ─── Rule model (S5 §3.2) ────────────────────────────────────────────────────
+
+export type EnforcementLevel = "block" | "warn" | "log";
+export type RuleSource = "declared" | "normative";
+
+export interface ComplianceRule {
+  readonly id: string;
+  readonly source: RuleSource;
+  readonly jurisdiction: Jurisdiction;
+  readonly legal_ref: LegalBasisRef;
+  readonly enforcement: EnforcementLevel;
+  readonly rationale: string;
+  readonly authority?: string; // e.g. "EDPB Guidelines 8/2020"
+}
+
+// ─── ComplianceContract (S5 §3.1) ────────────────────────────────────────────
+
+export type ComplianceMode = "strict" | "audit_only";
+
+export interface ComplianceContract {
+  readonly jurisdictions: Jurisdiction[];
+  readonly legal_bases: LegalBasisDecl[];
+  readonly data_class: DataClass;
+  readonly mode: ComplianceMode;
+  readonly tier: string;
+  readonly rules: ComplianceRule[];
+  readonly retention: string; // ISO duration e.g. "P7Y"
+  readonly audit_format?: "json" | "pdf";
+}
+
+// ─── Invocation context ───────────────────────────────────────────────────────
+
+export interface CapabilityInvocation {
+  readonly action: string; // e.g. "bastion.swap", "brain.archive", "glacis.attest"
+  readonly tenantId: string;
+  readonly dataClass: DataClass;
+  readonly legalBasis?: LegalBasisRef;
+  readonly jurisdiction?: Jurisdiction;
+  readonly requiresConsent?: boolean;
+  readonly requiresVerifiedHuman?: boolean;
+  readonly stepIndex?: number;
+  readonly workflowRunId?: string;
+}
+
+export interface TenantContext {
+  readonly tenantId: string;
+  readonly glacisMode: "verified" | "degraded_verified" | "unverified";
+  readonly verifiedHuman: boolean;
+  readonly jurisdictions: Jurisdiction[];
+}
+
+// ─── Decision types ───────────────────────────────────────────────────────────
+
+export interface ComplianceViolation {
+  readonly ruleId: string;
+  readonly articleRef: string; // e.g. "GDPR Art 6(1)(a)"
+  readonly description: string;
+  readonly severity: "block" | "warn";
+  readonly remediationHint?: string;
+}
+
+export type ComplianceGate =
+  | { readonly decision: "proceed"; readonly warnings: ComplianceViolation[] }
+  | { readonly decision: "block"; readonly violation: ComplianceViolation };
+
+export interface ComplianceAuditResult {
+  readonly decision: "proceed" | "block" | "warn";
+  readonly violations: ComplianceViolation[];
+  readonly auditClaimEmitted: boolean;
+  readonly evaluatedRules: number;
+}
+
+// ─── Manifest validation ──────────────────────────────────────────────────────
+
+export interface PolicyConflict {
+  readonly rule1Id: string;
+  readonly rule2Id: string;
+  readonly description: string;
+  readonly status: "CONFLICT" | "CONFLICT_UNDETERMINED";
+}
+
+export interface ManifestValidationResult {
+  readonly valid: boolean;
+  readonly conflicts: PolicyConflict[];
+  readonly missingLegalBases: string[];
+  readonly jurisdictionWarnings: string[];
+  readonly evaluationTimeMs: number;
+}
+
+// ─── Port interface ───────────────────────────────────────────────────────────
+
+export interface ComplianceContractPort {
+  /**
+   * Pre-step gate — called before any capability invocation.
+   * In 'strict' mode: block on first violation.
+   * In 'audit_only' mode: never block, accumulate warnings.
+   */
+  preStep(
+    invocation: CapabilityInvocation,
+    contract: ComplianceContract,
+    ctx: TenantContext
+  ): Promise<ComplianceGate>;
+
+  /**
+   * Post-step audit — called after capability invocation to emit audit claims.
+   * Always runs regardless of pre-step outcome.
+   */
+  postStep(
+    invocation: CapabilityInvocation,
+    contract: ComplianceContract,
+    ctx: TenantContext
+  ): Promise<ComplianceAuditResult>;
+
+  /**
+   * Manifest validation — called at registration, before any workflow runs.
+   * Cedar conflict detection per G-3. Timeout → CONFLICT_UNDETERMINED (not fail).
+   */
+  validateManifest(
+    contract: ComplianceContract,
+    opts?: { timeoutMs?: number }
+  ): Promise<ManifestValidationResult>;
+}
+
+// ─── Typed errors ─────────────────────────────────────────────────────────────
+
+export class CompliancePolicyError extends Error {
+  constructor(
+    message: string,
+    public readonly ruleId: string,
+    public readonly cause?: unknown
+  ) {
+    super(message);
+    this.name = "CompliancePolicyError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class ComplianceEvaluationTimeoutError extends Error {
+  constructor(
+    public readonly timeoutMs: number,
+    public readonly cause?: unknown
+  ) {
+    super(`Compliance evaluation timed out after ${timeoutMs}ms`);
+    this.name = "ComplianceEvaluationTimeoutError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}

package/src/ports/db.ts

@@ -2,6 +2,104 @@
  * DbPort — re-export of the existing minimal DbClient shape from
  * tracking/agent-run-tracker. Alias DbPort is the port-suffixed name
  * used across other ports; DbClient remains exported for back-compat.
+ *
+ * OTel instrumentation: import { createTracedDbPort } to wrap any
+ * DbPort implementation with OpenTelemetry spans per query.
+ * Gracefully degrades to noop spans when no OTel SDK is installed.
  */
+
+import type { Span } from "@opentelemetry/api";
+import { SpanStatusCode, trace } from "@opentelemetry/api";
+import type { DbClient } from "../tracking/agent-run-tracker.js";
+
+const PORT_TRACER = trace.getTracer("vauban-agent-sdk.ports", "0.1.0");
+
 export type { DbClient as DbPort } from "../tracking/agent-run-tracker.js";
 export type { DbClient } from "../tracking/agent-run-tracker.js";
+
+// ─── Typed errors ─────────────────────────────────────────────────────────────
+
+/**
+ * Thrown when the database connection is lost (ECONNREFUSED, pool exhausted,
+ * or TLS handshake failed). Callers should retry with exponential backoff
+ * once the connection pool is re-established.
+ */
+export class DbConnectionLostError extends Error {
+  constructor(message: string, public readonly cause?: unknown) {
+    super(message);
+    this.name = "DbConnectionLostError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+/**
+ * Thrown when a database query exceeds the configured statement_timeout or
+ * the caller-supplied timeoutMs. The query may have been cancelled by the
+ * server — retrying the same query without changes is unlikely to succeed.
+ */
+export class DbQueryTimeoutError extends Error {
+  /** The SQL statement that timed out (truncated for logging). */
+  readonly queryPreview: string;
+  /** Timeout that was exceeded, in milliseconds. */
+  readonly timeoutMs: number;
+
+  constructor(
+    message: string,
+    queryPreview: string,
+    timeoutMs: number,
+    public readonly cause?: unknown
+  ) {
+    super(message);
+    this.name = "DbQueryTimeoutError";
+    this.queryPreview = queryPreview;
+    this.timeoutMs = timeoutMs;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+/**
+ * Wrap any DbPort implementation with OTel spans per query() call.
+ * The span captures the SQL preview (first 200 chars) and params count.
+ * Gracefully degrades to noop spans when no OTel SDK is installed.
+ *
+ * Usage:
+ *   const raw: DbPort = pgPool;
+ *   const traced = createTracedDbPort(raw);
+ *   const { rows } = await traced.query("SELECT ...") // emits "db.query" span
+ */
+export function createTracedDbPort(impl: DbClient): DbClient {
+  return {
+    async query<T extends object>(
+      sql: string,
+      params?: unknown[]
+    ): Promise<{ rows: T[]; rowCount?: number | undefined }> {
+      return PORT_TRACER.startActiveSpan(
+        "db.query",
+        {
+          attributes: {
+            "db.sql_preview": sql.slice(0, 200),
+            "db.params_count": params?.length ?? 0,
+            "vauban.port.name": "db",
+          },
+        },
+        async (span: Span) => {
+          try {
+            const result = await impl.query<T>(sql, params);
+            span.setAttributes({
+              "db.row_count": result.rowCount ?? result.rows.length,
+            });
+            span.setStatus({ code: SpanStatusCode.OK });
+            return result;
+          } catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            span.setStatus({ code: SpanStatusCode.ERROR, message });
+            if (err instanceof Error) span.recordException(err);
+            throw err;
+          } finally {
+            span.end();
+          }
+        }
+      );
+    },
+  };
+}