@vauban-org/agent-sdk 1.0.0 → 1.2.0

package/dist/ports/bastion-action.js

@@ -0,0 +1,73 @@
+/**
+ * BastionActionPort — host adapter for Bastion DeFi capabilities.
+ *
+ * Implements the manifest ∩ client_policies validation gate (T-E invariant).
+ * All actions must pass through validateAgainstClientPolicies before HTTP execution.
+ *
+ * Source: MASTER-PLAN-v5.md §1.3.1, §2.3 (Q-Bastion-1..4)
+ */
+// ─── Typed errors ─────────────────────────────────────────────────────────
+export class BastionPolicyViolationError extends Error {
+    action;
+    tenantId;
+    cause;
+    constructor(message, action, tenantId, cause) {
+        super(message);
+        this.action = action;
+        this.tenantId = tenantId;
+        this.cause = cause;
+        this.name = "BastionPolicyViolationError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export class BastionInsufficientFundsError extends Error {
+    required;
+    available;
+    cause;
+    constructor(required, available, cause) {
+        super(`Insufficient funds: required ${required}, available ${available}`);
+        this.required = required;
+        this.available = available;
+        this.cause = cause;
+        this.name = "BastionInsufficientFundsError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export class BastionSlippageExceededError extends Error {
+    max_slippage_bps;
+    actual_slippage_bps;
+    cause;
+    constructor(max_slippage_bps, actual_slippage_bps, cause) {
+        super(`Slippage exceeded: max ${max_slippage_bps} bps, actual ${actual_slippage_bps} bps`);
+        this.max_slippage_bps = max_slippage_bps;
+        this.actual_slippage_bps = actual_slippage_bps;
+        this.cause = cause;
+        this.name = "BastionSlippageExceededError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export class BastionContractError extends Error {
+    contract_call;
+    contract_error;
+    cause;
+    constructor(contract_call, contract_error, cause) {
+        super(`Contract error on ${contract_call}: ${contract_error}`);
+        this.contract_call = contract_call;
+        this.contract_error = contract_error;
+        this.cause = cause;
+        this.name = "BastionContractError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export class BastionTransferUnauthorizedError extends Error {
+    reason;
+    cause;
+    constructor(message, reason, cause) {
+        super(message);
+        this.reason = reason;
+        this.cause = cause;
+        this.name = "BastionTransferUnauthorizedError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+//# sourceMappingURL=bastion-action.js.map

package/dist/ports/bastion-action.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bastion-action.js","sourceRoot":"","sources":["../../src/ports/bastion-action.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA+HH,6EAA6E;AAE7E,MAAM,OAAO,2BAA4B,SAAQ,KAAK;IAGlC;IACA;IACA;IAJlB,YACE,OAAe,EACC,MAAc,EACd,QAAkB,EAClB,KAAe;QAE/B,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,WAAM,GAAN,MAAM,CAAQ;QACd,aAAQ,GAAR,QAAQ,CAAU;QAClB,UAAK,GAAL,KAAK,CAAU;QAG/B,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;QAC1C,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED,MAAM,OAAO,6BAA8B,SAAQ,KAAK;IAEpC;IACA;IACA;IAHlB,YACkB,QAAgB,EAChB,SAAiB,EACjB,KAAe;QAE/B,KAAK,CAAC,gCAAgC,QAAQ,eAAe,SAAS,EAAE,CAAC,CAAC;QAJ1D,aAAQ,GAAR,QAAQ,CAAQ;QAChB,cAAS,GAAT,SAAS,CAAQ;QACjB,UAAK,GAAL,KAAK,CAAU;QAG/B,IAAI,CAAC,IAAI,GAAG,+BAA+B,CAAC;QAC5C,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED,MAAM,OAAO,4BAA6B,SAAQ,KAAK;IAEnC;IACA;IACA;IAHlB,YACkB,gBAAwB,EACxB,mBAA2B,EAC3B,KAAe;QAE/B,KAAK,CACH,0BAA0B,gBAAgB,gBAAgB,mBAAmB,MAAM,CACpF,CAAC;QANc,qBAAgB,GAAhB,gBAAgB,CAAQ;QACxB,wBAAmB,GAAnB,mBAAmB,CAAQ;QAC3B,UAAK,GAAL,KAAK,CAAU;QAK/B,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;QAC3C,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAE3B;IACA;IACA;IAHlB,YACkB,aAAqB,EACrB,cAAsB,EACtB,KAAe;QAE/B,KAAK,CAAC,qBAAqB,aAAa,KAAK,cAAc,EAAE,CAAC,CAAC;QAJ/C,kBAAa,GAAb,aAAa,CAAQ;QACrB,mBAAc,GAAd,cAAc,CAAQ;QACtB,UAAK,GAAL,KAAK,CAAU;QAG/B,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED,MAAM,OAAO,gCAAiC,SAAQ,KAAK;IAGvC;IACA;IAHlB,YACE,OAAe,EACC,MAAsD,EACtD,KAAe;QAE/B,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,WAAM,GAAN,MAAM,CAAgD;QACtD,UAAK,GAAL,KAAK,CAAU;QAG/B,IAAI,CAAC,IAAI,GAAG,kCAAkC,CAAC;QAC/C,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF"}

package/dist/ports/brain.d.ts

@@ -136,6 +136,25 @@ export declare class InMemoryProceduralMemory implements ProceduralMemoryPort {
     registerSkill(agentId: string, skill: ProceduralSkill): Promise<void>;
     shareSkill(skillName: string, fromAgentId: string, toAgentIds: string[]): Promise<void>;
 }
+/**
+ * Thrown when the Brain API is unreachable (connection refused, DNS failure,
+ * timeout on connect). Callers can retry with backoff or fall back to a local cache.
+ */
+export declare class BrainUnavailableError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/**
+ * Thrown when the Brain API returns 429 (rate limit exceeded).
+ * Callers should retry after the delay indicated in the `retryAfterMs` field
+ * (extracted from the Retry-After header) or use exponential backoff.
+ */
+export declare class BrainRateLimitError extends Error {
+    readonly cause?: unknown | undefined;
+    /** Retry-After delay in milliseconds. Derived from the HTTP Retry-After header. */
+    readonly retryAfterMs: number;
+    constructor(message: string, retryAfterMs: number, cause?: unknown | undefined);
+}
 export interface BrainPort {
     archiveKnowledge(entry: BrainEntryInput): Promise<BrainEntry | null>;
     queryKnowledge?(query: string, filters?: BrainQueryFilters): Promise<BrainEntry[]>;
@@ -144,4 +163,16 @@ export interface BrainPort {
     semantic?: SemanticMemoryPort;
     procedural?: ProceduralMemoryPort;
 }
+/**
+ * Wrap any BrainPort implementation with OTel spans.
+ * archiveKnowledge and queryKnowledge calls each get a span with the category
+ * and content preview. Gracefully degrades to noop spans when no OTel SDK
+ * is installed.
+ *
+ * Usage:
+ *   const raw: BrainPort = buildHttpBrain(...);
+ *   const traced = createTracedBrainPort(raw);
+ *   await traced.archiveKnowledge({ content: "..." }) // emits "brain.archiveKnowledge" span
+ */
+export declare function createTracedBrainPort(impl: BrainPort): BrainPort;
 //# sourceMappingURL=brain.d.ts.map

package/dist/ports/brain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"brain.d.ts","sourceRoot":"","sources":["../../src/ports/brain.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"brain.d.ts","sourceRoot":"","sources":["../../src/ports/brain.ts"],"names":[],"mappings":"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"}

package/dist/ports/brain.js

@@ -9,7 +9,10 @@
 export class InMemoryWorkingMemory {
     store = new Map();
     async set(runId, key, value, opts) {
-        this.store.set(`${runId}:${key}`, { value, expiresAt: Date.now() + (opts?.ttlMs ?? 300_000) });
+        this.store.set(`${runId}:${key}`, {
+            value,
+            expiresAt: Date.now() + (opts?.ttlMs ?? 300_000),
+        });
     }
     async get(runId, key) {
         const entry = this.store.get(`${runId}:${key}`);
@@ -102,4 +105,115 @@ export class InMemoryProceduralMemory {
         }
     }
 }
+// ─── Typed errors ─────────────────────────────────────────────────────────────
+/**
+ * Thrown when the Brain API is unreachable (connection refused, DNS failure,
+ * timeout on connect). Callers can retry with backoff or fall back to a local cache.
+ */
+export class BrainUnavailableError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "BrainUnavailableError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * Thrown when the Brain API returns 429 (rate limit exceeded).
+ * Callers should retry after the delay indicated in the `retryAfterMs` field
+ * (extracted from the Retry-After header) or use exponential backoff.
+ */
+export class BrainRateLimitError extends Error {
+    cause;
+    /** Retry-After delay in milliseconds. Derived from the HTTP Retry-After header. */
+    retryAfterMs;
+    constructor(message, retryAfterMs, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "BrainRateLimitError";
+        this.retryAfterMs = retryAfterMs;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+import { SpanStatusCode, trace } from "@opentelemetry/api";
+const PORT_TRACER = trace.getTracer("vauban-agent-sdk.ports", "0.1.0");
+/**
+ * Wrap any BrainPort implementation with OTel spans.
+ * archiveKnowledge and queryKnowledge calls each get a span with the category
+ * and content preview. Gracefully degrades to noop spans when no OTel SDK
+ * is installed.
+ *
+ * Usage:
+ *   const raw: BrainPort = buildHttpBrain(...);
+ *   const traced = createTracedBrainPort(raw);
+ *   await traced.archiveKnowledge({ content: "..." }) // emits "brain.archiveKnowledge" span
+ */
+export function createTracedBrainPort(impl) {
+    return {
+        working: impl.working,
+        episodic: impl.episodic,
+        semantic: impl.semantic,
+        procedural: impl.procedural,
+        async archiveKnowledge(entry) {
+            return PORT_TRACER.startActiveSpan("brain.archiveKnowledge", {
+                attributes: {
+                    "brain.entry.category": entry.category ?? "unknown",
+                    "brain.entry.content_preview": entry.content.slice(0, 200),
+                    "brain.entry.tags": entry.tags?.join(",") ?? "",
+                    "vauban.port.name": "brain",
+                },
+            }, async (span) => {
+                try {
+                    const result = await impl.archiveKnowledge(entry);
+                    if (result) {
+                        span.setAttribute("brain.entry.id", result.id);
+                    }
+                    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();
+                }
+            });
+        },
+        async queryKnowledge(query, filters) {
+            if (!impl.queryKnowledge)
+                return [];
+            const qk = impl.queryKnowledge.bind(impl);
+            return PORT_TRACER.startActiveSpan("brain.queryKnowledge", {
+                attributes: {
+                    "brain.query.preview": query.slice(0, 200),
+                    "brain.query.category": filters?.category ?? "none",
+                    "brain.query.limit": filters?.limit ?? -1,
+                    "vauban.port.name": "brain",
+                },
+            }, async (span) => {
+                try {
+                    const result = await qk(query, filters);
+                    span.setAttribute("brain.query.result_count", result.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();
+                }
+            });
+        },
+    };
+}
 //# sourceMappingURL=brain.js.map

package/dist/ports/brain.js.map

@@ -1 +1 @@
-{"version":3,"file":"brain.js","sourceRoot":"","sources":["../../src/ports/brain.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"brain.js","sourceRoot":"","sources":["../../src/ports/brain.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA0CH,MAAM,OAAO,qBAAqB;IACxB,KAAK,GAAG,IAAI,GAAG,EAAiD,CAAC;IAEzE,KAAK,CAAC,GAAG,CACP,KAAa,EACb,GAAW,EACX,KAAc,EACd,IAAyB;QAEzB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,KAAK,IAAI,GAAG,EAAE,EAAE;YAChC,KAAK;YACL,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,EAAE,KAAK,IAAI,OAAO,CAAC;SACjD,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,KAAa,EAAE,GAAW;QAClC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,KAAK,IAAI,GAAG,EAAE,CAAC,CAAC;QAChD,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QACxB,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;YACjC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,KAAK,IAAI,GAAG,EAAE,CAAC,CAAC;YACrC,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,KAAK,CAAC,KAAK,CAAC;IACrB,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,GAAW;QACrC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,KAAK,IAAI,GAAG,EAAE,CAAC,CAAC;IACvC,CAAC;CACF;AA2DD,MAAM,OAAO,sBAAsB;IACzB,MAAM,GAA0B,EAAE,CAAC;IAE3C,KAAK,CAAC,MAAM,CACV,OAAe,EACf,KAAa,EACb,KAAa,EACb,QAAkC,EAClC,IAA2B;QAE3B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;YACf,OAAO;YACP,KAAK;YACL,KAAK;YACL,QAAQ;YACR,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,OAAO,EAAE,IAAI,EAAE,OAAO;SACvB,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,KAAK,CACT,OAAe,EACf,OAAe,EACf,IAAyB;QAEzB,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM;aACzB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,OAAO,IAAI,CAAC,CAAC,SAAS,IAAI,OAAO,CAAC;aAC9D,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC;QAC7C,OAAO,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;IAChE,CAAC;IAED,KAAK,CAAC,YAAY,CAChB,OAAe,EACf,IAAyB;QAEzB,qFAAqF;QACrF,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC;QAClE,OAAO,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;IAChE,CAAC;CACF;AAWD,MAAM,OAAO,sBAAsB;IACzB,OAAO,GAAiB,EAAE,CAAC;IAEnC,KAAK,CAAC,KAAK,CAAC,CAAS,EAAE,OAA2B;QAChD,IAAI,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CACtC,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAClD,CAAC;QACF,IAAI,OAAO,EAAE,QAAQ;YACnB,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;QACnE,IAAI,OAAO,EAAE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC7C,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAC7B,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAC/C,CAAC;QACJ,CAAC;QACD,OAAO,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;IACpE,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,KAAsB;QAClC,MAAM,OAAO,GAAe;YAC1B,EAAE,EAAE,YAAY,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE;YACzC,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,QAAQ,EAAE,KAAK,CAAC,QAA+C;YAC/D,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACrC,CAAC;QACF,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC3B,OAAO,OAAO,CAAC;IACjB,CAAC;CACF;AAyBD,MAAM,OAAO,wBAAwB;IAC3B,MAAM,GAAG,IAAI,GAAG,EAA6B,CAAC;IAC9C,MAAM,GAAG,IAAI,GAAG,EAAoB,CAAC;IAE7C,KAAK,CAAC,aAAa,CAAC,OAAe;QACjC,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;QAC3C,MAAM,YAAY,GAAsB,EAAE,CAAC;QAC3C,KAAK,MAAM,CAAC,SAAS,EAAE,UAAU,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAClD,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;YACpD,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;gBAC9B,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;gBACtD,IAAI,KAAK;oBAAE,YAAY,CAAC,IAAI,CAAC,EAAE,GAAG,KAAK,EAAE,MAAM,EAAE,QAAiB,EAAE,CAAC,CAAC;YACxE,CAAC;QACH,CAAC;QACD,OAAO,CAAC,GAAG,GAAG,EAAE,GAAG,YAAY,CAAC,CAAC;IACnC,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,OAAe,EAAE,KAAsB;QACzD,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;QAChD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,GAAG,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;IACjD,CAAC;IAED,KAAK,CAAC,UAAU,CACd,SAAiB,EACjB,WAAmB,EACnB,UAAoB;QAEpB,KAAK,MAAM,QAAQ,IAAI,UAAU,EAAE,CAAC;YAClC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;YAClD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;gBAChC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,GAAG,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;YACvD,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAED,iFAAiF;AAEjF;;;GAGG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IACD;IAA7C,YAAY,OAAe,EAAkB,KAAe;QAC1D,KAAK,CAAC,OAAO,CAAC,CAAC;QAD4B,UAAK,GAAL,KAAK,CAAU;QAE1D,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAO1B;IANlB,mFAAmF;IAC1E,YAAY,CAAS;IAE9B,YACE,OAAe,EACf,YAAoB,EACJ,KAAe;QAE/B,KAAK,CAAC,OAAO,CAAC,CAAC;QAFC,UAAK,GAAL,KAAK,CAAU;QAG/B,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAoBD,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAE3D,MAAM,WAAW,GAAG,KAAK,CAAC,SAAS,CAAC,wBAAwB,EAAE,OAAO,CAAC,CAAC;AAEvE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAe;IACnD,OAAO;QACL,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,UAAU,EAAE,IAAI,CAAC,UAAU;QAE3B,KAAK,CAAC,gBAAgB,CAAC,KAAsB;YAC3C,OAAO,WAAW,CAAC,eAAe,CAChC,wBAAwB,EACxB;gBACE,UAAU,EAAE;oBACV,sBAAsB,EAAE,KAAK,CAAC,QAAQ,IAAI,SAAS;oBACnD,6BAA6B,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;oBAC1D,kBAAkB,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE;oBAC/C,kBAAkB,EAAE,OAAO;iBAC5B;aACF,EACD,KAAK,EAAE,IAAU,EAAE,EAAE;gBACnB,IAAI,CAAC;oBACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;oBAClD,IAAI,MAAM,EAAE,CAAC;wBACX,IAAI,CAAC,YAAY,CAAC,gBAAgB,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;oBACjD,CAAC;oBACD,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,EAAE,EAAE,CAAC,CAAC;oBAC5C,OAAO,MAAM,CAAC;gBAChB,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;oBACjE,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;oBACxD,IAAI,GAAG,YAAY,KAAK;wBAAE,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;oBACpD,MAAM,GAAG,CAAC;gBACZ,CAAC;wBAAS,CAAC;oBACT,IAAI,CAAC,GAAG,EAAE,CAAC;gBACb,CAAC;YACH,CAAC,CACF,CAAC;QACJ,CAAC;QAED,KAAK,CAAC,cAAc,CAClB,KAAa,EACb,OAA2B;YAE3B,IAAI,CAAC,IAAI,CAAC,cAAc;gBAAE,OAAO,EAAE,CAAC;YACpC,MAAM,EAAE,GAAG,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC1C,OAAO,WAAW,CAAC,eAAe,CAChC,sBAAsB,EACtB;gBACE,UAAU,EAAE;oBACV,qBAAqB,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;oBAC1C,sBAAsB,EAAE,OAAO,EAAE,QAAQ,IAAI,MAAM;oBACnD,mBAAmB,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC,CAAC;oBACzC,kBAAkB,EAAE,OAAO;iBAC5B;aACF,EACD,KAAK,EAAE,IAAU,EAAE,EAAE;gBACnB,IAAI,CAAC;oBACH,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;oBACxC,IAAI,CAAC,YAAY,CAAC,0BAA0B,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;oBAC7D,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,EAAE,EAAE,CAAC,CAAC;oBAC5C,OAAO,MAAM,CAAC;gBAChB,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;oBACjE,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;oBACxD,IAAI,GAAG,YAAY,KAAK;wBAAE,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;oBACpD,MAAM,GAAG,CAAC;gBACZ,CAAC;wBAAS,CAAC;oBACT,IAAI,CAAC,GAAG,EAAE,CAAC;gBACb,CAAC;YACH,CAAC,CACF,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/ports/citadel-action.contract.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * CitadelActionPort contract tests.
+ *
+ * Applied to any CitadelActionPort implementation. Tests tiered access control,
+ * state transitions, and governance claim emission.
+ *
+ * Source: vauban-gouvernance/rules/ai/tiered-gates.md + MASTER-PLAN-v5.md §1.3
+ */
+import { type CitadelActionPort } from "./citadel-action.js";
+export declare const citadelActionPortContract: (factory: () => CitadelActionPort) => void;
+//# sourceMappingURL=citadel-action.contract.test.d.ts.map

package/dist/ports/citadel-action.contract.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"citadel-action.contract.test.d.ts","sourceRoot":"","sources":["../../src/ports/citadel-action.contract.test.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAKL,KAAK,iBAAiB,EAMvB,MAAM,qBAAqB,CAAC;AA0D7B,eAAO,MAAM,yBAAyB,GAAI,SAAS,MAAM,iBAAiB,SAwMzE,CAAC"}

package/dist/ports/citadel-action.contract.test.js

@@ -0,0 +1,317 @@
+/**
+ * CitadelActionPort contract tests.
+ *
+ * Applied to any CitadelActionPort implementation. Tests tiered access control,
+ * state transitions, and governance claim emission.
+ *
+ * Source: vauban-gouvernance/rules/ai/tiered-gates.md + MASTER-PLAN-v5.md §1.3
+ */
+import { describe, expect, test } from "vitest";
+import { CitadelTierViolationError, CitadelTaskRefNotFoundError, CitadelSprintNotActiveError, CitadelInvalidStateTransitionError, } from "./citadel-action.js";
+function makeActionContext(overrides = {}) {
+    return {
+        agentId: "test-agent-001",
+        agentTier: "T3",
+        runId: crypto.randomUUID(),
+        ...overrides,
+    };
+}
+function makeSprintInput(overrides = {}) {
+    return {
+        name: "Sprint Test",
+        goal: "Test sprint",
+        project_slug: "test-project",
+        start_date: new Date().toISOString(),
+        end_date: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(),
+        ...overrides,
+    };
+}
+function makeTaskRef(overrides = {}) {
+    return {
+        ref: "test-project:sprint-1:task-001",
+        project: "test-project",
+        sprint: "sprint-1",
+        task_id: "task-001",
+        ...overrides,
+    };
+}
+function makeVerificationEvidence(overrides = {}) {
+    return {
+        passed: true,
+        evidence_text: "Verification scenario executed successfully",
+        evidence_hash: "abcd1234efgh5678ijkl9012mnop3456",
+        ...overrides,
+    };
+}
+function makeDecisionInput(overrides = {}) {
+    return {
+        decision: "Adopt new architecture",
+        context: "Performance issues in current stack",
+        options: ["Refactor current", "Migrate to new stack", "Hybrid approach"],
+        chosen: "Hybrid approach",
+        rationale: "Balance performance and migration cost",
+        ...overrides,
+    };
+}
+export const citadelActionPortContract = (factory) => {
+    describe("CitadelActionPort contract", () => {
+        test("createSprint requires T2+ tier", async () => {
+            const port = factory();
+            const input = makeSprintInput();
+            const ctx = makeActionContext({ agentTier: "T1" });
+            await expect(port.createSprint(input, ctx)).rejects.toThrow(CitadelTierViolationError);
+        });
+        test("createSprint succeeds for T2+ agents", async () => {
+            const port = factory();
+            const input = makeSprintInput();
+            const ctx = makeActionContext({ agentTier: "T2" });
+            const sprintRef = await port.createSprint(input, ctx);
+            expect(sprintRef.sprint_id).toBeDefined();
+            expect(sprintRef.project_slug).toBe(input.project_slug);
+            expect(sprintRef.name).toBe(input.name);
+        });
+        test("updateTaskStatus transitions task state", async () => {
+            const port = factory();
+            const taskRef = makeTaskRef();
+            const ctx = makeActionContext({ agentTier: "T2" });
+            // Transition todo → in_progress
+            await port.updateTaskStatus(taskRef, "in_progress", ctx);
+            // No throw = success
+            // Transition in_progress → done
+            await port.updateTaskStatus(taskRef, "done", ctx);
+            // No throw = success
+        });
+        test("updateTaskStatus blocks invalid transitions", async () => {
+            const port = factory();
+            const taskRef = makeTaskRef();
+            const ctx = makeActionContext({ agentTier: "T2" });
+            // Walk valid path: todo → in_progress → done
+            await port.updateTaskStatus(taskRef, "in_progress", ctx);
+            await port.updateTaskStatus(taskRef, "done", ctx);
+            // Now try invalid: done → in_progress (must throw)
+            await expect(port.updateTaskStatus(taskRef, "in_progress", ctx)).rejects.toMatchObject({
+                name: "CitadelInvalidStateTransitionError",
+                current_status: "done",
+                requested_status: "in_progress",
+            });
+        });
+        test("sealSprint requires T3+ tier", async () => {
+            const port = factory();
+            const evidence = makeVerificationEvidence();
+            const ctx = makeActionContext({ agentTier: "T2" });
+            await expect(port.sealSprint("sprint-1", evidence, ctx)).rejects.toThrow(CitadelTierViolationError);
+        });
+        test("sealSprint succeeds for T3+ agents with evidence", async () => {
+            const port = factory();
+            const evidence = makeVerificationEvidence({ passed: true });
+            const ctx = makeActionContext({ agentTier: "T3" });
+            const claim = await port.sealSprint("sprint-1", evidence, ctx);
+            expect(claim.sprint_id).toBe("sprint-1");
+            expect(claim.sealed_at).toBeDefined();
+            expect(claim.sealed_by_agent).toBe(ctx.agentId);
+            expect(claim.verification_evidence_hash).toBe(evidence.evidence_hash);
+        });
+        test("sealSprint fails if sprint not active", async () => {
+            const port = factory();
+            const evidence = makeVerificationEvidence();
+            const ctx = makeActionContext({ agentTier: "T3" });
+            try {
+                // Attempting to seal a sprint that is not in active status
+                await port.sealSprint("sprint-999", evidence, ctx);
+            }
+            catch (err) {
+                if (err instanceof CitadelSprintNotActiveError) {
+                    expect(err.sprint_id).toBe("sprint-999");
+                }
+            }
+        });
+        test("sealSprint emits SealedSprintClaim with anchor_id", async () => {
+            const port = factory();
+            const evidence = makeVerificationEvidence();
+            const ctx = makeActionContext({ agentTier: "T3" });
+            const claim = await port.sealSprint("sprint-1", evidence, ctx);
+            // anchor_id is optional (Phase 1+ deferred), but test should verify if present
+            if (claim.anchor_id) {
+                expect(claim.anchor_id.length).toBeGreaterThan(0);
+            }
+        });
+        test("recordDecision requires T2+ tier", async () => {
+            const port = factory();
+            const decision = makeDecisionInput();
+            const ctx = makeActionContext({ agentTier: "T1" });
+            await expect(port.recordDecision(decision, ctx)).rejects.toThrow(CitadelTierViolationError);
+        });
+        test("recordDecision succeeds for T2+ agents", async () => {
+            const port = factory();
+            const decision = makeDecisionInput();
+            const ctx = makeActionContext({ agentTier: "T2" });
+            const claim = await port.recordDecision(decision, ctx);
+            expect(claim.decision_id).toBeDefined();
+            expect(claim.created_at).toBeDefined();
+            expect(claim.archived_to_brain).toBeDefined();
+        });
+        test("recordDecision T3+ triggers cascade hook", async () => {
+            const port = factory();
+            const decision = makeDecisionInput({
+                decision: "ADR-ECO-NNN: Architectural Decision",
+            });
+            const ctx = makeActionContext({ agentTier: "T3" });
+            const claim = await port.recordDecision(decision, ctx);
+            // T3+ should trigger cascade (optional, implementation-specific)
+            // Just verify claim is returned
+            expect(claim.decision_id).toBeDefined();
+        });
+        test("tier violation error includes required and actual tier", async () => {
+            const port = factory();
+            const input = makeSprintInput();
+            const ctx = makeActionContext({ agentTier: "T1" });
+            try {
+                await port.createSprint(input, ctx);
+            }
+            catch (err) {
+                if (err instanceof CitadelTierViolationError) {
+                    expect(err.required_tier).toBe("T2");
+                    expect(err.actual_tier).toBe("T1");
+                    expect(err.operation).toBeDefined();
+                }
+            }
+        });
+        test("task not found error includes task ref", async () => {
+            const port = factory();
+            const taskRef = makeTaskRef({ ref: "nonexistent:sprint-1:task-999" });
+            const ctx = makeActionContext({ agentTier: "T2" });
+            try {
+                await port.updateTaskStatus(taskRef, "done", ctx);
+            }
+            catch (err) {
+                if (err instanceof CitadelTaskRefNotFoundError) {
+                    expect(err.task_ref).toContain("nonexistent");
+                }
+            }
+        });
+        test("sprint not active error includes current status", async () => {
+            const port = factory();
+            const evidence = makeVerificationEvidence();
+            const ctx = makeActionContext({ agentTier: "T3" });
+            try {
+                await port.sealSprint("completed-sprint", evidence, ctx);
+            }
+            catch (err) {
+                if (err instanceof CitadelSprintNotActiveError) {
+                    expect(err.sprint_id).toBe("completed-sprint");
+                    expect(err.current_status).toBeDefined();
+                }
+            }
+        });
+        test("T4 agents can seal sprints", async () => {
+            const port = factory();
+            const evidence = makeVerificationEvidence();
+            const ctx = makeActionContext({ agentTier: "T4" });
+            try {
+                const claim = await port.sealSprint("sprint-1", evidence, ctx);
+                expect(claim.sealed_by_agent).toBe(ctx.agentId);
+            }
+            catch (err) {
+                // May fail for other reasons (sprint not found), but not tier violation
+                if (err instanceof CitadelTierViolationError) {
+                    throw new Error("T4 should not have tier violation");
+                }
+            }
+        });
+    });
+};
+// ─── Mock implementation ──────────────────────────────────────────────────
+class MockCitadelActionPort {
+    sprintStates = new Map();
+    taskStates = new Map();
+    constructor() {
+        // Pre-populate some sprint states
+        this.sprintStates.set("sprint-1", {
+            status: "active",
+            tasks: new Map([
+                ["test-project:sprint-1:task-001", "todo"],
+                ["test-project:sprint-1:task-002", "in_progress"],
+            ]),
+        });
+        this.sprintStates.set("completed-sprint", {
+            status: "completed",
+            tasks: new Map(),
+        });
+    }
+    async createSprint(input, ctx) {
+        // T2+ only
+        if (ctx.agentTier === "T1") {
+            throw new CitadelTierViolationError(`T1 agents cannot create sprints`, "T2", ctx.agentTier, "createSprint");
+        }
+        const sprintId = `sprint-${Math.floor(Math.random() * 10000)}`;
+        this.sprintStates.set(sprintId, {
+            status: "planned",
+            tasks: new Map(),
+        });
+        return {
+            sprint_id: sprintId,
+            project_slug: input.project_slug,
+            name: input.name,
+            created_at: new Date(),
+        };
+    }
+    async updateTaskStatus(ref, status, ctx) {
+        // Check if task exists
+        if (!this.taskStates.has(ref.ref) && !ref.ref.startsWith("test-project")) {
+            throw new CitadelTaskRefNotFoundError(ref.ref);
+        }
+        // Get current status
+        const currentStatus = this.taskStates.get(ref.ref) || "todo";
+        // Validate state transitions
+        const validTransitions = {
+            todo: ["in_progress", "blocked", "rejected"],
+            in_progress: ["done", "blocked", "rejected"],
+            done: ["blocked", "rejected"],
+            blocked: ["in_progress", "rejected"],
+            rejected: [],
+        };
+        if (!validTransitions[currentStatus]?.includes(status)) {
+            throw new CitadelInvalidStateTransitionError(currentStatus, status);
+        }
+        this.taskStates.set(ref.ref, status);
+    }
+    async sealSprint(sprintId, evidence, ctx) {
+        // T3+ only
+        if (ctx.agentTier !== "T3" && ctx.agentTier !== "T4") {
+            throw new CitadelTierViolationError(`${ctx.agentTier} agents cannot seal sprints`, "T3", ctx.agentTier, "sealSprint");
+        }
+        // Check if sprint exists and is active
+        const sprintState = this.sprintStates.get(sprintId);
+        if (!sprintState) {
+            throw new CitadelSprintNotActiveError(sprintId, "not_found");
+        }
+        if (sprintState.status !== "active") {
+            throw new CitadelSprintNotActiveError(sprintId, sprintState.status);
+        }
+        // Update sprint status to completed
+        sprintState.status = "completed";
+        return {
+            sprint_id: sprintId,
+            sealed_at: new Date(),
+            verification_evidence_hash: evidence.evidence_hash,
+            sealed_by_agent: ctx.agentId,
+            anchor_id: `anchor-${crypto.randomUUID()}`,
+        };
+    }
+    async recordDecision(decision, ctx) {
+        // T2+ only
+        if (ctx.agentTier === "T1") {
+            throw new CitadelTierViolationError(`T1 agents cannot record decisions`, "T2", ctx.agentTier, "recordDecision");
+        }
+        const cascade = ctx.agentTier === "T3" || ctx.agentTier === "T4";
+        return {
+            decision_id: `decision-${crypto.randomUUID()}`,
+            created_at: new Date(),
+            archived_to_brain: true,
+            cascade_triggered: cascade,
+        };
+    }
+}
+// ─── Default contract application ──────────────────────────────────────────
+citadelActionPortContract(() => new MockCitadelActionPort());
+//# sourceMappingURL=citadel-action.contract.test.js.map