@oscharko-dev/keiko-quality-intelligence 0.2.0

package/dist/review/fourEyes.js

@@ -0,0 +1,45 @@
+// Quality Intelligence four-eyes pairing guard (Epic #270, Issue #282).
+//
+// Pure-domain check that two review records may be paired under four-eyes
+// governance. The contract guarantees `reviewerLabel` is display-only with NO
+// PII guarantee; this module compares labels as opaque strings only (post
+// trim + case-fold for the same-label check) and never persists them.
+export class QualityIntelligenceFourEyesViolationError extends Error {
+    code;
+    recordId;
+    candidateId;
+    constructor(code, record, candidate, detail) {
+        super(`[${code}] record="${record.id}" candidate="${candidate.id}": ${detail}`);
+        this.name = "QualityIntelligenceFourEyesViolationError";
+        this.code = code;
+        this.recordId = record.id;
+        this.candidateId = candidate.id;
+    }
+}
+const normaliseLabel = (label) => label.trim().toLowerCase();
+/**
+ * Assert that `record` and `candidate` may be paired for four-eyes governance.
+ * Throws a typed `QualityIntelligenceFourEyesViolationError` on:
+ *
+ *   * SELF_REVIEW_FORBIDDEN — both records have `reviewerKind === "human-author"`.
+ *     A human author may not also be the four-eyes second reviewer of their own
+ *     authored output.
+ *   * SAME_REVIEWER_LABEL — both records share the same (trimmed, case-folded)
+ *     `reviewerLabel`. Display-only string comparison; no identity guarantee.
+ *   * ALREADY_PAIRED — either record already references a `fourEyesPairedRecordId`.
+ *
+ * Returns `void` on success. The caller is responsible for actually wiring
+ * `fourEyesPairedRecordId` on both records when pairing succeeds.
+ */
+export const assertFourEyesPair = (record, candidate) => {
+    if (record.fourEyesPairedRecordId !== undefined ||
+        candidate.fourEyesPairedRecordId !== undefined) {
+        throw new QualityIntelligenceFourEyesViolationError("ALREADY_PAIRED", record, candidate, "One or both records already have fourEyesPairedRecordId set");
+    }
+    if (record.reviewerKind === "human-author" && candidate.reviewerKind === "human-author") {
+        throw new QualityIntelligenceFourEyesViolationError("SELF_REVIEW_FORBIDDEN", record, candidate, "Two human-author reviewers cannot pair under four-eyes governance");
+    }
+    if (normaliseLabel(record.reviewerLabel) === normaliseLabel(candidate.reviewerLabel)) {
+        throw new QualityIntelligenceFourEyesViolationError("SAME_REVIEWER_LABEL", record, candidate, "Both records share the same reviewerLabel");
+    }
+};

package/dist/review/index.d.ts

@@ -0,0 +1,5 @@
+export { applyReviewTransition, QualityIntelligenceReviewTransitionError, QUALITY_INTELLIGENCE_REVIEW_TRANSITION_EVENTS, type QualityIntelligenceReviewTransitionEvent, type QualityIntelligenceReviewTransitionErrorCode, type NextReviewState, } from "./stateMachine.js";
+export { isTerminalReviewState, canPairForFourEyes } from "./lifecyclePolicy.js";
+export { assertFourEyesPair, QualityIntelligenceFourEyesViolationError, type QualityIntelligenceFourEyesViolationCode, } from "./fourEyes.js";
+export { buildReviewAuditEvent, transitionedPayloadFromNext, QUALITY_INTELLIGENCE_REVIEW_AUDIT_EVENT_SCHEMA_VERSION, QUALITY_INTELLIGENCE_REVIEW_AUDIT_EVENT_KINDS, type QualityIntelligenceReviewAuditEventKind, type QualityIntelligenceReviewOpenedPayload, type QualityIntelligenceReviewTransitionedPayload, type QualityIntelligenceReviewFourEyesPairedPayload, type QualityIntelligenceReviewTerminatedPayload, type QualityIntelligenceReviewAuditEventPayload, type QualityIntelligenceReviewAuditEvent, type BuildReviewAuditEventInput, } from "./auditEvents.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/review/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/review/index.ts"],"names":[],"mappings":"AAWA,OAAO,EACL,qBAAqB,EACrB,wCAAwC,EACxC,6CAA6C,EAC7C,KAAK,wCAAwC,EAC7C,KAAK,4CAA4C,EACjD,KAAK,eAAe,GACrB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAEjF,OAAO,EACL,kBAAkB,EAClB,yCAAyC,EACzC,KAAK,wCAAwC,GAC9C,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,qBAAqB,EACrB,2BAA2B,EAC3B,sDAAsD,EACtD,6CAA6C,EAC7C,KAAK,uCAAuC,EAC5C,KAAK,sCAAsC,EAC3C,KAAK,4CAA4C,EACjD,KAAK,8CAA8C,EACnD,KAAK,0CAA0C,EAC/C,KAAK,0CAA0C,EAC/C,KAAK,mCAAmC,EACxC,KAAK,0BAA0B,GAChC,MAAM,kBAAkB,CAAC"}

