@connexum/ai-governance 1.0.0-beta.11

package/dist/retention/ingest-classifier.d.ts

@@ -0,0 +1,126 @@
+/**
+ * IngestClassifier -- P4-RET-01
+ *
+ * Wires DataClassifier at the audit-event ingress point.
+ *
+ * classifyAndTag() is the single entry point for all audit events entering
+ * the retention engine. It:
+ *   1. Resolves the DataClassTag for the event using DataClassifier.classify().
+ *   2. Attaches dataClass[] to the event metadata.
+ *   3. Enforces the PHI-without-HIPAA block: if the resolved dataClass is
+ *      PhiRecord and 'hipaa' is not in activePackIds, the call throws
+ *      PhiWithoutHipaaError (fail-closed -- no PHI enters the system without
+ *      an active HIPAA binding).
+ *   4. Returns the enriched event with dataClass stamped.
+ *
+ * PT-RET-5 (Unicode lookalike evasion):
+ *   The classifier matches write-site strings against the rule table using
+ *   exact-string and RegExp matching only. Write-site strings are
+ *   normalised to NFC Unicode before matching so Unicode lookalike attacks
+ *   (e.g. using Cyrillic 'а' U+0430 to impersonate ASCII 'a' U+0061) are
+ *   detected by the rule-miss guard and throw UnclassifiedWriteError.
+ *
+ * @connexum/ai-governance P4-RET-01
+ */
+import { DataClassifier, UnboundDataError, UnclassifiedWriteError, RetentionError } from './classifier';
+import { type DataClassTag, type SovereigntyZone } from './data-class';
+import type { ClassificationRule } from './classification-rules';
+/**
+ * Thrown when a PHI record arrives without an active HIPAA binding.
+ *
+ * Fail-closed: PHI must not enter the system without HIPAA governance.
+ * The calling layer must activate the hipaa compliance pack for the tenant
+ * before storing any protected health information.
+ *
+ * PT-RET-5 / P4-RET-01 AC 6.
+ */
+export declare class PhiWithoutHipaaError extends RetentionError {
+    readonly tenantId: string;
+    constructor(tenantId: string);
+}
+/**
+ * Minimal context supplied by the event source.
+ */
+export interface ClassifyAndTagInput {
+    /**
+     * Stable write-site identifier (e.g. 'audit:chain:append').
+     * Will be NFC-normalised before rule lookup to defeat Unicode lookalike
+     * substitutions (PT-RET-5).
+     */
+    writeSite: string;
+    /** Owning tenant ID. */
+    tenantId: string;
+    /**
+     * Contract under which this event was produced.
+     * If not known at call time, callers should use a sentinel like
+     * 'default-contract' rather than omitting the field.
+     */
+    contractId: string;
+    /**
+     * Pack IDs active for this tenant at event ingestion time.
+     * The classifier intersects these with the resolver output.
+     * If empty, UnboundDataError is thrown.
+     */
+    activePackIds: string[];
+    /**
+     * Optional: explicit sovereignty hint from the caller.
+     * When omitted the rule's sovereigntyResolver determines the zone.
+     */
+    sovereigntyHint?: SovereigntyZone;
+}
+/**
+ * The original event payload type the caller wants to enrich.
+ * We accept Record<string, unknown> to remain agnostic about the actual
+ * event schema (EventBus payload, AuditChainEntry, etc.).
+ */
+export type AuditEventRecord = Record<string, unknown>;
+/**
+ * Return value from classifyAndTag(). Combines the original event with
+ * the stamped DataClassTag and the resolved dataClass labels.
+ */
+export interface ClassifyAndTagResult<T extends AuditEventRecord = AuditEventRecord> {
+    /** The original event, unchanged. */
+    event: T;
+    /** The resolved DataClassTag. */
+    tag: DataClassTag;
+    /**
+     * Array of data class labels attached to the event.
+     * Currently always a single-element array (one class per write site)
+     * but typed as array for forward-compatibility with multi-class tagging.
+     */
+    dataClass: string[];
+}
+/**
+ * Return (or create) the shared DataClassifier instance.
+ * Custom rules can be injected via `options.rules` in tests.
+ */
+export declare function getClassifier(options?: {
+    rules?: ClassificationRule[];
+}): DataClassifier;
+/**
+ * Reset the shared DataClassifier instance. For tests only.
+ * @internal
+ */
+export declare function __resetClassifierForTest(): void;
+/**
+ * Classify an incoming audit event and stamp a DataClassTag onto it.
+ *
+ * Wraps DataClassifier.classify() with:
+ *   - NFC Unicode normalisation of writeSite (PT-RET-5 lookalike guard)
+ *   - PHI-without-HIPAA enforcement (PhiWithoutHipaaError)
+ *   - dataClass[] attachment to the result
+ *
+ * Throws:
+ *   - UnclassifiedWriteError: write site has no rule (fail-closed)
+ *   - UnboundDataError: resolved packBinding is empty
+ *   - PhiWithoutHipaaError: PHI record without active HIPAA pack
+ *
+ * @param event  The audit event to enrich (not mutated).
+ * @param ctx    Classification context.
+ * @param opts   Optional: inject custom classifier rules for tests.
+ */
+export declare function classifyAndTag<T extends AuditEventRecord = AuditEventRecord>(event: T, ctx: ClassifyAndTagInput, opts?: {
+    rules?: ClassificationRule[];
+}): ClassifyAndTagResult<T>;
+export { UnclassifiedWriteError, UnboundDataError };
+//# sourceMappingURL=ingest-classifier.d.ts.map