package/dist/review/index.js

@@ -0,0 +1,14 @@
+// Public barrel for the Quality Intelligence review sub-namespace (Epic #270, Issue #282).
+//
+// Pure-domain review governance: state machine, lifecycle policy, four-eyes pairing
+// guard, and the producer half of the audit-event envelope. No IO, no persistence,
+// no clock — callers supply `at` timestamps and `by` actor labels.
+//
+// Consumers:
+//   * Workflow runtime (#273) drives the state machine and emits audit events.
+//   * Evidence layer (#274) and audit ledger persist the emitted events.
+//   * UI (#280 follow-up) renders the resulting records.
+export { applyReviewTransition, QualityIntelligenceReviewTransitionError, QUALITY_INTELLIGENCE_REVIEW_TRANSITION_EVENTS, } from "./stateMachine.js";
+export { isTerminalReviewState, canPairForFourEyes } from "./lifecyclePolicy.js";
+export { assertFourEyesPair, QualityIntelligenceFourEyesViolationError, } from "./fourEyes.js";
+export { buildReviewAuditEvent, transitionedPayloadFromNext, QUALITY_INTELLIGENCE_REVIEW_AUDIT_EVENT_SCHEMA_VERSION, QUALITY_INTELLIGENCE_REVIEW_AUDIT_EVENT_KINDS, } from "./auditEvents.js";

package/dist/review/lifecyclePolicy.d.ts

@@ -0,0 +1,21 @@
+import type { QualityIntelligence } from "@oscharko-dev/keiko-contracts";
+/**
+ * Return true iff the supplied review state is terminal — i.e. no further
+ * transition is legal under `applyReviewTransition`.
+ *
+ * Terminal: `approved`, `rejected`, `withdrawn`. Non-terminal: `open`,
+ * `changes-requested`.
+ */
+export declare const isTerminalReviewState: (state: QualityIntelligence.QualityIntelligenceReviewState) => boolean;
+/**
+ * Return true iff `record` is eligible to be paired with a second review for
+ * four-eyes governance. A record is eligible when:
+ *
+ *   * its state is non-terminal, AND
+ *   * it has not already been paired (`fourEyesPairedRecordId` is absent).
+ *
+ * Eligibility is a structural predicate only — the actual reviewer-identity
+ * disjointness check lives in `assertFourEyesPair`.
+ */
+export declare const canPairForFourEyes: (record: QualityIntelligence.QualityIntelligenceReviewRecord) => boolean;
+//# sourceMappingURL=lifecyclePolicy.d.ts.map

package/dist/review/lifecyclePolicy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecyclePolicy.d.ts","sourceRoot":"","sources":["../../src/review/lifecyclePolicy.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAQzE;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,GAChC,OAAO,mBAAmB,CAAC,8BAA8B,KACxD,OAAqC,CAAC;AAEzC;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,mBAAmB,CAAC,+BAA+B,KAC1D,OAQF,CAAC"}

package/dist/review/lifecyclePolicy.js

@@ -0,0 +1,38 @@
+// Quality Intelligence review lifecycle policy (Epic #270, Issue #282).
+//
+// Pure predicates over the QualityIntelligenceReviewRecord contract. Used by
+// the runtime (#273) and the audit ledger (#274) to decide whether a record is
+// still live, whether it may be paired for four-eyes governance, and whether
+// downstream consumers should treat its state as final.
+const TERMINAL_STATES = new Set([
+    "approved",
+    "rejected",
+    "withdrawn",
+]);
+/**
+ * Return true iff the supplied review state is terminal — i.e. no further
+ * transition is legal under `applyReviewTransition`.
+ *
+ * Terminal: `approved`, `rejected`, `withdrawn`. Non-terminal: `open`,
+ * `changes-requested`.
+ */
+export const isTerminalReviewState = (state) => TERMINAL_STATES.has(state);
+/**
+ * Return true iff `record` is eligible to be paired with a second review for
+ * four-eyes governance. A record is eligible when:
+ *
+ *   * its state is non-terminal, AND
+ *   * it has not already been paired (`fourEyesPairedRecordId` is absent).
+ *
+ * Eligibility is a structural predicate only — the actual reviewer-identity
+ * disjointness check lives in `assertFourEyesPair`.
+ */
+export const canPairForFourEyes = (record) => {
+    if (isTerminalReviewState(record.state)) {
+        return false;
+    }
+    if (record.fourEyesPairedRecordId !== undefined) {
+        return false;
+    }
+    return true;
+};

package/dist/review/stateMachine.d.ts

@@ -0,0 +1,28 @@
+import type { QualityIntelligence } from "@oscharko-dev/keiko-contracts";
+export type QualityIntelligenceReviewTransitionEvent = "approve" | "request-changes" | "reject" | "withdraw" | "revise";
+export declare const QUALITY_INTELLIGENCE_REVIEW_TRANSITION_EVENTS: readonly QualityIntelligenceReviewTransitionEvent[];
+export type QualityIntelligenceReviewTransitionErrorCode = "TRANSITION_NOT_ALLOWED" | "UNKNOWN_FROM_STATE" | "UNKNOWN_EVENT";
+export declare class QualityIntelligenceReviewTransitionError extends Error {
+    readonly code: QualityIntelligenceReviewTransitionErrorCode;
+    readonly from: QualityIntelligence.QualityIntelligenceReviewState;
+    readonly event: QualityIntelligenceReviewTransitionEvent;
+    constructor(code: QualityIntelligenceReviewTransitionErrorCode, from: QualityIntelligence.QualityIntelligenceReviewState, event: QualityIntelligenceReviewTransitionEvent, detail: string);
+}
+export interface NextReviewState {
+    readonly state: QualityIntelligence.QualityIntelligenceReviewState;
+    readonly by: string;
+    readonly at: string;
+    readonly event: QualityIntelligenceReviewTransitionEvent;
+    readonly from: QualityIntelligence.QualityIntelligenceReviewState;
+}
+/**
+ * Apply a review transition. Returns the next state record on success; throws a
+ * typed `QualityIntelligenceReviewTransitionError` on every illegal combination
+ * (including unknown `from` state or unknown event).
+ *
+ * `by` and `at` are pass-through metadata for the caller's audit envelope —
+ * this function does not validate them beyond presence (it does not call
+ * `Date.parse`; that is the caller's responsibility).
+ */
+export declare const applyReviewTransition: (currentState: QualityIntelligence.QualityIntelligenceReviewState, event: QualityIntelligenceReviewTransitionEvent, by: string, at: string) => NextReviewState;
+//# sourceMappingURL=stateMachine.d.ts.map

package/dist/review/stateMachine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stateMachine.d.ts","sourceRoot":"","sources":["../../src/review/stateMachine.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAEzE,MAAM,MAAM,wCAAwC,GAChD,SAAS,GACT,iBAAiB,GACjB,QAAQ,GACR,UAAU,GACV,QAAQ,CAAC;AAEb,eAAO,MAAM,6CAA6C,EAAE,SAAS,wCAAwC,EACpC,CAAC;AAE1E,MAAM,MAAM,4CAA4C,GACpD,wBAAwB,GACxB,oBAAoB,GACpB,eAAe,CAAC;AAEpB,qBAAa,wCAAyC,SAAQ,KAAK;IACjE,SAAgB,IAAI,EAAE,4CAA4C,CAAC;IACnE,SAAgB,IAAI,EAAE,mBAAmB,CAAC,8BAA8B,CAAC;IACzE,SAAgB,KAAK,EAAE,wCAAwC,CAAC;gBAG9D,IAAI,EAAE,4CAA4C,EAClD,IAAI,EAAE,mBAAmB,CAAC,8BAA8B,EACxD,KAAK,EAAE,wCAAwC,EAC/C,MAAM,EAAE,MAAM;CAQjB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC,8BAA8B,CAAC;IACnE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,wCAAwC,CAAC;IACzD,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC,8BAA8B,CAAC;CACnE;AA2BD;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,GAChC,cAAc,mBAAmB,CAAC,8BAA8B,EAChE,OAAO,wCAAwC,EAC/C,IAAI,MAAM,EACV,IAAI,MAAM,KACT,eAiCF,CAAC"}