package/dist/retention/ingest-classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest-classifier.d.ts","sourceRoot":"","sources":["../../src/retention/ingest-classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACxG,OAAO,EAAa,KAAK,YAAY,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAClF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAMjE;;;;;;;;GAQG;AACH,qBAAa,oBAAqB,SAAQ,cAAc;IACtD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,QAAQ,EAAE,MAAM;CAY7B;AAMD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB,wBAAwB;IACxB,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;OAIG;IACH,aAAa,EAAE,MAAM,EAAE,CAAC;IAExB;;;OAGG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEvD;;;GAGG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC,SAAS,gBAAgB,GAAG,gBAAgB;IACjF,qCAAqC;IACrC,KAAK,EAAE,CAAC,CAAC;IACT,iCAAiC;IACjC,GAAG,EAAE,YAAY,CAAC;IAClB;;;;OAIG;IACH,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAQD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,kBAAkB,EAAE,CAAA;CAAE,GAAG,cAAc,CASxF;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,gBAAgB,GAAG,gBAAgB,EAC1E,KAAK,EAAE,CAAC,EACR,GAAG,EAAE,mBAAmB,EACxB,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,kBAAkB,EAAE,CAAA;CAAE,GACtC,oBAAoB,CAAC,CAAC,CAAC,CA0BzB;AAGD,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/retention/ingest-classifier.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * IngestClassifier -- P4-RET-01
+ *
+ * Wires DataClassifier at the audit-event ingress point.
+ *
+ * classifyAndTag() is the single entry point for all audit events entering
+ * the retention engine. It:
+ *   1. Resolves the DataClassTag for the event using DataClassifier.classify().
+ *   2. Attaches dataClass[] to the event metadata.
+ *   3. Enforces the PHI-without-HIPAA block: if the resolved dataClass is
+ *      PhiRecord and 'hipaa' is not in activePackIds, the call throws
+ *      PhiWithoutHipaaError (fail-closed -- no PHI enters the system without
+ *      an active HIPAA binding).
+ *   4. Returns the enriched event with dataClass stamped.
+ *
+ * PT-RET-5 (Unicode lookalike evasion):
+ *   The classifier matches write-site strings against the rule table using
+ *   exact-string and RegExp matching only. Write-site strings are
+ *   normalised to NFC Unicode before matching so Unicode lookalike attacks
+ *   (e.g. using Cyrillic 'а' U+0430 to impersonate ASCII 'a' U+0061) are
+ *   detected by the rule-miss guard and throw UnclassifiedWriteError.
+ *
+ * @connexum/ai-governance P4-RET-01
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnboundDataError = exports.UnclassifiedWriteError = exports.PhiWithoutHipaaError = void 0;
+exports.getClassifier = getClassifier;
+exports.__resetClassifierForTest = __resetClassifierForTest;
+exports.classifyAndTag = classifyAndTag;
+const classifier_1 = require("./classifier");
+Object.defineProperty(exports, "UnboundDataError", { enumerable: true, get: function () { return classifier_1.UnboundDataError; } });
+Object.defineProperty(exports, "UnclassifiedWriteError", { enumerable: true, get: function () { return classifier_1.UnclassifiedWriteError; } });
+const data_class_1 = require("./data-class");
+// ---------------------------------------------------------------------------
+// PHI-without-HIPAA error
+// ---------------------------------------------------------------------------
+/**
+ * Thrown when a PHI record arrives without an active HIPAA binding.
+ *
+ * Fail-closed: PHI must not enter the system without HIPAA governance.
+ * The calling layer must activate the hipaa compliance pack for the tenant
+ * before storing any protected health information.
+ *
+ * PT-RET-5 / P4-RET-01 AC 6.
+ */
+class PhiWithoutHipaaError extends classifier_1.RetentionError {
+    tenantId;
+    constructor(tenantId) {
+        super({
+            message: `PhiWithoutHipaaError: PHI record detected for tenant "${tenantId}" ` +
+                'but the hipaa compliance pack is not active. ' +
+                'Activate the hipaa pack for this tenant before storing protected health information. ' +
+                '(P4-RET-01 AC 6, PT-RET-5)',
+            code: 'PHI_WITHOUT_HIPAA',
+        });
+        this.name = 'PhiWithoutHipaaError';
+        this.tenantId = tenantId;
+    }
+}
+exports.PhiWithoutHipaaError = PhiWithoutHipaaError;
+// ---------------------------------------------------------------------------
+// Singleton classifier instance
+// ---------------------------------------------------------------------------
+let _classifier = null;
+/**
+ * Return (or create) the shared DataClassifier instance.
+ * Custom rules can be injected via `options.rules` in tests.
+ */
+function getClassifier(options) {
+    if (options?.rules) {
+        // Non-singleton path for tests: always create a fresh instance.
+        return new classifier_1.DataClassifier({ rules: options.rules });
+    }
+    if (!_classifier) {
+        _classifier = new classifier_1.DataClassifier();
+    }
+    return _classifier;
+}
+/**
+ * Reset the shared DataClassifier instance. For tests only.
+ * @internal
+ */
+function __resetClassifierForTest() {
+    _classifier = null;
+}
+// ---------------------------------------------------------------------------
+// Main API
+// ---------------------------------------------------------------------------
+/**
+ * Classify an incoming audit event and stamp a DataClassTag onto it.
+ *
+ * Wraps DataClassifier.classify() with:
+ *   - NFC Unicode normalisation of writeSite (PT-RET-5 lookalike guard)
+ *   - PHI-without-HIPAA enforcement (PhiWithoutHipaaError)
+ *   - dataClass[] attachment to the result
+ *
+ * Throws:
+ *   - UnclassifiedWriteError: write site has no rule (fail-closed)
+ *   - UnboundDataError: resolved packBinding is empty
+ *   - PhiWithoutHipaaError: PHI record without active HIPAA pack
+ *
+ * @param event  The audit event to enrich (not mutated).
+ * @param ctx    Classification context.
+ * @param opts   Optional: inject custom classifier rules for tests.
+ */
+function classifyAndTag(event, ctx, opts) {
+    // PT-RET-5: normalise writeSite to NFC Unicode to defeat lookalike substitutions.
+    // A Cyrillic 'а' (U+0430) in the write-site string will not match any
+    // ASCII rule and will hit the UnclassifiedWriteError guard.
+    const normalisedWriteSite = ctx.writeSite.normalize('NFC');
+    const classifier = getClassifier(opts);
+    // May throw UnclassifiedWriteError or UnboundDataError.
+    const tag = classifier.classify(normalisedWriteSite, {
+        tenantId: ctx.tenantId,
+        contractId: ctx.contractId,
+        activePackIds: ctx.activePackIds,
+        sovereigntyHint: ctx.sovereigntyHint,
+    });
+    // PHI-without-HIPAA block (P4-RET-01 AC 6, PT-RET-5).
+    if (tag.dataClass === data_class_1.DataClass.PhiRecord && !ctx.activePackIds.includes('hipaa')) {
+        throw new PhiWithoutHipaaError(ctx.tenantId);
+    }
+    return {
+        event,
+        tag,
+        dataClass: [tag.dataClass],
+    };
+}
+//# sourceMappingURL=ingest-classifier.js.map

package/dist/retention/ingest-classifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest-classifier.js","sourceRoot":"","sources":["../../src/retention/ingest-classifier.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;;;AA6GH,sCASC;AAMD,4DAEC;AAuBD,wCA8BC;AAjLD,6CAAwG;AAoLvE,iGApLR,6BAAgB,OAoLQ;AAAxC,uGApLkC,mCAAsB,OAoLlC;AAnL/B,6CAAkF;AAGlF,8EAA8E;AAC9E,0BAA0B;AAC1B,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAa,oBAAqB,SAAQ,2BAAc;IAC7C,QAAQ,CAAS;IAE1B,YAAY,QAAgB;QAC1B,KAAK,CAAC;YACJ,OAAO,EACL,yDAAyD,QAAQ,IAAI;gBACrE,+CAA+C;gBAC/C,uFAAuF;gBACvF,4BAA4B;YAC9B,IAAI,EAAE,mBAAmB;SAC1B,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAfD,oDAeC;AAiED,8EAA8E;AAC9E,gCAAgC;AAChC,8EAA8E;AAE9E,IAAI,WAAW,GAA0B,IAAI,CAAC;AAE9C;;;GAGG;AACH,SAAgB,aAAa,CAAC,OAA0C;IACtE,IAAI,OAAO,EAAE,KAAK,EAAE,CAAC;QACnB,gEAAgE;QAChE,OAAO,IAAI,2BAAc,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IACtD,CAAC;IACD,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,WAAW,GAAG,IAAI,2BAAc,EAAE,CAAC;IACrC,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;GAGG;AACH,SAAgB,wBAAwB;IACtC,WAAW,GAAG,IAAI,CAAC;AACrB,CAAC;AAED,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,cAAc,CAC5B,KAAQ,EACR,GAAwB,EACxB,IAAuC;IAEvC,kFAAkF;IAClF,sEAAsE;IACtE,4DAA4D;IAC5D,MAAM,mBAAmB,GAAG,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAE3D,MAAM,UAAU,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IAEvC,wDAAwD;IACxD,MAAM,GAAG,GAAG,UAAU,CAAC,QAAQ,CAAC,mBAAmB,EAAE;QACnD,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,aAAa,EAAE,GAAG,CAAC,aAAa;QAChC,eAAe,EAAE,GAAG,CAAC,eAAe;KACrC,CAAC,CAAC;IAEH,sDAAsD;IACtD,IAAI,GAAG,CAAC,SAAS,KAAK,sBAAS,CAAC,SAAS,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QAClF,MAAM,IAAI,oBAAoB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO;QACL,KAAK;QACL,GAAG;QACH,SAAS,EAAE,CAAC,GAAG,CAAC,SAAmB,CAAC;KACrC,CAAC;AACJ,CAAC"}