package/dist/review/stateMachine.js

@@ -0,0 +1,71 @@
+// Quality Intelligence review state machine (Epic #270, Issue #282).
+//
+// Pure-domain transitions over the QualityIntelligenceReviewState enum from
+// @oscharko-dev/keiko-contracts. Inspired structurally by the review-governance
+// scaffolding under Test Intelligence reference (TI) — modelled freshly here.
+//
+// No IO, no persistence, no clock. Callers pass `by` (display label of the actor)
+// and `at` (ISO 8601 timestamp produced by the caller's clock). The function is
+// total over the typed event enum: every illegal transition raises a typed
+// `QualityIntelligenceReviewTransitionError` with the offending `from`, `event`,
+// and a fail-closed reason code.
+export const QUALITY_INTELLIGENCE_REVIEW_TRANSITION_EVENTS = ["approve", "request-changes", "reject", "withdraw", "revise"];
+export class QualityIntelligenceReviewTransitionError extends Error {
+    code;
+    from;
+    event;
+    constructor(code, from, event, detail) {
+        super(`[${code}] from="${from}" event="${event}": ${detail}`);
+        this.name = "QualityIntelligenceReviewTransitionError";
+        this.code = code;
+        this.from = from;
+        this.event = event;
+    }
+}
+// Static transition table — pure data. Every legal `(from, event)` pair maps to
+// the resulting state. Lookups against this table are O(1); absence raises a
+// typed error.
+const TRANSITIONS = new Map([
+    ["open|approve", "approved"],
+    ["open|request-changes", "changes-requested"],
+    ["open|reject", "rejected"],
+    ["open|withdraw", "withdrawn"],
+    ["changes-requested|revise", "open"],
+    ["changes-requested|withdraw", "withdrawn"],
+]);
+const KNOWN_STATES = new Set([
+    "open",
+    "approved",
+    "changes-requested",
+    "rejected",
+    "withdrawn",
+]);
+const KNOWN_EVENTS = new Set(QUALITY_INTELLIGENCE_REVIEW_TRANSITION_EVENTS);
+/**
+ * Apply a review transition. Returns the next state record on success; throws a
+ * typed `QualityIntelligenceReviewTransitionError` on every illegal combination
+ * (including unknown `from` state or unknown event).
+ *
+ * `by` and `at` are pass-through metadata for the caller's audit envelope —
+ * this function does not validate them beyond presence (it does not call
+ * `Date.parse`; that is the caller's responsibility).
+ */
+export const applyReviewTransition = (currentState, event, by, at) => {
+    if (!KNOWN_STATES.has(currentState)) {
+        throw new QualityIntelligenceReviewTransitionError("UNKNOWN_FROM_STATE", currentState, event, `State "${currentState}" is not a known review state`);
+    }
+    if (!KNOWN_EVENTS.has(event)) {
+        throw new QualityIntelligenceReviewTransitionError("UNKNOWN_EVENT", currentState, event, `Event "${event}" is not a known transition event`);
+    }
+    const next = TRANSITIONS.get(`${currentState}|${event}`);
+    if (next === undefined) {
+        throw new QualityIntelligenceReviewTransitionError("TRANSITION_NOT_ALLOWED", currentState, event, `No legal transition from "${currentState}" via "${event}"`);
+    }
+    return Object.freeze({
+        state: next,
+        by,
+        at,
+        event,
+        from: currentState,
+    });
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@oscharko-dev/keiko-quality-intelligence",
+  "version": "0.2.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "description": "Internal workspace package: pure-domain Keiko Quality Intelligence test-design logic. Not published independently.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.json",
+    "typecheck": "tsc -b tsconfig.json",
+    "test": "vitest run"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@oscharko-dev/keiko-contracts": "0.2.0",
+    "@oscharko-dev/keiko-security": "0.2.0"
+  }
+}