package/dist/retention/legal-hold-errors.d.ts

@@ -0,0 +1,57 @@
+/**
+ * LegalHold error hierarchy -- P4-RET-03
+ *
+ * Fail-closed philosophy: every error condition is named and typed.
+ * Callers must handle each case explicitly.
+ *
+ * Spec: P4-RET-01 AC 21
+ *
+ * @connexum/ai-governance
+ */
+/**
+ * Base class for all LegalHold errors.
+ * Extends Error so callers can use instanceof LegalHoldError as a
+ * catch-all before narrowing to subtypes.
+ */
+export declare class LegalHoldError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/**
+ * Thrown when a LegalHold creation request carries a scope with NO
+ * populated fields (tenantId, contractId, agentId, caseTag, packId).
+ * A system-wide hold with an empty scope is not expressible by default
+ * (requires explicit opt-in not implemented in this cycle per spec).
+ *
+ * Spec: P4-RET-01 Section 2.3, "fail-closed. Empty scope refused."
+ */
+export declare class LegalHoldScopeEmptyError extends LegalHoldError {
+    constructor();
+}
+/**
+ * Thrown when a requested holdId does not exist in the store.
+ */
+export declare class LegalHoldNotFoundError extends LegalHoldError {
+    readonly holdId: string;
+    constructor(holdId: string);
+}
+/**
+ * Thrown when a race condition is detected that would let a hold be
+ * created and deleted in the same tick without an intervening approval
+ * event.
+ *
+ * The canonical scenario (pentest PT-RET-2): a deletion job starts
+ * scanning; another thread calls create() immediately followed by
+ * release() before the approval-queue event fires. The store detects
+ * this by verifying that a 'pending' hold cannot transition directly
+ * to 'released' without first passing through 'active' (which requires
+ * a resolved approval event).
+ *
+ * Spec: P4-RET-01 AC 21
+ */
+export declare class LegalHoldConcurrencyError extends LegalHoldError {
+    readonly holdId: string;
+    readonly attemptedTransition: string;
+    constructor(holdId: string, attemptedTransition: string);
+}
+//# sourceMappingURL=legal-hold-errors.d.ts.map

package/dist/retention/legal-hold-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legal-hold-errors.d.ts","sourceRoot":"","sources":["../../src/retention/legal-hold-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAO1C;AAMD;;;;;;;GAOG;AACH,qBAAa,wBAAyB,SAAQ,cAAc;;CAW3D;AAMD;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,cAAc;IACxD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,MAAM,EAAE,MAAM;CAQ3B;AAMD;;;;;;;;;;;;;GAaG;AACH,qBAAa,yBAA0B,SAAQ,cAAc;IAC3D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;gBAEzB,MAAM,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM;CAWxD"}

package/dist/retention/legal-hold-errors.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * LegalHold error hierarchy -- P4-RET-03
+ *
+ * Fail-closed philosophy: every error condition is named and typed.
+ * Callers must handle each case explicitly.
+ *
+ * Spec: P4-RET-01 AC 21
+ *
+ * @connexum/ai-governance
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LegalHoldConcurrencyError = exports.LegalHoldNotFoundError = exports.LegalHoldScopeEmptyError = exports.LegalHoldError = void 0;
+// ---------------------------------------------------------------------------
+// Base error
+// ---------------------------------------------------------------------------
+/**
+ * Base class for all LegalHold errors.
+ * Extends Error so callers can use instanceof LegalHoldError as a
+ * catch-all before narrowing to subtypes.
+ */
+class LegalHoldError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = 'LegalHoldError';
+        this.code = code;
+        // Maintains proper prototype chain in environments that transpile ES6 classes.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.LegalHoldError = LegalHoldError;
+// ---------------------------------------------------------------------------
+// Empty scope -- creation guard
+// ---------------------------------------------------------------------------
+/**
+ * Thrown when a LegalHold creation request carries a scope with NO
+ * populated fields (tenantId, contractId, agentId, caseTag, packId).
+ * A system-wide hold with an empty scope is not expressible by default
+ * (requires explicit opt-in not implemented in this cycle per spec).
+ *
+ * Spec: P4-RET-01 Section 2.3, "fail-closed. Empty scope refused."
+ */
+class LegalHoldScopeEmptyError extends LegalHoldError {
+    constructor() {
+        super('LegalHold scope must contain at least one field ' +
+            '(tenantId, contractId, agentId, caseTag, or packId). ' +
+            'An empty scope implying a system-wide hold is refused by default. ' +
+            'Populate at least one scope field.', 'LEGAL_HOLD_SCOPE_EMPTY');
+        this.name = 'LegalHoldScopeEmptyError';
+    }
+}
+exports.LegalHoldScopeEmptyError = LegalHoldScopeEmptyError;
+// ---------------------------------------------------------------------------
+// Not found
+// ---------------------------------------------------------------------------
+/**
+ * Thrown when a requested holdId does not exist in the store.
+ */
+class LegalHoldNotFoundError extends LegalHoldError {
+    holdId;
+    constructor(holdId) {
+        super(`LegalHold '${holdId}' not found.`, 'LEGAL_HOLD_NOT_FOUND');
+        this.name = 'LegalHoldNotFoundError';
+        this.holdId = holdId;
+    }
+}
+exports.LegalHoldNotFoundError = LegalHoldNotFoundError;
+// ---------------------------------------------------------------------------
+// Concurrency / race condition
+// ---------------------------------------------------------------------------
+/**
+ * Thrown when a race condition is detected that would let a hold be
+ * created and deleted in the same tick without an intervening approval
+ * event.
+ *
+ * The canonical scenario (pentest PT-RET-2): a deletion job starts
+ * scanning; another thread calls create() immediately followed by
+ * release() before the approval-queue event fires. The store detects
+ * this by verifying that a 'pending' hold cannot transition directly
+ * to 'released' without first passing through 'active' (which requires
+ * a resolved approval event).
+ *
+ * Spec: P4-RET-01 AC 21
+ */
+class LegalHoldConcurrencyError extends LegalHoldError {
+    holdId;
+    attemptedTransition;
+    constructor(holdId, attemptedTransition) {
+        super(`LegalHold '${holdId}' concurrency violation: attempted transition '${attemptedTransition}' ` +
+            'without an intervening approval-queue event. ' +
+            'A hold may not be released while still pending approval.', 'LEGAL_HOLD_CONCURRENCY');
+        this.name = 'LegalHoldConcurrencyError';
+        this.holdId = holdId;
+        this.attemptedTransition = attemptedTransition;
+    }
+}
+exports.LegalHoldConcurrencyError = LegalHoldConcurrencyError;
+//# sourceMappingURL=legal-hold-errors.js.map

package/dist/retention/legal-hold-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"legal-hold-errors.js","sourceRoot":"","sources":["../../src/retention/legal-hold-errors.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAEH,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;GAIG;AACH,MAAa,cAAe,SAAQ,KAAK;IAC9B,IAAI,CAAS;IAEtB,YAAY,OAAe,EAAE,IAAY;QACvC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,+EAA+E;QAC/E,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAVD,wCAUC;AAED,8EAA8E;AAC9E,gCAAgC;AAChC,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAa,wBAAyB,SAAQ,cAAc;IAC1D;QACE,KAAK,CACH,kDAAkD;YAChD,uDAAuD;YACvD,oEAAoE;YACpE,oCAAoC,EACtC,wBAAwB,CACzB,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AAXD,4DAWC;AAED,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E;;GAEG;AACH,MAAa,sBAAuB,SAAQ,cAAc;IAC/C,MAAM,CAAS;IAExB,YAAY,MAAc;QACxB,KAAK,CACH,cAAc,MAAM,cAAc,EAClC,sBAAsB,CACvB,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAXD,wDAWC;AAED,8EAA8E;AAC9E,+BAA+B;AAC/B,8EAA8E;AAE9E;;;;;;;;;;;;;GAaG;AACH,MAAa,yBAA0B,SAAQ,cAAc;IAClD,MAAM,CAAS;IACf,mBAAmB,CAAS;IAErC,YAAY,MAAc,EAAE,mBAA2B;QACrD,KAAK,CACH,cAAc,MAAM,kDAAkD,mBAAmB,IAAI;YAC3F,+CAA+C;YAC/C,0DAA0D,EAC5D,wBAAwB,CACzB,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;QACxC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,mBAAmB,GAAG,mBAAmB,CAAC;IACjD,CAAC;CACF;AAfD,8DAeC"}

package/dist/retention/legal-hold-store.d.ts

@@ -0,0 +1,191 @@
+/**
+ * LegalHoldStore -- P4-RET-03 Legal Hold Mechanism
+ *
+ * In-memory Map-based implementation for this cycle.
+ * Prisma-backed persistence is a follow-up (migration flagged below).
+ *
+ * Core contract:
+ *   - create()  -- validates scope, routes to approval queue, returns
+ *                  a 'pending' hold that does NOT match deletion queries.
+ *   - extend()  -- updates expiresAt after a fresh approval.
+ *   - release() -- marks 'released' after a fresh approval. Does NOT
+ *                  auto-delete previously held data (AC 10).
+ *   - findHoldsMatching() -- deletion-engine query: returns active holds
+ *                  whose scope covers the given record.
+ *   - list()    -- partner-admin / legal-reviewer query.
+ *
+ * Approval-queue hook:
+ *   create() and release() route through the provided ApprovalQueueHook
+ *   before committing status changes. The hook is intentionally thin: it
+ *   enqueues an entry and returns a promise that resolves when the entry
+ *   is resolved (approved/denied). This decouples LegalHoldStore from the
+ *   governance-server's full ApprovalQueue implementation so it can be
+ *   used in the core SDK without dragging in HTTP server dependencies.
+ *
+ * Spec: P4-RET-01 Section 2.3, AC 7-10
+ *
+ * @connexum/ai-governance
+ */
+import type { LegalHold, LegalHoldScope, ISO8601, AuditChainRef } from './legal-hold';
+/**
+ * Minimal interface the LegalHoldStore needs from the approval queue.
+ * The governance-server passes a real implementation; tests pass a stub.
+ *
+ * The store calls enqueue() and waits for the returned promise. If the
+ * reviewer denies the request, enqueue() should reject with an Error.
+ * The store surfaces that rejection to the caller as-is.
+ */
+export interface ApprovalQueueHook {
+    /**
+     * Enqueue a legal-reviewer approval request.
+     *
+     * @param subject   Human-readable description (e.g. "Create legal hold for tenant X").
+     * @param holdId    The hold being acted on.
+     * @param actor     Who is requesting the action.
+     * @param action    'create' | 'extend' | 'release'
+     * @returns         Promise that resolves with the approval-queue entry ID
+     *                  once the request is approved, or rejects if denied.
+     */
+    enqueue(subject: string, holdId: string, actor: string, action: 'create' | 'extend' | 'release'): Promise<string>;
+}
+/**
+ * Descriptor for the record being checked against active legal holds.
+ * All fields are optional; the store uses whichever fields are present.
+ */
+export interface RecordDescriptor {
+    tenantId?: string;
+    contractId?: string;
+    agentId?: string;
+    packBinding?: string[];
+    /** ISO-8601 timestamp of the record (used for dateRange scope filter). */
+    timestamp?: ISO8601;
+    /** Optional case tag on the record (matched against scope.caseTag). */
+    caseTag?: string;
+}
+export interface LegalHoldListFilter {
+    tenantId?: string;
+    contractId?: string;
+    agentId?: string;
+    caseTag?: string;
+    packId?: string;
+    status?: 'pending' | 'active' | 'released';
+}
+export interface CreateLegalHoldInput {
+    scope: LegalHoldScope;
+    reason: string;
+    expiresAt?: ISO8601;
+}
+export interface ExtendLegalHoldInput {
+    newExpiresAt: ISO8601;
+}
+/**
+ * The store calls this after every lifecycle transition so the
+ * governance-server can append to the tamper-evident audit chain.
+ * Returns the chain entry ID that gets recorded in chainOfCustody.
+ */
+export type AuditEmitter = (eventName: string, holdId: string, actor: string, metadata: Record<string, unknown>) => Promise<AuditChainRef>;
+export declare function makeNoOpAuditEmitter(): AuditEmitter;
+/**
+ * Stores, retrieves, and queries LegalHold entities.
+ *
+ * Thread-safety note: Node.js is single-threaded; the Map operations
+ * here are effectively atomic. The ConcurrencyError guard exists for
+ * the logical race (pending -> release without active transition) not
+ * for actual memory races.
+ */
+export declare class LegalHoldStore {
+    private readonly holds;
+    private readonly approvalQueue;
+    private readonly emitAudit;
+    constructor(approvalQueue: ApprovalQueueHook, emitAudit?: AuditEmitter);
+    /**
+     * Create a new LegalHold.
+     *
+     * The hold starts in 'pending' status and does NOT match deletion queries
+     * until a legal-reviewer approves it. Approval is handled via the
+     * ApprovalQueueHook provided at construction time.
+     *
+     * Throws LegalHoldScopeEmptyError if the scope has no populated fields.
+     *
+     * @param input  Creation parameters (scope, reason, optional expiresAt).
+     * @param actor  Authenticated actor submitting the request (JWT sub claim).
+     * @returns      The hold in 'pending' status after enqueuing approval.
+     *               The returned hold becomes 'active' asynchronously once
+     *               a legal-reviewer approves it. Callers should poll or
+     *               subscribe to audit events for the transition.
+     */
+    create(input: CreateLegalHoldInput, actor: string): Promise<LegalHold>;
+    /**
+     * Extend the expiry of an active LegalHold.
+     *
+     * Requires a fresh legal-reviewer approval (same queue, new entry).
+     * Only 'active' holds can be extended; pending holds must first become
+     * active. Released holds cannot be extended.
+     *
+     * @param holdId      The hold to extend.
+     * @param newExpires  New expiry ISO-8601 timestamp.
+     * @param actor       Authenticated actor requesting the extension.
+     */
+    extend(holdId: string, newExpires: ISO8601, actor: string): Promise<LegalHold>;
+    /**
+     * Release a LegalHold.
+     *
+     * Only 'active' holds can be released. A 'pending' hold cannot be
+     * released directly -- that would be a concurrency / logic bypass.
+     * Throwing LegalHoldConcurrencyError on the pending->released path
+     * covers the PT-RET-2 race scenario.
+     *
+     * Release does NOT auto-delete previously held data (AC 10). Records
+     * past their retention window at release time are flagged by the next
+     * scheduled job.
+     *
+     * @param holdId  The hold to release.
+     * @param actor   Authenticated actor requesting the release.
+     */
+    release(holdId: string, actor: string): Promise<LegalHold>;
+    /**
+     * Deletion-engine query.
+     *
+     * Returns all ACTIVE holds whose scope matches the given record.
+     * Pending and released holds are excluded (only 'active' blocks deletion).
+     *
+     * The tenant-scope is authoritative: a hold with tenantId='acme' catches
+     * every record where record.tenantId === 'acme', regardless of whether
+     * the hold also has a narrower agentId or packId constraint.
+     *
+     * @param record  Descriptor of the record being considered for deletion.
+     * @returns       Array of active LegalHold objects that cover the record.
+     *                Empty array means the record is not held and deletion may proceed.
+     */
+    findHoldsMatching(record: RecordDescriptor): Promise<LegalHold[]>;
+    /**
+     * Partner-admin / legal-reviewer query.
+     *
+     * Returns holds matching the given filter criteria (all fields are
+     * optional AND-combined). Returns all holds when no filter is supplied.
+     *
+     * @param filter  Optional filter criteria.
+     * @returns       Matching holds, ordered by createdAt descending.
+     */
+    list(filter?: LegalHoldListFilter): Promise<LegalHold[]>;
+    /**
+     * Activate a pending hold after approval.
+     * Used by routes that implement asynchronous approval resolution
+     * (e.g. a human clicks Approve in the dashboard after the initial
+     * POST /legal-holds request returned a 202).
+     *
+     * Emits the 'retention:legal-hold-created' audit event at activation
+     * time (not at enqueue time) so the chain reflects actual approval.
+     */
+    activatePending(holdId: string, approvalEntryId: string, actor: string): Promise<LegalHold>;
+    /**
+     * Get a single hold by ID. Returns undefined if not found.
+     * Used by routes for GET single-item endpoints.
+     */
+    get(holdId: string): LegalHold | undefined;
+    /**
+     * Internal size accessor (used in tests).
+     */
+    get size(): number;
+}
+//# sourceMappingURL=legal-hold-store.d.ts.map

package/dist/retention/legal-hold-store.d.ts.map

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